AI駆動開発の事故を防ぐには？ AGENTS.md / CLAUDE.md / copilot-instructions.md のスペック駆動開発設計ガイド
セキュリティチェックが消えていた。既存の重要ロジックが静かに書き換えられていた。
そして最後には、「そもそも何を作りたかったのか」をAI自身が見失っていた。
この記事は、そういった失敗の構造を解剖し、AIに実装させる前に仕様を与えるスペック駆動開発を論理的に整理する。 Codex・Claude Code・GitHub Copilot、それぞれの指示ファイル設計まで、実務で今日から使える粒度で解説する。
- なぜAI駆動開発は雑にやると壊れるのか
- 解決策は「AIの前に仕様を置く」こと
- スペック駆動開発とは何か
- Codex / Claude Code / GitHub Copilot の違いを俯瞰する
- Codexでスペック駆動開発を行うための事前設定
- Claude Codeでスペック駆動開発を行うための事前設定
- GitHub Copilotでスペック駆動開発を行うための事前設定
- 3ツール共通で使える「最小構成」推奨テンプレート
- 現時点での限界と、過信してはいけないポイント
- 結論
- すぐ使える設定ファイル雛形まとめ
なぜAI駆動開発は雑にやると壊れるのか
2026年3月時点、コードを生成するAIの性能は目を見張るものがある。しかし現場での実態は複雑だ。 「なんとなく動くコードは生成できる」が「チームが長期保守できる設計を自律的に組み上げる」には、いまだ大きなギャップがある。 そのギャップが事故を生む。問題は「AIの性能不足」だけではない。「人間の指示の曖昧さ」と「AIの能力限界」の掛け算が事故の本質だ。
失敗パターン1：曖昧なプロンプトによる仕様誤読
「ユーザー認証機能を追加してください」という指示は、エンジニアには「既存のセッション管理に乗っかりつつ、JWT（署名付きトークンベースの認証方式）を追加する」と聞こえるかもしれない。 しかしAIには「もっとも簡単な認証実装」に聞こえることがある。その結果、admin:adminでログインできるデモ実装が差し込まれた事例は、決して珍しくない。
- 「リファクタリングして」→ 既存の重要なビジネスロジック（例：請求計算の特殊ルール）が削除された
- 「最適化して」→ キャッシュが削除され、サーバー負荷が倍増した
- 「エラー処理を追加して」→ エラー時に機密情報がスタックトレースとしてレスポンスに含まれるようになった
- 「テストを追加して」→ テスト対象のロジックを変えてテストが通るようにされた
失敗パターン2：暗黙知の未反映
チームには「ソフトデリート（論理削除）のみ使用し、物理削除は原則禁止」という不文律があった。 しかしAIはそれを知らない。指示がなければ、自然に DELETE FROM users WHERE id = ? を書く。 暗黙知はコードの中に分散しており、AIはコードを全量読んでも文化的な制約を推測するのが苦手だ。
失敗パターン3：セキュリティ要求の無視
AIは機能を動かすことを最優先にしがちだ。OWASP Top 10（Webアプリの代表的な脆弱性リスト）、SQLインジェクション対策、CSRF対策（クロスサイトリクエストフォージェリ：ユーザーの意図しないリクエストを第三者が送り込む攻撃への対策）、認可チェックは、 プロンプトに明示しなければ実装される保証がない。「セキュリティ上問題のないコードを書いて」という一言では不十分で、 どのリスクを、どの水準で、何を使って防ぐかまで指定しなければ曖昧な実装になる。
失敗パターン4：テストなき実装の蓄積
「まず動くものを作って」と頼むと、AIはテストを書かずに実装を先行させることが多い。 結果として、リファクタリングの安全網がない状態でコードが積み重なり、 次のAIへの依頼でさらにテストなしのコードが追加される。技術的負債の加速装置になりうる。
失敗パターン5：AIの長期目標維持の弱さ――最も見落とされている問題
これは単なるコード品質問題とは別の、重要な失敗要因だ。
AIは長距離走が苦手で、短距離の局所最適に引っ張られやすい。
大きなタスク（例：「決済機能を新しいマイクロサービスに移行する」）を与えたとき、 AIは途中でビルドエラー、型エラー、依存関係の競合などに引っ張られる。 それらを解決しようとするうちに、当初の目的——移行後の整合性テスト、ロールバック設計、既存サービスとの並走設計——から外れていく。 「エラーを直すこと」が目的化し、「何のためにエラーを直していたか」を見失うのだ。
初期指示：「支払い処理をStripeからAWS Paymentに移行してください。既存のSubscriptionテーブルは維持すること」
AIの行動：
①Stripe SDKの削除 → ②AWS SDK追加でバージョン競合 → ③依存関係修正に集中 → ④型エラー対応でSubscriptionモデルを変更 → ⑤変更したモデルに合わせてマイグレーション追加 → ⑥気づいたらSubscriptionテーブルの構造が変わっており、既存のデータとの互換性が失われていた
AIは「自分が逸脱した」と自覚しないまま作業を進める。
失敗パターン6：共通処理化に失敗し、似た機能が増殖する
AIは局所的なリクエストを最短で満たすことを優先する。 「ここでログを出力して」と頼むと、既存の共通ロガーを調べて統合するより、 その場で動く新しいログ関数を追加する方が速く・確実に見えるため、そちらを選びがちだ。 これが繰り返されると、コードベースには似た責務を持つ関数・ラッパー・ヘルパーが静かに増殖していく。
- 最初の修正で
logError()が追加される - 次の修正で
writeAuditLog()が別ファイルに追加される - さらに次の修正で
emitOperationLog()が別モジュールに追加される - 3つの関数はログ形式・ログレベル・相関ID付与・PIIマスキング・出力先がそれぞれ異なる
- 本来は1つの共通ロガーに統合されるべきだった横断関心事が、3か所で別々に実装されている
なぜこの問題が起きるのか
AIは既存の共通抽象を積極的に探索・統合することよりも、 「今依頼された機能を動かすこと」を優先する。 既存の共通ロガーを発見しても、その設計を読み解き、正しく拡張するより 新しい小さな関数を書く方が安全に見える。 これはロギングだけでなく、バリデーション・例外処理・日時変換・認可判定といった 横断的関心事（クロスカッティングコンサーン）すべてで同様に起きる。 特にタスクが分割されて依頼される実務環境では、前回の修正でどんな共通処理が追加されたかを AIが把握していないため、重複実装が起きやすい。 また、既存の共通抽象を安全に拡張するには、その抽象が守っている不変条件や既存利用箇所への影響を理解する必要がある。 AIはそこを読み解くより、新しい薄いラッパーを追加して局所的に要求を満たす方を選びやすい。これは怠慢ではなく、構造上そうなりやすいという問題だ。
なぜこれが深刻なのか
「重複実装」「少しコードが汚くなる」という話ではない。横断処理の重複は、 セキュリティ・監査性・運用品質の問題に直結する。
- 監査性：ログ形式・相関IDが不統一になると、インシデント発生時の追跡が困難になる
- セキュリティ：PIIマスキングが一部の出力経路にしか適用されない状態が生まれる
- 障害解析：複数のログ関数が異なる出力先・フォーマットを使うと、ログ集約基盤が機能しない
- 保守性：バリデーションルールが複数箇所に散在すると、仕様変更時の修正漏れが構造的に発生する
- 認可の穴：認可チェックのヘルパーが複数存在し、一方にだけセキュリティ修正が当たるリスクが生まれる
- ログ出力は必ず既存の共通ロガー（
Loggerクラス・getLogger()等）を使用し、新規ログ関数の追加を禁止する - 既存のバリデーション・例外処理・認可チェックと責務が重複する utility / wrapper / helper の新規追加を禁止する
- 横断的関心事（ログ・バリデーション・認可・日時処理）を新規実装する前に、既存の共通実装が存在しないか必ず確認すること
- 「ログを追加して」ではなく「既存の共通ロガーに統合した上で、必要な出力フィールドを拡張すること」のように指示する
AIが「共通化すべき横断処理」を自律的に正しく判断するのは難しい。 だからこそ、共通化原則そのものをスペックとして指示ファイルに書く必要がある。 禁止事項に「eval()禁止」を書くように、「既存の共通抽象と責務が重複する実装の追加禁止」も明示する。 これは後付けのリファクタリングで解決できる問題ではなく、事前設計で防ぐべき構造問題だ。
「AIの問題」と「人間の指示不足」の正確な切り分け
上記の失敗を「AIが悪い」と断じるのは早計だ。整理すると以下のようになる。
| 失敗の種類 | 主因 | 緩和策 |
|---|---|---|
| セキュリティ見落とし | 人間の指示不足 | 禁止事項・セキュリティ要件を事前定義 |
| 既存ロジック削除 | 指示の曖昧さ＋AIの推測 | 「触ってはいけない範囲」を明示 |
| 暗黙知の未反映 | 人間の文書化不足 | 設計原則・禁止事項を構造化して渡す |
| 長期目標の逸脱 | AIの能力限界 | 北極星文書＋中間確認ポイントの設計 |
| テストなし実装 | 指示不足（TDD要求なし） | テスト戦略を事前指定 |
| 共通処理の重複増殖 | 指示不足＋AIの局所最適化 | 共通化原則を禁止事項として明示 |
- AI駆動開発の事故は「AIの性能不足」×「人間の指示不足」の掛け算で起きる
- AIの長期目標維持の弱さは、コード品質問題と別の重要な失敗要因
- AIは局所的に動く実装を優先しやすく、共通化すべき横断処理（ログ・バリデーション・認可等）が重複実装として増殖しやすい
- 暗黙知・禁止事項・セキュリティ要件はプロンプトに明示しなければ反映されない
- AIは「自分が逸脱したこと」に自覚的ではないため、人間側の構造的対策が必要
解決策は「AIの前に仕様を置く」こと
問題の構造が分かれば、解決策の方向性も見えてくる。 AIに実装を依頼する前に、AIが参照できる形で仕様を構造化して与えることだ。 これは「より良いプロンプトを書く」という話ではない。開発プロセス全体をAI可読な形に設計し直すことを意味する。
ステップ1：要件定義をAIと対話しながら厳密化する
多くのチームは「要件定義は人間がやってからAIに渡す」と考えるが、実際にはAIに要件の穴を洗い出させることが有効だ。 「この要件定義で実装したとき、どんなエッジケースが考慮されていないか」とAIに問うと、 人間が気づかなかった考慮漏れが出てくることがある。要件定義フェーズでのAI活用は、実装フェーズより安全で生産的だ。
ステップ2：設計原則を先に固定する
「クリーンアーキテクチャを採用する」「依存の向きはドメイン層→インフラ層の一方向」「サービス層はHTTPの概念を知らない」「依存性注入（依存するオブジェクトを外から渡すことで結合度を下げる設計原則）を必ず使う」といった設計原則は、 コードベースを見ても推測が困難だ。これらを文書として明示しなければ、AIは「もっとも自然に見える」構造でコードを書く。 それがチームの設計方針と一致しているとは限らない。
ステップ3：テスト戦略を先に決める
TDD（テスト駆動開発）を徹底するなら、AIにも「テストを先に書き、それを通す実装を書く」という順序を守らせなければならない。 「ユニットテスト・統合テスト・E2Eテストの比率」「モック（外部サービスやDBを実際に呼ばず、テスト用の偽実装で代替する手法）の使用方針」「テストカバレッジの最低基準」を文書化して渡すことで、 AIの生成コードの品質が変わる。
ステップ4：禁止事項を明示する
eval()・exec()・動的コード実行の使用禁止- 物理削除（
DELETE FROM）の直接実行禁止（ソフトデリート必須） - 認証・認可チェックのない管理系APIの作成禁止
- ハードコードされた認証情報・シークレットの埋め込み禁止
- エラーメッセージへのスタックトレース・内部情報の露出禁止
- 既存マイグレーションファイルの変更禁止
- 既存の共通処理（ロガー・バリデーション・認可チェック・例外ハンドラ）と責務が重複する utility / wrapper / helper の新規追加禁止
ステップ5：中間確認ポイントと停止条件を設計する
AIの長期目標逸脱に対する最も有効な対策は、完全自律で進めさせないことだ。 「要件整理が終わったら人間に確認を求める」「設計ドキュメントを作成したら実装前に提示する」 「既存APIの署名を変更しようとしたら作業を停止して報告する」といった停止条件を先に設計しておく。 AIが「自分が正しい方向にいるか」を疑う能力は低い。だから人間が確認できる仕組みを事前に埋め込む。
ステップ6：AIに「戻るべき北極星」を文書で渡す
Claude.md・AGENTS.md・copilot-instructions.mdといった指示ファイルは、まさにこの北極星として機能しうる。 「今回実装するのはXである」「Yは今回のスコープ外である」「完了条件はZである」を明示することで、 AIが途中で別の問題に引っ張られても、参照すべき基準点が存在する。 ただし、これらのファイルが長すぎたり曖昧すぎたりすると効力が落ちる——それは後の章で詳述する。
Before / After：依頼の質がどう変わるか
抽象的な説明だけでは伝わりにくいので、具体的なBefore/Afterで確認する。
| ❌ Before（曖昧な依頼） | ✅ After（スペック駆動の依頼） |
|---|---|
| 「決済機能をStripeからAWS Paymentに移行してください」 → AIは「最短で動く実装」を選択。Subscriptionテーブルの構造が変わり、既存データとの互換性が失われた。認証キーがコードに直書きされた。テストは書かれなかった。 |
「決済機能をStripeからAWS Paymentに移行してください。 制約：Subscriptionテーブルの構造は既存のまま維持すること。既存の公開APIの破壊的変更は禁止。シークレットは環境変数から取得。 手順：①設計ドキュメントを作成し提示する ②人間の承認後に実装を開始する ③全テストがパスしたら完了と報告する。 停止条件：スキーマ変更が必要と判断した場合は作業を止めて報告すること」 → AIは設計を先に提示し、承認を得てから実装を開始。既存テーブル構造を維持し、シークレットは環境変数化。テストも先に書いた。 |
この違いを毎回プロンプトに書くのは非効率だ。だからこそ、これらをAGENTS.md / CLAUDE.md / copilot-instructions.md に先に書いておくことが、スペック駆動開発の核心となる。
- 解決策は「より良いプロンプト」ではなく、「開発プロセスのAI可読化」
- 要件定義・設計原則・テスト戦略・禁止事項を先に文書化して渡す
- 中間確認ポイントと停止条件を事前に設計することでAIの逸脱を防ぐ
- 「AIが参照すべき北極星文書」を整備することが、AI駆動開発の基盤となる
スペック駆動開発とは何か
この記事におけるスペック駆動開発（Spec-Driven Development）を定義する。 これは単なるプロンプトエンジニアリングではない。 開発プロセスそのものをAI可読に構造化することであり、AIが参照できる形で設計知識を整備した上で開発を進めるアプローチだ。
スペック駆動開発の構成要素
記事中で「指示ファイル」と呼ぶのは、AIが作業前に読み込む永続的なルール文書の総称だ。 ツールごとに名前と位置づけが異なる。
| ファイル / 仕組み | ツール | 役割 |
|---|---|---|
AGENTS.md |
Codex | プロジェクト全体の永続ルール。禁止事項・目的・停止条件を記述する中心ファイル |
CLAUDE.md |
Claude Code | 同上。リポジトリルート・サブディレクトリ・ユーザーホームの3階層に配置できる |
.github/copilot-instructions.md |
Copilot | リポジトリ全体に常時適用されるルール。AGENTS.md / CLAUDE.md に相当 |
| SKILL.md（Skills） | Codex Claude Code | 特定タスクの再利用可能な手順定義。テキスト指示だけでなく、コマンド実行も記述できる |
| path-specific instructions （ .github/instructions/*.instructions.md） |
Copilot | 特定パス配下にだけ適用される指示。Skillsのディレクトリ別指定に近い役割 |
| agent skills / prompt files | Copilot | 特定タスクを再利用可能なスキルとして定義。Copilotにおける Skills 相当の仕組み |
各要素の「何を書くか」と「どのファイルに書くか」を整理する。まず要素ごとの定義を確認し、続いてツール別の配置場所を示す。
| 要素 | 内容 | 書く際の基本方針 |
|---|---|---|
| 要件 | 何を作るか。ユーザーストーリー・受け入れ条件まで含む | 指示ファイル冒頭に「今回の目的」として簡潔に記述 |
| 非機能要件 | パフォーマンス・可用性・スケーラビリティ・セキュリティ基準 | プロジェクトルートの指示ファイルに記述 |
| 設計原則 | アーキテクチャスタイル・依存方向・責務分離ルール | 詳細はSkill / 専用instructionsに分離し、指示ファイルから参照 |
| ディレクトリ・責務ルール | どのディレクトリに何を置くか・何を置かないか | サブディレクトリ単位の指示ファイルまたはpath-specific指示に記述 |
| セキュリティルール | 禁止事項・認証認可方針・入力検証方針 | セキュリティSkillまたは専用instructionsに分離 |
| テスト方針 | TDD要否・テスト種別と比率・モック方針・最低カバレッジ | TDD Skill / instructionsに分離して指示ファイルから参照 |
| レビュー基準 | レビュー時に何を確認するか・自動・人間の役割分担 | 指示ファイルまたはレビューSkillに記述 |
| 禁止事項 | 絶対にやってはいけない実装・変更・削除。共通処理と責務が重複するutility/helperの追加禁止も含む | 指示ファイルの冒頭に最優先で短く明示 |
| 実装手順・品質チェック | 実装の順序。lint・型チェック・テスト実行コマンドの標準化も含む | タスク別Skill / prompt filesに切り出す（コマンド実行も定義可能） |
| 中間確認・停止条件 | どの段階で人間に報告・承認を求めるか | 指示ファイルの🛑セクションとして必ず含める |
| Definition of Done | 何をもって「完了」とみなすかの合意基準 | 指示ファイルの✅セクションとして必ず含める |
続いて、各ツールごとの具体的な配置場所を示す。
| 要素 | Codex での書き場所 | Claude Code での書き場所 | Copilot での書き場所 |
|---|---|---|---|
| 要件・非機能要件 | AGENTS.md 冒頭 |
CLAUDE.md 冒頭 |
copilot-instructions.md 冒頭 |
| 設計原則 | 設計 Skill（SKILL.md） |
.claude/skills/clean-arch.md |
専用 path-specific instructions |
| ディレクトリ・責務 | サブディレクトリ AGENTS.md |
サブディレクトリ CLAUDE.md / .claude/rules/ |
.github/instructions/ 配下 |
| セキュリティ | セキュリティ Skill | .claude/skills/security.md または .claude/rules/security.md |
セキュリティ専用 instructions |
| テスト方針 | TDD Skill | .claude/skills/tdd.md |
copilot-instructions.md のテストセクション |
| 禁止事項 | AGENTS.md 冒頭 |
CLAUDE.md 冒頭 |
copilot-instructions.md 冒頭 |
| 実装手順・品質チェック | タスク別 Skill / 品質チェック Skill | .claude/skills/ 配下 |
agent skills / prompt files |
| 停止条件・DoD | AGENTS.md の🛑✅セクション |
CLAUDE.md の🛑✅セクション |
copilot-instructions.md の🛑✅セクション |
なぜ「プロンプトエンジニアリング」と違うのか
プロンプトエンジニアリングは「どう頼むか」の技術だ。スペック駆動開発は「何を前提として渡すか」の設計だ。 前者はリクエストごとに変わる。後者はリポジトリに永続し、チームで共有され、バージョン管理される。 プロンプトは一過性の指示であり、スペックは開発標準の文書化だ。
「AIに良いコードを生成させたいなら、AIが参照できる形で良いコードの定義を書け」
優秀な新人エンジニアが入ってきたとき、あなたはどうするか。 「とりあえず動くものを作って」とだけ言うか、それとも設計原則・テスト方針・禁止事項が書かれたオンボーディング文書を渡すか。 AIに対しても、同じ原則が成り立つ。
工程ごとの分解と、AIへの指示の粒度
- 要件整理フェーズ：AIに考慮漏れを洗い出させる。この段階では実装させない
- 設計フェーズ：アーキテクチャと責務設計をドキュメント化し、人間がレビューする
- テスト設計フェーズ：テストケースと受け入れ条件を先に定義する
- 実装フェーズ：スペックを参照しながら実装。禁止事項を守らせる
- 検証フェーズ：テストを実行し、Definition of Done（何をもって完了とみなすかの合意基準）と照合する
- 人間レビューフェーズ：セキュリティ・認可・データ変更・既存機能影響は必ず人間が見る
- スペック駆動開発とは「開発プロセスをAI可読に構造化すること」であり、プロンプト技法ではない
- 要件・設計・テスト・禁止・確認ポイント・DoD を文書化してAIに渡す
- 工程を分解し、各フェーズに適切な指示を与えることで、AIの自律と人間管理を両立させる
Codex / Claude Code / GitHub Copilot の違いを俯瞰する
主要機能比較表
| 比較軸 | Codex | Claude Code | GitHub Copilot |
|---|---|---|---|
| 永続的指示の主ファイル | AGENTS.md | CLAUDE.md | .github/copilot-instructions.md（リポジトリ全体の代表的な基本指示ファイル） |
| リポジトリ単位での共有 | ✅ AGENTS.mdをGit管理 | ✅ CLAUDE.mdをGit管理 | ✅ .github/以下をGit管理 |
| 個人設定の分離 | ✅ グローバルAGENTS.md（~/.codex/） | ✅ グローバルCLAUDE.md（~/.claude/） | ✅ VS Code personal instructions |
| パス/ディレクトリ単位指示 | △ ディレクトリ内にAGENTS.mdを配置可 | △ サブディレクトリにCLAUDE.md配置可 | ✅ path-specific instructions（applyTo指定） |
| 再利用可能なスキル | ✅ Skills（SKILL.md） | ✅ Skills（SKILL.md） | △ agent skills も一部環境・機能で見られるが、現時点では custom instructions / path-specific instructions / prompt files を中心に使う複合モデル |
| 目的逸脱防止のしやすさ | ✅ 停止条件・工程ゲートを明記しやすい | ✅ 停止条件・DoD定義に適した構造 | △ 可能だが仕組みとして弱い |
| エージェント的な自律実行 | ✅ クラウド実行・非同期タスク向き | ✅ ターミナル統合・ローカル実行 | △ エディタ補完・チャット補助が中心 |
| 組織レベルの標準適用 | △ 運用は主にリポジトリ/ユーザースコープが中心 | ✅ organization-wide CLAUDE.md と managed settings に対応（執筆時点） | ✅ Organization-level instructions |
| 最も向いているチーム | 自律的なAgentタスク・CI/CDパイプライン組み込み | ローカル開発・アーキテクト主導のTDD実践 | GitHub中心チーム・組織標準の横展開 |
| 主な注意点 | AGENTS.mdが長すぎると効力低下、Skill分割が重要 | CLAUDE.mdの長さとコンテキスト消費のバランス | エージェント制御の粒度が粗い、スキル概念がない |
3ツールの「思想」「構成」「運用」比較
| 軸 | Codex | Claude Code | GitHub Copilot |
|---|---|---|---|
| 思想 | 「エージェントに仕事を任せる」。タスクを定義して実行させる自律モデル | 「開発者と対話しながら進める」。ターミナルに統合された対話型エージェント | 「エディタ補助を強化する」。補完・チャット・レビューが中心 |
| 構成 | AGENTS.md + Skills（再利用可能なワークフロー） | CLAUDE.md（階層配置） + Skills（専門タスク） | copilot-instructions.md + path-specific instructions + agent instructions |
| 運用 | タスク投入→実行→確認のサイクル。CI/CDとの統合に向く | ローカルで対話しながら実装を進める。人間の判断が介入しやすい | 日常のコーディングに溶け込む。組織標準の浸透に向く |
「AIをどう制御しやすいか」という観点
Codexは「タスクの入口で制御する」設計だ。AGENTS.mdとSkillで、何をやらせるかを事前に厳密に定義する。 実行中の制御介入は難しいが、入口の設計が良ければ逸脱リスクは低い。
Claude Codeは「実行中に対話で制御する」設計だ。途中で人間が割り込みやすく、「今やっていることが正しいか」を随時確認しながら進められる。 ローカル実行のため、壊滅的なミスが起きにくい環境でもある。
GitHub Copilotは「補助ツールとしての制御」だ。コードを自律的に大量生成させることよりも、 エンジニアの判断をサポートする役割が強い。執筆時点の公式ドキュメントでは、 repository-wide custom instructions・path-specific instructions・agent instructions・prompt files・agent skills など複数のカスタマイズ手段が並立しており、組織標準の浸透から特定タスクの再利用まで、役割分担して使う設計になっている。 Codex・Claude Code のように「Skills を前面に出す」モデルとは構造が異なる点は押さえておきたい。
どのツールをどの場面で選ぶか
3ツールを比較するとき、「どれが最強か」という問いは意味をなさない。使い方の文脈が違うからだ。 選定の実務的な判断線は以下の通りだ。
- 自律的なAgentタスクをCI/CDに組み込みたい → Codex：バッチ的な実装タスク・リファクタリング・テスト生成をパイプラインで回したい場合に適する。事前定義型の制御と相性が良い
- 設計から実装まで対話しながら詰めたい → Claude Code：アーキテクト・シニアエンジニアがローカルで「考えながら作る」フローに合う。途中で人間が止めて確認しやすい
- 組織の開発標準をチーム全体に浸透させたい → GitHub Copilot：GitHub中心のチームで、エディタ補完から補助チャット・コードレビューまで統一的に標準を適用したい場合に最適
- 複数ツールを組み合わせる → 現実的な選択肢：Copilotで日常開発をカバーしつつ、大きなリファクタリングや設計タスクにCodexまたはClaude Codeを使うハイブリッド構成も有効だ
- 3ツールは「指示の渡し方」「自律性の度合い」「制御のタイミング」で思想が異なる
- Codexは事前定義型、Claude Codeは対話介入型、Copilotは補助特化型
- 自律Agentタスク → Codex、対話型設計・実装 → Claude Code、組織標準の横展開 → Copilot
- スペック駆動開発の観点では、Codex・Claude Codeは再利用可能なSkill（ワークフロー単位の指示）の仕組みを持ち、より細粒度の指示設計に向いている
- Copilotも repository-wide / path-specific / organization-wide の構造的指示に対応し、agent skills も一部環境・機能として登場しているが、現時点では custom instructions / path-specific / prompt files が中心
- ただし Copilot は「Skills を中心に据える」モデルではなく、custom instructions・path-specific instructions・prompt files・agent skills を組み合わせる複合設計
- Copilotは組織横断的な標準浸透に強みを持つ。複数ツールのハイブリッド構成も現実的な選択肢
Codexでスペック駆動開発を行うための事前設定
執筆時点の公式ドキュメントでは、Codexはローカル・ワークツリー・クラウドの各モードで動作する エージェント型コーディング環境であり、AGENTS.mdとSkillsによってその動作を制御する。
AGENTS.md の役割と配置
AGENTS.mdはリポジトリのルートに置き、Codexがタスクを実行する際の永続的な指示として読み込まれる。 グローバル設定（~/.codex/AGENTS.md）は個人の作業スタイルを定義し、リポジトリのAGENTS.mdがプロジェクト固有の標準を上書き・補完する。 サブディレクトリにもAGENTS.mdを配置でき、そのディレクトリ配下の作業時に追加で読み込まれる。
Skills の位置づけと分割戦略
Skillsは再利用可能なワークフロー定義だ。「要件整理」「クリーンアーキテクチャ設計」「TDD実装」「セキュリティレビュー」 といった、タスク種別ごとの手順をSKILL.mdとして切り出す。 AGENTS.mdに「このタスクはXというSkillに従うこと」と参照を書くことで、メインファイルの肥大化を防ぐ。
Skillsの内容はAIへの指示文だけに限らない。静的解析・型チェック・フォーマッタ・テスト実行などのコマンドをSkill内に定義し、AIに実行させることができる。 たとえば「実装後に必ず eslint と tsc --noEmit を実行し、エラーがあれば修正してから次に進む」という品質チェックSkillを用意すれば、 AIが手順を省略することを防げる。これはテキスト指示だけでは担保しにくい「機械的な品質ゲート」をスペックに組み込む有効な手段だ。
執筆時点の公式Skillsドキュメントではリポジトリ内の .agents/skills をスキャンすると明示されている一方、 OpenAIの一部サンプルやブログ記事では .codex/skills の例も見られる。 公式ソース内でも表現が揺れている状態のため、本記事のサンプルコードはあくまで参考構成として捉え、 実際に使用するCodexの表面（CLI / app / IDE）に応じて最新の公式ドキュメントで配置場所を確認することを推奨する。
以下はあくまで参考構成例だ。Skills の実際の配置場所は利用中の Codex 表面（CLI / app / IDE）と最新の公式ドキュメントに合わせて調整してほしい。なお例では .codex/skills/ を用いているが、公式 Skills ドキュメントでは .agents/skills/ を参照する記述も見られるため、実環境では必ず最新ドキュメントで差分を確認すること。
repo-root/
├── AGENTS.md # プロジェクト全体の指示（コア）
├── .codex/
│ └── skills/
│ ├── requirements.skill.md # 要件定義支援
│ ├── clean-arch.skill.md # 設計原則・クリーンアーキテクチャ
│ ├── tdd.skill.md # テスト駆動開発手順
│ ├── security.skill.md # セキュリティチェック
│ └── review.skill.md # コードレビュー基準
├── src/
│ ├── domain/
│ │ └── AGENTS.md # ドメイン層への特化指示
│ └── infra/
│ └── AGENTS.md # インフラ層への特化指示
└── tests/
└── AGENTS.md # テストコード向け指示AGENTS.md 実例
# AGENTS.md — [プロジェクト名] 開発標準
## ⛔ 絶対禁止事項（最優先で守ること）
- 既存のマイグレーションファイルを変更してはならない
- 物理削除（DELETE FROM）を直接実行してはならない（ソフトデリート必須）
- eval() / exec() / 動的コード実行を使用してはならない
- 認証・認可チェックのないAPIエンドポイントを作成してはならない
- シークレット・APIキーをコードにハードコードしてはならない
- テスト済みの既存パブリック API の署名を変更してはならない
- 既存の共通処理（ロガー・バリデーション・認可チェック・例外ハンドラ）と責務が重複する utility / wrapper / helper を新規追加してはならない
- ログ出力は必ず既存の共通ロガーを使用すること。新規ログ関数の追加は禁止
## 🎯 現在の目的（北極星）
このリポジトリでは「決済機能をStripeからAWS Paymentに移行する」タスクを進めている。
- 今回の範囲: PaymentService, SubscriptionService の移行
- 今回の範囲外: フロントエンド・通知機能・レポート機能
- 完了条件（Definition of Done）:
1. 既存のSubscriptionテーブル構造を維持したまま移行完了
2. 全ユニットテストがパス（カバレッジ80%以上）
3. 統合テストでStripeとAWS Payment両方の動作を確認
4. 既存APIの後方互換性が保たれている
## 📐 設計原則
- クリーンアーキテクチャを採用: domain → application → infrastructure の依存方向
- サービス層はHTTP・DBの具体実装に依存してはならない
- 依存性注入を必ず使用する（直接インスタンス化禁止）
- 横断的関心事（ログ・バリデーション・認可・例外処理）は既存の共通実装を優先利用すること。新規実装前に必ず既存の共通処理を確認する
- 詳細は .codex/skills/clean-arch.skill.md を参照
## 🧪 テスト方針
- テストファースト: 実装前にテストケースを書くこと
- ユニットテスト: 70% / 統合テスト: 25% / E2E: 5%
- 外部サービス（DB・API）は必ずモック化する
- 詳細は .codex/skills/tdd.skill.md を参照
## 🔐 セキュリティ
- 詳細は .codex/skills/security.skill.md を参照
- 入力値は必ずバリデーション後に処理する
- SQLはORMまたはパラメータ化クエリのみ使用
## 🛑 停止条件（ここで作業を止めて人間に報告すること）
以下の状況に遭遇した場合は、実装を止めて状況を報告し、指示を仰ぐこと:
- 既存APIの破壊的変更が必要と判断された場合
- 認証・認可ロジックの変更が必要な場合
- データベーススキーマの変更（列の削除・型変更）が必要な場合
- 既存のビジネスロジックの意図が不明確な場合
- セキュリティ上の懸念が発生した場合
- テストが通らない原因がロジックの根本的な問題である場合
## 🔄 目的再確認の指示
作業中に以下の状況になった場合、冒頭の「現在の目的」セクションに戻り、
自分の行動が目的に沿っているか確認すること:
- エラー修正に3ステップ以上かかった場合
- 依存関係の問題に遭遇した場合
- 実装方針について迷いが生じた場合
## 📋 実装前チェックリスト
実装を開始する前に以下を確認すること:
- [ ] 要件が「現在の目的」セクションと一致しているか
- [ ] 影響範囲を特定したか
- [ ] テストケースを先に書いたか
- [ ] 禁止事項に抵触しないかSkill 実例：TDD手順（.codex/skills/tdd.skill.md）
# SKILL: テスト駆動開発（TDD）手順
## このSkillの目的
実装品質を担保するため、テストファーストの開発手順を徹底させる。
## 実装手順（この順序を必ず守ること）
### Step 1: 要件の確認
- 実装する機能の入力・出力・副作用を明確化する
- エッジケースをリストアップする
### Step 2: テストファイルの作成
- まずテストファイルを作成し、テストケースを書く
- テストケースは「正常系・異常系・境界値」を網羅する
- この時点では実装はまだ書かない（テストは全てFAILすること）
### Step 3: 最小限の実装
- テストをパスさせる最小限のコードを書く
- この段階ではコードの美しさより正確さを優先する
### Step 4: リファクタリング
- テストがパスした状態でコードを整理する
- 設計原則（AGENTS.md参照）に沿った構造に改善する
### Step 5: 統合確認
- 既存のテストが全てパスすることを確認する
- カバレッジが基準値（80%）を下回っていないか確認する
## ⛔ 禁止事項
- テストを通すためにテスト側のコードを変更してはならない
- テストを削除することで「テストをパスさせる」ことは禁止
- カバレッジ基準を回避するためのダミーテスト追加は禁止Skill 実例：静的解析・品質チェック（.codex/skills/quality-check.skill.md）
# SKILL: 静的解析・品質チェック
# 使用タイミング: 実装完了後・レビュー前に必ず実行する
## このSkillの目的
テキスト指示だけでは防げない「機械的な品質問題」を、コマンド実行によって自動的に検出・修正する。
AIが手順を省略することを防ぎ、品質ゲートをスペックとして固定する。
## 実行するコマンド（この順序で必ず実行すること）
### Step 1: フォーマット
```bash
# TypeScript / JavaScript の場合
npx prettier --write "src/**/*.{ts,tsx,js}"
# Python の場合
black src/
```
エラーがあれば修正してから次へ進む。
### Step 2: 静的解析（Lint）
```bash
# TypeScript / JavaScript
npx eslint "src/**/*.{ts,tsx}" --max-warnings=0
# Python
flake8 src/ --max-line-length=100
```
警告ゼロを目標とする。既存の警告が増えた場合は必ず修正してから次へ進む。
### Step 3: 型チェック
```bash
# TypeScript
npx tsc --noEmit
# Python
mypy src/
```
型エラーがゼロであることを確認する。
### Step 4: テスト実行
```bash
# Node.js
npm test -- --coverage
# Python
pytest --cov=src --cov-report=term-missing
```
カバレッジがAGENTS.mdの基準値（80%）を下回った場合は実装を補完する。
## ⛔ このSkillで禁止すること
- lint エラーを suppress コメントで隠して通すこと（// eslint-disable など）
- 型チェックを `any` 型や `@ts-ignore` で回避すること
- テスト失敗を無視して次のステップに進むこと
- カバレッジ基準を満たすためだけのダミーテストを追加すること
## 実行結果の報告
全ステップ完了後、以下を人間に報告すること:
- 各コマンドの実行結果（pass / fail）
- 修正した内容の概要
- カバレッジの数値- AGENTS.mdには「禁止事項→現在の目的→設計原則→停止条件」の順で書く
- Skillsはテキスト指示だけでなく、lint・型チェック・テスト実行などのコマンド呼び出しも定義できる
- 品質チェックSkillにより、AIが手順を省略できない「機械的な品質ゲート」をスペックに組み込める
- 「停止条件」と「目的再確認の指示」はAIの長期目標逸脱を緩和する最重要項目
Claude Codeでスペック駆動開発を行うための事前設定
Claude Codeはターミナルに統合されたAnthropicのコーディングエージェントで、 執筆時点の公式ドキュメントではCLAUDE.mdが永続的な指示ファイルとして機能する。 リポジトリルートのCLAUDE.md（プロジェクト共有）と~/.claude/CLAUDE.md（個人設定）の2層構造を取る。 さらにサブディレクトリにCLAUDE.mdを配置すると、そのディレクトリ内での作業時に追加で読み込まれる。
CLAUDE.mdの最大の問題：長すぎると効かなくなる
CLAUDE.mdに何でも書けばいいわけではない。コンテキストウィンドウの消費、AIが「重要な指示」を相対的に見落とす確率の増加、 保守コストの増大という問題が生じる。CLAUDE.mdはコア指示に絞り、詳細はSkillsに切り出すことが重要だ。 目安として、CLAUDE.mdは200〜400行以内に収め、それ以上は専用Skillファイルに分離する。
CLAUDE.mdとSkillsの分担
| CLAUDE.mdに書く | Skillsに切り出す |
|---|---|
| プロジェクト概要・現在の目的 | 詳細な実装手順 |
| 禁止事項（最重要・短く） | 設計パターンの詳細説明 |
| 設計原則の要約（1〜2行） | テスト手順の詳細 |
| 停止条件（箇条書き） | セキュリティチェックリスト |
| Definition of Done | レビュー基準の詳細 |
| Skillsへの参照リスト | アーキテクチャ図・判断基準 |
| — | lint・型チェック・テスト実行などのコマンド呼び出し手順（品質チェックSkill） |
執筆時点の公式ドキュメントでは、CLAUDE.mdの肥大化を防ぐ別の手段として .claude/rules/ ディレクトリへのトピック別ルール分割も明示されている。 たとえば .claude/rules/security.md・.claude/rules/testing.md のように 関心事ごとにファイルを分割することで、CLAUDE.mdをさらに短く保てる。 Skillsが「タスク手順の再利用」を担うのに対し、.claude/rules/は 「常時適用されるルールの分類整理」に向いている。この2つを組み合わせて使うのが現状のベストプラクティスに近い。
CLAUDE.md 実例
# CLAUDE.md — [プロジェクト名]
## ⛔ 絶対禁止（最優先）
- 既存マイグレーションの変更禁止
- 物理削除禁止（ソフトデリート必須）
- 認証認可なしAPIの作成禁止
- シークレットのハードコード禁止
- パブリックAPIの破壊的変更禁止
- 既存の共通処理（ロガー・バリデーション・認可・例外ハンドラ）と責務が重複する utility / wrapper / helper の新規追加禁止
## 🎯 今回の目的とスコープ
**目的**: 決済機能をStripeからAWS Paymentに移行する
**今回やること**: PaymentService, SubscriptionService のみ
**今回やらないこと**: フロントエンド・通知・レポート・ユーザー管理
## ✅ Definition of Done
- [ ] Subscriptionテーブル構造が既存と同一
- [ ] 全ユニットテストパス（カバレッジ80%+）
- [ ] 統合テストで両Payment Provider確認済み
- [ ] 破壊的APIの変更なし
- [ ] CLAUDE.mdの禁止事項すべて遵守
## 📐 設計原則（詳細は skills/clean-arch.md）
- クリーンアーキテクチャ: domain → application → infrastructure
- 外部サービス依存はインターフェースで抽象化すること
- HTTPやDBの知識はinfra層より外に出さない
- 横断的関心事（ログ・バリデーション・認可・例外処理）は既存の共通実装を優先利用すること。重複する utility / wrapper は追加しない
## 🧪 テスト方針（詳細は skills/tdd.md）
- テストファースト必須
- 外部サービスは必ずモック化
- 既存テストを壊してはならない
## 🛑 停止条件（ここで停止し、状況を報告すること）
以下が発生した場合は実装を止め、状況・判断理由・提案を人間に提示すること:
1. 既存公開APIの破壊的変更が必要と判断された場合
2. 認証認可ロジックの変更が必要な場合
3. DBスキーマの削除・型変更が必要な場合
4. ビジネスロジックの意図が不明で推測が必要な場合
5. セキュリティ上の懸念が生じた場合
6. エラー修正が3ステップ以上にわたり目的から外れていると感じた場合
## 🔄 目的逸脱チェック（迷ったときに参照すること）
「今やっていることは、ページ冒頭の"今回の目的"に沿っているか？」
→ NOなら: 作業を停止し、目的に立ち戻り、必要なら人間に確認すること
## 📚 参照Skills
- 設計: .claude/skills/clean-arch.md
- TDD: .claude/skills/tdd.md
- セキュリティ: .claude/skills/security.md
- 要件整理: .claude/skills/requirements.mdSkill実例：要件整理支援（.claude/skills/requirements.md）
# SKILL: 要件整理支援
## このSkillを使うタイミング
新機能の実装を依頼されたとき、まずこのSkillを実行する。
## 手順
### Step 1: 要件の構造化
以下の形式で要件を整理すること:
```
機能名:
目的（なぜ必要か）:
入力:
出力:
正常系:
異常系・エッジケース:
今回のスコープ外:
影響する既存機能:
```
### Step 2: 考慮漏れの洗い出し
以下の観点で要件の穴を指摘すること:
- セキュリティ（認証認可・入力検証・レート制限）
- エラー処理（外部サービス障害・タイムアウト・リトライ）
- トランザクション（ロールバック・冪等性）
- 後方互換性（既存APIへの影響）
- パフォーマンス（ページネーション・N+1・インデックス）
- 監視・ログ（何をどのレベルでログするか）
### Step 3: 実装前確認
以下を明示すること:
- 実装を開始してよいか（YES/NO + 理由）
- 人間に確認が必要な事項のリスト
- 推奨する実装順序Skill実例：エラー対応で脇道に入ったときに戻る指示
# SKILL: 目的再確認・迷走防止
## このSkillを使うタイミング
- エラー修正が連続して3ステップを超えた場合
- 依存関係の問題に引っ張られている場合
- 「なぜこの作業をしているのか」が不明瞭になった場合
## 手順
### 1. 現在の作業を停止する
今やっていることを一度止める。
### 2. 起点を確認する
CLAUDE.mdの「今回の目的」を読み直す。
### 3. 現在の作業と目的の整合を確認する
- 今やっていることは、今回の目的に直接貢献しているか？
- エラー修正・依存解消は「本来の目的を達成するための手段」として正当か？
- NOなら: エラーを一時的に無視し、本来の目的に戻れるか検討する
### 4. 判断の報告
以下を人間に報告すること:
- 現在の状況と、なぜ止まったか
- 本来の目的への影響
- 提案する次のアクション（最低2つの選択肢）- CLAUDE.mdは200〜400行以内に収め、詳細はSkillsに分離する
- 禁止事項・目的・停止条件・DoDは必ずCLAUDE.mdに含める
- 「目的再確認・迷走防止Skill」はAIの長期目標逸脱への具体的な緩和策
- 「エラー対応中に本来目的を見失ったときに戻る手順」をSkillとして用意しておく
GitHub Copilotでスペック駆動開発を行うための事前設定
執筆時点の公式ドキュメントでは、GitHub Copilotはrepository-wide custom instructions（.github/copilot-instructions.md）、 path-specific instructions（特定パス配下のファイルにだけ適用される指示。.github/instructions/*.instructions.md）、 agent instructions（Copilotエージェント向け）という3層構造の指示システムを提供している。
優先順位の考え方
Personal instructions（VSCode設定）→ Repository instructions（copilot-instructions.md）→ Organization instructionsの階層があり、 より具体的な設定が優先される。path-specific instructionsはapplyToフィールドでglobパターンを指定し、該当パスのファイルに自動適用される。
執筆時点の公式ドキュメントでは、path-specific instructionsの対応状況は利用するサーフェスによって異なる。 GitHub.com では Copilot coding agent・Copilot code review 向けと明記されており、 VS Code や Visual Studio では別の対応状況が存在する。 特に VS Code / Visual Studio / GitHub.com の間で挙動や対応範囲が完全に一致するとは限らないため、 自分の環境で動作しない場合も想定して、使用する環境の最新ドキュメントを必ず確認すること。
Copilotでどこまで「開発標準」を埋め込めるか
執筆時点の公式ドキュメントでは、GitHub Copilotは以下の複数のカスタマイズ手段を持つ。
- repository-wide custom instructions（
copilot-instructions.md）：リポジトリ全体に常時適用される基本ルール - path-specific instructions（
.github/instructions/）：特定パス配下にだけ適用される指示 - agent instructions：Copilotエージェント向けのタスク指示
- prompt files：特定のプロンプトを再利用する仕組み
- agent skills：特定タスクを再利用可能なスキルとして定義する仕組み
Codex・Claude Code が「AGENTS.md / CLAUDE.md + Skills」という比較的一本化された設計であるのに対し、 Copilotは複数の手段を役割分担して組み合わせる設計だ。 「Skills がない」のではなく、「Skills だけに一本化されたモデルではない」と理解するのが正確である。
| Copilotのカスタマイズ手段 | 主な用途 | スペック駆動での位置づけ |
|---|---|---|
copilot-instructions.md |
常時適用の全体ルール・禁止事項・設計原則 | 北極星文書。CLAUDE.md / AGENTS.md に相当 |
| path-specific instructions | ディレクトリ別の責務・命名規則 | 層別ルール。サブディレクトリ CLAUDE.md に相当 |
| prompt files | 繰り返し使うプロンプトの再利用 | 定型タスクの標準化 |
| agent skills（執筆時点） | 特定タスクを再利用可能スキルとして定義 | Codex / Claude Code の Skills に近い概念 |
| organization-level instructions | 組織横断の標準適用 | Codex / Claude Code にない強み |
Copilotは手段が多い分、「どの手段に何を書くか」の設計を誤ると意図が分散しやすい。 スペック駆動開発の観点では次の役割分担が基本になる。 常時守らせるルール（禁止事項・設計原則・停止条件）→ copilot-instructions.md、 ディレクトリ別の責務ルール → path-specific instructions、 特定タスクの再利用 → agent skills / prompt files。 また、自律エージェント制御の粒度（停止条件・目的逸脱防止）は相対的に設計しにくいため、 人間の介入フローを別途設計しておくことを推奨する。
.github/copilot-instructions.md 実例
# GitHub Copilot Instructions — [プロジェクト名]
## プロジェクト概要
Webアプリケーション（TypeScript/Node.js + React）。
クリーンアーキテクチャを採用。PostgreSQL + Prisma。
## ⛔ 絶対禁止事項
- 既存マイグレーションファイルへの変更
- 物理削除（直接DELETE実行）の使用（ソフトデリート必須）
- 認証・認可チェックのないエンドポイントの作成
- any型の使用（TypeScriptの型安全性を維持すること）
- console.log()を本番コードに残すこと
- シークレット・APIキーのハードコード
- 既存の共通処理（ロガー・バリデーション・認可チェック・例外ハンドラ）と責務が重複する utility / wrapper / helper の新規追加
## 🎯 現在の開発目的
決済機能をStripeからAWS Paymentに移行する。
スコープ: PaymentService, SubscriptionService のみ。
既存のSubscriptionテーブル構造は変更してはならない。
## 📐 設計原則
- クリーンアーキテクチャ: domain/application/infrastructure の依存方向を守る
- ドメイン層はHTTP・ORM・外部サービスを知らない
- 依存性注入を必ず使用（直接new禁止）
- 単一責任原則: 1クラス/1関数は1つの責務のみ
- 横断的関心事（ログ・バリデーション・認可・例外処理）は既存の共通実装を優先利用すること。実装前に必ず既存の共通処理を確認する
## 🧪 テスト方針
- 新しい機能には必ずユニットテストを書く（テストファースト推奨）
- 外部サービスはモック化する
- テストファイルは対応するソースファイルと同じディレクトリに配置
- テストを削除・スキップしてテストをパスさせることは禁止
## 🔐 セキュリティ方針
- 入力値は必ずバリデーション（zodを使用）
- SQLはPrisma ORMのみ使用（rawクエリ禁止）
- 認証: JWTを使用、有効期限は必ず設定
- エラーレスポンスにスタックトレースを含めない
- ユーザー入力をそのままログに出力しない（PIIマスキング必須）
## 🛑 人間レビュー必須条件
以下の変更には必ず人間レビューを求めること:
- 認証認可ロジックの変更
- データベーススキーマの変更
- 既存APIの破壊的変更
- 外部サービスの認証情報取り扱い変更
- データ削除・移行処理
## 📋 実装前確認事項
提案するコードに以下が含まれていないか確認すること:
1. 上記禁止事項への違反
2. 既存テストの破壊
3. 型安全性の低下（any, as any）
4. セキュリティ上の懸念path-specific instructions 実例（バックエンド）
---
applyTo: "src/infrastructure/**"
---
# インフラ層（src/infrastructure/）の規約
## このディレクトリの責務
- 外部サービス（DB・API・メール・ストレージ）との通信のみ
- ビジネスロジックをここに書いてはならない
- ドメイン層のインターフェースを実装すること
## 具体的なルール
- Prismaクライアントの使用はこの層のみ許可
- HTTP通信はこの層のみ許可（axiosまたはfetch）
- エラーはドメイン例外に変換してから上位層に伝播させる
- 接続情報は必ず環境変数から取得（ハードコード禁止）
- リトライ・タイムアウト処理はこの層で実装する
## ファイル命名規則
- `*.repository.ts`: データベースアクセス
- `*.gateway.ts`: 外部API通信
- `*.adapter.ts`: 外部サービスのアダプターpath-specific instructions 実例（フロントエンド）
---
applyTo: "src/frontend/**"
---
# フロントエンド（src/frontend/）の規約
## このディレクトリの責務
- UIコンポーネントとユーザーインタラクション
- APIとの通信はsrc/frontend/api/以下に集約
- ビジネスロジックをコンポーネントに書いてはならない
## Reactの規約
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- カスタムフック（useXxx）でロジックを分離する
- Propsには必ずTypeScript型定義を付ける
- useEffectの依存配列を省略しない
## セキュリティ
- dangerouslySetInnerHTML の使用禁止
- ユーザー入力を直接DOMに反映しない
- APIトークンをlocalStorageに保存しない（HttpOnly Cookieを使用）
## デザイン
- Tailwind CSSを使用。インラインstyleは禁止
- コンポーネントファイルは1ファイル200行以内を目安に分割迷走防止のための確認ルール例
---
applyTo: "**"
---
# 全ファイル共通：目的逸脱防止ルール
## コード変更前の確認
変更を提案する前に以下を確認すること:
1. この変更は.github/copilot-instructions.mdの「現在の開発目的」に沿っているか
2. 禁止事項リストに抵触しないか
3. 影響範囲は最小限か（関係ない部分を変更していないか）
## 懸念がある場合
以下の場合はコードを提案する前に懸念を明示すること:
- 既存のテストが壊れる可能性がある場合
- 認証認可ロジックに触れる場合
- データの削除・変換が必要な場合
- 仕様が不明で推測が必要な場合- Copilotは「Skills がない」のではなく、agent skills・custom instructions・path-specific instructions・prompt files を組み合わせる複合モデル
- 常時ルール →
copilot-instructions.md、ディレクトリ別 → path-specific、タスク再利用 → agent skills / prompt files という役割分担が基本 - 組織標準をOrganization-level instructionsで横展開できる点はCodex・Claude Codeにない強み
- 自律エージェント制御の粒度は相対的に低いため、人間の介入フローを別途設計する
3ツール共通で使える「最小構成」推奨テンプレート
どのツールを使うにせよ、AIに渡すべき最小の情報セットは共通だ。 以下のテンプレートを土台に、ツールごとのファイルフォーマットに変換して適用する。
- プロジェクト概要・今回の目的・今回やらないこと
- 絶対禁止事項（最優先・ファイル冒頭に）
- 設計原則・アーキテクチャルール
- テスト戦略・品質基準
- 実装前・中・後のチェックリスト
- 停止条件・人間レビュー必須条件
- Definition of Done
## セクション1: プロジェクト概要・スコープ
プロジェクト: [名前]
技術スタック: [TypeScript / Python / Go など]
アーキテクチャ: [クリーンアーキテクチャ / MVC / マイクロサービス など]
今回の目的: [具体的に1〜2文で]
今回やること: [箇条書き]
今回やらないこと: [箇条書き]
壊してはいけない機能: [箇条書き]
---
## セクション2: 絶対禁止事項
- 物理削除（直接DELETE）禁止
- 認証認可なしAPIの作成禁止
- シークレットのハードコード禁止
- 既存マイグレーションの変更禁止
- eval() / exec() / 動的コード実行の禁止
- 既存パブリックAPIの破壊的変更禁止
- 既存の共通処理（ロガー・バリデーション・認可・例外ハンドラ）と責務が重複する utility / wrapper / helper の新規追加禁止
- [プロジェクト固有の禁止事項を追加]
---
## セクション3: 設計原則
- [依存方向のルール]
- [責務分離のルール]
- [命名規則]
- [ファイル配置のルール]
- 横断的関心事（ログ・バリデーション・認可・例外処理）は既存の共通実装を優先利用すること。重複する utility / wrapper は追加しない
---
## セクション4: テスト戦略
- テストファースト: [必須/推奨]
- テスト種別比率: ユニット[X]% / 統合[Y]% / E2E[Z]%
- カバレッジ基準: [X]%以上
- モック方針: [外部サービスはモック / DBは実DBで統合テスト など]
---
## セクション5: チェックリスト
### 実装前
- [ ] 要件が今回の目的と一致しているか
- [ ] 影響範囲を特定したか
- [ ] テストケースを先に書いたか
### 実装中（迷ったときに確認）
- [ ] 今やっていることは今回の目的に沿っているか
- [ ] 禁止事項に抵触していないか
- [ ] 既存テストを壊していないか
### 実装後
- [ ] 全テストがパスするか
- [ ] 禁止事項を守れているか
- [ ] DoDを満たしているか
---
## セクション6: 停止条件（実装を止めて人間に報告すること）
- 既存APIの破壊的変更が必要な場合
- 認証認可ロジックの変更が必要な場合
- DBスキーマの削除・型変更が必要な場合
- ビジネスロジックの意図が不明な場合
- セキュリティ上の懸念が生じた場合
- エラー修正が目的から逸脱していると感じた場合
---
## セクション7: Definition of Done
- [ ] 全ユニットテストパス
- [ ] カバレッジ[X]%以上
- [ ] 禁止事項すべて遵守
- [ ] 既存APIの後方互換性維持
- [ ] セキュリティチェック通過
- [ ] コードレビュー承認3ツールへのマッピング
| セクション | Codex | Claude Code | GitHub Copilot |
|---|---|---|---|
| プロジェクト概要・スコープ | AGENTS.md 冒頭 | CLAUDE.md 冒頭 | copilot-instructions.md 冒頭 |
| 絶対禁止事項 | AGENTS.md（⛔ セクション） | CLAUDE.md（⛔ セクション） | copilot-instructions.md（⛔ セクション） |
| 設計原則 | .codex/skills/clean-arch.skill.md | .claude/skills/clean-arch.md | copilot-instructions.md に要約 + path-specific で詳細 |
| テスト戦略 | .codex/skills/tdd.skill.md | .claude/skills/tdd.md | copilot-instructions.md に記述 |
| チェックリスト | AGENTS.md の実装前チェックリスト | CLAUDE.md の実装前チェックリスト | 全体適用instructions（applyTo: "**"） |
| 停止条件 | AGENTS.md（🛑 セクション） | CLAUDE.md（🛑 セクション） | copilot-instructions.md（🛑 セクション） |
| Definition of Done | AGENTS.md（✅ セクション） | CLAUDE.md（✅ セクション） | copilot-instructions.md（✅ セクション） |
- どのツールでも「禁止事項→目的→設計→テスト→確認→停止条件→DoD」の7構造が基本
- 最初は短くてもよい。1ページのAGENTS.md/CLAUDE.mdから始めて、育てていく
- ツール特性に合わせてSkills（Codex/Claude Code）またはpath-specific instructions・agent skills（Copilot）で詳細化する
現時点での限界と、過信してはいけないポイント
CLAUDE.md・AGENTS.md・copilot-instructions.mdを整備しても、AIがその内容を100%遵守する保証はない。 これらは法律ではなく、「強い文脈」だ。AIはあくまでも確率的な推論エンジンであり、 長い指示の後半にある重要なルールを見落とすことがある。
明確にしておくべき限界一覧
| 限界 | 現実 | 対策 |
|---|---|---|
| 指示ファイルは絶対ではない | AIは禁止事項を見落とすことがある。特に文書が長いほど | 禁止事項はファイル冒頭・短く・箇条書きで |
| 長すぎるルールは読まれにくい | 200行超のCLAUDE.mdは後半のルールが薄くなる | コア指示を短く保ち、詳細はSkillsへ |
| ツールごとに対応機能が揺れる | 執筆時点の仕様が変わることがある | 公式ドキュメントを定期的に確認する |
| AIは途中で目標を見失う | 複数ステップの作業で目的逸脱が起きやすい | 停止条件と中間確認を設計する |
| 完全放任は危険 | 中間確認なしで長時間実行させると取り返しのつかない変更が起きうる | 段階ごとに人間がアウトプットを確認する |
| 最終責任は人間にある | 「AIが書いたから」はプロとして通用しない | レビューと承認プロセスを廃止しない |
人間レビューが絶対必須な領域
- セキュリティ・認証認可：AIはセキュリティの文脈を誤解しやすい。ペネトレーションテスト相当の確認が必要
- データ削除・移行処理：取り返しのつかない変更。必ず人間がレビューし、バックアップを確認する
- 既存機能への影響範囲：AIは影響範囲の全貌を把握できないことがある
- 例外処理・障害対応設計：エラーハンドリングはビジネス要件と密接に絡む。AIの「合理的な判断」は文化や要件と合わない場合がある
- 個人情報・規制対応：GDPRや個人情報保護法の解釈はAIに委ねない
- 指示ファイルは「保証」ではなく「強い文脈」にすぎない
- 長すぎる指示は効力が落ちる。短く・重要なものを冒頭に
- AI駆動開発でも人間レビューを廃止してはならない
- セキュリティ・データ削除・認可・移行処理は必ず人間が最終判断する
AI駆動開発の競争力は「モデル性能」ではなく「設計知識の質」で決まる
AI駆動開発が話題になるとき、多くの議論は「どのモデルが賢いか」に向かいがちだ。 しかし現場で事故を起こしているチームと、成果を出しているチームの差は、モデルの性能ではなく、 「AIに渡す設計知識の質と構造」にある。
優秀なチームほど、プロンプトを工夫する前に標準を整備している。 要件・設計原則・禁止事項・テスト方針・停止条件・DoDを文書化し、 AIが参照できる形でリポジトリに永続させる。そうして初めて、AIは「任せられる存在」に近づく。
この記事が伝えたかったこと
- AI駆動開発の事故は「AIの性能不足」×「人間の指示不足」の掛け算で起きる
- AIの長期目標維持の弱さは、コード品質問題と別の、重要な失敗要因だ
- 解決策は「より良いプロンプト」ではなく「開発プロセスのAI可読化」だ
- AGENTS.md / CLAUDE.md / copilot-instructions.md は、その実践的な基盤となりうる
- ただし指示ファイルは法律ではない。中間確認と人間レビューは必ず残す
- AI駆動開発を成功させる能力とは、AIを上手く使う能力ではなく、開発知識を構造化する能力だ
今日から始める3つの具体的行動
- まずAGENTS.md / CLAUDE.md を1ページ書く：禁止事項・今回の目的・停止条件の3セクションだけでもよい。完璧を目指さず、今日作る
- 次のAIタスクで中間確認ポイントを設計する：「設計ドキュメントを提示してから実装を開始すること」という1行を指示に入れるだけでも違う
- チームの暗黙知を禁止事項リストに変換する：「うちは絶対物理削除しない」「ソフトデリート必須」といった不文律を、AIが読める禁止事項として書き起こす
すぐ使える設定ファイル雛形まとめ
以下は、今日からそのまま叩き台にできる設定ファイル雛形だ。プロジェクトに合わせて [ ] 内を置き換えて使用してほしい。
Codex AGENTS.md 雛形
# AGENTS.md — [プロジェクト名]
# Codex（OpenAI）用 永続指示ファイル
## ⛔ 絶対禁止事項（最優先・例外なし）
- 物理削除（DELETE FROM の直接実行）禁止 → ソフトデリートを使用
- 既存マイグレーションファイルの変更禁止
- 認証・認可チェックのないAPIエンドポイントの作成禁止
- シークレット・認証情報のハードコード禁止
- eval() / exec() / 動的コード実行の使用禁止
- テスト済みパブリックAPIの破壊的変更禁止
- 既存の共通処理（ロガー・バリデーション・認可・例外ハンドラ）と責務が重複する utility / wrapper / helper の新規追加禁止
- [プロジェクト固有の禁止事項を追記]
## 🎯 現在の目的（北極星）
目的: [何を作るか・1〜2文で]
今回やること:
- [タスク1]
- [タスク2]
今回やらないこと:
- [スコープ外1]
- [スコープ外2]
絶対に壊してはいけない機能: [既存の重要機能]
## ✅ Definition of Done
- [ ] 全ユニットテストパス（カバレッジ[X]%以上）
- [ ] 全統合テストパス
- [ ] 禁止事項すべて遵守
- [ ] 既存APIの後方互換性維持
- [ ] セキュリティチェック通過
## 📐 設計原則
アーキテクチャ: [クリーンアーキテクチャ / MVC / etc]
依存方向: [domain → application → infrastructure]
共通化原則: ログ・バリデーション・認可・例外処理は既存の共通実装を優先利用すること。責務が重複する utility / wrapper の新規追加は禁止
詳細: .codex/skills/clean-arch.skill.md を参照
## 🧪 テスト方針
方式: テストファースト（実装前にテストを書く）
比率: ユニット[70]% / 統合[25]% / E2E[5]%
詳細: .codex/skills/tdd.skill.md を参照
## 🔐 セキュリティ
入力バリデーション: 必須
SQLクエリ: ORMのみ（rawクエリ禁止）
詳細: .codex/skills/security.skill.md を参照
## 🛑 停止条件（実装を止め、状況・判断・提案を人間に報告すること）
- 既存パブリックAPIの破壊的変更が必要と判断した場合
- 認証認可ロジックの変更が必要な場合
- DBスキーマの列削除・型変更が必要な場合
- ビジネスロジックの意図が不明で推測が必要な場合
- セキュリティ上の懸念が生じた場合
- エラー修正が3ステップを超え、本来の目的から外れていると感じた場合
## 🔄 目的逸脱チェック
作業中に迷ったら、冒頭「現在の目的」を読み直し、
今やっていることがその目的に沿っているか確認すること。
沿っていなければ停止して報告すること。
## 📋 実装前チェックリスト
- [ ] 要件が「現在の目的」と一致しているか
- [ ] 影響範囲を特定したか
- [ ] テストケースを先に書いたか
- [ ] 禁止事項に抵触しないか
## 📚 Skills 参照リスト
- 設計: .codex/skills/clean-arch.skill.md
- TDD: .codex/skills/tdd.skill.md
- セキュリティ: .codex/skills/security.skill.md
- 要件整理: .codex/skills/requirements.skill.md
- 迷走防止: .codex/skills/refocus.skill.mdCodex SKILL.md 雛形（.codex/skills/security.skill.md）
# SKILL: セキュリティチェックリスト
# 使用タイミング: 新機能実装時・コードレビュー時
## 認証・認可
- [ ] すべてのエンドポイントに認証チェックがあるか
- [ ] リソースへのアクセスに認可チェック（本人/権限確認）があるか
- [ ] JWTには有効期限が設定されているか
- [ ] 管理者権限が必要な操作は別途ロールチェックがあるか
## 入力バリデーション
- [ ] すべてのユーザー入力がバリデーションされているか
- [ ] SQLクエリはパラメータ化またはORMを使用しているか
- [ ] ファイルアップロードのタイプ・サイズ制限があるか
- [ ] XSS対策（HTMLエスケープ）が実施されているか
## 出力・エラー処理
- [ ] エラーレスポンスにスタックトレース・内部情報が含まれていないか
- [ ] ログにパスワード・トークン・PIIが含まれていないか
- [ ] 機密情報がレスポンスに不要に含まれていないか
## 依存関係
- [ ] 追加するライブラリに既知の脆弱性がないか（npm audit / pip check 等）
- [ ] 環境変数が正しく使用されているか（ハードコードなし）
## セキュリティ懸念の報告
上記のいずれかに問題がある場合は実装を止め、
具体的な懸念内容と対策案を人間に報告すること。Claude Code CLAUDE.md 雛形
# CLAUDE.md — [プロジェクト名]
# Claude Code用 永続指示ファイル
## ⛔ 絶対禁止（例外なし・最優先）
- 物理削除禁止（ソフトデリート必須）
- 既存マイグレーション変更禁止
- 認証認可なしAPIの作成禁止
- シークレットのハードコード禁止
- any型の使用禁止（TypeScript使用時）
- 既存パブリックAPIの破壊的変更禁止
- 既存の共通処理（ロガー・バリデーション・認可・例外ハンドラ）と責務が重複する utility / wrapper / helper の新規追加禁止
## 🎯 今回の目的とスコープ
目的: [何を実装するか・1〜2文]
やること: [箇条書き]
やらないこと: [箇条書き]
壊してはいけないもの: [箇条書き]
## ✅ Definition of Done
- [ ] 全テストパス（カバレッジ[X]%+）
- [ ] 禁止事項遵守
- [ ] 後方互換性維持
- [ ] セキュリティ確認済み
- [ ] コードレビュー承認
## 📐 設計原則（詳細: .claude/skills/clean-arch.md）
- [アーキテクチャの1行要約]
- [依存方向のルール]
- 横断的関心事（ログ・バリデーション・認可・例外処理）は既存の共通実装を優先利用すること。重複する utility / wrapper は追加しない
## 🧪 テスト（詳細: .claude/skills/tdd.md）
- テストファースト必須
- 外部サービスはモック化
- 既存テストを壊さない
## 🛑 停止条件（停止→状況報告→人間の指示を待つ）
- 既存APIの破壊的変更が必要な場合
- 認証認可ロジックの変更が必要な場合
- DBスキーマの削除・型変更が必要な場合
- ビジネスロジックの意図が不明な場合
- セキュリティ上の懸念が生じた場合
- エラー修正で目的から逸脱していると感じた場合
## 🔄 迷走チェック
「今やっていることは今回の目的に沿っているか？」
→ NOなら停止して報告。詳細: .claude/skills/refocus.md
## 📚 参照Skills
- .claude/skills/clean-arch.md
- .claude/skills/tdd.md
- .claude/skills/security.md
- .claude/skills/requirements.md
- .claude/skills/refocus.mdClaude Code SKILL.md 雛形（.claude/skills/refocus.md）
# SKILL: 目的再確認・迷走防止
# 使用タイミング: エラー修正が3ステップ超 / 目的が不明瞭になったとき
## 手順
### Step 1: 作業を停止する
### Step 2: CLAUDE.mdの「今回の目的」を読み直す
### Step 3: 整合性チェック
以下を自問すること:
- 今やっていることは今回の目的に直接貢献しているか？
- エラー修正は「目的達成のための手段」として正当か？
- 本来の目的に戻れる状態か？
### Step 4: 報告（以下の形式で人間に提示する）
```
現在の状況: [何をしていたか]
止まった理由: [なぜ止まったか]
本来の目的との関係: [目的に沿っているか、外れているか]
提案する選択肢:
A) [選択肢1 + 理由]
B) [選択肢2 + 理由]
推奨: [AまたはB + 推奨理由]
```
### Step 5: 人間の確認を待つ
確認なしに再開してはならない。GitHub Copilot .github/copilot-instructions.md 雛形
# GitHub Copilot Instructions — [プロジェクト名]
## プロジェクト概要
[プロジェクトの1〜2行説明]
技術スタック: [TypeScript / Python / etc]
アーキテクチャ: [クリーンアーキテクチャ / MVC / etc]
## ⛔ 絶対禁止事項
- 物理削除（直接DELETE実行）禁止
- 既存マイグレーションの変更禁止
- 認証認可なしAPIの作成禁止
- シークレット・APIキーのハードコード禁止
- [TypeScript使用時] any型の使用禁止
- 既存パブリックAPIの破壊的変更禁止
- 既存の共通処理（ロガー・バリデーション・認可・例外ハンドラ）と責務が重複する utility / wrapper / helper の新規追加禁止
## 🎯 現在の開発目的
[何を作っているか・1〜2文]
スコープ外: [今回やらないことを明示]
絶対に壊してはいけない機能: [箇条書き]
## 📐 設計原則
- [アーキテクチャルール]
- [依存方向]
- [責務分離の方針]
- 横断的関心事（ログ・バリデーション・認可・例外処理）は既存の共通実装を優先利用すること。実装前に必ず既存の共通処理を確認する
## 🧪 テスト方針
- 新機能には必ずユニットテストを書く
- 外部サービスはモック化する
- テストを削除・スキップしてパスさせることは禁止
## 🔐 セキュリティ方針
- 入力値は必ずバリデーション
- SQLはORMのみ（rawクエリ禁止）
- エラーレスポンスにスタックトレースを含めない
- PIIを含むデータのログ出力には必ずマスキングを適用
## 🛑 人間レビュー必須条件
以下の変更を提案する場合は、必ず先に懸念を提示すること:
- 認証認可ロジックの変更
- DBスキーマの変更
- 既存APIの破壊的変更
- データ削除・移行処理
- 外部サービス認証情報の取り扱い
## 📋 コード提案前チェック
提案する前に以下を確認すること:
- 禁止事項に違反していないか
- 既存テストが壊れないか
- 影響範囲は最小限か
- 仕様が不明な場合は推測せず、懸念を先に提示することGitHub Copilot path-specific .instructions.md 雛形
---
applyTo: "src/[対象ディレクトリ]/**"
---
# [ディレクトリ名] の規約
## このディレクトリの責務
[このディレクトリが担当する責務を1〜3行で]
## このディレクトリに置くべきもの
- [ファイル種別と命名規則]
- [例: *.repository.ts — DBアクセス]
## このディレクトリに置いてはいけないもの
- [禁止事項]
- [例: ビジネスロジック]
## 依存関係のルール
- [使ってよい外部依存]
- [使ってはいけない依存]
## 命名規則
- [クラス名: XxxService / XxxRepository / etc]
- [ファイル名: xxx.service.ts / xxx.repository.ts / etc]
## セキュリティ固有ルール
- [このディレクトリ固有のセキュリティ要件]
## 変更時の確認事項
- [ ] このディレクトリの責務を超えていないか
- [ ] 外部依存が規約に沿っているか
- [ ] 対応するテストを更新・追加したか完璧な指示ファイルを最初から作る必要はない。今日のゴールは「何も書かれていない状態からの脱却」だ。
最初の1ページ：「⛔ 絶対禁止事項」「🎯 今回の目的」「🛑 停止条件」の3セクションだけを書く。 それだけで、AI駆動開発の最悪のシナリオ——目的を見失ったAIが禁止されているロジックを削除しながら暴走する——を、 大幅に減らすことができる。
