evolutionary-instructions

Evolutionary instructions

Instruction docs grow by accretion, not up-front specification. When a pattern has earned its place — through a user correction, a bug, or a non-obvious convention — write it down where the next session will read it.

When to apply

Trigger fires when:

• The user corrects the agent on a project-specific habit ("we use uv add, not uv pip install").
• The agent discovers an undocumented convention by reading code and doesn't want to rediscover it next session.
• A failure mode has happened twice and a written rule would have prevented it.
• A new tool, script, or workflow becomes load-bearing for the project.

Trigger does not fire on session start, on every commit, or on every "interesting fact." Bias toward appending less, not more.

Where to write

• Project root AGENTS.md (canonical filename). Add a CLAUDE.md symlink if the project doesn't already have one:

  ln -s AGENTS.md CLAUDE.md
  

• Per-subtree AGENTS.md for guidance scoped to that subtree.

How to write

• Telegraph style. Dense, imperative, no preamble. The doc is read by agents under context pressure; every sentence has to earn its place.
• Why-led when non-obvious. A rule with no reason gets rationalized away. ("# noqa is blocked because suppression hides problems we got bit by last quarter.")
• One concept per line where possible. Easier to grep, easier to prune.
• Living catalog of anti-patterns. Things the agent did that you don't want it to do again — capture them.

Graduation path

AGENTS.md is the long-lived store. Short-lived state belongs in WORKING_NOTES.md and decision rationale belongs in DECISIONS.md (see two-tier-state). Workflow:

• A pattern starts as a note in WORKING_NOTES.md ("we keep doing X").
• If it persists beyond a week and is project-wide, graduate it to AGENTS.md as a rule.
• If it's a one-off decision with rationale, append to DECISIONS.md instead.

Maintenance

• A mature project might have ~1k lines of AGENTS.md aggregate across the tree. That's fine; what matters is that each line still earns its place.
• Periodically prune entries that have become obvious from the code itself, that are now enforced by hooks, or that no longer apply.
• Don't pre-write AGENTS.md with speculative rules. Wait for the pattern to formalize.

Anti-patterns

• Long preambles ("This document describes the conventions for…"). Cut them.
• Restating what the code already shows. Rules belong here when the code can't tell you them.
• Writing rules as suggestions ("you might consider…"). Be direct.

Exit condition

The lesson is captured in AGENTS.md (root or scoped) in telegraph-style with a one-line why if the rule isn't self-evident.