AIに実装させるとき、どう書けば“勝手に推測”されない仕様になる？

結論（Conclusion）

AI開発での事故の多くは「コードが下手」ではなく 仕様に意思決定が書かれていないことが原因。

以下を“強制入力”にすると、AIが勝手に埋める余地が減って実装が安定する。

• 入力/出力（API/UI/データ/ログ）
• 制約（セキュリティ、レイテンシ、コスト、実行環境）
• 例外・失敗時の挙動（タイムアウト、再試行、部分成功）
• 受け入れ条件（テスト）
• フェーズ分割（レビューゲート）

Implementation examples may be available on DevSnips.

背景（Explanation）

AIに実装を任せると、仕様の穴がそのまま 勝手な設計判断として補完される。 よく起きるのはこの3つ。

• 真実のソースが曖昧（DBなのかキャッシュなのか）
• 失敗時の挙動が未定義（リトライ/エラー表示/ロールバック）
• 制約が未記載（権限、PII、コスト、p95レイテンシ）

長文にすることが目的ではない。拘束力のある仕様にするのが目的。

実務手順（Practical Guide）

1) まず「何を委譲するか」を決める

丸ごと実装を委譲するなら、最低限次が必要。

• 何を作るか（目的）
• 何を壊してはいけないか（制約）
• どう終わりを判定するか（テスト）

テストが書けないなら、委譲範囲を狭める（スパイク、設計案の比較まで、など）。

2) このテンプレをコピペして埋める

あなたはシニアソフトウェアエンジニアです。以下の仕様に従って実装してください。

## Goal（目的：1文）
[ユーザー価値として何を達成する？]

## Context（前提）
- Product: [どんなアプリか]
- Runtime: [Next.js / Node / Python など]
- Deploy: [Vercel / k8s など]

## Inputs（入力）
- [APIリクエスト、UIイベント、バッチ、スケジュール]

## Outputs（出力）
- [DB更新、APIレスポンス、UI状態、ログ/メトリクス]

## Constraints（絶対条件）
- Security: [認証/認可、PII、秘密情報、権限]
- Performance: [p95レイテンシ、バッチサイズ]
- Cost: [トークン/外部API料金、キャッシュ]
- Reliability: [タイムアウト、再試行、冪等性]

## Edge cases + failure behavior（例外と失敗時の挙動）
- [ケース] -> [期待する挙動]

## Acceptance criteria（受け入れ条件/テスト）
- Unit tests:
  - [テスト名] -> [期待値]
- Integration tests:
  - [シナリオ] -> [期待値]

## Delivery plan（分割）
1) Phase 1: 最小の縦切り + テスト
2) Phase 2: ハードニング + ログ/監視
3) Phase 3: リファクタ + ドキュメント

## Output format（出力順）
- 最初に：あなたが置いた設計判断を箇条書きで再掲
- 次に：Phase 1のみを実装
- 最後に：Phase 2/3のTODOを列挙

3) コードの前に「設計判断の再掲」を必ず出させる

ここがレビューのコア。 この箇条書きがズレていたら、コードを書く前に仕様を直す。

4) フェーズごとにレビューゲートを通す

• テスト
• セキュリティ境界（権限、PII、ログ）
• ロールバック可能性

失敗パターン（Pitfalls）

• 「いい感じに」だけで丸投げ（制約/テスト/失敗挙動がない）
• 真実のソースが不明で状態遷移を捏造される
• 1回で全部出させてレビュー不能
• 仕様変更の差分を渡さず、古い前提のまま実装が進む

チェックリスト（Checklist）

• [ ] 目的がユーザー価値として1文で書けている
• [ ] 入力が列挙されている（イベント/リクエスト/バッチ）
• [ ] 出力が列挙されている（DB/レスポンス/UI/ログ）
• [ ] 認証/認可ルールが明確
• [ ] PII/秘密情報の扱い（ログ禁止含む）が明確
• [ ] レイテンシ予算（p95/p99）が明確
• [ ] コスト予算（トークン/外部API/キャッシュ方針）が明確
• [ ] 失敗時の挙動（タイムアウト/再試行/部分成功）が明確
• [ ] 例外ケースが最低5つは書かれている
• [ ] 受け入れ条件が「実行可能なテスト」として書かれている
• [ ] フェーズ分割とレビューゲートがある
• [ ] コード前に設計判断の再掲をさせている

FAQ

Q1. リポジトリ全部を貼ったほうが正確？

基本は不要。実装判断が変わる情報（インターフェース、データモデル、制約）だけを渡す。大量貼り付けは幻覚を増やしやすい。

Q2. 制約がまだ分からない場合は？

その時点で実装を委譲しない。まず「設計案を2〜3個出して比較」するスパイクに切り替えて、制約を確定してから実装する。

Q3. 仕様が十分かどうかの判定は？

AIが出す「設計判断の再掲」が、人間のレビューで承認できる内容になっていること。そして受け入れ条件が具体で実行可能になっていること。

内部リンク（Internal links）

• 親記事（Hub）：AI開発：まずはここから
• 関連記事：
  • 曖昧な依頼を要件定義に変換する質問リスト
  • 文章のAI臭を消すチェックリスト
  • 認可（IDOR）を潰すチェックリスト

参考（一次情報）

• RFC 2119（MUST/SHOULDの言語）: https://www.rfc-editor.org/rfc/rfc2119

免責

機密情報はプロンプトに貼らないこと。