AIで回る「ドキュメント駆動開発」— Claude Codeスキル設計と運用の実践

はじめに

システム開発において、ドキュメントは実装と同じくらい重要です。しかし、多くのプロジェクトでドキュメントが実装に追いつかず、形骸化してしまうことがあります。

※ この記事は 2025年10月時点 の情報です。

この記事では、AI（Claude Code）を活用した次世代のドキュメント管理手法を紹介します。Claude Code のカスタムスキルを使うことで、ドキュメント管理を自動化・効率化できます。

導入は3ステップでOK

1. .claude/ を配置（本記事の雛形をコピー）
2. /deep-planning を実装前に必ず実行（PRテンプレに追記）
3. 月初に /document-consistency-check（定期的に実行）

想定読者

• ドキュメント管理に課題を感じているエンジニア
• プロジェクトの規模が大きくなりドキュメントが追いつかなくなった方
• AI を活用した開発手法に興味がある方
• チーム開発でドキュメントの一貫性を保ちたい方

この記事で学べること

• ✅ 体系的なドキュメント構成の設計方法
• ✅ AI（Claude Code）を活用したドキュメント駆動開発の実践
• ✅ ドキュメントと実装の同期戦略
• ✅ Claude Code カスタムスキルの活用法
• ✅ 実践的なレビュープロセス

ドキュメント管理の3つの課題

システム開発でよくあるドキュメント管理の課題：

1. ドキュメントが実装に追いつかない

症状:

• 「実装は完了したけど、ドキュメント更新は後回し」
• 「PR作成時に初めてドキュメントが古いことに気づく」

原因:

• ドキュメント更新を「最後のタスク」として扱っている
• ドキュメントと実装の同期チェックがない

2. ドキュメントの一貫性が保てない

症状:

• 「料金が複数のドキュメントで異なる値になっている」
• 「実装とAPIドキュメントの仕様が一致しない」

原因:

• 横断的な整合性チェックがない
• ドキュメント間の参照関係が不明確

3. ドキュメントが見つからない・読まれない

症状:

• 「どのドキュメントを読めばいいか分からない」
• 「古いドキュメントと新しいドキュメントが混在」

原因:

• ドキュメント構成が体系的でない
• ドキュメントの役割・対象読者が不明確

ドキュメント構成の設計

体系的なドキュメント構成を設計することで、これらの課題を解決できます。

番号付きディレクトリ構造

ドキュメントを番号付きディレクトリで整理すると、読む順序が明確になります。

docs/
├── 00_管理/                   # プロジェクト管理
│   ├── project-plan.md        # 全体計画・Phase管理
│   ├── reviews/               # セルフレビュー記録
│   └── plans/                 # タスク別詳細計画
│       ├── current/           # 進行中のタスク
│       └── completed/         # 完了したタスク
├── 10_業務要件定義/           # 業務要件定義
│   └── requirements.md
├── 20_システム要件定義/       # システム要件定義
│   ├── 00_システム概要/
│   ├── 10_機能要件/
│   └── 20_非機能要件/
├── 30_基本設計/               # 基本設計
│   ├── 00_システム全体/
│   ├── 10_データベース設計/
│   ├── 20_API設計/
│   ├── 30_認証設計/
│   ├── 40_外部連携設計/
│   └── 50_UI設計/
├── 40_詳細設計/               # 詳細設計（機能設計を含む）
│   └── [機能別設計書]
├── 50_単体テスト設計/         # 単体テスト設計
│   └── unit-test-strategy.md
├── 60_結合テスト設計/         # 結合テスト設計
│   └── integration-test-strategy.md
└── 80_運用設計/               # 運用設計
    └── operation-manual.md

ポイント:

• 番号で読む順序を明示: 00 → 10 → 20 → 30 の順に読む
• V字モデルに準拠: 左側（要件→設計）と右側（テスト設計）が対応
• 階層を深くしすぎない: 最大3階層まで
• 番号は10刻み: 後から新しいカテゴリを挿入できる（例: 25_中間設計/）

標準的なシステム開発のフェーズに従った構成です。要件定義 → 基本設計 → 詳細設計 → テスト設計の流れが明確になります。

ドキュメントの種類と目的

ドキュメント種類	目的	対象読者	更新頻度
業務要件定義	ビジネス要件を定義	PM, ビジネス側	低（初期のみ）
システム要件定義	技術要件を定義	エンジニア全員	中（Phase単位）
基本設計	アーキテクチャ・DB・API設計	エンジニア全員	高（実装前に更新）
詳細設計	個別機能の詳細設計	担当エンジニア	高（機能追加ごと）
単体テスト設計	単体テスト戦略	QA, エンジニア	中（機能追加ごと）
結合テスト設計	結合テスト戦略	QA, エンジニア	中（機能追加ごと）
運用設計	運用・監視の手順	インフラ、運用担当	低（リリース前後）

