Codexにソースコード全体レビューを任せるためのMarkdown指示書テンプレート

Codexに「このプロジェクト全体をレビューして」と頼みたい場面が増えてきました。小さな修正なら、チャット欄に数行書くだけでもそれなりに進みます。ただ、ソースコード全体のレビューになると話が変わります。

対象ファイルが多い。設計の前提もある。テストの流し方もプロジェクトごとに違う。さらに、セキュリティ、パフォーマンス、保守性、不要コード、ドキュメントの古さまで見てほしい。こうなると、毎回のプロンプトだけで全部を伝えるのはかなりしんどいです。

そこで今回は、Codexにプロジェクト全体のソースコードレビューを任せる前提で、どんな指示を渡すべきか、どのMarkdownファイルを用意しておくとよいかを実験ログとして整理します。結論から言うと、毎回の依頼文を長くするより、プロジェクト内にレビュー用のMarkdownを置いて、Codexが読める形で「判断基準」を残しておくのがかなり使いやすいです。

この記事は、Codexで大規模な修正を自動実行させる話ではありません。まずは「レビュー役」として使う話です。いきなり全部直させるより、最初は問題の洗い出し、優先度付け、修正方針の整理までを任せる。そこから人間が確認して、小さな単位で修正タスクに分ける。この流れが現実的だと感じました。

結論：Codexに渡すべきものは「目的」「範囲」「判断基準」「完了条件」

Codexにソースコード全体レビューを依頼するとき、いちばん避けたいのは「なんとなく全部見て、なんとなく改善案を出して」という頼み方です。これだと、Codexは広く浅く見ます。結果として、重要な問題と細かい好みの問題が混ざり、レビュー結果が使いにくくなります。

OpenAIのCodexベストプラクティスでも、良いプロンプトには「Goal」「Context」「Constraints」「Done when」を含める考え方が紹介されています。日本語で言えば、目的、背景、制約、完了条件です。これはコードレビューでもそのまま使えます。

今回のレビュー依頼で最低限入れたい要素は、次の4つです。

• 何のためにレビューするのか
• どの範囲を見て、どの範囲は見ないのか
• 何を問題として扱うのか
• どんな形式で結果を返してほしいのか

たとえば「本番障害につながる問題を優先して見たい」のか、「リファクタリング候補を集めたい」のか、「新メンバーが入りやすい構成になっているか見たい」のかで、見るポイントは変わります。ここを曖昧にしたまま全体レビューを頼むと、AIは親切にいろいろ拾ってくれますが、実務で使うにはノイズが多くなりがちです。

まず作るMarkdownファイル一覧

今回、プロジェクトに置くならこの構成が扱いやすいと感じました。

AGENTS.md
README.md
docs/
  architecture.md
  setup-and-commands.md
  code-review.md
  security-review.md
  performance-review.md
  review-scope.md
  review-output-template.md
  ai-review-log.md

全部を最初から完璧に書く必要はありません。むしろ、最初から気合いを入れすぎるとメンテできなくなります。最初に厚くするべきなのは、AGENTS.md と docs/code-review.md です。次に、プロジェクト構造が複雑なら docs/architecture.md。セキュリティが重要なら docs/security-review.md。この順番で育てるのがよさそうです。

Codexの公式ドキュメントでは、Codexは作業前に AGENTS.md を読み、グローバル指示とプロジェクト固有の指示を組み合わせて使うと説明されています。また、レビュー用のガイドラインを AGENTS.md に含めると、GitHub連携でのコードレビューにも使えるとされています。つまり、AGENTS.md は単なるメモではなく、Codexにとっての作業ルール置き場として扱えます。

AGENTS.mdに書くこと

AGENTS.md は、Codexに毎回読ませたい共通ルールです。ここに全部を書きすぎると重くなるので、役割は「入口」にします。プロジェクトの概要、作業時の禁止事項、レビュー時に参照するMarkdownへのリンクを書いておくイメージです。

AGENTS.mdのテンプレート

# AGENTS.md

## Project overview

このリポジトリは、〇〇を目的としたアプリケーションです。
主な利用者は〇〇で、重要な品質要件は次の通りです。

- 本番データを壊さないこと
- 認証・認可の抜け漏れを防ぐこと
- 既存の画面挙動を不用意に変えないこと
- 小さな差分でレビューしやすく保つこと

## Repository layout

- `src/`: アプリケーション本体
- `tests/`: 自動テスト
- `docs/`: 設計・運用・レビュー方針
- `scripts/`: 開発・運用補助スクリプト

