Auto-Improving AGENTS.md
Two modes of operation
Setup mode: The user asks to create, structure, or audit an AGENTS.md file. Follow the setup workflows below.
Session mode: The user wants ongoing auto-improvement during the current session. Follow the behavioral directives below — propose AGENTS.md updates when corrected or when discovering undocumented conventions.
Workflow: Bootstrap a new AGENTS.md
- Ask for (or discover) the project's build, test, and lint commands.
- Copy the starter template from assets/starter-agents.md into the project root as
AGENTS.md.
- Fill in the command placeholders.
- Delete the seed examples under Conventions.
- Leave all other sections with their comment placeholders — they fill organically.
- Commit the file.
Do NOT write a comprehensive AGENTS.md upfront.
Alternative bootstrap: Study the repo and draft initial rules, then ruthlessly prune — keep only what would surprise a competent developer reading the codebase for the first time.
Workflow: Add auto-improvement to an existing AGENTS.md
- Verify the file has clearly named sections (Commands, Conventions, Architecture Decisions, Boundaries, Gotchas). If not, restructure first — see references/01-bootstrapping-and-structure.md.
- Append the Self-Improvement Meta-Rules block from assets/starter-agents.md.
- Verify the file is under 150 rules. If over, prune first.
Workflow: Prune and audit
- Count rules (not lines — a multi-line code block is one rule).
- For each rule, apply the pruning checklist in references/03-maintenance-and-anti-patterns.md.
- Consolidate near-duplicate rules into single bullets.
- Compress any multi-sentence rule to one line. If it resists compression, link to a doc instead.
- Confirm the file is under 150 rules after all removals. If still over, repeat from step 2 with stricter criteria.
Pruning cadence: monthly for active projects, on major refactors, or whenever adding a rule would push past 150.
Behavioral directives: Real-time auto-improvement
When corrected by the user
- Apply the correction to the current task.
- Assess whether the correction reflects a recurring pattern (not a one-off).
- If recurring, propose a one-line rule for AGENTS.md. Specify the target section.
- Wait for user approval before writing.
When discovering undocumented conventions
Propose adding a convention only if it passes the ambiguity test: multiple valid approaches exist in the codebase and the code alone doesn't indicate the preference.
Rule writing format
- One bullet per rule. No paragraphs.
- NEVER/ALWAYS for hard constraints:
"NEVER use default exports"
- "Prefer X over Y" for soft preferences:
"Prefer composition over inheritance"
- Lead with the action, not the explanation.
- Include the actual command or code pattern, not a description of it.
- Place in the appropriate existing section. Create a new section only if none fits.
Behavioral directives: End-of-session reflection
When the user requests reflection (or after completing significant work):
- Review the session for corrections received, conventions discovered, and retries or mistakes.
- For each, draft a one-line rule that would have prevented the issue.
- Check each proposed rule against existing AGENTS.md for duplication.
- Present the diff before applying.
Edge cases
- No clear sections in existing file: Restructure into the recommended skeleton before adding meta-rules. See references/01-bootstrapping-and-structure.md.
- File exceeds 150 rules: Prune before adding any new rules.
- Tool doesn't read AGENTS.md natively: Create a minimal wrapper file that imports it (e.g.,
CLAUDE.md containing @AGENTS.md). Check the tool's docs for import syntax.
- Rule conflicts with linter/formatter: Remove the AGENTS.md rule. Deterministic tools always win.
- Root file at 150 despite pruning: Split into per-directory hierarchy. See references/01-bootstrapping-and-structure.md.
Reference material
- Bootstrapping, structure, and hierarchy: references/01-bootstrapping-and-structure.md
- Auto-improvement mechanics and meta-rules: references/02-improvement-mechanics.md
- Maintenance, pruning checklist, and anti-patterns: references/03-maintenance-and-anti-patterns.md
- Starter template: assets/starter-agents.md
1---2name: auto-improving-agents-md3description: Sets up, structures, and auto-improves AGENTS.md files for coding agent projects. Bootstraps new AGENTS.md with self-improvement meta-rules, structures sections for clean rule placement, audits and prunes existing files against an instruction budget, performs end-of-session reflection to capture learnings, and proactively proposes AGENTS.md updates when corrections or conventions are discovered mid-session. Use when setting up AGENTS.md, adding auto-improvement to an existing AGENTS.md, pruning or auditing AGENTS.md, performing end-of-session reflection, or when the user mentions auto-improving, self-improving, or maintaining agent instructions.4---56# Auto-Improving AGENTS.md78## Two modes of operation910**Setup mode:** The user asks to create, structure, or audit an AGENTS.md file. Follow the setup workflows below.1112**Session mode:** The user wants ongoing auto-improvement during the current session. Follow the behavioral directives below — propose AGENTS.md updates when corrected or when discovering undocumented conventions.1314## Workflow: Bootstrap a new AGENTS.md15161. Ask for (or discover) the project's build, test, and lint commands.172. Copy the starter template from [assets/starter-agents.md](assets/starter-agents.md) into the project root as `AGENTS.md`.183. Fill in the command placeholders.194. Delete the seed examples under Conventions.205. Leave all other sections with their comment placeholders — they fill organically.216. Commit the file.2223Do NOT write a comprehensive AGENTS.md upfront.2425**Alternative bootstrap:** Study the repo and draft initial rules, then ruthlessly prune — keep only what would surprise a competent developer reading the codebase for the first time.2627## Workflow: Add auto-improvement to an existing AGENTS.md28291. Verify the file has clearly named sections (Commands, Conventions, Architecture Decisions, Boundaries, Gotchas). If not, restructure first — see [references/01-bootstrapping-and-structure.md](references/01-bootstrapping-and-structure.md).302. Append the Self-Improvement Meta-Rules block from [assets/starter-agents.md](assets/starter-agents.md).313. Verify the file is under 150 rules. If over, prune first.3233## Workflow: Prune and audit34351. Count rules (not lines — a multi-line code block is one rule).362. For each rule, apply the pruning checklist in [references/03-maintenance-and-anti-patterns.md](references/03-maintenance-and-anti-patterns.md).373. Consolidate near-duplicate rules into single bullets.384. Compress any multi-sentence rule to one line. If it resists compression, link to a doc instead.395. Confirm the file is under 150 rules after all removals. If still over, repeat from step 2 with stricter criteria.4041**Pruning cadence:** monthly for active projects, on major refactors, or whenever adding a rule would push past 150.4243## Behavioral directives: Real-time auto-improvement4445### When corrected by the user46471. Apply the correction to the current task.482. Assess whether the correction reflects a recurring pattern (not a one-off).493. If recurring, propose a one-line rule for AGENTS.md. Specify the target section.504. Wait for user approval before writing.5152### When discovering undocumented conventions5354Propose adding a convention only if it passes the **ambiguity test**: multiple valid approaches exist in the codebase and the code alone doesn't indicate the preference.5556### Rule writing format5758- One bullet per rule. No paragraphs.59- NEVER/ALWAYS for hard constraints: `"NEVER use default exports"`60- "Prefer X over Y" for soft preferences: `"Prefer composition over inheritance"`61- Lead with the action, not the explanation.62- Include the actual command or code pattern, not a description of it.63- Place in the appropriate existing section. Create a new section only if none fits.6465## Behavioral directives: End-of-session reflection6667When the user requests reflection (or after completing significant work):68691. Review the session for corrections received, conventions discovered, and retries or mistakes.702. For each, draft a one-line rule that would have prevented the issue.713. Check each proposed rule against existing AGENTS.md for duplication.724. Present the diff before applying.7374## Edge cases7576- **No clear sections in existing file:** Restructure into the recommended skeleton before adding meta-rules. See [references/01-bootstrapping-and-structure.md](references/01-bootstrapping-and-structure.md).77- **File exceeds 150 rules:** Prune before adding any new rules.78- **Tool doesn't read AGENTS.md natively:** Create a minimal wrapper file that imports it (e.g., `CLAUDE.md` containing `@AGENTS.md`). Check the tool's docs for import syntax.79- **Rule conflicts with linter/formatter:** Remove the AGENTS.md rule. Deterministic tools always win.80- **Root file at 150 despite pruning:** Split into per-directory hierarchy. See [references/01-bootstrapping-and-structure.md](references/01-bootstrapping-and-structure.md).8182## Reference material8384- **Bootstrapping, structure, and hierarchy:** [references/01-bootstrapping-and-structure.md](references/01-bootstrapping-and-structure.md)85- **Auto-improvement mechanics and meta-rules:** [references/02-improvement-mechanics.md](references/02-improvement-mechanics.md)86- **Maintenance, pruning checklist, and anti-patterns:** [references/03-maintenance-and-anti-patterns.md](references/03-maintenance-and-anti-patterns.md)87- **Starter template:** [assets/starter-agents.md](assets/starter-agents.md)
msewell