references/anti-patterns.md
# Anti-patterns and fixes
Concrete before/after for every bloat pattern flagged in phase 3. Apply the **After** column directly.
---
## 1. Default-behavior instructions
Telling the agent to do things every modern agent already does. Each one steals an instruction slot from your real custom rules.
**Before**
```markdown
- Write clean, readable code
- Use meaningful variable names
- Handle errors appropriately
- Add comments where the code is complex
- Follow language best practices
- All interactive components must use proper ARIA
- Keyboard navigation must work
```
**After**: delete entirely. Keep only project-specific deviations from default behavior (e.g. "use Radix UI primitives, not custom ARIA").
---
## 2. Hardcoded inventories
Static counts and exhaustive lists go stale within days.
**Before**
```markdown
## Components (47 total)
Button, Input, Select, Dialog, Dropdown, Tooltip, Avatar, Badge, ...
```
**After**
```markdown
## Components
Discover available components: `ls src/components/ui/`
```
---
## 3. Prose where code would work
Verbose descriptions of formats a code block conveys instantly.
**Before** (5 lines)
> Commit messages should follow conventional commits format. The first line should be the type, followed by an optional scope in parentheses, then a colon and space, then a short description in imperative mood…
**After** (2 lines)
```markdown
## Commits
`type(scope): description` — imperative mood, ≤ 72 chars.
Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`.
```
---
## 4. Vague qualifiers
Words that give the model permission to ignore the instruction.
**Before**
```markdown
- Try to use semantic tokens when possible
- Ideally, components should be tested
- Consider using TypeScript strict mode
- You might want to add error handling
```
**After**
```markdown
- Use semantic tokens. Never use raw color scales.
- Test every component. Minimum: render, variant, ref forwarding.
- Enable TypeScript strict mode. No `any`.
- Handle errors with Result types.
```
---
## 5. Meta-instruction prefixes
Preambles that add tokens without meaning.
**Before**
```markdown
- You should always run the type checker before committing
- Remember to use the project's custom ESLint config
- It is important to follow the naming conventions
- Please use the approved icon library
```
**After**
```markdown
- Run `npx tsc --noEmit` before committing
- Use the project ESLint config (do not override)
- Follow naming conventions (see Code Style)
- Use icons from `src/components/ui/icons/`
```
---
## 6. Contradictory rules
Rules that fight each other produce unpredictable behavior.
**Before**
```markdown
## Code Style
- Keep functions under 20 lines
- Always add comprehensive error handling with retry logic
## Performance
- Minimize code in hot paths
- Add detailed logging for every operation
```
**After**: resolve via propose-and-ask, then scope:
```markdown
## Code Style
- Keep functions under 30 lines. Extract helpers for complex logic.
## Hot Paths
- Minimize allocations and logging. Log at `debug` only.
## Non-Hot Paths
- Structured logging at `info`. Retry transient failures with backoff.
```
---
## 7. Missing boundaries
Files that say what TO do but never what NOT to do. Most agent incidents come from unbounded actions, not wrong implementations.
**Before**
```markdown
## Workflow
- Use feature branches
- Write tests for new code
- Run the linter
```
**After**
```markdown
## Workflow
- Use `feature/` branches from `main`
- Write tests for new code (`npx vitest run`)
- Run `npm run lint` before committing
## Boundaries
- Never push directly to `main`
- Never run `git push --force`
- Never modify `.github/workflows/` without approval
- Never add runtime dependencies without checking existing alternatives
- Never delete test files
```
---
## 8. Monolithic files
Everything in a single 500+ line file instead of a layered architecture.
**Before**: one 600-line AGENTS.md including API reference (80 lines), token catalog (60), component props (100), full project history (50).
**After**
```
AGENTS.md (150 lines) # Core rules, commands, structure
references/
api-reference.md # API details
tokens.md # Token catalog
component-props.md # Props documentation
docs/adr/ # Architecture rationale
```
AGENTS.md links to reference files: "See `references/tokens.md` for the token catalog."
---
## 9. Inline rationale
Every rule immediately followed by its justification — doubles file length, and agents act on rules not reasons.
**Before**
```markdown
- Use `vitest` instead of `jest` because vitest has native ESM support,
faster execution through esbuild, and doesn't require babel for TypeScript.
- Use named exports because they enable better tree-shaking, make refactoring
easier with find-and-replace, and prevent naming conflicts at import sites.
```
**After** (rules in AGENTS.md, rationale in `docs/adr/`)
```markdown
- Use `vitest` (never `jest`)
- Use named exports (no default exports)
```
---
## 10. Tool-specific lock-in
Only one tool sees the file because the file uses tool-specific naming or syntax.
**Before**: only a `.cursorrules` file, or only a `CLAUDE.md` with Claude-specific tags.
**After**
```bash
# Primary file uses the open standard
AGENTS.md
# Symlinks for tool-specific discovery
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md .cursorrules
```
Content uses no tool-specific features.
---
## 11. Stale path references
Paths that no longer exist.
**Before**
```markdown
- Tests are in `src/__tests__/` (directory moved 3 months ago)
- Config is in `config/settings.yaml` (renamed to `config.yml`)
- See `docs/ARCHITECTURE.md` for details (file deleted)
```
**After**: verify every path. Prefer runtime discovery:
```markdown
- Tests are co-located: `find src -name '*.test.tsx'`
- Config: `config.yml`
- Architecture: `docs/adr/`
```
---
## 12. Generated content without staleness warning
Including command output without noting it will go stale.
**Before**
```markdown
## Dependencies (from package.json, last updated 2024-01-15)
react: 18.2.0
next: 14.0.4
```
**After**
```markdown
## Dependencies
Check current versions: `cat package.json | jq '.dependencies'`
```
---
## 13. Cross-section duplication
Same command, rule, or fact stated in multiple sections. The most common token waste in AGENTS.md files — each copy looks reasonable in isolation.
**Before** (same commands in 3 sections)
```markdown
## Quick Reference
| Test | `npm run test` |
| Lint | `npm run lint` |
## Verification
npm run test # All tests pass
npm run lint # Clean lint
## Quality Gates
| `npm run test` | vitest run |
| `npm run lint` | ESLint check only |
```
**After** (each fact has exactly one home)
```markdown
## Quick Reference
| Test | `npm run test` |
| Lint | `npm run lint` |
## Verification
After every change, run `npm run test:all` (typecheck + lint + tests).
```
**Detection**: for each CLI command, grep the file. If it appears in two or more H2 sections, it's duplicated. Same for stated rules.
---
## 14. Zero-value sections
A section whose entire content is already covered by the quick reference or another section.
**Before**
```markdown
## Quick Reference
| Components | `npm run docs:inventory` or `ls src/components/ui` |
## Component Inventory <-- adds nothing new
Discover components at runtime:
npm run docs:inventory
ls src/components/ui
```
**After**: delete the zero-value section entirely. If it has one unique fact, fold that fact into the quick reference row.
---
## 15. Unbounded "best practices"
Generic accessibility, generic security, generic performance rules that any modern agent applies by default.
**Before**
```markdown
## Accessibility Requirements
- All interactive components must use proper ARIA
- Keyboard navigation must work
- Focus indicators must be visible
- Screen reader labels must be present
```
**After**: delete. Only keep accessibility rules that are **project-specific**, e.g. "focus ring uses `focus-visible:ring-1` with the project's accent color" or "use Radix UI primitives, not custom ARIA".
references/templates.md
# Canonical templates
Use these verbatim. Fill `{placeholders}` from phase 1 survey. Drop sections marked `[optional]` when they don't apply.
---
## AGENTS.md (canonical, 80–150 lines)
```markdown
# {Project Name}
{One-sentence project description.}
| Item | Value |
|------|-------|
| Stack | {language}, {framework}, {key libraries} |
| Package manager | {npm/pnpm/bun/uv/cargo/...} |
| Build | `{build command}` |
| Test | `{test command}` |
| Lint | `{lint command}` |
| Dev | `{dev server command}` |
## Commands
```bash
{package_manager} install # Install dependencies
{dev_command} # Start dev server
{build_command} # Production build
{test_command} # Run tests
{lint_command} # Lint (check only)
{lint_fix_command} # Lint (auto-fix)
{typecheck_command} # Type check
```
## Project Structure
```
src/
{directory}/ # {purpose}
{directory}/ # {purpose}
tests/ # {test organization}
```
## Code Style
{One real code example from the codebase showing the project's preferred pattern.}
```{language}
{actual code example}
```
- {Rule 1: specific, imperative}
- {Rule 2: specific, imperative}
- {Rule 3: specific, imperative}
## Testing
- Framework: `{test_framework}`
- Runner: `{exact test command with flags}`
- Convention: {test file naming and location}
```{language}
{minimal test example}
```
## Git Workflow
- Branch: `{prefix}/{description}` — prefixes: `feat`, `fix`, `chore`
- Commits: `{format}` — imperative mood, ≤ 72 chars
- {Any PR or review process}
## Forbidden Patterns
| WRONG | CORRECT | Why |
|-------|---------|-----|
| {common mistake 1} | {correct approach} | {brief reason} |
| {common mistake 2} | {correct approach} | {brief reason} |
## Boundaries
- Never {dangerous action 1}
- Never {dangerous action 2}
- Never modify {protected files/dirs} without approval
## Verification
After every change:
1. `{typecheck command}` (zero errors)
2. `{test command}` (all pass)
3. `{lint command}` (clean)
## References
| File | Purpose |
|------|---------|
| `docs/adr/` | Architecture decision records |
| `docs/conventions.md` | Project-specific code conventions |
| `docs/workflow.md` | Full contribution workflow |
| `references/{topic}.md` | {what it contains} |
```
### Section-order rationale
1. Quick reference table — primacy effect, seen first
2. Commands — most frequently consulted
3. Project structure — orientation
4. Code style — daily reference
5. Testing — daily reference
6. Git workflow — per-commit reference
7. Forbidden patterns — high-compliance format
8. Boundaries — critical safety
9. Verification — recency effect, seen last
10. References — the map to deeper docs
### Exclude from AGENTS.md
- Token / color catalogs → `references/tokens.md`
- Component API docs → `references/api.md`
- Architecture rationale → `docs/adr/`
- Exhaustive inventories → runtime commands (`ls`, `find`)
- Default-behavior instructions → delete
- Inline rationale per rule → ADR or delete
---
## ADR (12–20 lines, store in `docs/adr/`)
```markdown
# ADR-{NNN}: {Title}
**Date**: {YYYY-MM-DD}
**Status**: Accepted
## Context
{2–3 sentences: what problem or choice prompted this decision.}
## Decision
{1–2 sentences: what was decided and why.}
## Consequences
- {Positive consequence}
- {Positive consequence}
- {Tradeoff or negative consequence}
```
Don't generate ADRs for obvious choices. Each ADR records a **non-obvious** technical decision a future agent might second-guess or contradict.
---
## docs/conventions.md (50–80 lines)
```markdown
# Conventions
Project-specific conventions for {project_name}. For language-level
standards, see {link to PEP8 / Rust API guidelines / Airbnb / etc.}.
## File Organization
{Where source lives, where tests live, naming patterns.}
## Naming
{Module naming, class/function naming patterns specific to this project.}
## Imports
{Import ordering, absolute vs relative, banned imports.}
## Error Handling
{How errors are handled here: Result types, exceptions, error codes.}
## Code Example
```{language}
{Real code snippet showing the project's preferred pattern. Pull
from an actual file in the codebase, not a hypothetical.}
```
## Patterns to Avoid
| Avoid | Use instead | Why |
|-------|-------------|-----|
| {anti-pattern 1} | {correct approach} | {brief reason} |
| {anti-pattern 2} | {correct approach} | {brief reason} |
```
---
## docs/workflow.md (30–50 lines)
```markdown
# Contribution Workflow
## Branch
```bash
git checkout -b {prefix}/{description}
```
Prefixes: `feature/`, `fix/`, `chore/`.
## Implement
{1–2 sentences: implementation expectations — tests, types, etc.}
## Validate
```bash
{test_command}
{lint_command}
{typecheck_command}
```
All must pass before committing.
## Commit
```
{commit_format}
```
{Commit message conventions: imperative mood, max length, etc.}
## Pull Request
{Where to open, what to include, who reviews.}
```
---
## References table (for the bottom of AGENTS.md)
```markdown
## References
| File | Purpose |
|------|---------|
| `docs/adr/` | Architecture decision records |
| `docs/conventions.md` | Project-specific code conventions |
| `docs/workflow.md` | Full contribution workflow with commands |
| `references/tokens.md` | Design token catalog |
| `references/api.md` | API surface details |
```
Only list rows for docs that actually exist on disk. Verify each path resolves before writing the row.
SKILL.md
---
name: agents-md
description: Audit and refactor a repository's AGENTS.md so an agent can act on it. Use when the user asks to audit AGENTS.md, fix AGENTS.md, set up agent docs, improve agent documentation, refactor for progressive disclosure, or invokes /agents-md. Use when AGENTS.md is missing, bloated past 200 lines, contradictory, or duplicates content elsewhere in the repo. Do not use to edit a single doc that AGENTS.md does not reference.
---
# Agent Docs Readiness
Every line in `AGENTS.md` gets loaded on every task. Bloat steals the budget you need for project-specific rules. Contradictions silently override each other. Default-behavior bullets dilute the rules that actually steer the model.
**Core principle.** Every line in `AGENTS.md` must be project-specific. If a competent model would do the right thing without it, delete it.
The root file is a map. Depth lives in `README.md`, `docs/`, and `references/`.
## Normative language
Use plain imperatives for routine workflow instructions. Reserve `MUST` / `MUST NOT` for hard constraints with clear failure modes, and use `SHOULD` for strong defaults where a deviation can be explained. Do not require every rule to begin with RFC 2119 keywords; keyword inflation hides the rules that actually matter.
## Workflow
### 1. Find contradictions
List each pair. Propose the version to keep — one sentence of reasoning. Ask the user. Never autoresolve.
Contradictions encode a user choice the model cannot see. Autoresolving silently picks a side.
### 2. Identify essentials for the root
Keep in `AGENTS.md` — nothing else:
- One-sentence project description
- Source-of-truth pointers for deeper project overview, architecture, install, and workflow docs
- Package manager — only if it isn't `npm`
- Non-standard build / test / lint / typecheck commands
- Forbidden Patterns table
- Boundaries — `never X` rules
- Verification commands
- References table
### 3. Triage bloat
Flag every instance. Concrete before/after for each pattern lives in `references/anti-patterns.md`.
- **Default-behavior** — "write clean code", "meaningful names", generic ARIA. Delete.
- **Vague qualifiers** — "try to", "ideally", "consider", "might want to". Rewrite imperative.
- **Meta-prefixes** — "You should", "Remember to", "Please". Strip.
- **Cross-section duplication** — same command in 2+ H2 sections. Keep the most-specific home.
- **Hardcoded inventories** — component lists, dependency versions. Replace with `ls` / `find` / runtime command.
- **Inline rationale** — "Use X because A, B, C" per rule. Move rationale to an ADR.
- **Zero-value sections** — entirely covered by another section. Delete.
- **README duplication** — project overview, install, usage, architecture tours, and package/distribution detail already maintained in `README.md`. Keep a one-line identity in `AGENTS.md`, then point to `README.md`.
- **Stale paths** — paths that no longer resolve. Verify, then fix or remove.
### 4. Group the rest
Sort remaining content:
- `README.md` — human-facing project overview, install/usage, package or distribution model, and broad architecture tour
- `docs/adr/` — non-obvious architectural decisions (see Final checks)
- `docs/conventions.md` — project-specific idioms beyond language defaults
- `docs/workflow.md` — branch / commit / PR cycle with exact commands
- `references/<topic>.md` — catalogs (tokens, API surface, icons) and rationale collections
### 5. Propose the file structure
Minimal root `AGENTS.md` with a `References` table at the bottom. Each topic file with its content. Suggested folder layout.
Produce the diff plan. Do not apply edits.
## Skip the restructure when
| Repo state | Reach for |
|---|---|
| `AGENTS.md` missing or under 20 lines | Generate from `references/templates.md` first; audit second. Splitting an empty file produces empty files. |
| Pure boilerplate (no project-specific content) | Fill in stack / commands / structure first. Splitting boilerplate doesn't make it useful. |
| Monorepo with multiple package manifests | Audit root, then recommend per-package `AGENTS.md` for packages with distinct conventions. |
| Already a 100–200 line map with `References` table | Run Final checks only. Do not restructure what is already correct. |
## Final checks
Before producing the plan, every item below must be true.
- **Propose 1–3 ADRs** in `docs/adr/` only when all four hold: (1) hard to reverse, (2) surprising without context, (3) the result of a real trade-off, (4) the stated rationale is technically accurate. Fact-check ecosystem claims ("X requires Y" about frameworks / versions / APIs) before canonizing them into an ADR. Skip obvious choices. Wrong rationales canonized as ADRs poison every future agent run.
- **Write a Forbidden Patterns table** — one row per mistake the project actually makes. Columns: `WRONG`, `CORRECT`, `Why`. No invented examples.
- **List 3–7 Boundaries** — `never X` rules covering the project's actual incident surface. More than seven and the model starts ignoring them.
- **Specify Verification commands** — exact CLI calls to run after every change.
- **Build the References table** at the bottom of `AGENTS.md`. Every row points to a doc that exists on disk.
- **Reference README when it owns orientation.** If `README.md` explains what the repo is, how it is installed, or how users consume it, list it in References instead of duplicating that content.
- **Verify paths on disk** — `test -e <path>` for every path mentioned in `AGENTS.md`. Any miss is a stale link.
- **Replace hardcoded inventories** with `ls`, `find`, or a runtime command. Static lists go stale.
- **Symlink `CLAUDE.md → AGENTS.md`.** Missing: `ln -s AGENTS.md CLAUDE.md`. Regular file: merge any unique content into `AGENTS.md`, then `rm CLAUDE.md && ln -s AGENTS.md CLAUDE.md`. Already a symlink to `AGENTS.md`: skip.
- **Read content, not just structure.** Three concrete passes — generic exhortation does not fire:
1. List every named entity in inventory sections (components, scripts, tokens, deps). Check the list for duplicates.
2. Cross-reference stated tooling with the actual stack: if `Stack` names Vite but `build` runs `tsup`, one of them is wrong — flag it.
3. Fact-check ecosystem claims before treating them as constraints. "X requires Y" — does Y actually require X, in the current version? Wrong rationales pretending to be facts are worse than no rationale.
## Common rationalizations
| Excuse | Reality |
|---|---|
| "This contradiction is obvious — I'll autoresolve it." | Both versions exist because someone disagreed. Ask. |
| "Default-behavior bullets feel safer to keep." | They steal slots from the rules that actually steer the model. Delete. |
| "Let me write the templates first; the user can pick." | Survey before generating. Templates without a survey produce a generic `AGENTS.md`, not this project's. |
| "I'll restructure as I read." | Survey, then plan, then apply. Restructuring while reading produces inconsistent structure. |
| "I'll skip path verification — they look right." | One stale path silently misleads every future agent run. Verify. |
| "Generic accessibility / security / 'clean code' rules are fine to keep." | They are default behavior. Keeping them dilutes the rules that aren't. |
## Verification
Run these on the proposed plan before handing it to the user.
- Re-read the new `AGENTS.md` as if blind to the repo. Can you execute one realistic task using only this file? If no, the file is still under-specified.
- For every CLI command in `AGENTS.md`, grep the file. If it appears in 2+ H2 sections, you duplicated.
- `test -e` every path. Any miss is a stale link.
## References
- `references/anti-patterns.md` — load when step 3 flags a pattern and you need the concrete before/after.
- `references/templates.md` — load when generating a new `AGENTS.md`, ADR, `conventions.md`, or `workflow.md` from scratch.
## Bottom line
```
AGENTS.md root → project-specific rules, verified paths, runtime discovery for inventories
Anything else → docs/ or references/ or deleted
```
If a line could appear in any project's `AGENTS.md`, it does not belong in this one.