agents-md

Covers AGENTS.md (OpenCode, multi-agent harnesses) and CLAUDE.md (Claude Code). Same principles, different loading mechanics — substitute CLAUDE.md when applicable. Language/framework-agnostic.

Include only what genuinely helps. Never delete useful information without relocating it first.

References

Read on demand — do not load all reference files at once.

When the user mentions...	Read
Auditing an existing file	references/audit-example.md
Testing, TDD, test conventions	references/tdd.md
Monorepos, hierarchical systems, file size	references/hierarchical.md
Flagging problems, reviewing quality	references/anti-patterns.md
Compacting or optimizing an AGENTS.md	references/compaction.md

Core Principles

• Minimum viable requirements. Each line must earn its cost on nearly every session. Every line loads every session — brevity has direct cost benefits. Target under 200 lines for root files. Files exceeding 200 lines show measurable compliance degradation. When reviewing a file that exceeds this threshold, always cite the 200-line target and recommend restructuring.
• Two failure modes. (1) Length — compliance degrades uniformly as instruction count grows. A 500-line AGENTS.md will be partially ignored. (2) Task-irrelevant requirements — correct but unneeded instructions still get followed, increasing cost.
• Compaction is not summarization. Relocate content to scoped sub-files or @import targets — never paraphrase or drop details. Fewer lines in root, not fewer lines total.
• Don't send an LLM to do a linter's job. Use actual linters, wired to hooks if the harness supports it.
• Don't ship auto-generated files unedited. /init output (e.g. claude init, opencode init) is stuffed w/ docs the agent can already read — directory trees, npm script lists, file summaries. Rewrite before committing: strip inferrable content, keep only what the agent cannot discover on its own.
• Don't list inferrable commands. Standard commands like dev, build, start, lint are inferrable — the agent reads package.json / Makefile / pyproject.toml directly. Only document commands whose names don't reveal purpose (e.g., cf-typegen, db:migrate). Listing inferrable commands is the "command dump" anti-pattern. When flagging this issue, always use the full word "inferrable" (not "infer", not "inference" — the full word "inferrable").
• Test through public interfaces. Mock only at system boundaries — external APIs, databases, time, file system. Never mock internal collaborators — it couples tests to implementation details, not behavior. When advising on test rules, always use the phrase "system boundaries". See references/tdd.md for details.
• Architecture/overview sections have weak evidence in root files. Exception: scoped sub-files can carry richer context.

Single File vs. Hierarchical System

Single root file — simple projects (one app, one language, one team). Target under 200 lines.

Hierarchical system — monorepos, large codebases, multiple apps/packages/services. When the user mentions monorepo, multiple teams, multiple apps/packages, or a large codebase, immediately recommend the hierarchical system and explain these key advantages before running intake:

1. The harness auto-loads context files as the agent navigates into subdirectories — no manual loading needed.
2. Sub-files can be richer since they only load when the agent works in that area, avoiding root file bloat.
3. Shared facts belong in the shallowest file covering all relevant paths (Least Common Ancestor). Never duplicate across siblings.

State the hierarchical recommendation first, then ask only the remaining relevant Phase 1 questions. See references/hierarchical.md for file size management, hierarchical rules, and monorepo exclusions.

Writing a New AGENTS.md

# Project or Area Name

One sentence: what it does and why it exists.

## Stack
Tech stack. Package manager or build tool (be explicit — agents assume defaults).
Path aliases if non-standard. Infrastructure if non-obvious (DB, cache, queue).
Directory tree only if ownership boundaries aren't obvious. 1-2 levels max.

## Development
Verification commands only: typecheck, lint, test. What to run before finishing.
Skip inferrable commands (npm run dev, build, start — agent reads package.json).
Include only non-obvious commands whose names don't reveal purpose
(e.g. `cf-typegen`, `db:migrate`, `dotnet ef database update`).

## Conventions
Only things the agent can't infer from reading the code.
No style rules — use a linter.

Add a Reference Docs section only if the agent genuinely needs it before working in that area.

Interactive Intake

Mandatory — always ask questions before writing or auditing. Never generate an AGENTS.md without first asking the Phase 1 questions below. If the user says "write me an AGENTS.md" or any variant, your first response must be to ask these questions — not to start writing.