AI時代のドキュメント駆動開発（Claude Code活用）

ここからが本題です。Claude Code のカスタムスキルを活用することで、ドキュメント管理を自動化・効率化できます。

Claude Code カスタムスキルとは？

Claude Code は、Anthropic が提供する AI 開発アシスタントです。その中で、**特定のタスクを自動実行する「スキル」**を定義できます。

スキルは .claude/skills/ ディレクトリに配置し、スラッシュコマンドで呼び出します。

# 実装前のドキュメント更新を自動化
/deep-planning サブスクリプション機能を実装

# 実装後の整合性チェックを自動化
/deep-self-review

# 横断的整合性の自動検証
/document-consistency-check

スキルの構成:

• .claude/skills/[スキル名]/SKILL.md - スキルの詳細手順
• .claude/commands/[スキル名].md - スラッシュコマンドのプロキシ

具体的なファイル配置:

.claude/
├── skills/
│   ├── deep-planning/
│   │   └── SKILL.md
│   ├── deep-self-review/
│   │   └── SKILL.md
│   └── document-consistency-check/
│       └── SKILL.md
└── commands/
    ├── deep-planning.md
    ├── deep-self-review.md
    └── document-consistency-check.md

最小のSKILL雛形:

.claude/skills/document-consistency-check/SKILL.md の例：

---
name: Document consistency check
description: ドキュメント横断整合性チェック - tsx↔md同期、料金・制限値等の横断的な数値・文言の一致を自動検証
---

# Document consistency check

## Instructions

ドキュメント更新完了後、またはコード変更後に、以下の手順で横断的な整合性を検証してください。
**重要**: 整合性の不一致を発見した場合は、必ず修正すること。

### 1. 検証対象の定義

以下のファイル群の整合性を検証します：

#### ユーザー向けドキュメント（tsx/jsx）
- `app/(marketing)/pricing/page.tsx` - 料金ページ
- `app/(marketing)/features/page.tsx` - 機能紹介ページ
- `components/landing/PricingSection.tsx` - ランディングページ料金セクション
- `components/landing/HeroSection.tsx` - ヒーローセクション

#### Markdownドキュメント
- `docs/50_UI設計/pricing-design.md` - 料金ページ設計（markdown）
- `docs/50_UI設計/features-design.md` - 機能紹介ページ設計（markdown）

#### 実装ファイル
- `lib/payment/config.ts` - 決済設定（料金、プランの実装）
- `types/subscription.ts` - サブスクリプション型定義

### 2. 横断的整合性検証

以下の項目について、**全ファイルで完全に一致していること**を検証します。

#### 2.1 サブスクリプション料金
- プラン別の料金が全ドキュメントで一致しているか

#### 2.2 機能制限値
- リクエスト回数上限、保存件数上限、その他の制限値が一致しているか

#### 2.3 用語の統一
- 技術用語、プラン名、機能名の表記が統一されているか

### 3. tsx ↔ md 同期チェック

以下のファイルペアの内容が完全に一致していることを検証します：

#### 3.1 料金ページ
- **tsx**: `app/(marketing)/pricing/page.tsx`
- **md**: `docs/50_UI設計/pricing-design.md`

#### 3.2 機能紹介ページ
- **tsx**: `app/(marketing)/features/page.tsx`
- **md**: `docs/50_UI設計/features-design.md`

### 4. 実装との整合性検証

#### 4.1 lib/payment/config.ts との整合性

**検証項目**:
- 設定ファイルの料金・制限値
- ドキュメント記載の料金・制限値

**確認方法**:
1. `lib/payment/config.ts` を読み込む
2. 料金・制限値の定義を確認
3. 全ドキュメントと完全一致しているか検証

### 5. 検証結果レポート生成

検証結果を以下の形式でユーザーに報告します：

---
## 横断的整合性検証結果

### 1. サブスクリプション料金
- プラン別料金: [✅/⚠️/❌] (不一致があれば詳細)

### 2. 機能制限値
- リクエスト上限: [✅/⚠️/❌]
- 保存件数上限: [✅/⚠️/❌]

### 3. tsx ↔ md 同期チェック
- pricing/page.tsx ↔ pricing-design.md - [✅/⚠️/❌]
- features/page.tsx ↔ features-design.md - [✅/⚠️/❌]

### 4. 実装との整合性
- lib/payment/config.ts - [✅/⚠️/❌]

## 発見された不整合（あれば）
[不整合の詳細をリスト]

## 推奨される修正（あれば）
[修正すべき箇所と修正内容]

---

## 重要な原則

