月曜の朝、取引先から「受注データのCSV出力で、一部の文字が欠けることがある」と連絡が入ります。対応するのは、日常的に複数案件を掛け持ちしている中小企業の開発担当者です。目的は不具合を直すことですが、担当者が最初に行うのはコードの修正ではありません。課題管理表で過去の対応履歴を探し、READMEや社内Wikiを読み、IDEの検索機能でCSV出力に関係するファイルを絞り込み、テストの実行方法やリリース時の注意事項を確かめます。



AIを使っていない現場でも、検索ツール、Gitの履歴、テストコード、チェックリストなどは活用されています。それでも着手時の調査が繰り返されるのは、必要な知識が複数の場所に分かれているためです。「CSVの文字コードはどこで決まるのか」「共通ライブラリを変更してよいのか」「最低限どのテストを通すのか」といった判断材料が、コード、文書、担当者の記憶に散在しています。

調査を終えて修正案を作っても、レビューで「その処理は別システムでも使っています」「この案件では結合テストも必要です」と指摘されれば、影響範囲の確認からやり直しです。担当者の能力不足ではなく、リポジトリ固有の前提を毎回組み立て直す工程に負担があります。この記事では、Codexが認識する任意のリポジトリ案内ファイルであるAGENTS.mdに、保守時に繰り返し参照する情報を集約し、調査、修正、確認の流れをどう変えられるかに焦点を当てます。

保守着手時の作業を分解すると、負担は単なる「資料探し」だけではありません。資料の所在を探し、内容を現在のコードと照合し、今回の障害に関係する箇所を分類し、実行すべき確認項目を組み立て、最後に認識が合っているかを別の担当者へ確認します。同じリポジトリを以前に扱った人でも、間が空けば似た調査を繰り返すことになるでしょう。



具体的には、資料探しではREADME、設計書、課題管理表、テスト設定などを横断します。転記では、見つけた制約やコマンドを作業メモへ写します。分類では、障害に直接関係する情報と、変更してはいけない境界を分けます。下書きでは、修正候補とテスト方針を整理します。確認では、古い文書を参照していないか、共通部品への影響を見落としていないかを人が点検します。

特に手戻りにつながりやすいのは、調査結果そのものより「どの情報を根拠に判断したか」が残っていない場合です。たとえば、担当者が既存テストを一つ実行して成功しても、それがチームの定める必須確認を満たすとは限りません。逆に、すべてのテストを無条件に実行すれば、今回の変更とは無関係な準備まで必要になる場合があります。

AGENTS.mdで減らしたいのは、こうした判断を人から取り除くことではありません。リポジトリの目的、規約、テスト基準、参照先、変更範囲など、案件ごとに変わりにくい前提を再利用しやすくすることです。障害の原因や修正の妥当性は毎回検討する必要がありますが、その検討を始める地点まで戻る反復は減らせる可能性があります。

OpenAIの公式クックブックでは、AGENTS.mdは任意のファイルですが、存在する場合はCodexが作業前に読む永続的なリポジトリガイダンスとして説明されています。記載候補には、リポジトリの目的、コーディング規約、テスト基準、関連するコンテキストファイル、プロジェクト固有の振る舞い、スコープと境界があります（出典: OpenAI Developers Cookbook）。これは2026年10月29日に取得した公式資料に基づく説明であり、公開時期を新機能の発表日として扱うものではありません。



同じ障害票、同じリポジトリ、同じ品質条件で比べると、工程の対応は次のように整理できます。

| 工程 | AIを使わない場合 | CodexとAGENTS.mdを使う場合 | 人が担うこと |
|---|---|---|---|
| 前提確認 | 文書や履歴を個別に探索 | AGENTS.mdの参照先と境界を起点に調査 | 記載内容が現状と一致するか判断 |
| 影響範囲 | 検索結果から手作業で整理 | 関連ファイルと呼び出し関係の候補を整理させる | 見落としや過剰な範囲を確認 |
| 修正案 | 担当者が変更箇所を下書き | 制約を踏まえた案と根拠を提示させる | 採用する設計を決定 |
| テスト | 手順書から必要項目を選択 | 記載済みの基準に沿って候補を組み立てる | 実行範囲と結果を承認 |

