Agents Md

• AGENTS.md (~100 lines max) — the map. Injected into every agent context. Pointers only.
• docs/ — the system of record. Deep knowledge lives here, loaded on demand.

Hard rules that are never negotiable:

• AGENTS.md stays under 100 lines of real content
• Every AGENTS.md must have a ## Quick Index TOC table as the first section
• Every AGENTS.md must have a ## Gotchas section — mandatory, no exceptions
• Domain-specific instructions go in <important if="..."> conditional blocks
• If content is > 20 lines and narrow-use, move it to a skill or docs/ — not AGENTS.md
• No directory listings, no formatter rules, no vague instructions
• If the agent can't read it in the repo, it doesn't exist — encode everything as markdown
• In monorepos, nearest AGENTS.md to the edited files wins; child scope can override parent scope

Gotchas section is always mandatory. Every AGENTS.md must include it. It is the section where known failure patterns, workarounds, and anti-patterns are captured so the agent never repeats them.

Practice anchors to enforce:

• Keep AGENTS.md concise and task-focused so high-signal instructions survive system relevance filtering.
• Use narrow <important if="..."> conditions only for situational instructions; keep core project facts always visible.
• Treat AGENTS.md as living documentation: update after failures, and keep instructions mechanically verifiable via commands, linters, and CI checks.

/new-agent-md

Purpose: Generate a fresh AGENTS.md from scratch for a new project using a PRD as the source of truth. This is the first-time setup path.

Step 1 — Ingest the PRD

Ask the user to paste the PRD or point to its location. Read it fully before asking any questions.

Step 2 — Sequential Confirmation

After reading the PRD, ask questions one at a time. Wait for the user to respond before moving to the next. Do not batch them. The goal is a natural back-and-forth that catches mismatches early before generating anything.

Ask in this order, one question per turn:

Q1 — Stack State what you inferred from the PRD: "I'm reading [X framework, Y language, Z database] — does that match your actual stack, or anything to correct?" → Wait for response. Update your understanding before continuing.

Q2 — Package manager + monorepo "Package manager looks like [npm / pnpm / yarn / bun] and [monorepo / single package]. Right?" → Wait for response.

Q3 — Test framework "Test setup — I'm seeing [Jest / Vitest / Playwright / none detected]. Correct, or what are you using?" → Wait for response.

Q4 — Primary domains "I'd create conditional blocks for: [list inferred domains]. Anything to add, remove, or rename?" → Wait for response.

Q5 — React "Is this a React project? This determines whether I include the useEffect gotcha as a mandatory entry." → Wait for response. If yes, seed it in the AGENTS.md ## Gotchas section.

Q6 — Hard rules "Any hard rules I should encode? Think: banned libraries, auth patterns, naming conventions, things agents always get wrong on this stack." → Wait for response. If none, move on.

Q7 — PRD constraints vs goals "Last one — anything in the PRD I should treat as a firm architectural constraint rather than a product goal? (e.g. 'must use X', 'never Y')" → Wait for response. Then proceed to generation.

Do not generate AGENTS.md until all seven questions are answered.

Step 3 — Generate the AGENTS.md

Apply this exact structure. No deviation.

# AGENTS.md

