AGENTS.md Edit

Make the default context small enough to use and complete enough to guide decisions. Preserve effective behavior, not inherited wording or layout. A shorter file is useful only when its rules remain findable, coherent, and correct. Read decision criteria for semantic editing and audit scope before interpreting script results.

Choose the scope

• For a specific rule change, map the file's headings and inspect the target domain, overlapping rules, and their authorities. Change the smallest coherent area; a one-line request does not authorize an unrelated rewrite.
• For a whole-file audit or cleanup, or when examples indicate a recurring structural problem, read the entire file first. Derive a new domain tree from the decisions governed, rather than renaming or grouping the existing headings. Account for every section and rules that interact across sections. Treat the whole document as the review scope; do not preserve a disorderly lower half merely because an upper section has improved.
• Keep an explicitly read-only review read-only. Review and edit use the same reasoning, but only an edit writes files.

Restructure by decisions

1. Identify generated regions and their maintenance sources. Inspect relevant linked authorities when judging whether detail can move out of default context. Edit a generated region through its source and regeneration process.
2. Inventory each existing instruction by the decision it changes, its scope and exceptions, and its owner. Group rules by the subject they govern, not merely by the workflow phase in which an agent encounters them. Use headings when they improve navigation; do not create one for every short rule. A small file can keep independent rules as a flat list under a simple rules heading, separate from its document index. In a larger file, avoid umbrellas such as “General,” “Work,” or “Engineering” that hide unrelated subjects. Find duplication across distant sections, misplaced rules, stale session scope, historical provenance, excessive enumeration, and conflicting absolutes. Give each item a disposition: retain, merge, move, route to a linked authority, remove, or unresolved. A preservation inventory is not a veto on changing layout or wording.
3. Test recoverability before moving content. For descriptive facts, check whether a fresh agent can find a current source and reconstruct the fact with a few cheap tool calls. Verify candidates against actual manifests, code, configuration, or tool help. Remove repeated facts when their source and the need to consult it are discoverable. A directive, safety boundary, gotcha, rationale, or navigation pointer is not redundant merely because related text exists elsewhere or automation checks it later. Investigate uncertainty; retain an unresolved behavior provisionally rather than guessing it away.
4. Give each enduring decision one canonical rule. Merge repeated wording, move misplaced rules, and state a shared category once instead of retaining a list of synonymous examples. Keep a named technology, condition, exception, number, path, or command only when its exact identity changes a future decision. Put historical dates, incident narratives, and implementation procedures in their authoritative records when they still have value. Do not delete a distinct constraint merely because it is verbose.
5. Place surviving content by loading need. For each default-loaded section, identify the decision it must change before an agent could reasonably retrieve a relevant document. A heading, current-state claim, pointer, or narrowly scoped maintenance reminder does not earn default loading merely by being true or actionable. If the index can lead an agent to the authoritative document before that decision, move the detail there and make the index summary accurate; do not leave a second pointer as a section. Verify that the destination actually states and owns the moved behavior; a document that points back to AGENTS.md cannot replace the rule. Keep broad rules and prohibitions whose omission could cause a consequential mistake in the AGENTS.md that governs their scope, even when relevant tasks are rare. Put repeatable procedures in skills. Keep one shared directive to read relevant documents; index entries concisely summarize content without trigger or consequence lists. Avoid repeating a category in every index row; use the document title and summary to route reading, and add grouping only when it improves navigation.
6. Resolve contradictions from current authority and explicit user intent. State unresolved conflicts instead of silently selecting a side. Preserve a rule's applicable scope when consulting a detailed guide; do not promote the guide's example procedure into a universal requirement. Do not add ambient system, developer, or session instructions to the edited file unless that change is explicitly requested. Do not turn a one-off example, temporary request, or frustration into a universal rule. An explicit new requirement may supersede stale evidence; never infer that permission from a stylistic preference.