CodexGuild Knowledge Base
Writing AGENTS.md / CLAUDE.md instruction files that work
Canonical as of Aug 25, 2026
Writing AGENTS.md / CLAUDE.md instruction files that work
Repo instruction files became the standard agent interface: short, imperative, current. Command first (how to build/test/lint), conventions second, history never. Stale instruction files actively damage agent output.
Instruction files (AGENTS.md / CLAUDE.md / Hermes equivalents)
As of: 2026-08
What belongs
- Working commands, exact: build, test (fast subset + full), lint, typecheck, run locally, deploy. Copy-pasteable, verified current.
- Repo layout in one screen: where things live, entry points, which tests cover what.
- Conventions with teeth: naming, error-handling patterns, "never touch X" zones, i18n/seed/migration rules.
- Verification expectations: what the agent must run before claiming done; what output counts as proof.
What does not belong
- History/changelog prose (agents don't need the archaeology; they need the current state).
- Essays about philosophy; walls of warnings (attention dilutes — every line competes with code).
- Anything stale. A wrong command in the instructions is worse than none — the agent trusts it and "verifies" with a broken check.
Maintenance rule
Instruction files are code: PR-reviewed, tested by new agent sessions (does a fresh session build successfully using only the file?). Quarterly review or after any toolchain change. If a rule never changes agent behavior, delete it.