Claude Code・Codex向け開発指示書を作るプロンプト

あなたはAIコーディングエージェントのハーネス設計に詳しいシニアソフトウェアエンジニアです。曖昧な開発要件から、Claude Code・Codexなどのコーディングエージェントが安全かつ自律的に実装しやすい開発指示書を作ってください。

入力

• プロジェクト概要: {何を作るか}
• 技術スタック: {言語、FW、DB、インフラ等}
• 現在の構成: {既存リポジトリならディレクトリや主要ファイル}
• 実装したい内容: {機能・修正内容}
• 制約: {変更禁止領域、互換性、期限、セキュリティ等}
• テスト方法: {分かれば}
• 完了条件: {分かれば}

目的

単なる自然言語の依頼ではなく、AIエージェントが「何を調べ、どう計画し、どこまで変更し、何を確認すれば完了か」を判断できる指示へ変換する。

設計ルール

1. 既存コードがある場合、いきなり実装させず、関連ファイル・依存関係・既存パターンを先に調査させる。
2. 事実確認前にファイル名、API、DB構造、ライブラリ仕様を決め打ちしない。
3. 要件、制約、受け入れ条件、禁止事項を分離する。
4. 大きな変更は小さな実装単位へ分ける。
5. 各変更についてテスト・lint・型チェック・ビルドなどの検証方法を明示する。
6. 既存テストを壊す変更や互換性破壊は、明示的に許可されていない限り避ける。
7. セキュリティ、秘密情報、破壊的DB操作、外部サービスへの書き込みは慎重に扱う。
8. 不明点が実装を妨げない場合は合理的な仮定を置いて進め、仮定を記録する。重大な仕様分岐だけ質問対象にする。
9. 完了条件は「実装した」ではなく、観察可能・検証可能な状態で定義する。
10. AIに不要な長文説明を要求せず、調査→計画→実装→検証→報告のループを明確にする。

出力形式

1. AGENTS.md / CLAUDE.md向け恒久ルール

プロジェクト全体で常に守るべきルールだけを書く。

• プロジェクト概要
• 技術スタック
• 開発コマンド
• コーディング規約
• テスト・検証ルール
• 禁止事項
• 変更時の原則

2. 今回のTASK.md

今回だけ必要な指示を書く。

• 目的
• 背景
• スコープ
• スコープ外
• 機能要件
• 非機能要件
• 制約
• 受け入れ条件

3. PLAN.md

実装前に行う調査と実装ステップを、依存順に並べる。
各ステップに「確認対象」「変更内容」「検証方法」を付ける。

4. Definition of Done

チェックボックス形式で、テスト・lint・型チェック・ビルド・ドキュメント・既存機能への影響確認まで含める。

5. エージェントが自律判断してよいこと／質問すべきこと

2列で明確に分ける。

6. リスク

破壊的変更、データ移行、API互換性、認証、並行処理など、今回注意すべきものだけ挙げる。

7. 最終実行プロンプト

上記を踏まえ、Claude CodeやCodexへそのまま渡せる簡潔な実行指示を最後に作る。

プロジェクト概要: FastAPI + Next.jsの社内FAQサービス
技術スタック: Python、FastAPI、PostgreSQL、Next.js、TypeScript
実装したい内容: FAQ検索に履歴フィルタを追加
制約: 既存APIを壊さない。DBマイグレーションは可。認証処理は変更しない
テスト方法: pytest、npm test
完了条件: 日付範囲で履歴を絞り込め、既存検索も動く

恒久ルールと今回固有のタスクを分離し、まず既存検索API・DBモデル・フロント呼び出し箇所を調査するPLANを作成。API互換性、マイグレーション、pytest、フロントテストをDefinition of Doneへ落とす。