## Review guidelines

コードレビューを行う場合は、必ず次のファイルを参照してください。

- `docs/code-review.md`
- `docs/security-review.md`
- `docs/performance-review.md`
- `docs/review-output-template.md`

レビューでは、単なる好みの指摘よりも、障害・セキュリティ・保守性に関わる問題を優先してください。

## Do not rules

- 秘密情報、APIキー、トークン、パスワードを表示しない
- `.env` や認証情報ファイルを読み上げない
- 本番環境へ接続しない
- 依頼なしにファイルを変更しない
- レビュー依頼時は、原則として修正まで実行しない
- 不明点を推測で断定しない

## Done means

レビュー完了時は、次の形式で出力してください。

1. 重大度別の指摘一覧
2. 影響範囲
3. 根拠となるファイル・関数・処理
4. 推奨対応
5. すぐ直すべきものと、後回しでよいもの

ポイントは、AGENTS.md に「レビュー依頼時は修正しない」と明記しておくことです。全体レビューでは、AIにそのまま直させるより、まず洗い出しに徹してもらったほうが安全です。特に、プロジェクト全体にまたがるリファクタリングは、想像以上に影響範囲が広がります。

docs/code-review.mdに書くこと

docs/code-review.md は、レビューの本体です。ここには「このプロジェクトで何を問題として扱うか」を書きます。人間のレビューでも同じですが、レビュー観点が曖昧だと、指摘の粒度がバラバラになります。

Codexに全体レビューを頼む場合は、レビュー観点を優先度付きで書いておくと使いやすいです。

code-review.mdのテンプレート

# Code Review Guide

## Review priority

レビューでは、次の順番で優先してください。

### P0: すぐ確認が必要

- 認証・認可を迂回できる可能性
- 個人情報や秘密情報の漏えいにつながる処理
- データ破壊や重複登録の可能性
- 本番障害につながる明らかな例外処理不足
- 外部APIの失敗時に復旧できない処理

### P1: 早めに直したい

- 境界値やnullの扱いが不十分
- トランザクションや排他制御の不足
- テストがない重要ロジック
- 仕様変更時に壊れやすい密結合
- ログが不足して障害調査しにくい処理

### P2: 改善候補

- 関数やクラスが大きすぎる
- 命名が分かりにくい
- 重複コードが多い
- コメントと実装がずれている
- READMEや設計書が古い

### P3: 好み・将来改善

- スタイルの細かな統一
- 今すぐ影響しない軽微なリファクタリング
- 将来の拡張に備えた提案

## Review policy

- 指摘には、必ず根拠となるファイル名と該当箇所を含める
- 推測の場合は「推測」と明記する
- 再現手順や確認コマンドがある場合は書く
- 影響が小さい好みの指摘を大量に出さない
- 修正案は、小さなPRに分けられる単位で提案する

## Output style

各指摘は次の形式にしてください。

- 重大度: P0 / P1 / P2 / P3
- 場所: ファイル名、関数名、処理名
- 内容: 何が問題か
- 影響: 起きうる不具合や運用上の困りごと
- 対応案: どう直すか
- 確認方法: テスト、コマンド、手動確認

このファイルを作っておくと、「レビューしてください」の意味がかなり具体的になります。Codexに限らず、人間のレビューでも使えます。レビューの文化をMarkdownに落とす感じです。

docs/review-scope.mdで対象範囲を決める

ソースコード全体レビューでありがちな失敗は、対象範囲が広すぎることです。全体を見ること自体は悪くありません。ただ、全部を同じ深さで見るのは現実的ではありません。

そこで、docs/review-scope.md に「重点的に見る場所」と「今回は見ない場所」を書きます。

# Review Scope

## Focus areas

今回の全体レビューでは、次の領域を優先して確認する。

1. 認証・認可まわり
2. 外部API連携
3. DB更新処理
4. バッチ・定期実行処理
5. エラーハンドリングとログ

## Lower priority areas

次の領域は、重大な問題が見つかった場合のみ指摘する。

- 表示文言の細かな揺れ
- CSSの細かな整理
- テストデータの軽微な重複

## Out of scope

今回は次を対象外とする。

- デザイン全面刷新
- フレームワーク移行
- ライブラリの大規模入れ替え
- 本番環境への接続確認
- 秘密情報ファイルの中身確認

## Review depth

