AIエージェントが毎回同じミスをするのは、AGENTS.md / CLAUDE.md の書き方が9割かもしれません — 手戻りを減らす指示ファイル設計の実践ガイド（30行ルール・import・monorepo）This practical guide argues that repetitive AI agent mistakes stem largely from…

AI coding agents such as those embedded in Cursor and Anthropic's Claude Code have become routine tools for everyday development, yet many users share a common frustration: the agent keeps repeating the same mistakes across sessions. A recent practical guide published on Qiita argues that these recurring errors stem largely from poorly structured instruction files, and that rewriting AGENTS.md and CLAUDE.md with clearer conventions can eliminate a large share of the rework they cause. The claim that this addresses roughly nine out of ten repeated mistakes is best read as an illustrative estimate rather than a measured figure, but the underlying reasoning is straightforward.

The central premise is that agents are largely stateless between sessions. They do not remember the correction you gave yesterday, and they rebuild their understanding of a project from whatever context is loaded at the start of each task. Instruction files like AGENTS.md and CLAUDE.md serve as that persistent memory. When the file is vague, contradictory, or bloated, the agent falls back on generic assumptions and reproduces the same errors. When the file states expectations precisely, the agent has a stable reference to follow, and the guide contends that most avoidable mistakes disappear as a result.

One of the guide's headline recommendations is a "30-line rule" for individual sections or rules. The idea is that instructions should be short, concrete, and scannable rather than sprawling essays. Overly long files appear to dilute the signal, and models may weight or truncate context in ways that cause important directives to be ignored. Keeping each rule tight also makes the file easier for humans to maintain, which matters because an instruction file that drifts out of sync with the actual codebase quickly becomes counterproductive.

The guide also emphasizes import management, meaning the practice of splitting instructions across multiple files and referencing them rather than duplicating content. CLAUDE.md in particular supports importing other files, allowing teams to keep a concise root file that pulls in shared conventions, coding standards, or directory-specific notes as needed. This modular approach reduces duplication and helps prevent the situation where two files give conflicting guidance. It also aligns with how larger projects naturally organize documentation.

Monorepo support is treated as a distinct challenge. In a repository that houses several packages or services, a single top-level instruction file often cannot capture the differing conventions of each subproject. The guide recommends placing scoped instruction files closer to the relevant code so that an agent working in one package picks up the rules that apply there, rather than applying blanket assumptions from the repository root. This mirrors the way both Cursor and Claude Code can resolve nested configuration, loading the most relevant guidance based on the files being edited.

Some background helps explain why this topic is gaining attention. AGENTS.md has emerged as an attempt at a tool-agnostic standard, an ordinary Markdown file intended to give any compatible coding agent a consistent place to read project instructions. It has been positioned as a complement to human-facing README files, separating documentation meant for people from guidance meant for machines. CLAUDE.md is Anthropic's specific convention for Claude Code, while Cursor has historically used its own rules files, and GitHub Copilot supports comparable custom instruction mechanisms. The broader industry appears to be converging on the idea that agents perform better with explicit, version-controlled context, even if the exact file names and formats still vary between tools.

All of this sits within the wider practice of prompt engineering, and instruction files can be understood as a durable, project-scoped form of prompting. Rather than repeating the same guidance in chat every session, teams encode it once and commit it alongside the code, so every contributor and every agent run starts from the same baseline. The trade-off is maintenance: these files require the same review discipline as any other part of a codebase, and stale instructions can mislead an agent as easily as good ones can guide it.

The practical takeaway from the guide is that instruction files deserve deliberate design rather than ad hoc growth. Whether the improvement reaches the headline proportion will depend on the project and the tooling, but the recommendations—concise rules, modular imports, and scope-aware placement in monorepos—reflect reasonable, widely applicable patterns for reducing repeated agent errors.