🤖

「AI 仕様駆動開発」の罠：AI も要件を読み飛ばす

2025/12/24に公開

「要件定義書を渡せば、AI が完璧に実装してくれる」
そう思っていた時期が、私にもありました。
Claude に要件定義書を渡して、「実装して」と言えば、魔法のように完璧なコードが出てくる。
...と思ってた。
結論から言うと、AI（Claude）も人間と同じミスをする。

要件定義書を渡しても、「全部読んで全部実装する」わけではない。
人間のエンジニアに仕様書を渡しても、見落としがあるのと同じ。
AI だから大丈夫、なんてことはなかった。

 この記事が役立つ方Claude Code / Cursor / Copilot 等で AI に実装を任せている方
「要件定義書を渡したのに実装されていない」経験をした方
AI 開発で品質を担保する仕組みを探している方
Claude Code のスキル（.claude/skills/）の実践例を知りたい方
「AI は万能」という幻想から目覚めたい方
AI 時代の開発フローを模索している方

 何が起きたか食事管理アプリの開発で、LINE LIFF と Cognito の認証統合を実装した。
要件定義書を丁寧に書いた。Acceptance Criteria（受け入れ条件）もチェックボックス形式で明記した。
### FR-007: ユーザーデータマッピング

**Acceptance Criteria:**

- [ ] Cognito ユーザー作成時、`sub` が `cognito_user_id` に保存される
- [ ] LINE ログイン時、LINE User ID が `line_user_id` に保存される
- [ ] 既存 LINE ユーザーの移行後、両方の属性が設定される
- [ ] DynamoDB の GSI1（`line_user_id`）と GSI2（`cognito_user_id`）が機能する
設計書にも、ID マッピングのルールが明記されていた。
「これだけ丁寧に書けば、AI も間違えないだろう」
Claude に要件定義書と設計書を渡して、「実装して」と依頼した。

 結果8 個の問題が発生した。
「え...？」
特に致命的だったのが、Cognito sub をそのまま DynamoDB の user_id として使っていたこと。
LINE Bot 経由で登録済みのユーザーが、LIFF 経由でログインするとデータにアクセスできない。
「山田さんのデータください」「山田さん？いませんね」「いや、この前登録したよ！」「ああ、YAMADA さんですか。別人ですよ」
...同じ人なのに。
要件定義書には「Cognito sub は cognito_user_id に保存する」と書いてあった。

設計書には「DynamoDB の user_id を正とする」と書いてあった。
両方とも無視されていた。
丁寧に書いた仕様書、読んでなかったの...？

 なぜ AI も見落とすのか人間と同じ理由だ。


人間がやりがちなこと
AI もやる


優先度が低そうな要件を後回しにする
同じ

目の前の問題解決に集中して全体を見失う
同じ

「動いた」時点で完了と判断する
同じ

チェックリストを確認せずに完了報告する
同じ

AI も人間も、本質的に同じミスをする。
FR-007 の Acceptance Criteria。チェックボックスは未チェックのまま「実装完了」と報告された。
「全部できました！」
...できてない。チェックボックス、一個もチェックされてないじゃん。
新人エンジニアに「仕様書読んでね」と渡して、読まずに実装されたあの感じ。
AI だからって、違わなかった。

 AI は「自分で自分をチェックしない」これが本質的な問題。
人間のエンジニアでも、自分で書いたコードのレビューは甘くなる。「たぶん大丈夫」と思いがち。
AI も同じ。
実装した AI 自身に「要件を満たしているか確認して」と聞いても、「はい、満たしています」と答えがち。
**自分のテスト答案を自分で採点するようなもの。**甘くなる。
実際にデータがどう流れているか、DynamoDB にどんな値が入っているか、確認しない。「コード書いたから、動くはず」で終わる。
...人間と同じじゃん。

 解決策：仕組みで防ぐAI も見落とすなら、見落とせない仕組みを作るしかない。
「次から気をつけます」は通用しない。人間でも AI でも。
仕組みで強制する。

 Claude Code のスキル機能Claude Code には「スキル」という機能がある。.claude/skills/ にマークダウンファイルを置くと、特定のタイミングで自動的に実行される手順書のようなもの。
これを使って「自分で自分をチェックする」仕組みを作った。

 acceptance-checker スキル「実装完了」と言われたら自動発動。逃げられない。
## ワークフロー

### Step 1: 要件定義から AC を抽出

1. 要件定義書を読み込む
2. 各機能要件の Acceptance Criteria を抽出
3. チェックリストを生成

### Step 2: AC を 1 つずつ検証

各 AC に対して以下を確認：

□ AC: [Acceptance Criteria の内容]

検証方法:

