verl/docs/contributing/editing-agent-instructions.md

# Editing Agent Instructions

> Read this before modifying `AGENTS.md` or any guide it links to.

## File Layout

| Generic     | Variants                   | Audience        | Scope                          |
| ----------- | -------------------------- | --------------- | ------------------------------ |
| `AGENTS.md` | `CLAUDE.md`, ...           | Agents          | Project-wide instructions.     |
| `.agent/`   | `.claude/`, `.codex/`, ... | Agents          | Agent specification directory. |
| `docs/`     | N/A                        | Humans & Agents | Project documentation.         |

Generic files are framework-agnostic. Variants directly symlink generic files or refer to them and add framework-specific content.

For skills, keep canonical content under `.agent/skills/<skill-name>/SKILL.md`.
Variant trees such as `.codex/skills/<skill-name>` and `.claude/skills/<skill-name>` should be directory symlinks to the canonical `.agent` skill directory, not directories containing only a symlinked `SKILL.md`.
Codex documents support for symlinked skill folders and can skip file-level `SKILL.md` symlinks during discovery. Claude Code discovers the file-level symlink layout in current versions, but directory symlinks match the shared skill-package structure and keep supporting files in sync across frameworks.

## 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.
- Refer to existing files (e.g., "follow the PR template") instead of restating their content — keep a single source of truth.
- 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?

## Acknowledgements

This guide is adapted from the [vLLM project](https://github.com/vllm-project/vllm)'s [`editing-agent-instructions.md`](https://github.com/vllm-project/vllm/blob/main/docs/contributing/editing-agent-instructions.md).

Last updated: 05/13/2026