## Quick Index
| Document | Purpose | When to Read |
|---|---|---|
| [ARCHITECTURE.md](./ARCHITECTURE.md) | Domain map, package layers, dependency rules | Before designing anything |
| [docs/DESIGN.md](./docs/DESIGN.md) | UI/UX patterns, component conventions | Frontend work |
| [docs/SECURITY.md](./docs/SECURITY.md) | Auth, validation, secrets | Any auth or data boundary work |
| [docs/QUALITY_SCORE.md](./docs/QUALITY_SCORE.md) | Per-domain quality grades | Before opening a PR |
| [docs/exec-plans/active/](./docs/exec-plans/active/) | In-progress execution plans | Picking up ongoing work |
| [Gotchas](#gotchas) | Known failures, workarounds, anti-patterns | Always — read before starting |

---

## Project
[2 sentences: what the product is, primary stack, deployment target]

## Key Commands
- Install: [command]
- Dev: [command]
- Test: [command]
- Typecheck: [command]
- Lint: [command]

## Hard Rules
- [Rule 1 — specific and mechanical, not vague]
- [Rule 2]
- [Rule 3 — max 5-6 rules total. If you have more, they're not all hard rules.]

---

## Gotchas
Keep this section in AGENTS.md and append entries over time.

[Seed this section with the React entry if applicable, plus any gotchas clearly implied by the PRD or stack.]

---

<important if="you are writing or modifying tests">

## Testing
[3-6 precise rules about test setup, helpers, mocking patterns for this repo]

</important>

<important if="you are building or modifying API endpoints">

## API Conventions
[3-6 precise rules about routing, auth middleware, error shapes, validation]

</important>

<important if="you are working on database migrations or schema changes">

## Database
[3-5 rules: migration tool, how to run, when to flag for human review]

</important>

<important if="you are creating a commit or pull request">

## PRs
- Title format: [scope] Short imperative description
- Run [lint + test command] before committing
- Update QUALITY_SCORE.md if you changed a domain

</important>

Step 4 — Populate the Gotchas Section

Always include a ## Gotchas section in AGENTS.md. Never leave it empty.

See the /gotchas section below for the entry format and seeding rules.

Step 5 — Generate the docs/ Skeleton

Create stub files for each doc in the Quick Index (if they don't exist). A stub is just a title and 2-3 placeholder headings — enough that the agent can navigate the structure.

/improve-agents-md

Purpose: Sync an existing AGENTS.md to the current state of the codebase and PRD. Use this when the codebase has evolved, new patterns have emerged, or the PRD has changed.

Step 1 — Spawn a Codebase Summary Subagent

Dispatch a subagent to scan the codebase and return a condensed summary. The subagent should NOT return raw file contents — only a structured summary. This protects the parent context window.

Subagent prompt template:

You are a codebase analyst. Your job is to produce a concise structured summary of this repository
for the purpose of updating its AGENTS.md file.

Return ONLY the following — nothing else:

## Stack
[Language, framework, package manager, test runner, linter, DB]

## Key Entry Points
[Max 5 files/directories that are the core of the application]

## Domains
[List of the primary business domains you can identify from the code]

## Patterns in Use
[Observed patterns: auth approach, validation library, error handling style, logging approach]

## Drift Detected
[Anything in the current AGENTS.md that appears stale or no longer matches the code]

## Suggested New Conditional Blocks
[New domain-specific patterns that warrant a new `<important if>` block]

Cite sources as filepath:line — do not reproduce file contents.

Step 2 — Read the Current PRD

Read the current PRD (ask the user for location if not obvious). Identify:

• What has changed since the last AGENTS.md update?
• What new features, domains, or constraints exist that aren't reflected?
• What is in the current AGENTS.md that is no longer accurate?

Step 3 — Diff and Present Changes

Before rewriting, show the user a structured diff of proposed changes:

## Proposed AGENTS.md Changes

### Remove (stale or no longer accurate)
- [item]: reason

### Update (content has changed)
- [item]: what changed

### Add (new patterns or domains)
- [item]: source (codebase / PRD)

### Gotchas Section Changes
- [any new gotchas identified during the scan]

Proceed? (yes / modify first)

Do not rewrite until the user confirms.

Step 4 — Rewrite with Strict Rules Applied

Apply the same structure as /new-agent-md. Hard constraints:

• AGENTS.md stays under 100 lines
• TOC Quick Index updated to reflect current docs/
• Gotchas section preserved and updated
• All conditional blocks reviewed — remove ones that no longer apply
• No content that belongs in docs/ gets added inline

/gotchas

Purpose: Capture a known agent failure pattern in the AGENTS.md ## Gotchas section after a work session. Also used to seed the section on project creation.

When to Trigger

• After any session where the agent repeated a mistake more than once
• After a session where a workaround was discovered
• On first run of /new-agent-md (seed with mandatory entries)
• Anytime the user says "Claude kept doing X wrong" or "I had to keep correcting"

Step 1 — Identify the Gotcha

Ask the user (or infer from context):

What did the agent keep getting wrong?
- What was the incorrect behavior?
- What is the correct behavior?
- Is there a one-line rule that would prevent it?

Step 2 — Write the Gotcha Entry

Each ## Gotchas entry follows this format:

### [Short name for the failure pattern]
**Symptom:** [What the agent did wrong]
**Correct behavior:** [What it should do instead]
**Rule:** [One precise, actionable instruction]

Step 3 — Append to ## Gotchas

Add the entry to AGENTS.md under ## Gotchas. Do not rewrite the whole file — append only.

Gotchas Section Structure

## Gotchas lives inside AGENTS.md and is listed in Quick Index.

# AGENTS.md

...

---

## Gotchas

Known agent failure patterns, workarounds, and anti-patterns for this repository.

[Entries that apply regardless of what task is being done]

---

### React

<important if="you are writing or modifying React components">

### Do not use useEffect()
**Symptom:** Agent reaches for useEffect() to sync state, fetch data, or respond to prop changes.
**Correct behavior:** Use event handlers, React Query / SWR for data fetching, derived state for
computed values, and refs for imperative DOM access. useEffect() is almost never the right tool
and introduces subtle bugs and unnecessary re-renders.
**Rule:** Never use useEffect(). If you think you need it, stop and find another pattern.

</important>

---

### [Domain-specific gotchas as they accumulate]

The useEffect rule is mandatory for any React project. It is seeded automatically by /new-agent-md when React is detected and by /gotchas if React is in the stack.

docs/ Knowledge Store Layout

AGENTS.md                        <- the map (~100 lines)
ARCHITECTURE.md                  <- top-level domain + package map
docs/
├── design-docs/
│   ├── index.md
│   ├── core-beliefs.md
│   └── [feature].md
├── exec-plans/
│   ├── active/                  <- in-progress plans (versioned markdown)
│   ├── completed/               <- decision history
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md             <- auto-generated, always fresh
├── product-specs/
│   ├── index.md
│   └── [feature].md
├── references/
│   └── [library]-llms.txt       <- condensed API docs for key dependencies
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md             <- per-domain quality grades
├── RELIABILITY.md
└── SECURITY.md

Key principle: If the agent can't read it in the repo, it doesn't exist. Encode everything — architectural decisions, key Slack threads, design rationale — as markdown in the repo.

Mechanical Enforcement

Custom Linters with Agent-Facing Error Messages

Write lint error messages specifically to inject remediation instructions into agent context:

Error: console.log() found in application code.
Remediation: Replace with structured logger. Import from packages/logger.
See docs/RELIABILITY.md#logging for the logging contract.

CI Validation of the Knowledge Base

• All docs linked from AGENTS.md exist
• QUALITY_SCORE.md domains present and dated
• exec-plans/active/ entries have recent progress log entries
• Cross-links in docs resolve

Recurring Doc-Gardening Agent

Background agent on a regular cadence:

• Scans for docs that don't reflect current code behavior
• Updates quality grades
• Opens targeted fix-up PRs (most automerge in under a minute)

What NOT to Include in AGENTS.md

Reference Files

• references/examples.md — Annotated good and bad real-world AGENTS.md files with anti-patterns explained