- コード確認: [該当するファイル:行番号]
- データ確認: [DynamoDB / API レスポンス]
- テスト確認: [テストファイル:テスト名]

結果: ✅ Pass / ❌ Fail / ⚠️ Partial

証跡:

- [実際のコード/データ/ログの抜粋]
ポイントは証跡。「インフラ定義の存在 ≠ 機能の実装」を区別する。
❌ ダメな検証（AI がやりがち）:
□ Cognito ユーザーが作成される
  結果: ✅ Pass
  証跡: Terraform で aws_cognito_user_pool を定義している
「設計図がある」と「家が建った」は違う。
Terraform で定義しただけでは、実際にデータが流れているか分からない。でも AI は「設計図あるから OK」と判断しがち。
✅ 良い検証:
□ Cognito sub が cognito_user_id に保存される

  検証方法:
  1. liff_login Lambda のコードを確認
  2. _ensure_dynamodb_user() で cognito_sub を保存しているか
  3. 実際の DynamoDB レコードを確認

  結果: ❌ Fail

  証跡:
  - src/lambda/liff_login/__init__.py
    → cognito_sub を user_id として使用している
    → cognito_user_id カラムへの保存処理がない
**「実際に動いているか」を確認する。**設計図じゃなくて、建った家を見る。
これで「要件を実装していない」ことが検出できる。

 design-reviewer スキル設計完了時に発動。実装の前に、設計段階でミスを潰す。
## 検証項目

### データフロー

□ データの流れが明確か
□ ID マッピングが定義されているか
□ 移行パスが設計されているか

### 見落としやすい項目

要件:
"既存 LINE ユーザーの移行時、両方の属性が設定される"

設計で見落としがち:

- どのタイミングで設定するか
- 誰が（どのコンポーネントが）設定するか
- 既存データのマイグレーションはどうするか
**「見落としやすい項目」をスキルに書いておく。**これが重要。
AI は「書いてあること」は見る。でも「書いてないこと」は見ない。
だから、「見落としがちなこと」を明示的に書いておく。

 効果このスキルを導入した後、同じ種類の問題は発生していない。
「実装完了」の定義が明確になった:
❌ コードを書いた（これだけでは不十分）
❌ テストが通った（テストも見落としてる可能性）
✅ 要件定義の AC を証跡付きですべてパスした
**「できた」の定義を厳しくする。**それだけで、品質が上がる。

 教訓
 1. AI も人間と同じミスをする「AI に任せれば大丈夫」は幻想。
AI は魔法じゃない。優秀なジュニアエンジニアみたいなもの。
優秀だけど、見落としはある。指示は必要。チェックも必要。

 2. 仕組みで防ぐ見落としを「注意力」で防ごうとしてはいけない。人間でも AI でも。
「次から気をつけます」は、次も忘れる。
自動的に検証が走る仕組みを作る。スキルファイルを書く。逃げられないようにする。

 3. 証跡が重要「設計図がある」と「家が建った」は別。
AI に「できた？」と聞くと「できました！」と答える。でも、実際のデータを見せてと言うと、見せられないことがある。
実際のコード・データ・ログで確認する。証拠を求める。

 4. AI 時代の開発フロー従来:
  要件 → 設計 → 実装 → （人間が）レビュー → 完了

AI 時代:
  要件 → 設計 → AI が実装 → AI がスキルで自己検証 → 人間が結果確認 → 完了
AI に実装を任せるなら、AI に検証も任せる。
ただし、検証の仕組みは人間が設計する。AI に「自分をチェックして」と言っても甘くなる。だから、チェック方法を人間が決めて、それを AI に強制する。
採点基準は先生（人間）が作る。生徒（AI）は採点基準に従うだけ。

 まとめ「AI 仕様駆動開発」は、要件定義書を渡せば完璧に実装してくれる夢の開発手法...ではない。
AI も人間と同じように要件を見落とす。だから、見落とせない仕組みを作ることで対処する。
AI は万能じゃない。でも、仕組みと組み合わせれば、とても強力になる。
Claude Code のスキル機能を活用して、「要件を実装までに見落とさない」仕組みを作ってみてください。

人間がやりがちなこと	AI もやる
優先度が低そうな要件を後回しにする	同じ
目の前の問題解決に集中して全体を見失う	同じ
「動いた」時点で完了と判断する	同じ
チェックリストを確認せずに完了報告する	同じ

この記事が役立つ方

何が起きたか

結果

なぜ AI も見落とすのか

AI は「自分で自分をチェックしない」

解決策：仕組みで防ぐ

Claude Code のスキル機能

acceptance-checker スキル

design-reviewer スキル

効果

教訓

1. AI も人間と同じミスをする

2. 仕組みで防ぐ

3. 証跡が重要

4. AI 時代の開発フロー

まとめ

Discussion