1. **全ファイルで完全一致を確認**
   - 数値、文言は完全に一致していなければならない
   - 曖昧な表現や、微妙に異なる表現も不整合とみなす

2. **不整合を発見したら必ず修正**
   - レポート生成だけで終わらせない
   - 修正すべき箇所を特定し、修正を実施

3. **tsx ↔ md は完全同期が必須**
   - ユーザー向けページ（料金、機能紹介等）は tsx と md で完全に一致していなければならない
   - どちらか一方だけ更新されている状態は避ける

4. **実装との整合性が最優先**
   - `lib/payment/config.ts` の値が実装の真実
   - ドキュメントが実装と異なる場合は、実装に合わせるか、実装を修正

---

## 実行例

### 例1: 新機能追加後の検証

**ユーザー**: サブスクリプション機能のドキュメント更新が完了したので、整合性をチェックしてください

**実行内容**:
1. 全ドキュメント（tsx 3、md 2）を読み込む
2. サブスクリプション料金を検証 → ✅ 全一致
3. 機能制限値を検証 → ✅ 全一致
4. tsx ↔ md 同期チェック → ✅ 全一致
5. lib/payment/config.ts との整合性 → ✅ 全一致
6. レポート生成 → **横断的整合性: ✅ 完全一致**

### 例2: 料金変更時の検証

**ユーザー**: サブスクリプション料金を変更したので、整合性をチェックしてください

**実行内容**:
1. 全ドキュメントを読み込む
2. 料金を検証
   - PricingSection.tsx: ✅ 新料金
   - pricing/page.tsx: ⚠️ 旧料金（未更新）
   - pricing-design.md: ⚠️ 旧料金（未更新）
   - lib/payment/config.ts: ✅ 新料金
3. レポート生成 → **不整合2件発見**
4. 修正提案 → 2ファイルの料金を更新

このSKILL雛形をベースに、プロジェクト固有の監視対象や正規表現をカスタマイズできます。

なぜ AI でドキュメント管理を自動化するのか？

従来のワークフロー（人間だけ）:

1. 実装を開始
2. 実装完了後に「ドキュメント更新を忘れた」と気づく
3. 慌ててドキュメント更新
4. 複数のドキュメントで料金が異なることに気づく
5. 手動で全ファイルを確認 → 時間がかかる

AI駆動のワークフロー（Claude Code）:

1. /deep-planning で実装前にドキュメント自動更新
2. 実装作業
3. /deep-self-review で整合性を自動チェック
4. 不整合を自動検出 → 修正
5. /document-consistency-check で最終確認

効果:

• ✅ ドキュメント更新忘れを防止
• ✅ 不整合を自動検出（人間では見落としがち）
• ✅ レビュー時間を大幅削減（手動チェックが不要）

スキル1: deep-planning（実装前のドキュメント更新を自動化）

目的: 実装を開始する前に、関連ドキュメントをすべて更新する

実行タイミング: 新機能実装やバグ修正の開始前

実行内容:

1. project-plan.md を読み込み、現在のPhase・タスクを確認
2. タスクの性質分析（新規タスク vs 既存タスクへの追加）
3. 該当タスクファイル（docs/00_管理/plans/current/YYYY-MM-DD-*.md）の確認または作成
4. 最近のコミット履歴確認
5. 影響範囲の分析（変更が必要なファイル・コンポーネントを特定）
6. 関連ドキュメントの更新:
   • 10_業務要件定義/
   • 20_システム要件定義/
   • 30_基本設計/
   • 40_詳細設計/
   • 50_単体テスト設計/
7. タスクファイルの更新（TodoList、成果物、検証項目）
8. ユーザーに計画を提示 → 承認後、実装開始

使用例:

$ /deep-planning サブスクリプション機能を実装

✅ project-plan.md 確認完了
✅ 新規タスクとして分類
✅ タスクファイル作成: docs/00_管理/plans/current/2025-10-20-subscription-feature.md
✅ 影響範囲分析完了:
  - 決済設定ファイル（lib/payment/config.ts）
  - 料金表示コンポーネント（components/landing/PricingSection.tsx）
  - 料金ページ設計（docs/50_UI設計/pricing-design.md）

✅ ドキュメント更新完了:
  - 20_システム要件定義/system-requirements.md
  - 30_基本設計/basic-design.md
  - 40_詳細設計/subscription-design.md

計画をユーザーに提示中...
承認後、実装を開始してください。

SKILL.md 雛形:

.claude/skills/deep-planning/SKILL.md の例：

---
name: Deep planning
description: 作業開始前にproject-planを確認・分析し、関連ドキュメントを更新してから実装を開始する
---

# Deep planning

## Instructions

新しい機能や大きな変更を実装する前に、必ず以下の手順を実行してください。
**重要**: ドキュメントの更新は実装の前に必ず行うこと。

