Better Agent MD

Treat agent instruction files as operational guidance, not general documentation.

Workflow

1. Find the target file and read it fully.
2. Read only the codebase files needed to verify its claims and commands.
3. Read references/how-to-write-a-better-agent-md.md before giving recommendations.
4. Use it as the only reference unless the user gives new source material.
5. Classify every instruction as one of:
   • Keep: repo-specific, procedural, durable, and hard for the agent to infer cheaply.
   • Rewrite: useful idea, but vague, bloated, redundant, or too broad.
   • Remove: redundant overview, fast-changing detail, human-facing documentation, or unnecessary requirement.
6. Produce both critique and remediation. Do not stop at observations alone.

What To Optimize For