AIエージェントが解決済みの問題を何度も拾う原因｜最新版の機能メモで重複作業を減らす方法

なぜ、解決済みの問題がまた出てくるのか

AIエージェントは、目の前にあるコード、Gitの履歴、コメント、テスト、ログなどから状況を判断します。

そこに昔の「不具合」「未対応」「TODO」が残っていると、今も続いている問題なのか、解決までの記録なのかが分かりにくくなります。

Gitを読めば変更の経緯は追えます。ただ、次の作業で最初に知りたいのは、主にこの3つです。

• 今はどう動くのが正しいか
• どこまで解決しているか
• 何がまだ残っているか

この現在地を短く示すのが、この記事でいう「機能メモ」です。

Git、AGENTS.md、機能メモ、テストを分ける

ここで迷いやすいのが、すべてを1つのファイルへ書くのか、それぞれ分けるのかという点です。

整理すると、それぞれの役割は違います。

機能メモを変更のたびに増やすと、「最新版2」「本当の最新版」のような状態になりかねません。

原則は、1つの機能につき1つのファイルを更新します。過去の説明はGitに任せ、機能メモには現在の情報を残します。

CodexのAGENTS.mdで公式に確認できたこと

ここからは、私の運用案ではなく、2026年8月13日にOpenAI公式資料で確認した内容です。

Codexは、作業を始める前にAGENTS.mdを読みます。グローバルな指示に加えて、プロジェクトのルートから現在の作業フォルダまで指示ファイルを探し、順番に重ねます。

現在の作業場所に近い指示ほど後から加わるため、より具体的な指示として優先されます。AGENTS.override.mdがある場合の読み分けや、1回の実行を始めるときに指示のつながりを作ることも説明されています。

OpenAI公式：Custom instructions with AGENTS.md

ここで大事なのは、公式資料が説明しているのはAGENTS.mdの読み込み方だという点です。

「機能ごとにdocs/features/へ最新版メモを置けば重複作業が減る」という部分は、公式仕様ではなく、私が検討している運用案です。

機能メモを作る単位

小さな修正まで全部別ファイルにすると、読むメモのほうが増えてしまいます。

私は、利用者から見て1つの目的になる機能を目安にするのが分かりやすいと思います。

docs/features/
├── login.md
├── profile-edit.md
├── payment.md
├── article-publishing.md
└── notification.md

ボタンの色を変えただけなら、専用メモは必要なさそうです。

一方で、ログイン方法、認証API、セッション保存、権限、ログアウト後の動作まで関係するなら、login.mdへまとめる価値があります。

判断に迷ったら、次の項目を見ます。

• 複数のファイルや画面にまたがる
• 保存、再読み込み、権限、外部APIが関係する
• 過去に同じ不具合が繰り返された
• 今後も変更される可能性が高い
• 新しいAIエージェントが毎回、仕組みを調べ直している

作業前は、メモだけでなく現在のコードも見る

機能メモは便利そうですが、古くなれば逆にAIを迷わせます。

そのため、作業を始めるときは次の順番で確認します。

1. 対象機能のメモ
2. 現在のコード
3. 未コミットの差分
4. 関連する直近のコミット
5. 関連テスト
6. 呼び出し元と利用先

メモとコードが違うときは、どちらかを推測で正解にしません。実際の動作やテストを確認し、「説明と実装が食い違っている」と報告してもらいます。

対象ファイルだけで終わらず、一本道で追う

1つのファイルだけ直しても、保存後や別画面で反映されないことがあります。

そこで、可能な範囲で次の流れを追います。

入口 → 入力処理 → 内部処理 → API → 保存 → 表示 → 再読み込み

プロフィール編集なら、保存ボタンが反応しただけでは終わりません。

入力内容がAPIへ渡り、保存され、画面に表示され、ページを開き直しても残っているかまで確認します。

変更前には、次の内容を短く出してもらうと、途中で範囲が広がっていないか確認しやすくなります。

• 現在の動作
• 今回変更すること、変更しないこと
• 影響する機能とファイル
• 前提条件と想定する失敗
• 実行する確認

テストは省くのではなく、再実行する理由をはっきりさせる

同じテストが走ると、つい「前に通ったから不要では」と思います。

でも、コードや環境が変われば、同じテストにも意味があります。前回の結果が途中で切れていた場合や、新しい失敗経路が見つかった場合も同じです。

反対に、コードも環境も条件も変わっておらず、完全な成功結果が残っているなら、もう一度実行する理由を確認できます。

目的はテストを減らすことではなく、今回の変更に必要な確認を選ぶことです。

作業が終わったら、同じ変更の中で機能メモも直す

機能メモには、長い作業日記ではなく、次のAIエージェントが現在地をつかむための情報を残します。

# 機能名

## 状態
実装済み / 修正済み / 未対応 / 廃止

## 現在の仕様
現在のコードで有効な動作

## 処理経路
入口 → 処理 → API → 保存 → 表示 → 再読み込み

## 関係ファイル
- ファイルパス

## 解決済み事項
- 症状、原因、修正内容、再発確認方法

## 未対応・既知の制約
- 今も残っている問題だけ

## 検証
- 実行した確認と結果
- 実行していない確認

## 最終確認
- 確認日
- 検証時のベースコミットID
- 未コミット差分の有無

検証時のベースコミットIDを書くのは、「どの状態を基準に調べたか」を残すためです。

今回の変更自身のコミットIDは、コミットするまで確定しません。コミットを修正すればIDも変わります。変更履歴はGitへ任せ、メモには検証した基準と現在の差分を残します。

解決済みの問題をもう一度直す条件

機能メモに「解決済み」とあり、修正も現在のコードに残っているなら、古いログだけを根拠に再修正はしません。

もう一度対応するのは、たとえば次の証拠があるときです。

• 現在の環境で問題が再現する
• 関連テストが失敗する
• 機能メモとコードが明らかに違う
• 新しい変更による再発経路が見つかった
• 一部の画面にしか修正が反映されていない

再対応するときは、「今も残っている証拠」「以前の修正では足りない理由」「今回触る範囲」を先に示してもらいます。

まずは短い指示で試してみる

いきなり完璧な機能メモを作る必要はありません。

この記事の「コピーして使う指示」をAIエージェントへ渡し、繰り返し調べられている機能を1つだけ選ぶところから始められます。

Codexでプロジェクト全体に守ってほしい部分はAGENTS.mdへ、個別機能の現在仕様はdocs/features/へ分けます。ほかのAIエージェントを使う場合は、その製品が指定するルールファイルや設定方法を確認してください。

まとめ：履歴、ルール、現在仕様を混ぜない

私が今のところ分かりやすいと考えている分け方は、次のとおりです。

• Gitには過去の変更履歴を残す
• AGENTS.mdには毎回守る作業ルールを置く
• 機能メモには現在の仕様を残す
• 現在のコードとテストで、メモが古くないか確認する
• 解決済みの問題は、今も残る証拠を見てから再対応する
• テストは省略ありきにせず、変更と影響範囲に合わせて選ぶ
• 実装と機能メモを同じ作業の中で更新する

私はまだ、この方法を長期間運用して効果を測ったわけではありません。

それでも、「過去の記録」と「今の正解」を分けておけば、AIエージェントが同じ調査を始めたときに、なぜ必要なのかを確認しやすくなります。