### 1. 現状分析フェーズ

1. **現在のブランチ確認とブランチ作成**
   - `git branch --show-current`で現在のブランチを確認
   - **原則**: 新しい作業を開始する場合は、origin/main から新規ブランチを作成
   - ブランチ作成手順:
     ```bash
     git checkout -b feature/[機能名] origin/main
     # または
     git checkout -b fix/[修正名] origin/main
     ```

2. **project-plan.mdの確認**
   - `docs/00_管理/project-plan.md`を読み込む
   - 現在のPhase、完了済みタスク、未完了タスクを確認

3. **タスクの性質分析**
   - このタスクは**新規の独立したタスク**か、**既存タスクへの追加**か？

### 2. 深い思考フェーズ

ユーザーの要求を分析し、以下を深く考える：

1. **要求の分析**
   - 実装したい機能は何か？
   - project-planのどのPhaseに該当するか？

2. **技術的な影響範囲の分析**
   - 既存のコードにどのような影響があるか？
   - どのファイル・コンポーネントを変更する必要があるか？

### 3. ドキュメント更新フェーズ（実装前に必ず実行）

分析結果をもとに、関連ドキュメントを更新：

1. **関連する設計ドキュメントの確認と更新**
   - 10_業務要件定義/ - 機能要件や非機能要件の追加・変更
   - 20_システム要件定義/ - システムアーキテクチャの変更
   - 30_基本設計/ - 具体的な実装設計
   - 40_詳細設計/ - 実装の詳細仕様
   - 50_テスト設計/ - テスト計画

2. **タスクファイルの作成または更新**
   - 新規タスク: `docs/00_管理/plans/current/YYYY-MM-DD-[タスク名].md` を作成
   - 既存タスク: `docs/00_管理/plans/current/YYYY-MM-DD-*.md` を更新

3. **project-plan.mdの概要更新**
   - マイルストーンの更新
   - 進捗状況の更新

### 4. 実装計画の策定

具体的な実装計画を立てる：

1. **タスクの分解**
   - 大きな機能を小さなタスクに分解
   - 各タスクの実装順序を決定

2. **TodoWriteでタスク管理**
   - TodoWriteツールを使って実装タスクを登録

3. **ユーザーに実装計画を提示**
   - 分析結果と実装計画をユーザーに提示
   - ユーザーの承認を得てから実装開始

---

## 重要な原則

1. **必ず計画を確認してから作業する**
   - 衝動的に実装を開始しない
   - project-planとの整合性を常に意識

2. **ドキュメントは実装の前に更新**
   - 実装後に「後で更新する」は避ける
   - **この原則は絶対に守ること**

3. **影響範囲を過小評価しない**
   - 小さな変更でも、広範囲に影響する可能性がある

---

## 実行例

### 例1: 新機能の実装

**ユーザー**: サブスクリプション機能を実装したい

**実行内容**:
1. project-plan.md確認 → Phase 4（サブスクリプション機能）
2. タスクの性質分析 → 新規の独立した機能 → 新規タスク
3. 新規タスクファイル作成（例: `2025-10-24-subscription-feature.md`）
4. 影響範囲分析（決済API、Firestore、UI）
5. ドキュメント更新（basic-design.md、test-cases.md等）
6. TodoWriteでタスク登録
7. ユーザーに計画提示 → 承認後、実装開始

### 例2: バグ修正

**ユーザー**: ログイン時にエラーが出る問題を修正したい

**実行内容**:
1. project-plan.md確認 → Phase 2（認証機能）
2. タスクの性質分析 → バグ修正（小さな改善） → 既存タスクへの追加
3. 進行中のタスクファイル確認
4. エラー原因分析、影響範囲確認
5. 必要に応じてドキュメント更新
6. 修正開始

効果:

• ✅ 実装前にドキュメントを書くことで、設計の曖昧さを早期発見
• ✅ 影響範囲を可視化し、変更漏れを防止
• ✅ タスクファイルで進捗管理し、TODO忘れを防止

Doc-Driven Development（ドキュメント駆動開発） の実践です。実装の前にドキュメントを書くことで、「こんなはずじゃなかった」を防げます。

スキル2: deep-self-review（実装後の整合性チェックを自動化）

目的: 実装完了後、ドキュメントと実装の整合性を徹底的にチェック

実行タイミング: PR作成前

実行内容:

1. 横断的整合性検証（数値・制限値・料金等の一致）
   • 料金が全ドキュメントで一致しているか
   • 機能制限値（リクエスト回数、保存件数等）が一致しているか
   • API仕様が実装と一致しているか
2. 参照整合性検証（削除・変更したファイルへの参照）
   • 削除したファイルが他のドキュメントから参照されていないか
   • 内部リンクが正しく機能するか
