2026/11/02
AI活用
Codexに迷わせない保守ルールづくり――散在する規約をAGENTS.mdへ集約する手順
対象読者：上級者向け
ルール探しから始まる保守作業
架空の中小企業が運用する受注管理システムを考えます。開発担当者は、APIの項目名変更や依存ライブラリの更新に着手するたび、README、社内Wiki、CI設定、テストコード、過去のレビュー履歴を行き来しています。目的はコードを直すことだけではありません。既存クライアントとの互換性を守り、所定のテストを通し、変更してはいけない生成物や運用設定に触れず、レビュー可能な差分に収める必要があります。
従来の道具でも、この確認は可能です。全文検索で関連語を探し、Gitの履歴から変更理由を読み、Wikiの規約と実際のコードを照合すれば、必要な情報へたどり着けます。しかし、ルールが一つの場所にまとまっていないと、担当者ごとに検索語や参照範囲が変わります。レビューで初めて「そのディレクトリでは別のテストが必要です」「その設定は運用チームの管理対象です」と分かり、計画や実装を戻すこともあるでしょう。
ここで扱う中心課題は、Codexにコードを書かせることではなく、作業開始前に参照すべき保守ルールをAGENTS.mdへ整理することです。AGENTS.mdはCodexが認識する任意のファイルであり、存在する場合は作業前に永続的なリポジトリ指針として読み込まれると公式資料で説明されています（出典: OpenAI Cookbook）。ただし、ファイルを置けば正しい規約が自動的に完成するわけではありません。何を正式な根拠とみなすか、どの範囲へ適用するか、例外を誰が承認するかは人が決めます。
この記事では、Git、テスト、CI、リポジトリ構造を理解している開発者を対象にします。散在した資料の棚卸し、根拠付きの草案作成、同一課題を使った適用前後の比較、人による承認までを一続きの保守工程として扱います。以下の手順とお願い文は実務への導入案であり、特定のリポジトリで検証済みの結果ではありません。
手戻りを生む五つの分断
保守作業の手間は、単なる資料探しだけではありません。最初に発生するのは探索です。担当者はREADMEで開発手順を読み、CI設定から実際の検証コマンドを特定し、リンターやフォーマッターの設定を確認します。Wikiに設計上の制約があれば、現在のコードと矛盾していないかも見なければなりません。過去のレビューコメントは有力な手掛かりですが、その場限りの提案なのか、現在も有効なチーム規約なのかをコメントだけで判断するのは危険です。
二つ目は転記です。見つけたルールを作業メモやCodexへの依頼文へ写す際、条件や対象範囲が落ちやすくなります。「テストを実行してください」だけでは、単体テストと結合テストのどちらが必要なのか分かりません。「生成ファイルを編集しないでください」と伝えても、該当するパスがなければ判断が揺れます。三つ目は分類で、全体規約、特定ディレクトリの規約、今回だけの要件を分ける作業です。ここが曖昧だと、一時的な依頼が永続ルールとして残る恐れがあります。
四つ目は計画の修正です。Codexが変更案を作った後で未提示の制約が判明すると、対象ファイル、テスト戦略、差分の分割方法を見直すことになります。最後はレビューの再実施です。規約違反を直した差分は再確認が必要になり、機能要件に集中したいレビュー担当者が、形式的な指摘を繰り返すことになります。
重要なのは、AGENTS.mdでこれらの工程を完全に消せると考えないことです。初回の棚卸しや、ルール変更時の更新は残ります。減らせる可能性があるのは、作業ごとに同じ資料を探し、同じ制約を依頼文へ転記し、指示漏れをレビューで発見する繰り返しです。正式な根拠が不明な規則まで書き込むと、かえって古い制約を固定化します。そのため、集約対象は「繰り返し適用され、根拠と適用範囲を説明できるルール」に絞る必要があります。
AGENTS.mdで変える工程と人に残す判断
比較条件をそろえるため、入力を「同じコミットのリポジトリ、同じ保守チケット、同じ変更権限」、成果物を「変更計画、コード差分、テスト結果」、品質条件を「既存仕様、チーム規約、CI条件を満たすこと」と定めます。そのうえで、AIを使わない場合とAGENTS.mdを参照するCodexの場合を対応付けます。
| 工程 | 従来の進め方 | AGENTS.mdを使う進め方 | 人に残る判断 |
| --- | --- | --- | --- |
| 資料探索 | 作業ごとにREADMEやWikiを検索 | 繰り返し使う規約を最初の参照先へ集約 | 根拠資料が現行かを判断 |
| ルール転記 | チケットや依頼文へ都度記載 | Codexが永続的な指針として参照 | 今回固有の要件を追加 |
| 作業計画 | 担当者が制約を照合して作成 | Codexに制約付き計画の草案を依頼 | 設計方針と影響範囲を承認 |
| 実装と検証 | 規約を見ながら変更とテスト | 規約に記載した境界と基準を踏まえて補助 | 差分とテスト結果を確認 |
| レビュー | 指示漏れも含めて指摘 | 機械的な漏れを事前確認 | 例外、品質、事業影響を判断 |
公式資料では、AGENTS.mdにリポジトリの目的と概要、コーディング規約、テスト基準、関連する文脈ファイル、プロジェクト固有の振る舞い、スコープと境界などを記載できると説明されています（出典: OpenAI Cookbook）。これを実務へ当てはめるなら、「何を目指すリポジトリか」だけでなく、「変更前に何を読むか」「どの検証を行うか」「どこへ触れてはいけないか」まで、根拠を示して書く構成が考えられます。
Codexに任せるのは、資料候補の列挙、重複や矛盾の抽出、草案の整形、ルールを考慮した計画案の作成です。組織上の正式な決定、例外の許可、セキュリティ境界の変更、実行コストが高い検証の要否までは委ねません。この境界が明確なら、AGENTS.mdは人の判断を置き換える規則集ではなく、判断前の探索と転記を減らす入口として使えます。
根拠を失わない棚卸しの準備
作業前に、対象リポジトリの既定ブランチ、テスト構成、主要ディレクトリ、コード所有者、変更承認の流れを理解しておきます。Gitの差分と履歴を読めること、CI設定やパッケージ管理ファイルから検証方法を特定できることも前提です。機密情報を含むWikiやチケットを参照する場合は、Codexへ渡してよい範囲を社内規程に沿って決めます。認証情報、顧客データ、非公開URLをそのままAGENTS.mdへ転記してはいけません。
棚卸しでは、ルール候補ごとに「内容」「適用範囲」「根拠」「確認者」「状態」を記録します。状態は、確定、要確認、廃止候補など、チーム内で意味が共有できる区分にします。READMEに書かれたコマンドでもCIで使われていなければ、直ちに正式ルールとは扱いません。逆に、CI設定だけに存在する必須チェックは、開発者向け資料への記載漏れかもしれません。Codexには矛盾を解決させず、矛盾箇所と参照元を並べてもらいます。
コピーして使う、読み取り専用の棚卸し依頼例です。これは提案であり、パスや正式な資料名は対象リポジトリに合わせて置き換えます。
このリポジトリで繰り返し適用される開発・保守ルールを調査してください。
この段階ではファイルを変更しないでください。
README、開発者向け文書、CI設定、テスト設定、リンター設定、
コード所有情報、関連する履歴を確認してください。
候補ごとに次を示してください。
- ルールの要約
- 適用されるパスまたは作業
- 根拠となるファイルと該当箇所
- 現在のコードやCIとの整合性
- 矛盾、曖昧さ、確認が必要な点
レビューコメントや履歴上の発言だけを正式規約と断定しないでください。
機密情報らしい内容は転記せず、存在と確認先だけを報告してください。
出力を受け取ったら、担当者は根拠ファイルを実際に開き、記述と現行設定が一致するかを確認します。資料にない規則を「一般的なベストプラクティス」という理由だけで追加しないことも大切です。AGENTS.mdの目的は理想の開発規約を新設することではなく、既に承認されている知識を再利用しやすくすることだからです。
根拠付きAGENTS.mdを作る五段階
作成は五段階に分けると管理しやすくなります。第一段階では、前章の読み取り専用調査を実行し、候補一覧だけを作ります。第二段階では、担当領域の責任者が各候補を確定、保留、除外へ分類します。第三段階でCodexにAGENTS.mdの草案を依頼し、第四段階で差分を人がレビューします。第五段階では、小さな保守課題に適用してから正式に承認します。
CodexにはAGENTS.mdを生成する`/init`コマンドがあり、ディレクトリの内容からファイルを作成しようとすると公式資料で紹介されています（出典: OpenAI Cookbook）。ただし、根拠や適用範囲を厳密に管理したい既存リポジトリでは、自動生成された内容も未承認の草案として扱うべきです。既存ファイルがある場合は上書きを前提にせず、現在の記述と棚卸し結果の差分を先に確認します。
草案作成用のお願い文の例です。書き込みを許可する前に、対象ファイルと予定内容を提示させます。
承認済みのルール候補だけを使い、リポジトリ直下のAGENTS.mdの草案を提案してください。
まだファイルは変更しないでください。
構成には次を含めてください。
- リポジトリの目的
- 全体に適用するコーディング規約
- テストと検証の基準
- パスごとの適用範囲
- 変更禁止または別承認が必要な領域
- 作業前に読む関連資料
- 不明点がある場合の停止条件
各ルールには根拠となるリポジトリ内のパスを添えてください。
根拠資料にない要件は追加せず、不明点として分離してください。
同じ内容の重複、相互に矛盾する指示、広すぎる禁止事項も報告してください。
最後に、作成予定の見出しと変更対象ファイルを示し、承認を待ってください。
架空の記載例では、「`packages/api`の変更ではAPI用の既存テストを実行してください。根拠はCI設定と同ディレクトリのテスト構成です」「`generated`配下は生成工程の出力であり、直接編集せず生成元を変更してください」といった形が考えられます。ただし、実際のパスや検証方法が根拠資料に存在するときだけ採用します。「保守性を高めてください」のような評価基準が曖昧な表現や、すべての変更に全テストを要求する過剰な制約は避けます。短くても、対象、行動、根拠、例外時の確認先が分かる記述のほうが運用しやすいでしょう。
同じ保守課題による適用前後の検証
AGENTS.mdの効果は、読みやすさだけで判断しません。同じ状態のリポジトリと同じ依頼を使い、適用前後の計画と差分を比較します。架空の評価課題として「APIレスポンスの項目名を変更し、互換性に関係するテストを更新する」を設定します。これは実施例の提案であり、実在するシステムでの検証結果ではありません。
比較の第一段階では、AGENTS.mdを参照しない条件でCodexに読み取り専用の変更計画を作らせます。第二段階では、同じコミット、同じ課題文、同じ権限、同じモデル設定を用意し、承認済みのAGENTS.mdを参照する条件で計画を作らせます。計画には、対象ファイル、守るべき互換性、実行予定のテスト、触れない領域、未解決の質問を含めます。条件の違いをAGENTS.mdの有無にできるだけ限定しなければ、比較結果を解釈できません。
計画を承認した後にコード差分まで比べる場合は、互いに影響しない作業環境を用意し、外部書き込みやデプロイを許可しない範囲で実施します。実行する検証コマンドは、リポジトリ内で確認できたものだけを使います。Codexの説明だけでテスト成功とせず、終了状態、失敗内容、変更されたファイルを人が確認してください。
| 確認項目 | 観察する証拠 | 良否の判断 |
| --- | --- | --- |
| 規約の把握 | 計画に列挙された制約と根拠 | 適用対象を過不足なく説明できるか |
| 対象範囲 | 変更予定または変更済みファイル | 禁止領域や無関係な領域へ広がっていないか |
| 検証計画 | 実行予定のテストと理由 | 変更内容に対応し、実在する手順か |
| 手戻り | 人が追加した指示と再作成回数 | 規約の再説明が減ったか |
| 差分品質 | 実際の差分とレビュー指摘 | 機能要件と規約を両方満たすか |
比較では、AGENTS.md適用後のほうが必ず優れるとは限りません。誤った規則が入っていれば、Codexは一貫して誤った方向へ進む可能性があります。適用前の計画で見つかり、適用後に消えた有益な探索も確認対象です。結果が悪化した場合はお願い文を足すのではなく、まずAGENTS.mdの根拠、範囲、表現を修正します。評価記録には、準備、確認、修正に要した作業も含めることで、集約作業そのものの負担を隠さず判断できます。
人が承認する正当性・機密性・制約の強さ
最終承認では、文面の読みやすさより先に正当性を確認します。各ルールが、現在のCI設定、承認済み設計文書、チーム規約、実際のコード構造のいずれに基づくのかを追跡します。過去のレビューコメントしか根拠がない場合は、発言者や担当責任者へ確認し、正式規約として残すかを決めます。資料同士が矛盾する場合、Codexに多数決をさせてはいけません。運用責任者が正しい情報源を決め、誤っている資料も併せて更新する必要があります。
機密性の確認では、認証情報や個人情報だけでなく、社外秘のシステム構成、内部ホスト名、顧客固有の運用手順が紛れ込んでいないかを見ます。AGENTS.mdがバージョン管理されるなら、その閲覧範囲も考慮します。秘密情報の値を記載する代わりに、「所定の秘密管理方法を利用し、値をリポジトリへ保存しないでください」のような行動境界と、アクセス可能な正式資料への参照だけを残す方法が考えられます。
制約の強さも審査対象です。「設定ファイルを変更しないでください」と一律に禁止すると、本来必要な保守まで止まるかもしれません。「変更には運用担当者の承認が必要です」とすべきなのか、「今回の作業範囲外です」とすべきなのかを区別します。テスト基準も同様で、すべての変更へ最も重い検証を要求すると、日常的に無視されるファイルになりかねません。変更種別や対象パスに応じて、必須の確認と追加承認が必要な確認を分けます。
承認時には、開発責任者、対象領域の所有者、必要に応じてセキュリティや運用の担当者が差分を読みます。Codexが作ったという理由で承認範囲を省略せず、人が作った規約変更と同じ手続きを適用してください。コミット、プッシュ、デプロイ、外部サービスへの書き込みは、AGENTS.md作成とは別の承認単位にします。承認日、確認者、次回見直しの契機をチームの既存方式で記録すれば、ルールが古くなった際にも追跡しやすくなります。
小さな対象から効果を確かめる運用
導入効果は、削減率を先に決めず、工程ごとの観察で確かめます。候補になる指標は、作業開始から計画承認までに参照した資料数、規約を追加説明した回数、計画の作り直し回数、規約漏れに関するレビュー指摘、不要なファイル変更、テスト手順の訂正回数です。件数だけでなく、どのルールが役立ち、どの記述が誤解を生んだかも残します。AGENTS.mdの準備、レビュー、更新にかかった手間を含めなければ、従来工程との公平な比較にはなりません。
適用前後で成果物の品質条件を変えないことも欠かせません。従来は人が確認していた互換性やセキュリティを、導入後だけ評価対象から外せば、見かけ上は速くなります。反対に、AGENTS.md導入を機に検証項目を増やした場合は、時間だけでなく検出できた問題や監査可能性も別に評価します。少数の課題では偶然の影響が大きいため、異なる種類の保守作業で記録を蓄積し、定性的な傾向として判断するのが妥当です。
最初の一歩は、リポジトリ全体の規約を一度に統合することではありません。レビューで同じ指摘が繰り返されている一つのディレクトリ、またはテスト手順が散在している一種類の保守作業を選びます。読み取り専用の棚卸しを行い、三つから五つ程度のルール候補について根拠と所有者を確認し、短い草案を作ります。その後、同じ条件の小さな課題で計画を比較し、人が承認できる差があるかを見てください。
期待できるのは、判断そのものの自動化ではなく、判断に入る前の探索、転記、分類を再利用可能にすることです。試行で規約の再説明が減らなければ、AGENTS.mdを長くする前に、対象範囲や根拠の明確さを見直します。反対に有効な記述が確認できたら、隣接する領域へ少しずつ広げます。この小さな更新と検証の循環が、形だけの規約ファイルにしないための現実的な運用になります。