- まず全体構造を把握する
- 次に重要領域を深掘りする
- 最後に修正タスクへ分解する

ここまで書くと、Codexのレビューがかなり実務寄りになります。特に「今回は対象外」を書くのが大事です。AIに限らず、優秀な人ほど気になる点をたくさん見つけます。でも、今やりたいことから外れた指摘が増えると、結局動けなくなります。

docs/architecture.mdで設計の前提を渡す

レビュー品質を上げるには、コードだけでなく設計の前提も必要です。たとえば、あえて冗長にしている処理、外部サービスの制約でそうせざるを得ない処理、過去の障害対策として残している処理などは、コードだけ見ても分かりません。

ここを何も書かずにレビューさせると、Codexが「もっとシンプルにできます」と提案してくれることがあります。ただ、そのシンプル化が過去の障害対策を消す方向だと危険です。

# Architecture Notes

## System purpose

このシステムは〇〇を行うためのものです。
最も重要なのは、〇〇のデータを安全に扱うことです。

## Main flow

1. ユーザーが〇〇を入力する
2. APIで〇〇を検証する
3. DBへ保存する
4. 外部サービスへ通知する
5. 結果を画面へ返す

## Important constraints

- 外部APIは失敗することがある
- 同じリクエストが再送されることがある
- DB更新は重複実行される可能性がある
- 古いデータ形式も一定期間サポートする

## Historical reasons

- `legacy/` 配下は移行期間中のため、削除提案は慎重に扱う
- `retry` 処理は過去のAPIタイムアウト対策として入っている
- `manualOverride` は運用上必要なため、未使用に見えても削除しない

## Known weak points

- テストが不足している領域: 〇〇
- ログが少ない領域: 〇〇
- 将来分割したい領域: 〇〇

このファイルは、ベテランメンバーの頭の中にある「暗黙知」を外に出す役割があります。AIレビュー以前に、新しく入った人にも効きます。

docs/security-review.mdは必ず分ける

セキュリティ観点は、通常のコードレビューとは分けたほうがよいです。理由は、重大度の判断が違うからです。命名が分かりにくい問題と、トークン漏えいの可能性を同じレビュー表に並べると、優先順位がぼやけます。

# Security Review Guide

## Must check

- 認証が必要なAPIで認証チェックが抜けていないか
- ユーザー権限に応じた認可チェックがあるか
- 入力値を信頼しすぎていないか
- SQLインジェクション、XSS、コマンドインジェクションの余地がないか
- APIキー、トークン、パスワードがコードやログに出ていないか
- エラーメッセージに内部情報を出しすぎていないか
- ファイルアップロードや外部URL取得に制限があるか

## Secrets policy

- `.env` の中身を表示しない
- 秘密情報らしき文字列を見つけた場合は値を伏せて報告する
- ログ出力に秘密情報が含まれる可能性がある場合はP0またはP1で指摘する

## Output rule

セキュリティ指摘は、悪用手順を詳しく書きすぎない。
必要な範囲で、影響と修正方針を説明する。

最後の「悪用手順を詳しく書きすぎない」も入れておくと安心です。レビュー結果をチーム内で共有する場合、必要以上に攻撃手順が具体的だと扱いに困ることがあります。実務では、直すために必要な情報と、広げるべきでない情報を分ける感覚が大事です。

docs/review-output-template.mdで結果の形を固定する

AIレビューで地味に困るのが、毎回出力形式が変わることです。ある日は長文、ある日は箇条書き、ある日は表。これだと、後から比較しにくくなります。

そこで、レビュー結果のテンプレートもMarkdownで用意しておきます。

# Review Output Template

レビュー結果は次の形式で出力する。

## Summary

- 全体評価:
- 重大な懸念:
- すぐ対応すべき件数:
- 後回しでよい件数:

## Findings

### Finding 1

- Severity:
- Area:
- File:
- Problem:
- Impact:
- Recommendation:
- Verification:

## Suggested fix plan

### Phase 1: すぐ対応

- [ ] タスク1
- [ ] タスク2

### Phase 2: 次のスプリントで対応

- [ ] タスク1
- [ ] タスク2

### Phase 3: 余裕があれば対応

- [ ] タスク1
- [ ] タスク2

## Questions for humans

- 判断に迷った点
- 仕様確認が必要な点
- 削除してよいか確認したい点

この形式にしておくと、レビュー結果をそのままIssue化しやすくなります。特に「Questions for humans」は便利です。Codexが迷った点を最後にまとめてもらうと、人間が見るべき場所がはっきりします。