AGENTS.mdはコードやテスト結果を置き換える「正解集」ではありません。古い規約を書けば、Codexの提案も古い前提に引っ張られる可能性があります。また、障害票にない業務要件や、担当者だけが知る運用上の例外までは自動的に補えません。そのため、Codexには探索と整理を補助させ、仕様の解釈、変更可否、受け入れ判断は人に残します。

効果が期待できるのは、案件固有の入口が明示されているときです。反対に、AGENTS.mdへ設計書の全文や一時的な進捗まで詰め込むと、どれが恒久的なルールなのか分かりにくくなります。長く使う前提、詳しい情報の参照先、禁止事項を中心にし、個別障害の事実は依頼文や課題管理表で渡す分担が適しています。

作成前には、過去の保守で何度も確認した質問を集めます。候補は「最初に読む設計資料」「変更してよいディレクトリ」「触れてはいけない生成物」「使用中の言語やフレームワーク」「テストの選び方」「外部システムへの接続条件」「コミットやデプロイに必要な承認」などです。情報源が見つからない項目は推測で埋めず、未確認事項として担当者を明記します。



次の記載例は、公式仕様の転記ではなく、保守チーム向けの提案例です。実際のファイル名やテストコマンドは、対象リポジトリで確認した内容に置き換えてください。

```markdown
このシステムは受注データを取り込み、社内処理用のCSVを生成します。

- README.md
- docs/csv-spec.md
- 対象機能に近い既存テスト

- 依頼範囲外のリファクタリングは提案だけにとどめてください。
- 生成済みファイルは直接編集しないでください。
- 外部送信、デプロイ、コミットは個別の承認なしに行わないでください。

- 変更箇所に対応する既存テストを確認してください。
- 実行コマンドはリポジトリ内の正式な手順から特定してください。
- 実行できないテストは、理由と未確認のリスクを報告してください。

変更候補、根拠、影響範囲、実施した確認、未解決事項を分けてください。
```

公式クックブックでは、`/init`コマンドがディレクトリ内容からAGENTS.mdの生成を試みる方法も紹介されています（出典: OpenAI Developers Cookbook）。ただし、自動生成された内容をそのまま規約として採用するのではなく、実際の保守責任者が確認する必要があります。既存文書と矛盾していないか、実在しない手順が混ざっていないか、秘密情報や認証情報を記載していないかを点検してください。

最初から網羅的な文書を目指す必要はありません。一件の保守で繰り返した確認事項から、根拠を示せる三つから五つ程度を登録し、次の案件で役立ったかを見直すほうが管理しやすくなります。AGENTS.mdの更新担当とレビュー方法も決めておけば、古い知識が固定される危険を抑えられます。

AGENTS.mdを用意した後も、いきなり修正を依頼するのは避けたほうが安全です。初回の依頼では、対象の障害票、期待する正常動作、再現条件、変更してよい範囲を渡し、読み取り専用の事前調査を求めます。Codexの調査結果を人が確認してから、修正とテストへ進む二段階の運用にすると、誤った前提のままファイルが変更される可能性を抑えられます。



以下はコピーして調整できる提案例です。山括弧の部分を対象案件の事実に置き換えてください。

```text
このリポジトリに適用されるAGENTS.mdを読み、記載された規約と境界に従ってください。
対象は「＜障害の概要＞」です。期待する動作は「＜正常時の条件＞」、確認済みの再現条件は「＜入力と操作＞」です。

この段階ではファイルを変更しないでください。読み取り専用で調査し、次の項目を報告してください。
1. 関連する可能性があるファイルと、その根拠
2. 現在の処理経路と、問題が起きる候補地点
3. 影響を受ける可能性がある呼び出し元、出力、テスト
4. AGENTS.mdや既存資料から確認できた制約
5. 情報不足のため人に確認すべき点
6. 最小限の修正方針と、実行を提案するテスト

根拠にしたファイル名と箇所を示してください。推測は事実と分けてください。調査結果の承認を受けるまで、修正、外部送信、コミット、デプロイは行わないでください。
```

