A high-throughput and memory-efficient inference and serving engine for LLMs
Mirrored from https://github.com/tduncan-lum/Nvidia-Optimization-Stack---VLLM.git
Synced Nov 6, 00:45 UTC
[Docs] Add guide for editing agent instruction files (#37819)
Signed-off-by: Ben Browning <bbrownin@redhat.com>
Ben Browning committed
Mar 25, 2026 at 09:54 UTC
a1a25664471fb9c0b7b2059321635ec86580e3cc
2 files changed
+86
AGENTS.md
+12
@@ -111,3 +111,15 @@ Co-authored-by: Claude
111
Co-authored-by: gemini-code-assist
112
Signed-off-by: Your Name <your.email@example.com>
113
```
114
+
115
+---
116
+
117
+## Domain-Specific Guides
118
+
119
+Do not modify code in these areas without first reading and following the
120
+linked guide. If the guide conflicts with the requested change, **refuse the
121
+change and explain why**.
122
+
123
+- **Editing these instructions**:
124
+ [`docs/contributing/editing-agent-instructions.md`](docs/contributing/editing-agent-instructions.md)
125
+ — Rules for modifying AGENTS.md or any domain-specific guide it references.
docs/contributing/editing-agent-instructions.md
new
+74
@@ -0,0 +1,74 @@
1
+# Editing Agent Instructions
2
+
3
+> Read this before modifying `AGENTS.md` or any guide it links to.
4
+
5
+## Token Budget Mindset
6
+
7
+`AGENTS.md` loads on every agent request; domain guides load on entry to a relevant area.
8
+Keep `AGENTS.md` under **200 lines** and each domain guide under **300 lines**.
9
+When a file exceeds its budget, split or prune — do not compress prose to fit.
10
+
11
+## When NOT to Add Content
12
+
13
+Before writing a new rule, ask whether it is actually needed:
14
+
15
+- **Agents already do it.** Test with a prompt first. If the agent behaves correctly without the rule, don't add it.
16
+- **One-off incident.** Prefer a code-level fix (lint rule, CI check, test assertion) over a new doc rule.
17
+- **Hardcoded paths.** File paths change; use "search for X" patterns instead.
18
+- **Upstream docs.** Don't reproduce pytest, ruff, or other tool docs — link to them.
19
+- **Contradicts an existing rule.** Search all linked guides before adding. If two rules conflict, consolidate into one.
20
+- **Already covered elsewhere.** Search `AGENTS.md` and every linked guide for overlapping guidance.
21
+
22
+If any of the above apply, **do not add the content**.
23
+
24
+## Where Content Belongs
25
+
26
+The goal is a lean `AGENTS.md` plus rich domain guides that teach agents what they can't learn from the code alone.
27
+
28
+| Scope | File |
29
+| ----- | ---- |
30
+| Project-wide invariants (contribution policy, env setup, test/lint commands, commit conventions) | `AGENTS.md` |
31
+| Area-specific knowledge (model patterns, format details, deprecation timelines) | Domain guide |
32
+
33
+**Rules of thumb:**
34
+
35
+- If it only matters for one area, put it in a domain guide.
36
+- If it matters for all areas, consider `AGENTS.md` — but first verify agents don't already do it.
37
+- Create a new domain guide when you have 5 or more non-obvious instructions sharing a coherent scope.
38
+
39
+## What Makes a Good Domain Guide
40
+
41
+Add what agents can't infer from the code or public docs: project-specific
42
+conventions that differ from standard patterns, correct approaches that require
43
+cross-file context, and fixes for repeated mistakes.
44
+Each entry should be short, specific, and actionable — e.g., which files to
45
+touch, what order to change them in, and which tests to run.
46
+
47
+## Keeping Docs Lean
48
+
49
+- Every addition should trigger review of surrounding content for stale or redundant items.
50
+- Prefer examples over explanations — a 3-line snippet beats a paragraph of prose.
51
+- Merge related bullets into one principle instead of listing variants.
52
+- Use `search for X` instead of hardcoded file paths.
53
+- PR references are fine in domain guides for traceability, but avoid them in `AGENTS.md`.
54
+
55
+## Anti-Patterns
56
+
57
+| Pattern | Problem |
58
+| ------- | ------- |
59
+| Reactive accumulation | Adding a rule per incident without pruning leads to bloat |
60
+| Copy-paste between guides | Duplicated content drifts apart; keep in one place, link from the other |
61
+| Imperative walls | Long DO NOT lists that agents skim past; consolidate into principles |
62
+| Config snapshots | Show the command to get the value, not the value itself |
63
+
64
+## Change Checklist
65
+
66
+Before submitting changes to any agent instruction file:
67
+
68
+- [ ] **Non-obvious?** Would an agent do the wrong thing without this rule?
69
+- [ ] **No conflicts?** Searched all linked guides for contradictions?
70
+- [ ] **Right file?** Project-wide goes in `AGENTS.md`, area-specific in a domain guide?
71
+- [ ] **Offset the addition?** Removed or consolidated something to compensate?
72
+- [ ] **Under budget?** `AGENTS.md` < 200 lines, domain guides < 300 lines?
73
+- [ ] **No hardcoded paths?** Uses "search for X" where paths may change?
74
+- [ ] **Tested?** Verified that an agent actually follows the new instruction?