Claude Code + Codex MCP を使った開発プロジェクトの標準的なフォルダ構成と開発フロー。 AIエージェント開発の情報管理-原則 のフォルダ構成をベースに、Claude Code のシステム上の制約を組み合わせたもの。
原則のフォルダ構成をそのまま採用し、Claude Code 固有の設定ファイル群（.claude/, CLAUDE.md）を追加する。
project-root/
├── CLAUDE.md # rules/ の抜粋 + Claude Code 固有の設定
├── .claude/ # Claude Code の設定・ルール・スキル
├── rules/ # 方針・スコープ・拘束的制約
├── backlog/ # やること・バグメモ等（追跡可能一時情報）
│ └── plans/ # Claude Code の plan mode 出力先
├── decisions/ # 意思決定ログ（ADR, append-only）
├── derived/ # 派生ビュー（正からの一方通行導出）
├── references/ # 参照情報（技術的知見・ハマりどころ等）
├── tmp/ # 揮発的一時情報（.gitignore 対象）
├── (実装コード) # 言語・フレームワークに依存（Go, Swift 等）
└── (テスト) # 言語に応じた配置
原則のフォルダに加え、Claude Code のシステムが要求するファイルがある。
CLAUDE.md: Claude Code が毎セッション自動で読み込むファイル。rules/ の全内容を毎回読み込ませるとコンテキストを圧迫するため、rules/ の抜粋と Claude Code 固有の設定（ビルドコマンド、レビュー手順等）を置く。rules/ が正であり、CLAUDE.md は抜粋。
.claude/: Claude Code の設定（settings.json）、パス限定ルール（rules/）、スキル（skills/）を格納する。詳細は Claude Code のドキュメントを参照。
原則の領域をそのまま使うが、以下に Claude Code 固有の事情がある。
backlog/plans/: Claude Code の plan mode が出力するファイルの置き場所。plan ファイル自体はコミットしない。実装完了時にはテスト・ソース・コミットメッセージ・references・decisions に内容が分散済みのため。tmp/（.gitignore 対象）ではなく backlog/ に置く理由は、/simplify が plan を git の差分として認識できる必要があるため。
一部の手順は Claude Code のスキル（/ で呼び出すコマンド）で自動化している。スキルの一覧は末尾の「スキル一覧」を参照。
ユーザーが scope や途中で気づいた修正事項を backlog/ に記録する。チーム開発の場合は GitHub Issues 等で代替してもよい。
ユーザーがタスクを指示
↓
Claude Code が plan mode に入る
↓
backlog/plans/ にプランファイルを作成
↓
Claude によるレビュー（開発全般 → 領域固有）
↓
MUST / SHOULD の新規指摘をプランに反映
新規指摘あり → Claude レビューに戻る
↓
Codex セカンドオピニオン
↓
Codex の知見を tmp/codex-findings.md に追記
↓
指摘あり → 反映してClaude レビューに戻る
指摘なし → ExitPlanMode
Claude 自身によるレビューの新規指摘がゼロになってから Codex レビューに進む。
注意点: 前回対処済みの指摘の再表現（「もっと明示的に」等）や、やらないと判断済みの事項の蒸し返しは新規とみなさない。この区別をしないとレビューが収束しない。判断が必要な指摘はユーザーに確認する。
プラン承認後、実装を進める
↓
references/ を事前に確認する
↓
実装・テスト
references/ 配下の knowledge.md 等に、過去の実装で得た技術的知見（ライブラリの罠、エッジケース等）が蓄積されている。CLAUDE.md は毎回自動で読み込まれるが、references/ は必要なタイミングで手動参照する。
計画レビューと同じ構造（Claude によるレビュー → Codex セカンドオピニオン）で進める。
実装・テスト完了
↓
/simplify（変更コードの簡素化チェック、ループの冒頭で1回のみ）
↓
Claude によるレビュー（開発全般 → 領域固有）
↓
MUST / SHOULD の新規指摘を実装に反映
新規指摘あり → Claude レビューに戻る
↓
Codex セカンドオピニオン
↓
Codex の知見を tmp/codex-findings.md に追記
↓
指摘あり → 反映してClaude レビューに戻る
↓
手動確認（テストだけでは検証が難しい項目がある場合）
↓
コミットへ
注意点: 実装中に計画から意図的に変更した箇所がある場合、plan ファイルも更新する。更新しないとプラン準拠チェックで差異が指摘され続ける。
- 判断記録が必要か判断し、必要なら decisions/ に作成する
- references/ に知見を追記（該当あれば）
- backlog/plans/ の対応するプランファイルを削除
- stage してコミット（Conventional Commits 形式、英語）
plan ファイルはコミット対象に含めない。実装完了時点で plan の内容はテスト・ソース・コミットメッセージ・references・decisions に分散済みのため、plan 自体をコミットする必要はない。
レビュースキルは3層構造で構成する。
- グローバルスキル（
~/.claude/skills/）: 言語非依存の観点。全プロジェクト共通 - 領域固有スキル（
~/.claude/skills/）: 言語・DB・フレームワーク等、特定領域固有の観点。グローバルに置き、プロジェクトの CLAUDE.md で使用を指定する - Codex レビュー（
~/.claude/skills/）: 異なるモデルによるセカンドオピニオン。Claude が見落としやすいパターンを補完する
| 観点 | プランレビュー（3観点） | 実装レビュー（最大4観点） |
|---|---|---|
| 1 | 整合性（仕様との矛盾） | プラン準拠（プランがある場合のみ） |
| 2 | 状態遷移（異常系） | 仕様整合性 |
| 3 | 過剰設計（YAGNI） | エッジケース・異常系 |
| 4 | - | 過剰設計（YAGNI） |
領域固有レビューは上記に加えて実行される。例: Swift の場合は concurrency/メモリ管理/SwiftUI 固有の観点が追加される。
新規の MUST / SHOULD がゼロになるまで繰り返す。前回対処済みの指摘の言い換えは新規とみなさない。無限ループを防ぐ仕組みが組み込まれている。
開発フローの一部をスキルで自動化している。スキルはプロジェクトローカル（.claude/skills/）とグローバル（~/.claude/skills/）の2箇所に配置する。
プロジェクトローカルスキル（リポジトリにコミット）:
| スキル | 用途 |
|---|---|
/commit |
判断記録 → 知見追記 → plan 削除 → コミット |
グローバルスキル（~/.claude/skills/、全プロジェクト共通）:
| スキル | 用途 |
|---|---|
/self-plan-review |
3観点並列プランレビュー |
/self-impl-review |
最大4観点並列実装レビュー |
/self-*-review-{lang} |
領域固有レビュー（Swift, Go 等） |
/codex-plan-review |
Codex によるプランレビュー |
/codex-impl-review |
Codex による実装レビュー |
/simplify |
変更コードの簡素化チェック |
/codex |
Codex への質問（ワンショット） |
/codex-session |
Codex とのマルチターン対話 |
/codex-discuss |
Claude と Codex の対等な議論 |
/debug |
段階的デバッグ |
Codex レビューで得られた知見（Claude が見落としやすいパターン、言語固有の罠等）を蓄積し、スキルの改善に還元するフロー。
Codex レビューで知見が出る
↓
tmp/codex-findings.md に追記
↓
20-30件 蓄積したら分類・整理
↓
該当するスキルの SKILL.md に反映
↓
findings をナレッジベースにアーカイブ
↓
tmp/codex-findings.md をリセット