Writing Agents Md

Core Filter

Before keeping any line, ask:

1. Can the model discover this easily and reliably by reading the repo?
2. Does this matter for most tasks, not just some tasks?
3. Is this likely to remain true as files, paths, and architecture evolve?

If the answer is yes / no / no, it does not belong in a global rule file.

Even if something is technically discoverable, keep it only when omitting it is likely to cause a costly mistake and the model is unlikely to infer the right choice reliably.

Keep

Good candidates for AGENTS.md or CLAUDE.md:

• non-obvious tool choices like uv, not pip
• environment-specific constraints like WSL path behavior
• expensive landmines like false-positive cache behavior
• legacy areas that still have production imports and must not be removed casually

Keep constraints that redirect the agent away from costly wrong defaults. Be cautious with instructions that add new standing requirements the agent would not otherwise follow.

Delete Or Move Out

Usually remove these from global files:

• package scripts copied from package.json
• directory tours and architecture summaries
• tech stack summaries the repo already makes obvious
• file-path-heavy instructions that will rot quickly
• task-specific workflows, style preferences, or domain guidance

Move workflow or domain guidance into a skill instead of keeping it globally.

Every standing instruction is a potential landmine. Prefer a smaller file over a more prescriptive one.

Guardrails

• Do not generate repo overviews, directory tours, or handbook-style summaries in global agent files.
• Do not repeat information the model can discover from code, docs, or config.
• Do not mention legacy technologies without clearly labeling them as legacy or avoid-using.
• Do not keep broad instructions in the global file if they only matter for some tasks.
• If the repo has little truly global guidance, prefer a very short file over a padded one.
• If unsure whether a line earns its keep, cut it.

Output Shape

Aim for a short file that may include sections like:

• environment or tooling constraints
• important landmines
• minimal routing notes to existing skills

Avoid turning the file into a setup guide, architecture document, or coding standards manual.

If the repo has almost no truly global, non-obvious constraints, a tiny file is acceptable and no file is sometimes acceptable too.

References

• See references/checklist.md for the full keep/delete decision list.
• See references/examples.md for bad, better, and good examples.
• See references/principles.md for the underlying rationale.