How I Avoid Reinventing Mechanisms for AI When Developing with Claude Code and Codex
This page has been translated by machine translation. View original
Introduction
As I use Claude Code and Codex in my everyday development, I have come to feel that agent failures follow set patterns. They mistake premises, pile up reports and lose track of the latest state, drift in what a term refers to, or get the order of starting work wrong.
Every time such a failure occurs, I am tempted to build a new mechanism dedicated to the agent. I have tried several approaches myself. Recently, however, I have settled on the view that rather than building a new mechanism, we should first consider the methods engineers have long practiced. This means leaving terms, constraints, requirements, specifications, design, progress state, and so on in documents, consolidating them by type of information, and referring to them from everywhere else... a referentially transparent way of handling information, so to speak.
Gunpei Yokoi, a developer at Nintendo, left behind the idea of "lateral thinking with withered technology." It is the idea of creating new value by repurposing technology that has become widespread and easy to handle. In this article, I would like to write about how the same idea is useful in development with agents, while introducing the methods I practice. I will also touch on how my approach differs from those introduced in papers and prior examples.
I have previously introduced task management using Beads, an issue tracking tool for AI coding agents, in the following two articles. This article also touches on the real-world examples reported there.
Target audience
- Those who have started using Claude Code or Codex for development at work and are troubled that the agent does not behave as intended
- Those who are trying to build their own memory or handoff mechanisms for agents
References
- gastownhall/beads (GitHub)
- 横井軍平ゲーム館 (筑摩書房)
- Documenting Architecture Decisions (Michael Nygard, 2011)
- Coding agents love decision records (Duncan Davidson, 2026)
- Ubiquitous Language (Martin Fowler, 2006)
- How Claude remembers your project (Claude Code Docs)
- Best practices for Claude Code (Anthropic)
- Critical-Path Planning and Scheduling (James E. Kelley, Morgan R. Walker, 1959)
- Ubiquitous language for AI plans (AgentPatterns.ai)
- Lost in Context Compaction: When LLM Systems Drop Side Constraints (arXiv:2608.11242)
- Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv:2602.11988)
Background
AI agents are excellent in settings where a task is self-contained. However, when handling information across tasks, they repeat the same kinds of failures.
Looking back, these failures are not unique to agents. The same kinds of failures have long occurred in human teams as well. Here are the four agent failures I have repeatedly encountered in practice, paired with the corresponding failures of human teams.
| # | Agent failure | Corresponding human team failure |
|---|---|---|
| 1 | Confusing means with requirements | A proposal raised in a meeting comes to be treated as a decision before anyone notices |
| 2 | Mixed descriptions caused by appending | A Slack conversation is treated as the record as is, and no one can tell which statements are currently valid |
| 3 | Confusion of names | Terms have no definitions, so the same word refers to different things |
| 4 | Starting order without rationale | Tasks are started from whatever is closest at hand without designing dependencies and priorities |
If the failures are not new, it should be best to look for countermeasures first among long-established methods. We engineers have long faced the problems of how to record information and how to manage progress. I think it is good to first bring that accumulated knowledge into development with agents as well.
There are developers overseas who feel the same way. Duncan Davidson, who created Apache Tomcat and Apache Ant, says the following about ADRs, which I introduce later.
Like many tools built for human software teams, ADRs work remarkably well for coding agents too.
He says that, like many tools built for human software teams, ADRs work remarkably well for coding agents too.
Methods I practice
From here, for each of the four failures, I introduce my approach and show how it differs from approaches in papers and prior examples. Since I have not measured the effects of my approach numerically, please read it as an example of operation.
1. Confusing means with requirements
When I tell an agent "I want to do this," it makes a concrete plan. For example, the AI proposes, "If you use Cloudflare, you can achieve it like this." If I reply, "But that wouldn't let us do what we really want to do, would it?", the agent answers, "I will research how to achieve it with Cloudflare." I never said to use Cloudflare. The agent mistook the means it had proposed itself for a requirement and narrowed the scope.
In human teams as well, a proposal someone raises in a meeting is sometimes treated as a decision before anyone notices.
So I record decisions and divide them into three categories: confirmed, provisional, and undecided. I also leave the date and the approver as the basis for each decision.
## 確定
| 内容 | 根拠 |
| --- | --- |
| 通知はメールで送る | 2026-10-01 越井が承認 |
## 仮置き
| 内容 | 確定の条件 |
| --- | --- |
| 配信基盤に Cloudflare Workers を使う | 2026-10-15 の検証で要件を満たせば確定。判断は越井 |
## 未決
| 内容 | 判断の時期 |
| --- | --- |
| 通知の再送の要否 | 運用の担当者との打ち合わせ後 |
I have the agent record the means it proposes as provisional, and I decide in advance that only a human makes things confirmed. This way, means and requirements are distinguished on the document. When a proposal turns out not to satisfy the requirements, I can instruct the agent to remove the provisional means and reconsider from the requirements.
For recording decisions, there is a standard format called ADR (Architecture Decision Record). Proposed by Michael Nygard in 2011, it assigns each decision a status such as "proposed," "accepted," "deprecated," or "superseded," and describes the context, decision, and consequences. Distinguishing by status is the same as my approach, but ADRs have no section for listing issues that are not yet decided as "undecided."
The difference lies in how outdated decisions are handled. Davidson reports a case where agents stuck to ADRs even more rigidly than humans and kept following decisions that had already become outdated. For that reason, he says he instructs in AGENTS.md to "follow approved ADRs, but if they conflict with the work, stop and consult, and propose a change." Explicitly giving the agent permission to question decisions is something I could probably incorporate into my own approach.
2. Mixed descriptions caused by appending
When you ask an agent to manage progress, it tends to keep appending comments endlessly. A correction is added after an old description, and then a further supplement is added after that. In the second article introduced in the "Introduction" section, I aggregated Beads notes across 25 repositories, and reported that the total reached about 550,000 characters, along with an example where only a correction was appended after an incorrect figure.
This is the same as, for humans, for example, the problem that occurs when a Slack conversation is treated as the record as is. You can't tell which statements are still valid without reading back through the conversation. Whether the reader is a human or an agent, the context gets polluted, and it becomes impossible to correctly identify the latest description.
So I separate "the place that describes the current state" from "the place that preserves the history." In places that represent the current state, such as the body of a GitHub Issue, I in principle have the agent rewrite the existing description.
For example, if you keep appending to the body of an Issue for the notification feature, it looks like this.
- 09/28 通知は Slack で送る方針
- 10/01 訂正: 通知はメールで送る
- 10/03 補足: 配信基盤は Cloudflare Workers が候補
- 10/06 訂正: 配信基盤の検証は 10/10 ではなく 10/15 に実施
To learn the latest policy, you have to read every line and apply the corrections in your head. Rewriting the same content to contain only the current state looks like this.
## 現在の状態
- 通知はメールで送る (decisions.md の確定事項)
- 配信基盤は Cloudflare Workers を仮置き。10/15 の検証で確定する
- ブロッカー: なし
## 経緯
- 通知手段と配信基盤の比較検討: docs/reports/2026-10-03-notification.md
Only currently valid content remains in the body, and the history of the comparison can be referenced from the research report.
However, you must not erase the rationale for decisions or the evidence of verification through rewriting. History worth keeping is moved to another place, such as a research report, before rewriting. Old versions of documents are not deleted but declared non-current at the top, and I have the agent write out discrepancies between documents and the implementation into a single file as soon as they are found.
In my case, I keep research reports as Markdown files in the docs/reports directory of the repository. Since they are managed with Git together with the code, they can be referenced by file path from both Issues and agents. In the Issue example above, I have the agent move the history of corrections to a report in this directory before rewriting.
# 通知手段と配信基盤の比較検討
## 通知手段
- 09/28 時点では Slack で送る方針だった
- 10/01 に、利用者の多くが Slack を使っていないと分かり、メールに変更した。越井が承認
## 配信基盤
- 候補は Cloudflare Workers と AWS Lambda
- 検証は 10/10 の予定だったが、検証用アカウントの準備が遅れ、10/15 に延期した
Design documents that have become outdated due to a change of policy are not deleted; instead they declare "not current" at the top and point to the current document.
> この文書は現行ではありません。2026-10-01 に通知手段を Slack からメールへ変更しました。現行の設計は docs/design/notification-v2.md を参照してください。
# 通知機能の設計 v1
(以下、当時の本文をそのまま残す)
Discrepancies between documents and the implementation are written one line at a time into a file like the following as soon as they are found, and the line is deleted once resolved.
| 箇所 | ドキュメントの記述 | 実装の状態 | 対応 |
| --- | --- | --- | --- |
| 通知の送信元アドレス | noreply@example.com から送る | 開発用のアドレスのまま | 実装を直す |
| 通知の再送 | 記述なし (decisions.md では未決) | 失敗時に 1 回だけ再送する | 未決の判断が出たら、ドキュメントか実装をそろえる |
By looking at this file, you can see at a glance the discrepancies that remain.
Incidentally, the idea of "separating the current state from the history" seems to be shared with the literature as well. Davidson reports that when agents are made to update decision records, they try to preserve the history and appends pile up.
The difference is where the history is kept. Davidson has records hold only the current body and leaves the change history to Git history. In Nygard's ADRs, a decision is not rewritten; it is replaced by a new record, and the old record is kept with a "superseded" mark. I move the history to research reports. The places differ among the three, but the purpose is common: keep the current state easy to read without losing the history.
3. Confusion of names
Codex tends to call me "the user." If left alone, it writes things like "the user approved this approach" in GitHub comments.
However, the product I'm developing also has "users." It ends up calling both me, the requester, and the product's "end users" by the same word, "user." Someone who reads this Issue later can't tell who approved it.
In domain-driven design, cultivating a rigorous shared language between developers and users is called "Ubiquitous Language." In introducing this idea of Eric Evans, Martin Fowler states the reason as follows.
rigorous, since software doesn't cope well with ambiguity.
This means that because software doesn't cope well with ambiguity, language needs to be rigorous.
So I keep a glossary in one place and don't define terms in other documents. The glossary includes the people involved too, and I have the agent write them under distinct names.
| 用語 | 定義 |
| --- | --- |
| 越井 | 本プロジェクトの開発者。作業の依頼と承認を行う |
| 利用者 | 開発しているアプリケーションを使うエンドユーザー |
| 仮置き | 確定の条件を満たすまで暫定で採用する判断 |
Other documents do not redefine terms; they refer to the glossary. Some operations assign IDs to decisions, but I don't think that is essential. What matters is that the definition is in one place and other documents refer to it.
The idea of giving agents a glossary also appeared in prior examples. AgentPatterns.ai points out that agents invent new names every time they plan a feature, and recommends fixing the language with a glossary and a small number of ADRs. However, it also lists as cautions that the glossary should be created only when it becomes necessary, and that in projects where code changes quickly, the glossary becomes outdated and the agent ends up following old descriptions.
However, I did not find any example that includes the people involved in the glossary within the scope I investigated this time. On the other hand, preparing against the risk of a glossary becoming outdated is something I could probably incorporate into my own approach.
4. Starting order without rationale
When you let an agent choose the next task, it sometimes starts work haphazardly for reasons like "it's easy and will be done quickly" or "the ID is small." In human teams as well, it's a common failure to start from whatever task is closest at hand without deciding dependencies and priorities, and then suffer rework later.
I entrust the design of dependencies and priorities itself to the agent. I have it identify the dependencies among tasks and the top-priority task and present them as a way to proceed. I review that plan and approve it before having the agent start. I tell it not to use ease or ID order as a reason for starting.
When managing on GitHub, I first have the agent create priority labels, writing the criteria for judgment in the description. The criteria are decided not by "by when it must be done" but by "how it affects delivery to customers." For example, something that blocks a feature to be delivered to customers in the next release is P1, and something that doesn't block delivery but causes manual work in operations is P2. If the criteria are written on the label itself, both agents and humans can judge priority by the same criteria.
On top of that, I have it assign a priority and dependencies to each Issue, and present the way to proceed summarized in a single Issue.
For example, in the example above, the typo fix in the README in #4 is quick work, but it affects neither delivery to customers nor operations, so it is placed last. Also, the retry Issue #3 carries a blocked label because whether to retry is undecided.
As a method for determining the order of work from dependencies, the critical path method, published in 1959 by James E. Kelley and Morgan R. Walker, is the classic. However, I did not find in this investigation any literature discussing the approach of entrusting this design to agents.
Instructions common to the four methods
In every method, I attach two instructions for the agent: have it read the document in which information is consolidated at the start of work, and have it update that document when a decision or state changes.
Consolidating information in documents is meaningless if they are not read. In the first article introduced in the "Introduction" section, I reported a case where a decision was recorded but written in a place that was not handed over to the next session, so a settled discussion was reopened. It is important to write information in a place where the agent will reliably read it.
On the other hand, regarding the amount to have it read, there is also a paper that showed results different from my approach. A group including ETH Zurich reports that giving agents context files such as AGENTS.md did not generally raise task success rates and increased inference costs by more than 20% on average. The same paper also states that it is useful for specifying non-standard coding practices.
Anthropic's best practices also recommend writing in CLAUDE.md only what cannot be read from the code. I leave terms, constraints, requirements, specifications, design, and progress state broadly, but it seems I need to think separately about the scope of what I keep and the amount the agent reads every time.
How to choose tools
The methods so far do not depend on specific tools. They can be practiced with Backlog, GitHub, or Jira. The condition I ask of a tool is that it be "AI Ready" and at the same time "human Ready." In other words, it should be easy to use for both agents and humans.
What I emphasize as ease of use for humans is being able to grasp the situation instantly in a list view. If the situation can be grasped visually, like in Backlog's Gantt chart, the cognitive load on the recipient of the information drops and work moves faster. The same holds for agents: a tool that delivers necessary and sufficient information fastest is suitable.
I currently use Beads to manage task state. Beads handles dependencies between issues and can distinguish issues that can be started from those that are stuck. It may look like new technology, but I see its essence as the withered technique of issue management made easy for agents to handle through commands.
Insights gained from comparing with the literature
When I compared my methods with the literature, the core parts, "recording decisions" and "deciding on one place for information and referring to it from elsewhere," were common. The differences were in details such as "how to classify the state of decisions," "where to keep the history," and "how much to have the agent read." I think the core is common because many agent failures have the same shape as problems human teams have long had.
On the other hand, I think the details are a fluid part that depends on model performance and project circumstances. Both the tendency to cling to old decisions that Davidson reported and the results of the paper measuring the effect of context files are observations made with the models of that time. The approach I introduced in this article is also merely "the best for me right now," leaning very heavily toward the concrete. I believe the right attitude is to accept that it will change and keep searching for the best method at each point in time.
Honestly, the content of this article leans quite concrete, so it may become useless by next year. Even so, if what I was thinking at this point remains, I think it will be material for looking back at my thinking of the time. Just as an ADR preserves the background of a decision, I will leave this article as a record of my judgment as of October 2026.
Summary
I feel that many failures in development with agents have the same shape as failures that have long occurred in human teams. Before building new mechanisms for agents, please first review how your team already uses issue management and documents. Then, I recommend leaving terms, constraints, requirements, specifications, design, and progress state in documents and consolidating them by type of information, having the agent read them at the start of work, centered on decisions and terms that cannot be understood from the code, and rewrite them when something changes. As for the details, please keep revisiting them as models change, while also referring to papers and prior examples. I hope this article serves as a reference when you think about how to proceed with development with agents.