調査結果が妥当なら、「承認した修正方針の範囲だけを実装し、差分、実行したテスト、結果、未確認事項を報告してください」と続けます。この追加依頼も提案例であり、Codexが常に正しい原因を特定したり、すべてのテストを実行できたりすることを保証するものではありません。

成果物として期待するのは、コード差分だけではありません。関連ファイルと根拠、想定した影響範囲、実際に実行した確認、実行できなかった確認を分けた報告も含めます。これにより、レビュー担当者はCodexの説明をそのまま信頼するのではなく、どの前提を再確認すべきか判断しやすくなります。

Codexが修正案を出した後は、仕様、差分、検証結果の順で確認します。最初に見るのはコードの巧拙ではなく、期待する正常動作の理解です。障害票、設計資料、既存テストと提案内容を照合し、入力、出力、エラー時の扱い、互換性の条件が一致しているかを確かめます。要件が曖昧なら、実装を進める前に業務担当者へ戻す必要があります。



影響範囲の確認では、変更ファイルだけでなく、その処理を利用する別機能、設定値、出力形式、ログ、エラー処理にも目を向けます。Codexが「影響なし」と説明していても、根拠となる検索範囲や呼び出し関係を確認してください。依頼外の整形やリファクタリングが混ざっていれば、必要な変更と分離させます。差分が小さいことと、影響が小さいことは同義ではありません。

テスト結果は、成功という要約だけで承認しません。実行したコマンド、対象となったテスト、終了状態、失敗や警告の有無を確認します。AGENTS.mdで定めた基準と照らし、未実行の確認があれば理由を記録します。外部サービス、認証情報、本番相当データが必要で実行できない場合は、人が別環境で確認するのか、今回の承認条件から除外するのかを明示します。

最後に、AGENTS.md自体へ追記すべき知識が生まれたかを判断します。今回だけの障害内容や一時的な回避策は課題管理表へ残し、将来も繰り返し使うテスト基準や変更境界だけを候補にします。追記する場合も、既存規約の所有者によるレビューを通します。Codexの出力を承認資料に変えるのは、根拠と未確認事項を人が照合する工程です。

導入効果は「AIを使ったら速くなったはず」という感想ではなく、工程ごとに確かめます。比較対象には、規模と種類が近い保守案件を選びます。入力となる障害票、求める成果物、品質条件をそろえたうえで、調査、修正、確認に要した時間や反復回数を記録してください。準備したAGENTS.mdの作成・更新時間と、Codexの誤認を直すための時間も含めます。



調査工程では、関連ファイルと必須資料を特定するまでの時間、同じ資料を探し直した回数、担当者への確認件数を記録できます。修正工程では、承認前に出た方針のやり直し、依頼範囲外の差分、追加説明が必要だった回数が観察対象になります。確認工程では、必須テストの漏れ、実行結果の再取得、レビューで見つかった前提違いを残します。数値が改善しなくても、どの情報がAGENTS.mdに不足していたかを特定できれば次の更新材料になります。

評価時には、短縮された時間だけでなく、新たに増えた作業も見ます。AGENTS.mdの保守、プロンプトの調整、調査結果の検証が重ければ、対象業務が小さすぎるか、文書の粒度が合っていない可能性があります。反対に、同じ規約やテスト基準を何度も確認するリポジトリでは、準備を再利用できるため効果が現れやすいと考えられます。ただし、実際の効果は案件の複雑さや既存文書の品質に左右されます。

最初の一歩は、過去一件の保守記録を開き、着手時に二度以上探した情報を三つ選ぶことです。その根拠を確認して短いAGENTS.mdへ記載し、次の小規模な修正では読み取り専用の調査だけをCodexへ依頼します。修正まで一度に任せず、調査報告が人の見立てと合うかを確認してください。そこで再利用できた情報、足りなかった情報、誤解を招いた表現を記録すれば、自社の保守工程に合う案内ファイルへ少しずつ育てられます。

- Iterating Development Workflows with Codex