Writing Agent Instructions

AGENTS.md

CLAUDE.md

Keep, Move, or Remove

• Keep non-obvious commands, expensive tripwires, domain vocabulary, and project-specific ownership/compatibility decisions.
• Move a rule to the narrowest subtree or on-demand skill that needs it. Link long rationale or incident evidence instead of embedding it.
• Remove generic engineering advice, duplicated rules, stale model pins, rhetorical emphasis, fixed response ceremonies, and procedures already owned by the harness or toolchain.
• A rule must name when it applies. Availability of a skill does not justify requiring it for every task. Preserve concrete safety and product invariants while narrowing their procedure.

Work

1. Read the relevant instructions, current repository contracts, and user decisions. Check recent changes before pruning policy; keep historical evidence separate from active rules.
2. Review rules by concern: keep, rewrite, relocate, or remove. Record material policy changes and relocations in a concise summary; a line-by-line public verdict table is unnecessary unless requested.
3. Resolve contradictions using the user's current direction and the repository's authoritative policy. Ask only if a remaining conflict changes the outcome and has no established owner.
4. Edit the owning file once and update its pointers. Preserve symlinks and tool-generated blocks; avoid parallel copies that drift.
5. Check that important invariants and real commands remain reachable, nested instructions agree, and removed rules are not silently reintroduced by skills or memory. Review links and changed behavior; prose-only edits do not need tests that freeze wording.