Claude Codeのknown-failures.mdを育てる運用設計 A practical guide to maintaining a known-failures.md file for Claude Code: how to write en…

Anyone who uses an AI coding agent like Claude Code in real projects eventually notices the same classes of mistakes recurring. This article proposes a disciplined way to capture and reuse those lessons through a living document called known-failures.md, and discusses how to grow it over time rather than letting it rot.

The author structures the operational design around three concerns. The first is how to write entries. Rather than verbose postmortems, each entry should compactly describe the symptom, the underlying cause, and the workaround at a granularity dense enough that the agent, once given the context, actually changes its behavior. Searchability and consistent formatting matter, because the file is read by both humans and an LLM with limited attention.

The second concern is how to make the agent read it. Simply committing the file is not enough; it needs to be wired into the project context, typically via CLAUDE.md or similar entry-point files, so relevant entries surface during related tasks. Loading the entire log on every prompt wastes tokens, so the piece suggests splitting by topic or tagging by use case to let the agent pull only what is relevant.

The third concern, and arguably the most underappreciated, is staleness. Library upgrades, API changes, or model updates can turn a once-valid workaround into actively misleading guidance. The author recommends stamping each entry with dates and target versions, and scheduling periodic reviews to retire or rewrite stale items, treating the file like code that needs maintenance rather than an append-only journal.

This pattern fits a broader trend across AI coding tools. Anthropic's CLAUDE.md convention, Cursor's rules, Aider's CONVENTIONS.md, and GitHub Copilot's custom instructions all converge on the idea of in-repo memory that steers an agent. Treating recurring failures as a first-class artifact also echoes long-standing engineering practices like postmortems and Architecture Decision Records, suggesting that these documents are evolving into shared artifacts read by both humans and machines.

There is a tension worth flagging. Bloated context can itself degrade model behavior, encouraging hallucination or causing the agent to ignore instructions buried deep in a long file. The value of known-failures.md therefore depends less on exhaustive coverage than on editorial judgment about what to keep, what to compress, and what to delete. In that sense, maintaining such a file may become a small but meaningful new craft for teams shipping with AI assistance, sitting somewhere between documentation, prompt engineering, and knowledge management.