Agents MD Best Practices

Overview

Refactor an AGENTS.md into a minimal root file with links to focused docs, following progressive disclosure. Produce contradictions to resolve, a root essentials set, grouped files, a suggested docs/ structure, and deletion flags.

Workflow

0) Gather inputs

• Ask which AGENTS.md to refactor (path or pasted content).
• Ask whether to apply file changes or draft only.
• Ask where to place new docs/ (default: docs/agents/).

1) Parse and normalize

• Read the AGENTS.md content.
• Split into individual instructions (one per line/bullet/paragraph).
• Keep original wording; annotate with a short label so you can reference items precisely.

2) Find contradictions

• Identify instructions that conflict (opposing directives, incompatible tools, or contradictory constraints).
• Present each contradiction as a pair (or set) and ask which to keep.
• Pause before restructuring until contradictions are resolved.

3) Identify essentials for root AGENTS.md

Keep only what belongs in the root file:

• One-sentence project description.
• Package manager if not npm.
• Non-standard build/typecheck commands.
• Anything truly relevant to every single task.

Ask if the user wants any other item in root before finalizing.

4) Group the rest into categories

• Cluster remaining instructions into logical, named categories (e.g., TypeScript, Testing, API design, Git workflow, UI, Infra).
• Create a separate markdown file per category.
• Keep categories actionable and scoped; avoid mixed topics.

5) Create the file structure

Provide:

• A minimal root AGENTS.md with markdown links to the category files.
• Each category file with its relevant instructions.
• A suggested docs/ folder structure.

Use the template in references/output-template.md when helpful.

6) Flag for deletion

Identify instructions that are:

• Redundant (agent already knows this).
• Too vague to be actionable.
• Overly obvious (e.g., “write clean code”).

List these separately with a short reason and ask for confirmation before removing.

Output requirements

• If no contradictions, explicitly say “No contradictions found.”
• Use clear section headings in the response: Contradictions, Root AGENTS.md, New Files, Suggested docs/ Structure, Flags for Deletion.
• Provide file contents in fenced code blocks with filenames.

Guardrails

• Do not delete or rewrite instructions without user confirmation when conflicts exist or items are flagged.
• Do not expand scope beyond the AGENTS.md content unless the user asks.