Codexに実際に投げる依頼文

Markdownを用意したら、Codexに投げる依頼文は短くできます。毎回のプロンプトでは、目的と今回の重点だけを書けばよくなります。

全体レビュー用プロンプト

このプロジェクト全体のソースコードレビューをしてください。

目的:
本番障害、セキュリティリスク、保守性の問題を早めに見つけたいです。
今回は修正は行わず、レビュー結果の整理だけをお願いします。

参照してほしいファイル:
- AGENTS.md
- docs/code-review.md
- docs/security-review.md
- docs/performance-review.md
- docs/review-scope.md
- docs/review-output-template.md
- docs/architecture.md

重点的に見てほしい観点:
1. 認証・認可の抜け漏れ
2. DB更新や外部API連携の失敗時処理
3. 例外処理とログ
4. テスト不足の重要箇所
5. 影響範囲が広い密結合

やらないこと:
- ファイル変更はしない
- 依存ライブラリを追加しない
- 本番環境へ接続しない
- 秘密情報の中身を表示しない
- 好みレベルの細かい指摘を大量に出さない

出力:
docs/review-output-template.md の形式で、重大度順にまとめてください。
最後に、修正するならどの順番で小さなPRに分けるべきか提案してください。

この依頼文のポイントは、「修正は行わない」と先に書いていることです。レビューと修正を同時にやると、見つけた問題の全体像が見えないまま差分が膨らむことがあります。まずはレビューだけ。次に、人間が見て、修正タスクに分ける。この段階分けが安全です。

レビュー後に修正を頼むときの依頼文

レビュー結果を見て、P0またはP1だけ直したい場合は、修正範囲を絞って依頼します。

前回のレビュー結果のうち、P0とP1だけを対象に修正案を作ってください。

条件:
- まず修正計画を提示してください
- まだファイルは変更しないでください
- 1つのPRにまとめず、影響範囲ごとに分割してください
- 各修正について、確認方法とテスト方針を書いてください

出力:
1. 修正対象の一覧
2. PR分割案
3. 各PRの目的
4. 変更予定ファイル
5. テスト方法
6. 人間に確認が必要な点

いきなり「全部直して」ではなく、まず修正計画を出してもらいます。ここで人間が確認し、問題なければPR単位に分けて作業させます。AIに任せるほど、このワンクッションが効きます。

やってみて分かったこと

実際にこの形で考えてみると、Codexへの依頼文そのものより、事前に置くMarkdownのほうが大事だと感じました。毎回チャット欄に長々と書くより、プロジェクトの中にレビュー基準を置いたほうが、再利用できます。

特に良かったのは、レビューの優先順位が安定することです。何も指定しないと、AIは「改善できそうなところ」を広く拾います。それ自体はありがたいのですが、実務では「今すぐ直すべきもの」と「そのうち整えたいもの」を分けないと動けません。P0からP3までの基準を作っておくと、レビュー結果をそのままタスク化しやすくなります。

もうひとつ良かったのは、AIにレビューを頼むための準備が、そのまま人間向けの開発ドキュメントになることです。architecture.md や code-review.md を整えると、Codexだけでなく、未来の自分や新しく入ったメンバーも助かります。AI用に書いているようで、実はチームの暗黙知を棚卸ししている感じです。

逆に注意したいこと

注意点もあります。まず、Codexに全体レビューを頼んだからといって、結果をそのまま鵜呑みにするのは危ないです。AIはコードを広く読むのが得意ですが、事業上の事情、過去障害の背景、顧客との約束、運用チームの事情までは、ドキュメントにない限り分かりません。

なので、レビュー結果には必ず「人間に確認が必要な点」を出してもらうのがよいです。特に、削除提案、設計変更、認証まわり、データ移行、外部API仕様に関わる部分は、人間が判断するべきです。

また、全体レビューは一度で完璧に終わらせようとしないほうがよいです。最初は「セキュリティだけ」「DB更新だけ」「外部API連携だけ」のように分けてもいいです。Codexの公式ベストプラクティスでも、複雑な作業では文脈と構造を与えることが重要とされています。大きすぎる依頼は、結局レビューする人間側も読み切れません。

SE視点では「レビュー結果の運用」まで決めたい

SE視点で見ると、AIレビューを導入するときに一番もったいないのは、レビュー結果を出して満足してしまうことです。大事なのは、その後です。

