Creates, updates, or optimizes an AGENTS.md file for a repository with minimal, high-signal instructions covering non-discoverable coding conventions, tooling quirks, workflow preferences, and project-specific rules that agents cannot infer from reading the codebase. Use when setting up agent instructions or Claude configuration for a new repository, when an existing AGENTS.md is too long, generic, or stale, when agents repeatedly make avoidable mistakes, or when repository workflows have changed and the agent configuration needs pruning. Applies a discoverability filter—omitting anything Claude can learn from README, code, config, or directory structure—and a quality gate to verify each line remains accurate and operationally significant.
85
94%
Does it follow best practices?
Impact
72%
1.14xAverage score across 5 eval scenarios
Passed
No known issues
{
"context": "An agent is given a bloated AGENTS.md and asked to trim it. The file contains a mix of genuinely useful non-discoverable guidance (landmines, deployment quirks) and noise (tech stack summaries, directory listings, style rules already enforced by tooling, generic workflow platitudes). A quality pruning removes the noise while preserving the landmines.",
"type": "weighted_checklist",
"checklist": [
{
"name": "Removes tech stack summary",
"description": "The 'About this project' section or equivalent lines describing the tech stack (Node.js, Express, TypeScript, PostgreSQL, Redis, React, TailwindCSS) are removed or substantially reduced. This information is discoverable from package.json and config files.",
"max_score": 6
},
{
"name": "Removes or omits directory structure listing",
"description": "The directory structure section (src/, src/api/, src/models/, etc.) is removed or not reproduced. Directory layouts are trivially discoverable by listing the repo.",
"max_score": 6
},
{
"name": "Removes code style rules duplicated by linter/formatter config",
"description": "Lines such as '2-space indentation', 'single quotes for strings', 'semicolons at end of statements', 'camelCase for variables', 'PascalCase for classes' are removed. These are enforced by ESLint/Prettier and add no agent value.",
"max_score": 10
},
{
"name": "Removes generic development workflow platitudes",
"description": "Lines like 'Write descriptive commit messages', 'Test your code before committing', 'Use feature branches and open PRs for review', 'Keep PRs small and focused' are removed. These are universal best-practice noise that does not help an agent work in this specific repo.",
"max_score": 6
},
{
"name": "Removes or collapses obvious/redundant command descriptions",
"description": "Self-evident command descriptions such as 'npm install - Install dependencies', 'npm run build - Build for production', 'npm test - Run tests', 'npm run lint - Run ESLint' are removed or collapsed. The command names themselves are sufficient; trivial descriptions add no information.",
"max_score": 7
},
{
"name": "Retains the --legacy-peer-deps flag warning",
"description": "The output preserves the non-obvious information that npm install requires the --legacy-peer-deps flag due to peer dependency version conflicts. This is a landmine that cannot be discovered without running the command and hitting the error.",
"max_score": 14
},
{
"name": "Retains the scripts/migrate.sh requirement",
"description": "The output preserves the instruction to run scripts/migrate.sh after pulling from main to apply pending DB migrations. This is a mandatory non-obvious step that an agent would not infer from the codebase alone.",
"max_score": 14
},
{
"name": "Retains the payments/ module separate deployment pipeline warning",
"description": "The output preserves the warning that the payments/ module has its own deployment pipeline and must not be included in standard releases. This is critical operational knowledge that is not discoverable from code.",
"max_score": 14
},
{
"name": "Output is shorter than input",
"description": "The revised AGENTS.md is meaningfully shorter than the original (not just trivially shorter by removing one line). The original is approximately 50 lines; the output should be under 30 lines and ideally under 20.",
"max_score": 7
},
{
"name": "Retained lines are specific and actionable",
"description": "Every line that remains in the output is specific to this project and tells an agent something it could not trivially discover or infer. There are no filler sentences or generic advice remaining.",
"max_score": 10
},
{
"name": "Does not introduce new inaccuracies or hallucinated content",
"description": "The agent does not add new information not present in the original, does not rephrase landmine warnings in a way that dilutes or changes their meaning, and does not accidentally drop key qualifiers (e.g. 'after pulling from main', 'separate deployment pipeline').",
"max_score": 6
}
]
}