Standards as Agent Instructions¶

A standards file that is actionable for humans is, verbatim, an instruction file for agents — the same document does both jobs when written precisely.

The Dual-Audience Property¶

Standards files — STANDARDS.md, CLAUDE.md, .github/copilot-instructions.md — are read by humans checking their own work and by agents producing output. A precise standard needs no translation layer; a vague one fails both audiences.

The distinguishing property is actionability:

Vague (fails both)	Actionable (serves both)
"Be concise"	"Max 500 words for pattern pages; max 750 for techniques"
"Follow naming conventions"	"Use kebab-case file names; no prefixes or numbering"
"Write good commit messages"	"Use conventional commits: `type(scope): description`"
"Avoid filler"	`"No phrases: 'in this guide', 'let's explore', 'as you may know'"`

The actionable form gives a verifiable rule; the vague form gives interpretive latitude, which produces inconsistent output.

Why Agents Read Standards Literally¶

Humans read standards with context — domain knowledge, edge-case judgment, intent over letter. Agents apply the rule as written. Ambiguity does not yield a reasonable interpretation; it yields the interpretation most consistent with training data, which may not match project conventions — the gap that concrete examples close. Standards designed so agents can follow them without interpretation are also clearer for humans.

File Hierarchy¶

Standards work at multiple scopes. Claude Code reads CLAUDE.md in a hierarchy: managed policy → project → user (Claude Code memory docs). GitHub Copilot reads .github/copilot-instructions.md at the repository level (Copilot customization docs).

A root standards file applies to all tasks; nested files add specificity. A rule in src/auth/CLAUDE.md overrides or extends the root when an agent works in that directory. Keep area-specific rules out of the root — they add noise to every task even when irrelevant.

Concrete Examples as Anchors¶

Standards with examples are more reliably followed than rule-only prompts — few-shot prompting research consistently shows this (Anthropic context engineering). An agent reading "no filler phrases" must infer what counts. An agent reading:

No filler phrases: "in this guide", "let's explore", "as you may know", "it's worth noting"

has a concrete reference set. Where a rule has clear correct and incorrect forms, include both — the contrast eliminates the ambiguity zone where interpretation errors occur.

Standards as Quality Gates¶

Reviewers use the standards file as a diff target: output either satisfies the rule or it does not. This works only if the rule produces a binary determination. "Be concise" fails as a gate — any output can be argued to satisfy it. "Max 500 words" succeeds — word count is measurable. Designing standards for reviewability forces the precision that also makes them work as agent instructions.

Example¶

A STANDARDS.md excerpt written so both a human reviewer and an agent can apply every rule without interpretation:

## Commit Messages

Format: `type(scope): lowercase description under 72 chars`
Types: feat, fix, docs, refactor, test, chore
Scope: directory name or filename stem

✅ `docs(agent-harness): add tool registration example`
❌ `Updated the agent harness docs`

## Page Structure

1. YAML frontmatter with `title`, `description` (80–160 chars), `tags` (≥1)
2. H1 matching the `title` field
3. Blockquote summary (one sentence, defines the concept — not "This page covers…")
4. Body sections using H2; never skip heading levels
5. `## Related` section with relative markdown links

## Word Limits

| Directory        | Max body words |
|------------------|---------------|
| `patterns/`      | 750           |
| `anti-patterns/` | 500           |
| `articles/`      | 5000          |

## File Naming

- kebab-case, no prefixes, no numbering
- Stem matches the concept: `agent-harness.md`, not `01-harness-overview.md`

A human reviewer reads these rules and checks a pull request against them. An agent reads the same file as its instruction set and produces output that satisfies every rule on the first pass. No translation layer, no separate prompt — one document serves both.

Why It Works¶

Agents lack the sociolinguistic context humans use to interpret vague norms. A human reading "be concise" draws on domain conventions and professional context to calibrate output; an agent pattern-matches against training data, producing output that is concise in general rather than in the project-specific sense. Precision replaces that missing context — "max 500 words for pattern pages" gives a verifiable target independent of inference. Examples work by the same mechanism: they narrow the interpretation space by demonstrating the intended form directly.

When This Backfires¶

Precision improves adherence only while the standards file stays short. Adherence degrades as length grows — keeping context to a minimal set of high-signal tokens is the core of Anthropic's context engineering guidance, and the Claude Code memory docs put a number on it: target under 200 lines per CLAUDE.md file, because "longer files consume more context and reduce adherence."

Three failure modes:

Context bloat: A 400-line file loads every session regardless of relevance. At high context utilization, precision on rule 300 offers no advantage — competition for attention makes it unreliable.
Priority saturation: When every rule is stated with equal precision, nothing signals higher priority. An agent following 80 precisely-worded rules has no principled way to break ties.
Scope mismatch: Project-wide standards that include area-specific rules inject irrelevant constraints into every task. Use directory-scoped files (.claude/rules/, nested CLAUDE.md) to keep standards contextually relevant.

When standards files grow large, the correct response is decomposition — not more precision.

Key Takeaways¶

Actionable standards require no translation to serve as agent instructions — precision serves both audiences
Agents read literally; ambiguity produces training-data defaults, not project-appropriate interpretation
Scope rules via file hierarchy: project-wide at root, area-specific in nested files
Include concrete examples — correct and incorrect forms — to eliminate the ambiguity zone
Design for reviewability (binary pass/fail per rule) to force precision that works for agents
Keep standards files short; precision degrades as file length grows past ~200 lines