execution|tool\s+call)\s+(?:write|emit|output)\s+(?:one\s+line|summary|brief)/i, description: 'Enforces single-line execution telemetry' }, { id: 'FAILURE_VISIBILITY', pattern: /(?:quote\s+error|verbatim\s+failure|raw\s+stack|halt\s+on\s+error)/i, description: 'Mandates raw error output and execution halt' }, { id: 'ADJACENT_INSPECTION', pattern: /(?:read\s+adjacent|scan\s+surrounding|inspect\s+nearby)\s+(?:lines?|code|context)/i, description: 'Requires pre-write context scanning' }, { id: 'API_INVENTION_GUARD', pattern: /(?:do\s+not\s+invent|avoid\s+fabricating|use\s+existing)\s+(?:imports|paths|interfaces)/i, description: 'Prevents hallucinated dependencies' }, { id: 'TASK_BOUNDARY', pattern: /(?:single\s+task|one\s+change|isolated\s+modification)/i, description: 'Enforces atomic task execution' }, { id: 'STYLE_CONSISTENCY', pattern: /(?:match\s+existing|follow\s+project|preserve\s+conventions)/i, description: 'Maintains codebase formatting standards' }, { id: 'VERIFICATION_GATE', pattern: /(?:run\s+tests|execute\s+suite|validate\s+before\s+commit)/i, description: 'Requires pre-commit verification' } ];

export function validateAgentConfig(filePath: string): ComplianceReport { const content = fs.readFileSync(filePath, 'utf-8'); const normalized = content.replace(/\s+/g, ' ').trim();

const matched = BEHAVIORAL_RULES.filter(rule => rule.pattern.test(normalized)); const missing = BEHAVIORAL_RULES.filter(rule => !rule.pattern.test(normalized)).map(r => r.id);

return { file: path.basename(filePath), totalRules: BEHAVIORAL_RULES.length, matchedRules: matched.length, coverage: Math.round((matched.length / BEHAVIORAL_RULES.length) * 100), missing }; }

// CLI entry point if (require.main === module) { const target = process.argv[2]; if (!target || !fs.existsSync(target)) { console.error('Usage: node validator.js <path-to-config>'); process.exit(1); } const report = validateAgentConfig(target); console.log(JSON.stringify(report, null, 2)); }

### Architecture Decisions and Rationale

1. **Regex-based pattern matching over LLM evaluation:** LLM-based validators introduce latency, cost, and non-deterministic scoring. Regex patterns anchored to behavioral keywords provide deterministic, sub-millisecond validation suitable for CI pipelines.
2. **Normalized whitespace handling:** Agent configs often contain irregular formatting. Collapsing whitespace before pattern matching prevents false negatives caused by line breaks or indentation variations.
3. **Explicit rule IDs over descriptive scoring:** Returning structured rule IDs enables automated remediation suggestions and version-controlled compliance tracking across repository branches.
4. **Separation of behavior rules from project context:** Context (tech stack, build commands) belongs in documentation. Behavior rules belong in configuration. Mixing them dilutes rule visibility and increases parsing complexity.

## Pitfall Guide

### 1. The README Mirage
**Explanation:** Teams paste their `README.md` content into the agent configuration file, assuming project context equals behavioral guidance. The dataset shows 8% of files scored 0/12 because they contained only project descriptions or installation instructions.
**Fix:** Maintain separate files for onboarding context and behavioral contracts. Use the configuration file exclusively for execution boundaries, failure modes, and verification gates.

### 2. Vague Directive Syndrome
**Explanation:** Instructions like "be careful," "follow best practices," or "write clean code" provide zero deterministic constraints. LLMs interpret these as stylistic preferences rather than operational boundaries, resulting in high-variance outputs.
**Fix:** Replace subjective language with explicit behavioral commands. Use imperative verbs, specify file boundaries, and define exact output formats.

### 3. Silent Failure Tolerance
**Explanation:** Agents are optimized for task completion, not error propagation. When a command fails, the model often paraphrases the error or continues execution, burying stack traces in success prose. 91% of scanned files lacked explicit failure visibility rules.
**Fix:** Mandate raw error quoting and execution halts. Require the agent to output the exact error message and terminate the current task branch rather than attempting recovery without explicit instructions.

### 4. Scope Creep by Default
**Explanation:** Without explicit boundaries, agents treat adjacent files as fair game for refactoring, formatting, or dependency updates. 98% of files missed scope constraints, resulting in PRs with 500 lines of noise wrapping 3 lines of actual logic changes.
**Fix:** Implement a deterministic scope rule that forces the agent to declare intent before touching unrelated modules. Require explicit confirmation for cross-file modifications.

