実装が進むほど仕様書とコードがズレていく。気づくのはたいてい受入テストの段階で、「仕様書ではAだったのに実装はBになってる」と発覚し、後出しでドキュメントを直す。これがいわゆる仕様ドリフトです。
「AIで仕様書レビュー」と聞きますが、単発で要約させても全体整合は確認できません。本当に効くのは、要件→仕様→テスト→コードの繋がりをSkillで毎週自動監査し、PMが差分にだけ集中する運用です。
この記事では、Claude Codeで仕様トレーサビリティを保ち、ドリフトを早期検知する実装を、現場で動かせる粒度で解説します。
なぜ仕様ドリフトは止められないのか
仕様ドリフトが起きるのは、PMの怠慢ではなく構造的な問題です。
- 要件ID・仕様ID・テストID・コードのリンクが手書き：仕様書のExcel列に「テストID」を埋めるが、テストが増減しても更新されない
- レビューが目視：仕様書とコードを並べて目で確認するため、規模が大きいと回らない
- 不整合の検知が事後：受入テストや本番障害ではじめて発覚し、手戻りコストが膨大になる
Claude Codeは、Skillで「ID紐づけ表」を毎週再生成し、不整合のあるIDだけPMに提示する運用を素直に組めます。
Claude Codeを「仕様トレーサビリティ監査器」にする全体像
必要な要素は次の3つです。
- 要件・仕様・テストID台帳：
docs/specs/配下にYAML形式で保管 - トレーサビリティ監査Skill：要件→仕様→テスト→コードの繋がりを毎週検証する
- CLAUDE.md仕様運用ルール：ID命名規則、不整合検出時の対応、ドリフト防止のレビュー基準
これが揃うと、PMは月曜にSkillを叩くだけで「先週から不整合になったID」だけが手元に届き、レビューが差分集中型になります。
ステップ1：ID台帳をYAML化する
docs/specs/requirements.yaml、specs.yaml、tests.yaml の3ファイルを用意します。
# docs/specs/requirements.yaml
requirements:
- id: REQ-001
title: "ユーザーはメールアドレスでログインできる"
related_specs: [SPEC-101, SPEC-102]
status: "approved"
# docs/specs/specs.yaml
specs:
- id: SPEC-101
title: "ログインAPIの認証ロジック"
related_requirement: REQ-001
related_tests: [TEST-A1, TEST-A2]
code_paths: ["src/api/auth/login.ts"]
last_updated: "2026-04-15"
# docs/specs/tests.yaml
tests:
- id: TEST-A1
title: "正常系：正しいパスワードでログイン成功"
related_spec: SPEC-101
test_code: "tests/api/auth/login.spec.ts"ID命名は REQ-XXX SPEC-XXX TEST-XXX で統一。命名規則がCLAUDE.mdで明文化されていれば、AIが新規IDを提案するときにもブレません。
ステップ2：トレーサビリティ監査Skillを定義する
.claude/skills/spec-trace/SKILL.md を作成します。
---
name: spec-trace
description: docs/specs/ のYAML台帳をベースに、要件→仕様→テスト→コードの繋がりを監査し、不整合（孤立・欠落・参照切れ・更新遅延）を tmp/specs/{YYYY-MM-DD}-trace.md に出力する
disable-model-invocation: true
allowed-tools: Read, Write, Glob, Grep
---
# 仕様トレーサビリティ監査Skill
## 入力
- なし（実行日のスナップショットを取る）
## 処理
1. requirements.yaml / specs.yaml / tests.yaml を読み、グラフ構造を構築
2. 次の不整合を検出
- 孤立要件：related_specsが空のREQ
- 孤立仕様：related_requirementが空または存在しないSPEC
- 孤立テスト：related_specが空または存在しないTEST
- コード参照切れ：specs.yamlのcode_pathsが実ファイルに存在しない
- 更新遅延：related_codeのファイル更新日 > spec.last_updatedで30日以上ズレ
3. 影響度（高・中・低）を付与
4. PMが優先確認すべきID一覧を上位に表示
## 出力フォーマット
- ファイル名：`tmp/specs/{YYYY-MM-DD}-trace.md`
- 章立て：①サマリー（不整合数） ②要対応IDトップ10 ③不整合詳細表 ④更新遅延一覧 ⑤PM判断欄（**空欄**）
## 厳守
- 不整合の原因をAIが推測しない（事実だけを列挙）
- 影響度判定は要件のstatus（approved/draft）を考慮
- 孤立要件は最優先で表示「原因をAIが推測しない」が重要。仕様ドリフトの原因は文脈依存なので、AIには「事実列挙」だけ任せ、原因分析と対応はPMが行います。
ステップ3：CLAUDE.mdに仕様運用ルールを書く
## 仕様トレーサビリティ運用ルール
### ID命名規則
- 要件：REQ-XXX（3桁、ゼロ埋め）
- 仕様：SPEC-XXX（3桁、ゼロ埋め）
- テスト：TEST-AXX（カテゴリ文字＋2桁）
### 不整合検出時の対応
- 孤立要件：要件オーナーに即エスカレーション、その週中にspec紐づけ
- コード参照切れ：実装担当に確認、spec or code どちらが正かを判断
- 更新遅延30日超：レビュー会議の議題に上げる
### ドリフト防止のレビュー基準
- 仕様変更PRは spec.yaml の last_updated 必須更新
- コードと仕様が乖離する場合、PR説明欄に「仕様側を後追い更新する旨」を明記
- 仕様書のないPRはマージしない（CIで弾く）ルールはCLAUDE.mdに集約しておくと、Skillの中身を変えなくてもポリシー変更が反映されます。
ステップ4：実際の運用フロー
毎週月曜の運用は次の通りです。
- PMが
claudeを起動し/spec-traceを実行 - 生成された
tmp/specs/{date}-trace.mdの「要対応IDトップ10」を確認 - ⑤PM判断欄に「優先対応するID」「ペンディングするID」「追加調査するID」を分類記入
- 仕様会議で対応ID担当をアサイン、追跡
慣れれば月曜の30分で「今週どこを直すか」が決まります。
期待効果と運用上の注意点
導入チームから報告される効果は3点です。
- 受入テスト時の手戻りが激減：仕様ドリフトを毎週潰すため、後発の不整合が減る
- PMのレビューが差分集中型になる：全体目視ではなく不整合IDだけ見ればよくなる
- 新任メンバーが仕様の構造を理解しやすい：ID台帳が常に最新で参照しやすい
落とし穴は3つ。
- ID台帳のメンテを放置しない：YAMLが古いとSkillの監査結果も古くなる
- AIに不整合の原因を聞かない：原因はAIには分からない。事実列挙までで止める
- CIで仕様PRを必須化する：ルールだけでは守られない。コードPRで仕様更新を強制する仕組みを入れる
まとめ
- 仕様ドリフトはID紐づけの手書きと全体目視レビューの2つで悪化する
- SkillでID台帳を毎週監査し、PMは差分にだけ集中するのが現実解
- AIには「事実列挙」を任せ、「原因分析」と「対応判断」はPMが担う
- CLAUDE.mdにID命名・不整合対応ルールを書くと、運用が崩れにくい
ここまでで「動く仕様トレーサビリティ監査器」は作れます。実務でこれを“品質を担保する運用”に育てるには、要件管理プロセス、変更管理（CCB）の設計、テスト戦略との接続といった上位設計が必要です。
AIX-101『仕様書・報告書・議事録』 と IPJ-105『要件・仕様統制』 を組み合わせると、本記事のSkillをベースに、要件→仕様→テストの統制プロセス全体をAIで加速する体系を学べます。仕様ドリフトに毎回振り回されているPMが、最短で“仕組みで止める運用”に到達するための導線です。