たとえば、レビュー結果を次のように扱うと運用に乗りやすいです。

• P0はその日のうちに人間が確認する
• P1はIssue化して次の作業候補に入れる
• P2はリファクタリング候補としてまとめる
• P3は大量に出しすぎない
• 誤検知や不要な指摘は docs/code-review.md に反映する

AIレビューは、一回きりのイベントではなく、レビュー基準を育てるサイクルにしたほうが効果が出ます。Codexが同じような不要指摘を繰り返すなら、AGENTS.md や code-review.md に「これは指摘しない」と書く。逆に、見逃してほしくない問題があったら、チェック項目を増やす。こうすると、レビューがだんだん自分のプロジェクト向けになります。

ai-review-log.mdでレビュー履歴を残す

最後に、レビュー履歴を残すファイルも用意しておくと便利です。AIに何を見てもらったか、何が出たか、人間がどう判断したかを軽く残します。

# AI Review Log

## 2026-07-06 project-wide-review

### Tool

- Codex

### Request

- プロジェクト全体のコードレビュー
- 修正は行わず、P0〜P3で指摘整理

### Main findings

- P0: 0件
- P1: 3件
- P2: 8件
- P3: 5件

### Human decisions

- P1のうち2件を次回修正
- 1件は仕様確認後に判断
- P2はリファクタリング候補として保留

### Follow up

- docs/code-review.md にログ出力ルールを追加
- docs/security-review.md にトークンマスク方針を追加

このログは、細かすぎる必要はありません。むしろ、軽く続けられることが大事です。後から「前にも同じ指摘が出ていたな」「このルールを追加してから誤検知が減ったな」と見返せるだけで十分役に立ちます。

最小セットならこの3ファイルで始める

ここまでいろいろ書きましたが、最初から全部そろえる必要はありません。まず試すなら、次の3ファイルで十分です。

• AGENTS.md
• docs/code-review.md
• docs/review-output-template.md

この3つがあれば、Codexに「どうレビューしてほしいか」「何を優先してほしいか」「どんな形式で返してほしいか」を伝えられます。セキュリティや設計のドキュメントは、必要に応じて後から足していけばOKです。

自分の感覚では、AI開発で大事なのは最初から完璧なルールを作ることではありません。AIに一度やらせてみて、ズレたところをMarkdownに戻す。この繰り返しです。畑で言えば、いきなり理想の土を作るというより、育ち方を見ながら少しずつ調整する感じに近いです。

まとめ

Codexにプロジェクト全体のソースコードレビューを任せるなら、単発の長いプロンプトより、レビュー用Markdownをプロジェクトに置くのがよさそうです。

特に重要なのは、AGENTS.md を入口にして、docs/code-review.md や docs/security-review.md に判断基準を分けることです。さらに、docs/review-output-template.md で出力形式を固定しておくと、レビュー結果をIssueやPRに落とし込みやすくなります。

AIにレビューを任せると、見落としを減らせる可能性があります。ただし、AIが出した指摘をそのまま正解にするのではなく、人間が優先順位を決めることが前提です。Codexはレビュー担当の一人として使う。最終判断は人間が持つ。この距離感が、今のところいちばん安全で実務に乗せやすいと感じました。

今回の実験で、自分の中では「Codexに何を言うか」より「プロジェクト側に何を残しておくか」のほうが大事だと分かりました。レビュー基準をMarkdownにしておけば、AIにも人間にも共有できます。ソースコード全体レビューを任せたいなら、まずはコードを直す前に、レビューのルールをコードベースの中に置く。ここから始めるのがよさそうです。

参考URL

• OpenAI Developers – Custom instructions with AGENTS.md
  https://developers.openai.com/codex/guides/agents-md
• OpenAI Developers – Codex best practices
  https://developers.openai.com/codex/learn/best-practices
• OpenAI Developers – Code review in GitHub
  https://developers.openai.com/codex/integrations/github
• OpenAI Developers – Codex web
  https://developers.openai.com/codex/cloud
• GitHub – openai/codex
  https://github.com/openai/codex
• GitHub Blog – Spec-driven development with AI
  https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• 食べログ Tech Blog – AI×運用設計で2,410メソッド削除！食べログのデッドコード削除戦略
  https://tech-blog.tabelog.com/entry/dead-code-removal-with-ai
• 半農エンジニアラボ – AIコーディングエージェントに任せるIssueの切り方
  https://kobayashi.works/2026/06/25/ai-coding-agent-issue-template/