### 5. Tool Preference Ambiguity
**Explanation:** Leaving tool selection to the agent introduces non-deterministic execution paths. One session uses `grep`, another uses `rg`, another uses `find`. This fragments execution logs and complicates debugging.
**Fix:** Specify preferred tooling explicitly. Example: "Use `rg` for search operations, `fd` for file discovery, `make` for builds." Consistent tooling improves log parsing and reduces context window waste.

### 6. Token Budget Blindness
**Explanation:** Unbounded generation loops occur when agents lack explicit token or step limits. The model continues reasoning, refactoring, or verifying until the context window fills, causing silent truncation or degraded output quality.
**Fix:** Define per-task token budgets and step limits. Require the agent to halt and request continuation when thresholds are approached, preserving context integrity.

### 7. Verification Gate Omission
**Explanation:** Only 13% of files missed the test execution rule, making it the most commonly included constraint. However, many implementations lack explicit gate placement. Agents run tests after formatting passes or dependency updates, masking the actual failure source.
**Fix:** Position verification gates immediately after logic changes, before formatting or cleanup steps. Require test output to be included in the execution summary.

## Production Bundle

### Action Checklist
- [ ] Audit existing configuration files against the 12-rule behavioral baseline
- [ ] Remove project context and README content from behavioral configuration files
- [ ] Add explicit scope boundary rules to prevent out-of-scope modifications
- [ ] Implement single-line execution telemetry after each tool invocation
- [ ] Mandate raw error quoting and execution halts for all failure states
- [ ] Require adjacent code inspection before writing new logic
- [ ] Specify preferred tooling to standardize execution paths
- [ ] Integrate behavioral validation into CI pipelines to prevent regression

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Small team, rapid iteration | 4-rule guardrail (scope, telemetry, failure, adjacent) | Delivers 66% reliability with minimal maintenance | Low (minutes to implement) |
| Enterprise, compliance-heavy | Full 12-rule baseline + CI validation | Ensures deterministic outputs and audit trails | Medium (initial setup + pipeline integration) |
| Legacy codebase, high drift | Scope boundary + style consistency + verification gate | Reduces formatting noise and enforces existing conventions | Low-Medium |
| Multi-agent orchestration | Explicit tool preferences + task boundaries + token budgets | Prevents cross-agent interference and context exhaustion | Medium |

### Configuration Template

```markdown
# Agent Behavioral Contract
# This file defines execution boundaries, failure modes, and verification gates.
# Do not include project context or installation instructions here.

## Execution Boundaries
- Restrict modifications to files directly related to the current task.
- Declare intent before touching unrelated modules or dependencies.
- Execute one isolated change per session. Do not bundle unrelated modifications.

## Execution Telemetry
- After each tool invocation, output a single line: [TOOL] changed [FILE] for [REASON].
- Do not emit verbose reasoning logs. Preserve context for task execution.

## Failure Visibility
- If any command fails, quote the error verbatim and halt execution.
- Never paraphrase stack traces or attempt silent recovery.
- Surface partial success states explicitly. Do not mask failures in success prose.

## Pre-Write Inspection
- Read the adjacent 20–40 lines of existing code before writing new logic.
- Do not invent imports, file paths, or interfaces. Use existing patterns.
- Match the project's formatting conventions. Check 3 nearby files if uncertain.

## Verification Gates
- Run the test suite immediately after logic changes, before formatting or cleanup.
- Cap per-task token budget at 8000 tokens. Halt and request continuation when approached.
- Stop and ask if the task scope is ambiguous or conflicting patterns emerge.

Quick Start Guide

1. Extract existing configuration: Locate your CLAUDE.md or AGENTS.md file in the repository root.
2. Strip context noise: Remove project descriptions, installation steps, and README content. Preserve only behavioral instructions.
3. Apply the template: Replace the file content with the configuration template above. Adjust tool preferences and token budgets to match your stack.
4. Validate compliance: Run the TypeScript validator against the updated file. Confirm coverage meets your target threshold (≥7/12 for production).
5. Integrate CI: Add the validator to your pre-commit hook or pipeline. Block merges if behavioral compliance drops below the defined threshold.

The gap between experimental AI agent usage and production reliability is not model capability. It is behavioral specification. By treating agent configuration files as deterministic contracts rather than descriptive documents, teams can eliminate 90% of common failure modes with minimal overhead. The data shows the median configuration covers a quarter of necessary rules. The fix requires four explicit sentences, not a model upgrade.