mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-21 04:37:48 +08:00
refactor(project-context): per-section admission rules, two-tier guide
Revisions from two end-to-end trials plus review: - Replace the global non-derivable test with per-section admission rules: brevity (orientation), authority (policy), universal need verified by execution (commands, verification), wrong-default-assumption (conventions), localization value (pointers), observed failure only (pitfalls) - Two-tier output: AGENTS.md (orientation + policy + pointer) for every session, AGENTS-dev.md for coding sessions; single file when tiny - Pitfalls can never be nominated by scans: sources are recorded lessons, maintainer recall, session evidence, and the writing session's own caught mistakes; retirement only when the guarded thing is gone or the human says so, since a working rule erases its own evidence - Interview ergonomics: recall questions, never review lists; testimony the repo contradicts is surfaced with evidence, never written or dropped - Trial-driven fixes: guide-to-filesystem link check, mutating-command go-ahead as the interview's first question, plain-English rewrite throughout
This commit is contained in:
Alex Verkhovsky
@@ -5,11 +5,11 @@ description: 'Write and maintain a project''s agent guide (AGENTS.md): verified
|
||||
|
||||
# Overview
|
||||
|
||||
The product is a good `AGENTS.md` — the short guide an agent loads before every task in this project. The evidence is blunt: generated documentation volume makes agents worse, while a short prescriptive guide of verified, non-derivable facts makes them better. We already know what such a guide contains — the section plan in `references/guide-contract.md` is fixed, and the job is to fill those sections with verified evidence, not to explore the repository for interesting facts. The repository is where claims get *verified*; it is not where the knowledge comes from. The irreplaceable content lives in executable configuration, targeted history, observed agent mistakes, and human heads — in that order of increasing irreplaceability.
|
||||
The product is a good agent guide — a short `AGENTS.md` every session loads, plus an `AGENTS-dev.md` that coding sessions read. Generated documentation makes agents worse; what helps is a short guide where every line passed its section's admission rule and its facts are verified. The section plan in `references/guide-contract.md` is fixed: the job is to fill it with verified evidence, not to explore the repository for interesting facts. The repository is where claims get verified; the knowledge itself comes from configuration, history, observed agent mistakes, and the people who maintain the project.
|
||||
|
||||
Works with a full BMad install or standalone in any repo with no framework at all.
|
||||
Works with a full BMad install or standalone in any repo.
|
||||
|
||||
**Args:** intent (`bootstrap` | `refresh` | `record` | `audit`); `--auto` for headless; a scope path to bound the run; extra source paths or URLs. Supplied values are used directly and skip their questions.
|
||||
**Args:** intent (`bootstrap` | `refresh` | `record` | `audit`); `--auto` for headless; a scope path to limit the run; extra source paths or URLs. Supplied values are used directly and skip their questions.
|
||||
|
||||
## Resolution rules
|
||||
|
||||
@@ -20,31 +20,31 @@ Works with a full BMad install or standalone in any repo with no framework at al
|
||||
|
||||
1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. Execute `{workflow.activation_steps_prepend}`; treat `{workflow.persistent_facts}` entries as standing context (`file:` = paths/globs to load, others verbatim).
|
||||
2. Config: if `{project-root}/_bmad` exists, `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` and read `{user_name}`, `{communication_language}` (use it every turn), `{output_folder}`. Standalone: skip, and default `{output_folder}` to `_bmad-output`.
|
||||
3. Read the active steering set: root and nested `AGENTS.md`, `CLAUDE.md` and other agent files, and the ledger at `{output_folder}/project-context-ledger.md` if present. These are the current instructions agents actually receive; every run starts from them.
|
||||
4. Detect intent and greet `{user_name}`: **bootstrap** (no useful guide yet, or the user wants a rewrite — the default), **refresh** (guide and ledger exist; reconcile with reality), **record** (the user reports an observed agent mistake, lesson, or new rule), **audit** (re-verify and prune). For interactive bootstrap/refresh, ask one opening question: any sources outside the repo (org handbooks, wiki exports, planning docs, MCP knowledgebases) and any area to focus on — note paths for the evidence sweep, don't read them now. Fold `{workflow.external_sources}` into the same list. Execute `{workflow.activation_steps_append}`.
|
||||
3. Read the existing agent instruction files — root and nested `AGENTS.md`, `CLAUDE.md` and similar — and the ledger at `{output_folder}/project-context-ledger.md` if present.
|
||||
4. Detect intent and greet `{user_name}`: **bootstrap** (no ledger — this skill's first run here, whether the repo has no guide, a poor one, or a good handwritten one to build on — the default), **refresh** (ledger exists; update the guide to match the repo), **record** (the user reports an observed agent mistake, lesson, or new rule), **audit** (re-verify and prune). For interactive bootstrap/refresh, ask one opening question: any sources outside the repo (org handbooks, wikis, planning docs, MCP knowledgebases) and any area to focus on — note paths for later, don't read them yet. Add `{workflow.external_sources}` entries to the same list. Execute `{workflow.activation_steps_append}`.
|
||||
|
||||
## Bootstrap and Refresh
|
||||
|
||||
Discovery is progressive — each step narrows the next; broad scanning before the guide is planned is the failure mode this skill replaces. Load `references/guide-contract.md` and `references/evidence.md` before step 1.
|
||||
Load `references/guide-contract.md` and `references/evidence.md` before step 1. The order matters: plan before scanning, select before writing.
|
||||
|
||||
1. **Plan the guide.** Instantiate the contract's section plan for this repo, and list per section the evidence it needs. In a repo with a handwritten `AGENTS.md`, that file is the baseline being improved, never raw material to discard: map its content into the plan first.
|
||||
2. **Gather evidence.** Fan out parallel subagents, one per evidence lane in `references/evidence.md` — lanes are editorial jobs, not file categories. Each returns ledger-shaped candidates: claim, evidence paths, target section, what behavior it changes, verification status. Corpus rules in the reference bind every scanner.
|
||||
3. **Verify mechanically.** Run the commands the guide will state (read-only commands freely; anything mutating needs the user's go-ahead) and path-check every claim that names a file. A claim verified by execution or path-check is *verified* — never ask the user to confirm it.
|
||||
4. **Interview.** Only what no scan can reach: org requirements, frozen areas, domain concepts, intent, priorities — and always "what do agents keep getting wrong here?". Rules and caps in `references/evidence.md`. Log every answer and rejection to the ledger as it lands.
|
||||
5. **Compose.** Selection and grouping happen before writing: decide what each section says from the accepted candidates, then write the guide as one coherent document under the contract. Copy-editing is the last step, never the curation mechanism. Where an instruction outside the guide contradicts it (a stale `CLAUDE.md` line, a retired command still recommended), propose the concrete fix to that file — surfacing the conflict and leaving both instructions live is a defect.
|
||||
6. **Coverage check and close.** Walk the ledger: every accepted candidate traces to a guide line, a scoped guide, or a rejection with a reason — an untraceable candidate means the check failed. Confirm the guide meets the contract's budget. Tell the user what was written, what was rejected and why, and — whenever `AGENTS.md` carries the guide — say plainly: if your harness doesn't auto-load `AGENTS.md`, make the file it does load pull this one in (e.g. a `CLAUDE.md` containing `@AGENTS.md`).
|
||||
1. **Plan the guide.** Instantiate the contract's section plan for this repo and list, per section, the evidence it needs. A handwritten `AGENTS.md` is the baseline being improved, never raw material to discard: map its content into the plan first.
|
||||
2. **Gather evidence.** Launch parallel subagents, one per evidence source in `references/evidence.md` (sources 1–5; the maintainer, source 6, is step 4). Each returns candidates for the ledger: claim, evidence paths, target section, what behavior it changes, verification status. The scan-scope rules in that file bind every scanner.
|
||||
3. **Verify.** Run the commands the guide will state and path-check every claim that names a file. Read-only commands run freely; a mutating command (a build, a test suite) waits for its go-ahead, asked as the interview's first question. A claim verified by execution or path-check is verified — never ask the user to confirm it.
|
||||
4. **Interview.** Only what no scan can reach: org requirements, frozen areas, domain concepts, intent — and always "what do agents keep getting wrong here?". Rules in `references/evidence.md`. Write every answer and rejection to the ledger as it arrives.
|
||||
5. **Compose.** Decide what each section says from the accepted candidates, then write the guide as one coherent document under the contract. Copy-editing comes last; it is not how selection happens. Where an instruction outside the guide contradicts it (a stale `CLAUDE.md` line, a retired command still recommended), propose the concrete fix to that file — leaving two live contradictory instructions is a defect.
|
||||
6. **Coverage check and close.** Go through the ledger: every accepted candidate must trace to a guide line, a scoped guide, or a rejection with a reason. Check every repo-relative path the guide names against the filesystem; fix dead links before closing. Confirm the guide fits the contract's budget. Tell the user what was written, what was rejected and why, and — whenever `AGENTS.md` carries the guide — that a harness which doesn't auto-load `AGENTS.md` needs its own file to pull it in (e.g. a `CLAUDE.md` containing `@AGENTS.md`).
|
||||
|
||||
**Refresh** runs the same steps against the existing guide and ledger: never re-ask what a prior run settled, re-verify the commands and paths the guide states, and update or remove lines whose evidence is gone. The guide grows only when new evidence earns it.
|
||||
**Refresh:** same steps against the existing guide and ledger. Never re-ask what a prior run settled; re-verify the commands and paths the guide states; update or remove lines whose evidence is gone. The guide grows only when new evidence justifies it.
|
||||
|
||||
**Greenfield:** same pipeline seeded from a spec or planning document (or pure interview). Commands that don't exist yet are written from the decided stack and marked for verification on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — deserves the `bmad-architecture` skill rather than a call made here.
|
||||
**Greenfield:** same process, based on a spec or planning document (or interview alone). Commands that don't exist yet are written from the decided stack and marked for verification on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — deserves the `bmad-architecture` skill rather than a call made here.
|
||||
|
||||
## Record
|
||||
|
||||
The cheapest and highest-value intent: capture one observed agent mistake or lesson at the moment it happens. Get the task, the mistake, the correction, and the evidence (a session, a review comment, the user's testimony); log it to the ledger. First occurrence makes a candidate; a recurring or costly mistake earns a line in the guide's pitfalls section now — write it, show the diff. If the mistake is mechanically preventable, say so and propose the hook, lint, or CI check instead: enforcement beats prose.
|
||||
Record one observed agent mistake or lesson at the moment it happens. Get the task, the mistake, the correction, and the evidence (a session, a review comment, the user's testimony); log it to the ledger. A first occurrence is a candidate; a recurring or costly mistake gets a line in the guide's pitfalls section now — write it, show the diff. If the mistake is mechanically preventable, propose the hook, lint, or CI check instead: enforcement beats prose.
|
||||
|
||||
## Audit
|
||||
|
||||
Re-verify and shrink: run every command the guide states, path-check every named file, apply the contract's pruning test to every line, and check for contradictions between the guide and other active steering files. Lines that fail move to a scoped guide, get fixed, or die — present proposed deletions for confirmation (interactive) before removing. Audit ends with the guide smaller or equal, never larger.
|
||||
Run every command the guide states, path-check every named file, apply the contract's pruning test to every line, and check for contradictions with other agent instruction files. Lines that fail move to a scoped guide, get fixed, or are deleted — present proposed deletions for confirmation (interactive) before removing. A pitfall or policy line is deleted only when the thing it guards is gone or the user retires it; absence of recent failures is never grounds. Audit ends with the guide smaller or equal, never larger.
|
||||
|
||||
## Modes
|
||||
|
||||
@@ -52,10 +52,10 @@ Interactive is the default. **Auto mode** (headless, or on request) never asks:
|
||||
|
||||
```json
|
||||
{"status": "complete", "intent": "bootstrap", "guide": "AGENTS.md",
|
||||
"scoped_guides": ["src/billing/AGENTS.md"],
|
||||
"dev_guide": "AGENTS-dev.md", "scoped_guides": ["src/billing/AGENTS.md"],
|
||||
"ledger": "_bmad-output/project-context-ledger.md"}
|
||||
```
|
||||
|
||||
## Finalize
|
||||
|
||||
Confirm the ledger reflects the run — every candidate dispositioned, every interview answer captured — and run `{workflow.on_complete}` if non-empty.
|
||||
Confirm the ledger reflects the run — every candidate has a disposition, every interview answer is recorded — and run `{workflow.on_complete}` if non-empty.
|
||||
|
||||
@@ -1,27 +1,27 @@
|
||||
# Evidence
|
||||
|
||||
Where guide content comes from, how it is verified, and how the run is recorded. True and useful are different properties: verification establishes truth; only a section's editorial job establishes usefulness. A verified fact with no section that needs it is rejected, with the reason in the ledger.
|
||||
Where guide content comes from, how it is verified, and how the run is recorded. Verification establishes that a claim is true; a claim is useful only if one of the guide's sections needs it. A verified fact no section needs is rejected, with the reason in the ledger.
|
||||
|
||||
## Channels
|
||||
## Sources
|
||||
|
||||
In increasing order of irreplaceability — later channels hold what earlier ones cannot:
|
||||
Sources 1–5 are scanner work; source 6 is the interview. Later sources hold what earlier ones cannot.
|
||||
|
||||
1. **Active steering files** — root and nested `AGENTS.md`, `CLAUDE.md`, editor rule files. What agents are told today: the baseline, plus conflicts and staleness to fix.
|
||||
2. **Executable configuration and CI** — manifests, lockfiles, workflow files, hooks, Makefiles, linter configs. The commands, gates, and enforcement points. The highest-yield scan there is; most of Commands, Verification, and Policy comes from here and gets verified by execution.
|
||||
3. **Tracked source** — for boundaries (vendored, generated, frozen areas), conventions that differ from defaults, and entry points. This channel answers questions the section plan already asked; it is never mined for "interesting facts", because a fact's novelty says nothing about whether any agent needs it.
|
||||
4. **Git history** — targeted, never wholesale: a surprising constraint found in the current state → `git blame` its introduction → `git show` the change → `git log -S`/`-G` for prior attempts and reversions → verify the reason still holds against the present tree. Commit messages are evidence of past intent, not current truth.
|
||||
5. **Agent session logs and review corrections** — when available or pointed at: the only source that can establish *observed* agent mistakes. Extract structure, never transcripts: task, mistake, correction, consequence, whether an instruction could have prevented it, occurrence count, source sessions. One occurrence is a candidate; recurrence makes a pitfall line. Filter incidental noise (tool outages, typos), and route mechanically-preventable mistakes to hooks/lint/CI proposals instead of prose.
|
||||
6. **The human** — org requirements, domain concepts, frozen areas, intent, priorities, and mistakes they've watched agents make. The only source for these; no scan substitutes.
|
||||
1. **Existing recorded instructions and lessons** — root and nested `AGENTS.md`, `CLAUDE.md`, editor rule files, and lessons written anywhere nearby (notes files, warnings in READMEs). What agents are told today: the baseline, plus conflicts and stale claims to fix. Recorded lessons are standing maintainer testimony — kept by default, challenged only with evidence that a referent is gone or wrong.
|
||||
2. **Executable configuration and CI** — manifests, lockfiles, workflow files, hooks, Makefiles, linter configs. Most of Commands, Verification, and Policy comes from here, verified by execution.
|
||||
3. **Tracked source** — boundaries (vendored, generated, frozen), conventions that differ from defaults, entry points. Scanned to answer the section plan's questions, never for novelty: an interesting fact no agent needs is noise, and a trap-looking fact is at most an interview question, never a pitfall line.
|
||||
4. **Git history** — targeted, never wholesale: when the current state contains a surprising constraint, find the change that introduced it and any reverted attempts to remove it, then check the reason still holds today. Commit messages are past intent, not current truth.
|
||||
5. **Agent session logs and review corrections** — when available or pointed at: the only source of *observed* agent mistakes. Extract structure, never transcripts: task, mistake, correction, consequence, occurrence count, source sessions. One occurrence is a candidate; recurrence makes a pitfall line. Ignore one-off noise (tool outages, typos); route mechanically preventable mistakes to a proposed hook, lint, or CI check instead of prose.
|
||||
6. **The human** — org requirements, domain concepts, frozen areas, intent, priorities, and mistakes they've watched agents make. No scan substitutes.
|
||||
|
||||
External sources the user names (org handbooks, wikis, prior architecture docs, MCP knowledgebases) join at rank 3: mined for candidates, untrusted until verified against the repo or confirmed by the user.
|
||||
Documents the user names from outside the repo (org handbooks, wikis, prior architecture docs, MCP knowledgebases) are treated like source 3: scanned for candidates, untrusted until verified against the repo or confirmed by the user.
|
||||
|
||||
## Corpus rules — binding on every scanner
|
||||
## Scan scope — binding on every scanner
|
||||
|
||||
The corpus is tracked files (`git ls-files`); dependency, vendored, generated, build-output, and cache directories are out unless a specific claim requires looking inside one, and then the scanner states why. Scanners return candidates with evidence; they never decide what gets written.
|
||||
Scanners read tracked files (`git ls-files`). Dependency, vendored, generated, build-output, and cache directories are out unless a specific claim requires looking inside one, and then the scanner states why. Scanners return candidates with evidence; they never decide what gets written.
|
||||
|
||||
## The ledger
|
||||
|
||||
`{output_folder}/project-context-ledger.md` — one plain markdown file, the skill's memory across runs. One block per candidate:
|
||||
`{output_folder}/project-context-ledger.md` — one plain markdown file, this skill's memory across runs. One block per candidate:
|
||||
|
||||
```markdown
|
||||
## <short claim>
|
||||
@@ -32,12 +32,15 @@ The corpus is tracked files (`git ls-files`); dependency, vendored, generated, b
|
||||
- disposition: guide | scoped:<path> | rejected — <reason> | pending
|
||||
```
|
||||
|
||||
Interview answers, rejections (with reasons), conflicts found in other steering files, and auto-mode assumptions all land here the moment they happen — never batched for session end. Refresh and audit read it first and never re-litigate a recorded disposition unless its evidence changed. The ledger is working memory, not context: agents never load it, and nothing in it counts against the guide's budget.
|
||||
Interview answers, rejections with reasons, conflicts found in other instruction files, and auto-mode assumptions are all written here the moment they happen. Refresh and audit read the ledger first and don't revisit a recorded disposition unless its evidence changed. Agents never load the ledger; nothing in it counts against the guide's budget.
|
||||
|
||||
## Interview rules
|
||||
|
||||
- **Never ask what a scan could answer.** A claim verified by execution or path-check proceeds as verified; asking the user to confirm it is a defect.
|
||||
- Chunked rounds, eight questions maximum, fewest possible. Open questions over confirmations: "what do agents keep getting wrong here?", "what would a new engineer be told on day one that's written nowhere?", "what must never be touched?".
|
||||
- An unverifiable claim from docs or an external source is surfaced as "the docs say X — still true?", never stated as fact.
|
||||
- Before writing, one closing ask: name in a line what will be captured and ask what's missing — a frozen area, an org rule, a recurring mistake. This class of material is unrecoverable by any later scan.
|
||||
- A round that yields nothing new is the signal to write, not to invent another round. Out-of-scope material the user volunteers is captured in the ledger, never deflected.
|
||||
- **Ask recall questions, never review lists.** "What do agents keep getting wrong?" works because the maintainer's memory has already selected what mattered. Never hand the human a selection problem a scan created.
|
||||
- A mistake this session itself made and caught while reading or verifying the repo is an observed agent failure (sample of one) — worth offering as a question.
|
||||
- Ask in batches of at most eight questions; fewer is better. Prefer open questions ("what do agents keep getting wrong here?") over confirmations.
|
||||
- An unverifiable claim from docs or an outside document is asked as "the docs say X — still true?", never stated as fact.
|
||||
- When the repo contradicts the user's own testimony, show the evidence and ask — never write the claim as given, never drop it silently. Either the claim or the reading of the evidence gets corrected, and the outcome is recorded in the ledger.
|
||||
- Before writing, one closing question: say in a line what the guide will contain and ask what's missing — a frozen area, an org rule, a recurring mistake. This material is unrecoverable by any later scan.
|
||||
- A batch that yields nothing new means it is time to write, not to ask more. Off-topic information the user offers is recorded in the ledger, never ignored.
|
||||
|
||||
@@ -1,40 +1,46 @@
|
||||
# Guide Contract
|
||||
|
||||
The guide is `AGENTS.md` at the repo root — loaded into every agent session, the highest-cost real estate this skill manages. Every line is paid for in every future task. This contract governs every write to it, in any intent or mode.
|
||||
The guide is the project's agent instructions, written as two files at the repo root:
|
||||
|
||||
- **`AGENTS.md`** — loaded by every session, whatever its kind: Orientation, Policy, and one closing pointer line: "Editing code? Read `AGENTS-dev.md` first."
|
||||
- **`AGENTS-dev.md`** — read via that pointer by sessions that will touch code: Commands, Verification, Conventions, Where things are, Known pitfalls. Planning and review sessions never pay for it.
|
||||
|
||||
When the whole guide fits in about 20 instructions, write a single `AGENTS.md` instead — the extra hop isn't worth it. Every line in either file has a recurring cost; this contract governs every write.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **Instruction budget: ~150–200 instructions across all always-loaded content, a ceiling not a target.** Instruction-following measurably decays past this range. Count instructions, not lines — one line carrying three rules is three instructions, and whatever `CLAUDE.md` or other always-loaded files add counts against the same ceiling. When the budget is threatened, the weakest line moves to a scoped guide or a linked doc, or dies; the budget is never raised.
|
||||
- **Priority ordering.** Most load-bearing rules first — the rules whose violation costs the most. A reader who stops halfway got the half that matters most.
|
||||
- **The pruning test.** *Would removing this line change agent behavior?* If no, the line is deleted. Applied to every line at every write.
|
||||
- **The inclusion test.** A line earns its place only by being **non-derivable** (the agent cannot learn it from the code in reasonable time) and **behavior-changing** (an agent without it does something wrong). Verified is necessary but not sufficient — a perfectly true fact that changes nothing is still noise.
|
||||
- **Instruction budget: ~150–200 instructions across everything a coding session loads — a ceiling, not a target.** Instruction-following degrades past this range. Count instructions, not lines (one line carrying three rules is three instructions), and count what `CLAUDE.md` or other always-loaded files add. When the budget is exceeded, the weakest lines move behind links or are deleted; the budget is never raised.
|
||||
- **Priority order.** Rules whose violation costs the most come first, so a reader who stops halfway got the half that matters most.
|
||||
- **The pruning test.** *Would removing this line change agent behavior?* If no, delete it. Applied to every line at every write.
|
||||
|
||||
## Section plan
|
||||
## Sections and what admits a line
|
||||
|
||||
The default plan; rename sections to fit the project, omit sections that would be empty, never pad one to look complete. Each section is an editorial job, and evidence is gathered *for* it — not sorted into it after the fact.
|
||||
Each section has its own admission rule. There is no global "non-derivable" test: some sections admit derivable content on purpose, and no section admits content merely for being true.
|
||||
|
||||
1. **Orientation** — two to four sentences: what this project is, the stack, where planning, tickets, PRs, and deeper docs live. Under 100 tokens; it orients, it does not tour.
|
||||
2. **Commands** — build, test (including a single test), lint, run: the exact invocation with flags, plus warnings where an operation is expensive ("the full suite is slow — run the single file while iterating") or where the obvious guess fails.
|
||||
3. **Verification** — what must pass before commit and push, stated as the exact commands CI runs.
|
||||
4. **Policy and safety** — branch rules, protected and frozen paths, generated files never edited by hand, secrets handling, what must never be done.
|
||||
5. **Conventions that differ from defaults** — only the divergences an agent following ecosystem norms would get wrong. Each with its enforcement point or source file linked.
|
||||
6. **Where things are** — subsystem → entry-point pointers, and "working on X? read Y first" pointers into deeper docs. This is the progressive-disclosure layer: depth lives behind links, never inline.
|
||||
7. **Known pitfalls** — recurring agent mistakes with their mitigations. Only with evidence (observed sessions, review corrections, or maintainer testimony); a pitfall nobody has hit is a guess.
|
||||
1. **Orientation** (`AGENTS.md`) — three or four sentences: what this project is, the stack, where planning, tickets, PRs, and deeper docs live. No admission test beyond brevity.
|
||||
2. **Policy and safety** (`AGENTS.md`) — admitted by **authority**: what the org and the maintainers require and the code cannot express — branch rules, protected and frozen paths, generated files, secrets, what must never be done.
|
||||
3. **Commands** (`AGENTS-dev.md`) — admitted by **universal need, verified by execution**: build, test (including a single test), lint, run — exact invocations with flags, plus warnings where an operation is expensive or the obvious guess fails. Derivability is no objection: rediscovery is paid at the start of every session, and a derived command is a guess — both trials found repos where the obvious guess is wrong.
|
||||
4. **Verification** (`AGENTS-dev.md`) — same rule: what must pass before commit and push, as the exact commands CI runs.
|
||||
5. **Conventions that differ from defaults** (`AGENTS-dev.md`) — admitted when **the agent's default assumption is wrong**: an agent writing new code follows ecosystem norms unless told otherwise. Each line links its enforcement point or source file. Not admitted for being unusual, intricate, or interesting — a fact nobody would get wrong by default is not a convention line.
|
||||
6. **Where things are** (`AGENTS-dev.md`) — admitted by **localization value**: entry points where work actually lands, and "working on X? read Y first" pointers. Earned per pointer, never exhaustive. Details go behind links, never inline.
|
||||
7. **Known pitfalls** (`AGENTS-dev.md`) — admitted by **observed failure only**: a lesson already recorded in the repo's instruction files or notes, the maintainer's recollection, session-log evidence, or a mistake the writing session itself made and caught while working. A scan cannot nominate a pitfall: the repo yields hundreds of trap-looking facts and no property of the fact separates the few that cause real mistakes — that signal exists only in observed behavior. A surprising fact from scanning becomes, at most, an interview question ("do agents actually trip on this?"). Apparent derivability is irrelevant here in both directions: most working pitfall rules restate something readable, because agents misread it anyway.
|
||||
|
||||
**Retiring pitfall and policy lines:** a line retires only when the thing it guards is gone (removed, or now mechanically enforced) or the human retires it. Absence of recent failures is never grounds — a working rule erases its own evidence, and half the value of the guide is failures that no longer happen.
|
||||
|
||||
## What never enters
|
||||
|
||||
| Excluded | Why |
|
||||
|---|---|
|
||||
| Repo overviews, directory trees, tech-stack lists | Measured zero benefit at real cost; agents derive structure fresh in seconds and stored maps rot |
|
||||
| Anything readable from the code | A paraphrase is a second copy that drifts while the original stays true |
|
||||
| Repo overviews, directory trees, tech-stack lists | No measured benefit; agents derive structure fresh, and stored copies drift |
|
||||
| Facts included for being interesting or unusual | Interest is not evidence of need — this is the failure mode this skill replaces |
|
||||
| Style rules an agent is meant to self-enforce | That job belongs to a formatter, linter, hook, or CI check — propose one instead |
|
||||
| Platitudes ("write clean code") | Already the agent's default; changes nothing |
|
||||
| Fast-changing facts, pasted code, changelog content | Staleness magnets — the guide is not a memory system |
|
||||
| Aspirational state | What the system *should* become belongs in specs; an agent acting on aspiration ships fiction |
|
||||
| Platitudes ("write clean code") | Already the agent's default |
|
||||
| Fast-changing facts, pasted code, changelog content | Go stale quickly; the guide is not a memory system |
|
||||
| Aspirational state | Belongs in specs; the guide describes what is |
|
||||
|
||||
## Shape and style
|
||||
|
||||
Terse imperative lines under plain headings — no prose paragraphs beyond Orientation, no introduction, no summary. Present truth only: never the story of an edit ("we removed X because…" is banned; git holds history). Every named decision, doc, file, or system carries a path or URL a fresh session can follow. Links must survive the file's location: the guide links only to repo-relative paths that exist. Target shape:
|
||||
Terse imperative lines under plain headings — no prose paragraphs beyond Orientation, no introduction, no summary. State present truth only; git holds history. Every named decision, doc, file, or system includes a repo-relative path or URL that exists. Target shape (single-file form):
|
||||
|
||||
```markdown
|
||||
# acme-billing
|
||||
@@ -43,14 +49,14 @@ Planning lives in docs/planning/, tickets in Linear (ACME board), PRs on GitHub.
|
||||
|
||||
## Commands
|
||||
- Test: `pnpm test` (vitest — do NOT use jest syntax); single file: `pnpm test -- path/to/file`
|
||||
- Full suite takes ~15 min; run single files while iterating.
|
||||
- The full suite is slow; run single files while iterating.
|
||||
|
||||
## Before pushing
|
||||
- `pnpm lint && pnpm test` must pass — same commands CI runs.
|
||||
|
||||
## Policy
|
||||
- Never push to main; PRs only, one approval required.
|
||||
- `legacy/` is frozen: never modify; it is being strangled out.
|
||||
- `legacy/` is frozen: never modify; it is being replaced.
|
||||
- `src/generated/` is generated by `pnpm codegen` — never edit by hand.
|
||||
|
||||
## Conventions that differ from defaults
|
||||
@@ -68,12 +74,12 @@ Planning lives in docs/planning/, tickets in Linear (ACME board), PRs on GitHub.
|
||||
|
||||
## Editing an existing guide
|
||||
|
||||
A handwritten `AGENTS.md` is the baseline, not raw material. Keep its phrasing where it works, propose changes as a diff, and never delete human-written content without agreement — stale human content gets flagged with its evidence, then removed only on confirmation. Human-written content may violate this contract's style and survive; the contract binds what this skill writes, not what humans keep.
|
||||
A handwritten guide is the baseline, not raw material. Keep its phrasing where it works, propose changes as a diff, and never delete human-written content without agreement. Its recorded lessons — wherever they live: the old `AGENTS.md`, `CLAUDE.md`, notes files, warnings in READMEs — are standing maintainer testimony: keep them by default, and challenge one only with evidence that its referent is gone or wrong, never because scans show no recent failures. Restructuring a single old file into the two-file form is fine; losing its content is not.
|
||||
|
||||
## Scoped guides
|
||||
|
||||
A subsystem earns its own nested `AGENTS.md` when work keeps landing there and its truths don't belong at root — most harnesses auto-load the nearest file. 25–35 lines answering, in order: what is this, who owns it, how do I run it, what's surprising, where do I go next. Every path verified. Coverage is demand-driven, never wall-to-wall.
|
||||
A subsystem gets its own nested `AGENTS.md` when work keeps landing there and its truths don't belong at root — most harnesses auto-load the nearest file. 25–35 lines answering, in order: what is this, who owns it, how do I run it, what's surprising, where do I go next. Every path verified. Created when a subsystem needs one, never for every subsystem.
|
||||
|
||||
## Small guides are success
|
||||
|
||||
A small project needs Orientation, Commands, Verification, and little else. When the evidence supports ten lines, ten lines is the deliverable — manufacturing content to look thorough is exactly the failure this skill replaces.
|
||||
When the evidence supports ten lines, ten lines is the deliverable.
|
||||
|
||||
Reference in New Issue
Block a user