About AgentFails
AgentFails (智能体翻车库) collects the ways AI coding agents go wrong and pairs each one with a fix you can paste into your repo today. It is free, open source, and built from community submissions.
The three-part view
Checking an agent's work comes down to three questions. The framing comes from @liushiyumath's X thread on reviewing agent output. Every pattern here belongs to exactly one:
1. Wrong feature: Did it build the right thing?
It built something other than what you intended. Reviewing the PR is too late. Have teammates annotate the spec, mockup or artifact before code, and write acceptance checks that rule out the wrong reading.
Wrong feature →2. Bug: Is it bug-free?
The feature is right but buggy. Catch it with a review pass (a /code-review style skill or a fresh-context reviewer), real tests the agent cannot weaken, and evidence instead of claims.
Bug →3. Overreach: Is it how you wanted it, with no overreach?
It works and has no bugs, but it isn't how you wanted it. Example: you asked for a small frontend tweak and the agent changed backend logic. Fix it with a shared /verify skill, scope rules, diff budgets and hooks kept in the repo, so the whole team runs the same guardrails.
Overreach →
How a pattern is built
- A name and a type (wrong feature, bug or overreach).
- The symptom you see, why agents do it, and a minimal example.
- Copy-paste fixes: rules for CLAUDE.md, AGENTS.md and .cursor/rules, plus a Claude Code hook, skill or CI check where one helps.
- Sources. Rules in a context file are advice; hooks, permissions and CI checks are enforcement. We say which is which.
Agent tags show which agents a pattern's fixes cover. Most patterns are reported across agents, so most entries carry all four.
Credits
The seed patterns are adapted from these public taxonomies and guides. Each pattern page links its specific sources. Go read the originals.
- ralfyishere/agent-failure-modes (AFM index, CC BY 4.0)
- vnmoorthy/agent-review: TAXONOMY.md (35 agent bug patterns)
- developertoolkit.ai: A failure taxonomy for agent-written changes
- Agentic SDLC handbook, ch. 20: Anti-patterns and failure modes
- Kaplira: When an AI agent changes unrelated files
- Night Forge: Stop your AI agent editing the wrong files
- dev.to (yureki_lab): scope creep and the diff budget
- claudecodeguides.com: Stop Claude Code modifying unrelated files
- Anthropic: Solving code review at Anthropic
Maintained by @liushiyumath. Content lives in GitHub; changes are pull requests.
Submit a failure