3. 実装との整合性検証（ドキュメントと実装コードの一致）
   • API設計書と実装が一致しているか
   • 型定義とドキュメントのデータモデルが一致しているか
4. 新たな矛盾の発見
   • 作業による副作用で生じた矛盾がないか
5. レビュー結果を記録（docs/00_管理/reviews/YYYY-MM/vX.XX-*.md）

使用例:

$ /deep-self-review

✅ 横断的整合性検証:
  - 料金: 全7ファイルで一致 ✅
  - 制限値: 全6ファイルで一致 ✅
  - API仕様: 設計書と実装で一致 ✅

✅ 参照整合性検証:
  - 削除ファイルへの参照なし ✅
  - 内部リンク健全性: すべて有効 ✅

✅ 実装との整合性検証:
  - lib/payment/config.ts と設計書が一致 ✅
  - types/subscription.ts と型定義ドキュメントが一致 ✅

⚠️ 新たな矛盾: 1件発見
  - components/landing/PricingSection.tsx で古い料金表示
  → 修正推奨

レビュー結果を記録中: docs/00_管理/reviews/2025-10/v2.26-subscription-feature.md

効果:

• ✅ 人間では見落としがちな不整合を自動検出
• ✅ レビュー結果を記録し、後から確認可能
• ✅ 同じミスを繰り返さないための履歴管理

SKILL.md 雛形:

.claude/skills/deep-self-review/SKILL.md の例：

---
name: Deep self review
description: 作業完了後に深くセルフレビューをする。
---

# Deep self review

## Instructions

作業完了後に、作業結果を深く深くセルフレビューしてください。
その際に、既存のdocsと実装を深く確認してください。
あなたは矛盾を確認したら、無視をせず必ず深く追求してください。
またそれを個別レビューファイル (`docs/00_管理/reviews/YYYY-MM/vX.XX-*.md`) に記録してください。

### 1. 横断的整合性検証

- 数値 (制限値、料金、回数等) が全ドキュメントで一致しているか
- プラン別の制限が明確に記載されているか
- 技術用語・API名が統一されているか

### 2. 参照整合性

- 削除・変更したファイルへの参照が残っていないか
- 内部リンクが正しく機能するか
- 設計書間の相互参照が正確か

### 3. 実装との整合性

- ドキュメントの記載と実装コードが一致しているか
- 型定義とドキュメントのデータモデルが一致しているか
- API仕様書と実際のエンドポイントが一致しているか

### 4. 新たな矛盾の発見

- 作業による副作用で生じた矛盾がないか
- 見落としていた関連箇所はないか
- エッジケースでの不整合はないか

### 5. レビュー結果の記録

新しいバージョンのレビュー記録を `reviews/YYYY-MM/vX.XX-{description}.md` に作成:

1. **ファイル名決定** (例: `v2.26-feature-name.md`)
2. **ファイル配置**: `docs/00_管理/reviews/YYYY-MM/`
3. **ファイル内容**: 9セクション構造
   - レビュー情報、変更サマリー
   - 横断的整合性検証
   - 参照整合性検証
   - 実装との整合性検証
   - 新たな矛盾・問題の発見
   - コード品質評価
   - ビジネス影響度の評価
   - リグレッションテスト結果
   - 推奨アクション、総合評価

---

## 重要な原則

1. **全ファイルで完全一致を確認**
   - 数値、文言は完全に一致していなければならない
   - 曖昧な表現や、微妙に異なる表現も不整合とみなす

2. **不整合を発見したら必ず修正**
   - レポート生成だけで終わらせない
   - 修正すべき箇所を特定し、修正を実施

3. **矛盾を無視しない**
   - 小さな不一致でも、後で大きな問題になる可能性がある
   - 徹底的に追求すること

---

## 実行例

### 例1: サブスクリプション機能実装後のレビュー

**ユーザー**: /deep-self-review

**実行内容**:
1. 横断的整合性検証
   - 料金: 全7ファイルで一致 ✅
   - 制限値: 全6ファイルで一致 ✅
2. 参照整合性検証
   - 削除ファイルへの参照なし ✅
3. 実装との整合性検証
   - lib/payment/config.ts と設計書が一致 ✅
4. 新たな矛盾: 1件発見
   - PricingSection.tsx で古い料金表示 ⚠️
5. レビュー結果を記録
   - docs/00_管理/reviews/2025-10/v2.26-subscription-feature.md

レビュー記録の例:

docs/00_管理/reviews/2025-10/v2.26-subscription-feature.md

# セルフレビューレポート v2.26

## レビュー情報

- **レビュー日**: 2025-10-24
- **レビュー対象**: サブスクリプション機能
- **関連PR**: #XXX