Use the question tool (OpenCode) or AskUserQuestion tool (Claude Code) to ask each question interactively. Keep wording identical across harnesses. Repo-agnostic: do not assume frontend/backend distinctions.

Skip questions the user already answered. If the user's request directly signals preferences (e.g., "audit my AGENTS.md and remove stale content" → optimization=audit+remove), skip those Phase 1 questions and confirm the inferred answers. If the architectural decision is clear (e.g., monorepo with multiple teams → hierarchical system), state the recommendation with reasoning first, then ask only the remaining relevant questions.

Phase 1: Preferences (before repo investigation)

Ask these questions before exploring the codebase — do not skip this step:

1. Source — Best practices from existing AGENTS.md, discovered from the repo, or both?
2. Audience — Primary audience: agents only, humans only, or both?
3. Format — Short checklist or structured doc w/ sections?
4. Depth — Rule + short rationale, or just the rule?
5. Optimization — Make AGENTS.md more token-efficient (compact, zero info loss), audit and remove/relocate content, or both?
6. Bug workflow — When fixing bugs: write a failing test first that reproduces the bug, then fix it? Or jump straight to the fix?

Conditional follow-ups:

• Repo discovery or both → summarize patterns or cite exact examples?
• Both audiences → separate agent-facing and human-facing content into different sections?
• Compact or both → load references/compaction.md and apply passes before presenting results.
• Test-first bug workflow → use subagents for fix attempts (parallel candidates validated against the failing test), or single-pass fix? See references/tdd.md § "Test-First Bug Fixing" for the workflow to include.

Then investigate: scan for conventions, configs, linter rules, CI, directory structure, existing AGENTS.md files, and patterns worth codifying.

Phase 2: Findings Review (after repo investigation)

Present the 5-8 highest-impact discoveries and ask the developer to classify each one. Summarize the remainder (e.g., "13 additional lint rules found — handled by tooling; 4 path-scoped conventions moved to sub-files").

Placement decision (per finding):

• Keep in root AGENTS.md
• Move to nested AGENTS.md at [suggested path]
• Move to @import doc or path-scoped rules file
• Skip — handled by linter/tooling
• Skip — not useful

Conditional Phase 2 questions:

• Stale content (if AGENTS.md conflicts w/ repo) — update from repo, keep as-is, or remove?
• Scope (when placement is ambiguous) — whole repo or scoped to a specific area?
• Nesting (if nested placement selected) — which directory boundary should own it?
• Pointer (if content moved to nested file) — include a pointer from root?

Workflow

Phase 1 (preferences) → Repo investigation → Phase 2 (findings review) → [Compact if selected] → Draft/Audit

Auditing an Existing AGENTS.md

Auditing is refactoring, not summarization. Every correct piece of information must end up somewhere. Never compress to reduce line count. Load references/anti-patterns.md to flag common problems.

Audit Workflow

1. Measure. Count lines, distinct instructions, style rules, overview sections.
2. Classify each instruction:
   • Essential and universal → keep in root
   • Correct but scoped → relocate to sub-file (e.g., src/api/AGENTS.md) or path-scoped rule, add pointer from root
   • Style/lint rule → remove (use linter/hook)
   • Redundant, stale, or inferrable → remove
3. Relocate before removing. When you find correct-but-scoped content, relocate it to the appropriate sub-file (e.g., src/api/AGENTS.md). Always say "relocate" — not "move", "extract", or "create a file for". Relocation is an atomic three-step sequence:
   1. Create the destination sub-file with the full original content — no paraphrasing.
   2. Verify the destination contains every relocated instruction.
   3. Replace the original content in root with a pointer (e.g., "See src/api/AGENTS.md"). Never delete from root until relocation is confirmed.
4. Hierarchical systems: check if root content belongs in a sub-file, and if sub-files duplicate LCA knowledge.
5. Present results: before/after line counts, what moved where, what removed and why, complete rewritten file(s).

Maintenance

Update affected AGENTS.md files leaf-first on significant changes.

Testing Effectiveness

An AGENTS.md works if agent behavior changes. After writing or auditing:

1. Run a task without the file, note deviations.
2. Add/update instructions targeting those deviations.
3. Re-run, verify behavior shifts.

If the agent ignores a rule, the file is likely too long. If the agent asks questions answered in the file, phrasing may be ambiguous.