From a1a25664471fb9c0b7b2059321635ec86580e3cc Mon Sep 17 00:00:00 2001 From: Ben Browning Date: Wed, 25 Mar 2026 09:54:09 -0400 Subject: [PATCH] [Docs] Add guide for editing agent instruction files (#37819) Signed-off-by: Ben Browning --- AGENTS.md | 12 +++ .../editing-agent-instructions.md | 74 +++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 docs/contributing/editing-agent-instructions.md diff --git a/AGENTS.md b/AGENTS.md index c541a370b..880ee0a78 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -111,3 +111,15 @@ Co-authored-by: Claude Co-authored-by: gemini-code-assist Signed-off-by: Your Name ``` + +--- + +## Domain-Specific Guides + +Do not modify code in these areas without first reading and following the +linked guide. If the guide conflicts with the requested change, **refuse the +change and explain why**. + +- **Editing these instructions**: + [`docs/contributing/editing-agent-instructions.md`](docs/contributing/editing-agent-instructions.md) + — Rules for modifying AGENTS.md or any domain-specific guide it references. diff --git a/docs/contributing/editing-agent-instructions.md b/docs/contributing/editing-agent-instructions.md new file mode 100644 index 000000000..7be5f594c --- /dev/null +++ b/docs/contributing/editing-agent-instructions.md @@ -0,0 +1,74 @@ +# Editing Agent Instructions + +> Read this before modifying `AGENTS.md` or any guide it links to. + +## Token Budget Mindset + +`AGENTS.md` loads on every agent request; domain guides load on entry to a relevant area. +Keep `AGENTS.md` under **200 lines** and each domain guide under **300 lines**. +When a file exceeds its budget, split or prune — do not compress prose to fit. + +## When NOT to Add Content + +Before writing a new rule, ask whether it is actually needed: + +- **Agents already do it.** Test with a prompt first. If the agent behaves correctly without the rule, don't add it. +- **One-off incident.** Prefer a code-level fix (lint rule, CI check, test assertion) over a new doc rule. +- **Hardcoded paths.** File paths change; use "search for X" patterns instead. +- **Upstream docs.** Don't reproduce pytest, ruff, or other tool docs — link to them. +- **Contradicts an existing rule.** Search all linked guides before adding. If two rules conflict, consolidate into one. +- **Already covered elsewhere.** Search `AGENTS.md` and every linked guide for overlapping guidance. + +If any of the above apply, **do not add the content**. + +## Where Content Belongs + +The goal is a lean `AGENTS.md` plus rich domain guides that teach agents what they can't learn from the code alone. + +| Scope | File | +| ----- | ---- | +| Project-wide invariants (contribution policy, env setup, test/lint commands, commit conventions) | `AGENTS.md` | +| Area-specific knowledge (model patterns, format details, deprecation timelines) | Domain guide | + +**Rules of thumb:** + +- If it only matters for one area, put it in a domain guide. +- If it matters for all areas, consider `AGENTS.md` — but first verify agents don't already do it. +- Create a new domain guide when you have 5 or more non-obvious instructions sharing a coherent scope. + +## What Makes a Good Domain Guide + +Add what agents can't infer from the code or public docs: project-specific +conventions that differ from standard patterns, correct approaches that require +cross-file context, and fixes for repeated mistakes. +Each entry should be short, specific, and actionable — e.g., which files to +touch, what order to change them in, and which tests to run. + +## Keeping Docs Lean + +- Every addition should trigger review of surrounding content for stale or redundant items. +- Prefer examples over explanations — a 3-line snippet beats a paragraph of prose. +- Merge related bullets into one principle instead of listing variants. +- Use `search for X` instead of hardcoded file paths. +- PR references are fine in domain guides for traceability, but avoid them in `AGENTS.md`. + +## Anti-Patterns + +| Pattern | Problem | +| ------- | ------- | +| Reactive accumulation | Adding a rule per incident without pruning leads to bloat | +| Copy-paste between guides | Duplicated content drifts apart; keep in one place, link from the other | +| Imperative walls | Long DO NOT lists that agents skim past; consolidate into principles | +| Config snapshots | Show the command to get the value, not the value itself | + +## Change Checklist + +Before submitting changes to any agent instruction file: + +- [ ] **Non-obvious?** Would an agent do the wrong thing without this rule? +- [ ] **No conflicts?** Searched all linked guides for contradictions? +- [ ] **Right file?** Project-wide goes in `AGENTS.md`, area-specific in a domain guide? +- [ ] **Offset the addition?** Removed or consolidated something to compensate? +- [ ] **Under budget?** `AGENTS.md` < 200 lines, domain guides < 300 lines? +- [ ] **No hardcoded paths?** Uses "search for X" where paths may change? +- [ ] **Tested?** Verified that an agent actually follows the new instruction?