## 横断的整合性検証

### 料金の一致確認

| ファイル | Proプラン料金 | ステータス |
|---------|-------------|----------|
| requirements.md | ¥X,XXX/月 | ✅ 一致 |
| payment/config.ts | ¥X,XXX/月 | ✅ 一致 |
| pricing-design.md | ¥X,XXX/月 | ✅ 一致 |

**結果**: ✅ すべて一致

## 総合評価

✅ **合格** - ドキュメントと実装が完全に一致しています。

スキル3: document-consistency-check（横断的整合性の自動検証）

目的: 料金・制限値などの数値が全ドキュメントで一致しているか自動チェック

実行タイミング:

• 料金変更時
• ユーザー向けページ更新時
• 月次定期チェック

検証項目:

1. サブスクリプション料金（無料プラン・有料プラン）
2. 機能制限値（リクエスト回数、保存件数等）
3. 最大処理数（データ件数、アイテム数等）
4. tsx ↔ md 同期（pricing/page.tsx ↔ pricing-design.md）
5. 実装との整合性（lib/payment/config.ts との一致）

使用例:

$ /document-consistency-check

📋 ドキュメント横断整合性チェック

1. サブスクリプション料金の一致確認...
   ✅ 全7ファイルで一致

2. 機能制限値の一致確認...
   ✅ 全6ファイルで一致

3. 最大処理数の一致確認...
   ✅ 全6ファイルで一致

4. tsx ↔ md 同期チェック...
   ✅ pricing/page.tsx ↔ pricing-design.md 一致
   ✅ features/page.tsx ↔ features-design.md 一致

5. 実装との整合性チェック...
   ✅ lib/payment/config.ts と全ドキュメント一致

📊 チェック完了
総合評価: ✅ 合格（新たな不整合なし）

効果:

• ✅ 料金変更時の人為的ミスを防止
• ✅ 重要ドキュメントの正確性を保証（ユーザー向けページと実装の不一致を防止）
• ✅ 定期的な健全性チェックで、ドキュメントの信頼性を維持

料金や制限値の不一致は、ユーザーとのトラブルに直結します。document-consistency-check で必ず横断的整合性をチェックしましょう。

スキルの組み合わせ例

実際の開発では、複数のスキルを組み合わせて使用します。

パターン1: 新機能実装時

# 1. 実装前の準備（ドキュメント自動更新）
$ /deep-planning サブスクリプションのキャンセル機能を実装
→ ドキュメント更新、タスクファイル作成、影響範囲分析

# 2. 実装作業
$ git add . && git commit -m "feat: サブスクリプションのキャンセル機能を実装"

# 3. 実装後のレビュー（整合性チェック）
$ /deep-self-review
→ 横断的整合性、参照整合性、実装との整合性チェック

# 4. PR作成
$ git push && gh pr create

パターン2: 料金変更時

# 1. 実装前の準備
$ /deep-planning サブスクリプション料金を変更
→ 影響範囲分析: 決済設定、LP、料金ページ、機能紹介ページ

# 2. 実装作業
$ # 決済設定、LP、料金ページ、機能紹介ページを更新

# 3. 横断的整合性チェック（重要！）
$ /document-consistency-check
→ 全ドキュメントで料金が統一されているか確認

# 4. 実装後のレビュー
$ /deep-self-review
→ レビュー記録を作成

# 5. PR作成
$ git push && gh pr create

パターン3: 月次定期チェック

# 月初に定期的に実行
$ /document-consistency-check
→ ドキュメントの健全性をチェック

# 不整合が見つかった場合
$ /deep-planning ドキュメント不整合を修正
→ 不整合箇所を修正

$ /deep-self-review
→ 修正後の整合性を確認

リスクとガードレール

AI駆動のドキュメント管理を導入する際は、以下のリスクに注意が必要です。

1. 幻覚・誤修正への対策

リスク: AIが誤った情報を生成・修正してしまう

ガードレール:

• ✅ --dry-run をデフォルトにし、提案パッチとして出力
• ✅ 人間による承認ステップを必須化
• ✅ 重要ファイル（ユーザー向けページ等）は自動修正不可・差分提案のみ

# 安全な運用例
$ /document-consistency-check --dry-run
→ 差分を確認
→ 問題なければ手動で適用

2. 機密情報の取り扱い

リスク: 機密情報がAIに送信されてしまう

ガードレール:

• ✅ docs/80_運用設計/ai-usage-policy.md で送信禁止ファイルパターンを定義
• ✅ /.env*, /secrets/**, /config/production/** をスキル側で除外
• ✅ ローカル実行のみ（外部API送信なし）

# AI-usage-policy.md の例
## 送信禁止ファイルパターン
- /config/production/** （本番設定は人間のみ）
- /.env* （環境変数）
- /secrets/** （機密情報）

3. 責務分離

リスク: AIが本来触れない領域を変更してしまう

ガードレール:

• ✅ 重要ドキュメント（ユーザー向けページ等）は自動修正不可・差分提案のみ
• ✅ 重要ファイルは手動承認を必須化
• ✅ ファイルパターンで対象を制限

重要: 重要ドキュメントや機密情報には、AIによる自動修正を適用しないでください。差分提案のみに留め、人間による最終承認を必須化しましょう。

ドキュメント駆動開発（Doc-Driven Development）の実践

Doc-Driven Development（ドキュメント駆動開発） は、実装の前にドキュメントを書く開発手法です。

なぜドキュメントを先に書くのか

1. 設計の曖昧さを早期発見: 実装前に設計の矛盾に気づける
2. レビューが容易: コードレビュー前に設計レビューが可能
3. 実装との乖離が起きない: ドキュメントが最新であることが保証される

AI駆動のDoc-Drivenワークフロー

1. 要件確認
   ↓
2. /deep-planning 実行 ← AI がドキュメントを自動更新！
   - 業務要件定義
   - システム要件定義
   - 基本設計
   - 詳細設計
   ↓
3. ドキュメントレビュー
   - 設計の妥当性を確認
   - 影響範囲の確認
   - 承認
   ↓
4. 実装
   ↓
5. /deep-self-review 実行 ← AI が整合性を自動チェック！
   - 横断的整合性検証
   - 参照整合性検証
   - 実装との整合性検証
   ↓
6. PR作成・マージ

実装前にドキュメントを書くことで、設計の曖昧さを早期に発見できます。実装してから「こんなはずじゃなかった」を防げます。

ドキュメントテンプレート

ドキュメントの形式を統一することで、書きやすく・読みやすくなります。

基本設計書のテンプレート

# [機能名] 設計書

## ドキュメント管理情報
- **作成日**: YYYY-MM-DD
- **最終更新日**: YYYY-MM-DD
- **バージョン**: 1.0
- **ステータス**: 承認待ち / 承認済み
- **親ドキュメント**: [システム要件定義書](../20_システム要件定義/README.md)
- **関連ドキュメント**:
  - [業務要件定義書](../10_業務要件定義/requirements.md)
  - [データベース設計書](./10_データベース設計/firestore-schema.md)

## 1. 概要
[機能の概要を簡潔に記載]

## 2. 要件
[システム要件定義からの引用]

## 3. 設計
[詳細設計]

### 3.1 アーキテクチャ
[アーキテクチャ図、コンポーネント図]

### 3.2 データモデル
[Firestoreスキーマ、型定義]

### 3.3 API設計
[エンドポイント、リクエスト/レスポンス形式]

## 4. 実装方針
[実装時の注意点、ベストプラクティス]

## 5. テスト方針
[単体テスト、結合テストの方針]

## 6. 変更履歴
| バージョン | 日付 | 変更内容 |
|-----------|------|---------|
| 1.0 | YYYY-MM-DD | 初版作成 |

ポイント:

• ドキュメント管理情報: バージョン、更新日、関連ドキュメントを明記
• 変更履歴: 誰がいつ何を変更したか記録
• 親ドキュメント・関連ドキュメント: ドキュメント間の関係を明確化

レビュープロセス

ドキュメントの品質を保つために、セルフレビューを実施します。

セルフレビューのチェックリスト

実装完了後、PR作成前に以下をチェックします。

レビューチェックリスト

## 横断的整合性

- [ ] **料金**: 全ドキュメントで一致しているか
- [ ] **機能制限値**: リクエスト回数、保存件数などの制限値が一致しているか
- [ ] **サービスプラン**: プラン別の機能・制限が全ドキュメントで一致しているか

## 参照整合性

- [ ] **削除したファイル**: 他のドキュメントから参照されていないか
- [ ] **変更したAPI**: API設計書が更新されているか
- [ ] **変更した型**: 型定義ドキュメントが更新されているか

## 実装との整合性

- [ ] **API仕様**: API設計書と実装が一致しているか
- [ ] **データモデル**: Firestoreスキーマと型定義が一致しているか
- [ ] **UI仕様**: 画面遷移図と実装が一致しているか

## 新たな矛盾

- [ ] **今回の変更**: 既存ドキュメントと矛盾していないか
- [ ] **副作用**: 他の機能に影響していないか

## ドキュメント品質

- [ ] **バージョン番号**: 更新されているか
- [ ] **最終更新日**: 更新されているか
- [ ] **変更履歴**: 記録されているか

AI駆動のレビュー:

• /deep-self-review を実行することで、これらのチェック項目を自動検証
• レビュー結果は docs/00_管理/reviews/ に自動記録

よくある課題と解決策

課題1: ドキュメント更新を忘れる

従来の解決策: PR作成前チェックリスト

AI駆動の解決策: /deep-planning を実行し、実装前にドキュメントを自動更新

$ /deep-planning 新機能を実装
→ ドキュメントを自動更新 → 実装開始
→ ドキュメント更新忘れを防止！

課題2: ドキュメントの不整合に気づかない

従来の解決策: 手動で全ファイルを確認（時間がかかる）

AI駆動の解決策: /document-consistency-check で横断的整合性を自動検証

$ /document-consistency-check
→ 料金・制限値の不一致を自動検出
→ 人間では見落としがちな不整合を発見！

課題3: レビューが形骸化する

従来の解決策: レビューチェックリストを用意（でも時間がかかる）

AI駆動の解決策: /deep-self-review で整合性チェックを自動化

$ /deep-self-review
→ 横断的整合性・参照整合性・実装との整合性を自動検証
→ レビュー結果を自動記録
→ レビュー時間を大幅削減！

成果を測るKPI

AI駆動のドキュメント管理の効果を定量化することで、「効いた」が伝わる運用ができます。

推奨KPI（5つ）

KPI	測定方法	目標
不整合検出率	(#検出不整合 / #チェック実行)	月次で減少傾向
ドキュメント更新遅延	実装マージからドキュメント反映までの中央値（分）	60分以内
PR滞留時間	open→merge の中央値（時間）	24時間以内
レビューワークロード	レビューコメント数/PR、修正コミット数/PR	30%削減
重大インシデント件数	料金/規約の公開後不一致件数	ゼロ

効果測定の例

導入前（3ヶ月間）:

• 不整合検出率: 0%（手動チェックなし）
• ドキュメント更新遅延: 平均120分
• PR滞留時間: 平均48時間
• レビューコメント数: 平均8件/PR
• 重大インシデント: 2件（料金表示の不一致）

導入後（3ヶ月間）:

• 不整合検出率: 15% → 5%（月次で減少）
• ドキュメント更新遅延: 平均30分（75%削減）
• PR滞留時間: 平均18時間（62%削減）
• レビューコメント数: 平均5件/PR（37%削減）
• 重大インシデント: 0件（完全防止） ✅

KPIを可視化することで、経営層への説明や他チームへの導入促進に活用できます。

まとめ

この記事では、AI（Claude Code）を活用した次世代のドキュメント管理術を解説しました：

• ✅ 体系的なドキュメント構成: 番号付きディレクトリ（V字モデル準拠）
• ✅ AI駆動のドキュメント管理: deep-planning, deep-self-review, document-consistency-check
• ✅ 実装前にドキュメントを書く: 設計の曖昧さを早期発見
• ✅ 横断的整合性の自動検証: 料金・制限値の不一致を自動検出
• ✅ レビュー結果の自動記録: 同じミスを繰り返さない

AI時代のドキュメント管理の未来

Claude Code のようなAIツールを活用することで、ドキュメント管理の負担を大幅に軽減できます。

従来のワークフロー（人間だけ）:

• ❌ ドキュメント更新を忘れる
• ❌ 不整合に気づくのはレビュー時
• ❌ 手動チェックに時間がかかる

AI駆動のワークフロー（Claude Code）:

• ✅ 実装前にドキュメントを自動更新
• ✅ 不整合を自動検出
• ✅ レビュー結果を自動記録

次のステップ

1. ドキュメント構成を見直す: 番号付きディレクトリに移行
2. Claude Code を導入: カスタムスキルを作成
3. ドキュメント駆動開発を実践: 実装前にドキュメントを書く習慣
4. 定期的な整合性チェック: 月次で /document-consistency-check を実行

重要な原則

「人力チェックを"最後の砦"にし、日々の整合はAIに任せる」

これでドキュメントは"遅れて追いかけるもの"から、"実装を先導するレール"になります。

参考資料

• Claude Code 公式ドキュメント
• Documentation-Driven Development
• Docs as Code - Treating Documentation as Code
• The Documentation System - Divio
• Technical Writing | Google for Developers

---

Delivroute について

Delivrouteは、配送ルート最適化を簡単に行えるWebアプリケーションです。

• 🗺️ 最大10地点のルート最適化: Google Maps Routes APIで最適な配送順序を自動計算
• ⚡ 簡単CSVインポート: CSVファイルから一括で配送先を登録
• 💰 クレジット制: 無料プラン（月3回）、Proプラン（月60回）で気軽に利用可能

👉 サービスはこちら: https://delivroute.com

---

この記事が役に立ったら、ぜひいいね👍やコメント💬をお願いします！