はじめに
こんにちは！AOE部の荒川です。
私たちは、日々の開発業務でClaude Codeを使用しており、AI-DLC（AI-Driven Development Life Cycle）という開発手法で開発を進めています。AI-DLCでは、AIが要件定義、アーキテクチャ設計、実装計画といったドキュメントを大量に生成します。
しかし、AIが生成したドキュメントは開発途中で古くなっていってしまいます。
実装中に設計変更があったとき、どのドキュメントを更新すべきか分からず、結局ドキュメントが放置されてしまう...。
せっかく生成したドキュメントが誰も見ない資料になってしまうのではないか、と考えました。
そこで、本記事では、AIが生成したドキュメントの継続管理を支援するために、私が作成したClaude Code用のHooks・Skillについて解説します。
この機能により、ドキュメントを「作って終わり」から「継続的に価値を提供する資産」に変えることができます。
Claude CodeのHooksとSkills
まず、Claude Codeの機能である「Hooks」と「Skills」について押さえておきましょう。
今回作成した継続管理機能は、これら2つの仕組みを活用しています。
Hooks（自動で気づかせる） とは、Claude Codeにおいて、特定のイベント（ファイル編集、セッション終了など）が発生したときに自動的にスクリプトを実行する仕組みです。
今回の実装では、コードを変更したときに「このドキュメントの更新も必要かも」と教えてくれるようにしました。
Skills（必要な時に使える道具） とは、Claude Codeにおいて、ユーザーが呼び出したときにAIが特定のタスクを実行する仕組みです。
今回の実装では、/doc-syncと入力すれば「今どのドキュメントが古いか」を詳しく分析し、優先度付きの更新リストを生成してくれるようにしました。
HooksとSkillsの両方を組み合わせることで、開発中に自然とドキュメントが更新され続けます。
継続管理機能の詳細
ここからは、私が作成したClaude Code用のHooks・Skillの詳細を紹介します。
実装の全体像：
- Hooks: Bashスクリプトで実装し、
hooks.jsonで定義 - Skills: Markdownファイルで実装し、Claude Codeの標準ツール（Glob、Grep、Read）を使用
メインとなる3つの機能を順番に見ていきましょう。
1. /doc-sync - ドキュメント差分検出
/doc-syncは、実装とドキュメントの差異を自動検出し、優先度付きの更新リストを生成するSkillです。
使い方:
/doc-sync
具体的な用例:
例えば、ECサイトのプロジェクトでConstructionフェーズを終え、ARCHITECTURE.md、README.md、units.mdなどのドキュメントが生成されている状況を想定します。
開発中にpackage.jsonのReactバージョンを18.0.0から18.2.0に更新し、PaymentServiceという新しいコンポーネントを追加したとします。
この時点で/doc-syncを実行すると、以下のような結果が返ってきます：
# ドキュメント差分レポート 生成日時: 2026-03-03T15:30:00Z ## 🔴 HIGH優先度（今すぐ対応） - [ ] README.md - 技術スタックセクション - 依存関係のバージョン情報の更新 - 場所: README.md:25行目 - 詳細: package.jsonでは react@18.2.0 ですが、README.mdでは react@18.0.0 と記載 - [ ] ARCHITECTURE.md - 新規コンポーネント追加 - PaymentServiceの追加を記載 - 場所: ARCHITECTURE.md:コンポーネント構成セクション ## 🟡 MEDIUM優先度（今週中に対応） - [ ] units.md - 実装済みユニット数の更新 - 実装進捗の反映 - 詳細: 3/5ユニット完成していますが、ドキュメントは2/5のまま ## 🟢 LOW優先度（余裕がある時に） - [ ] README.md - トラブルシューティングセクション - 新規Q&A追加
このように、何を、どこで、なぜ更新すべきかが一目で分かります。
Skillの実装例:
Skillは以下のようなMarkdownファイルで定義されています（抜粋）：
--- name: doc-sync description: AI-DLC生成ドキュメントと実装の差異を検出し、更新が必要なドキュメントを特定する --- # ドキュメント差分検出 ## 目的 実装とドキュメントの差異を検出し、優先度付きの更新リストを生成します。 ## 実行手順 1. プロジェクト構造を分析 - Globツールで実装ファイルを収集 - 主要なコンポーネント、モジュールを特定 2. ドキュメントの現状を確認 - `aidlc-docs/managed/living/`配下のドキュメントを読み込み - 記載されている情報を抽出 3. 差異を検出 - 実装に存在するが、ドキュメントに記載されていない要素 - ドキュメントに記載されているが、実装と異なる情報 - バージョン番号、依存関係の不一致 4. 優先度を判定して出力 - HIGH: 技術的な重要情報の不一致（バージョン、新規コンポーネント） - MEDIUM: 実装状況の更新が必要 - LOW: 表現の改善や補足情報
動作の仕組み:
- コード構造を分析: Globツールでファイル一覧を取得
- ドキュメントと比較: Grepツールで主要な情報を抽出して比較
- 差異を検出: バージョン番号や実装状況の不一致を発見
- 優先度を判定:
- バージョン情報の不一致 → HIGH
- 新規コンポーネントの未記載 → HIGH
- 細かい表現の違い → LOW
これにより、効率的にドキュメントを更新できます。
2. /arch-validate - アーキテクチャ検証
/arch-validateは、AI-DLCで設計されたアーキテクチャと実装が一致しているかを検証するSkillです。
使い方:
/arch-validate
具体的な用例:
例えば、ARCHITECTURE.mdにおいて「認証」と「ユーザー管理」を分離する設計になっているプロジェクトで、実装時にUserController.tsに認証処理とユーザー管理処理を混在させてしまったとします。
この時点で/arch-validateを実行すると、以下のような結果が返ってきます：
# アーキテクチャ検証レポート 検証日時: 2026-03-03T15:35:00Z ## ✅ 設計通りの項目 - 依存関係: 設計されたルールに従っている - 構造: 設計されたコンポーネント構造を維持 - パターン: 設計されたパターンが一貫して適用されている ## ⚠️ 設計との軽微な差分 - UserController.ts: 責任の範囲が設計と異なる可能性 - 現状: 認証処理とユーザー管理処理が混在 - 推奨: 設計では「認証」と「ユーザー管理」を分離することになっていました - 影響: 単一責任の原則に反し、保守性が低下する可能性 ## ❌ 設計と異なる項目 - なし
このように、設計から外れている箇所を早期に発見できます。
確認する項目:
- 依存関係のルール: 設計で定義された依存方向が守られているか
- 構造の一貫性: 設計されたコンポーネント構造が維持されているか
- パターンの適用: 設計で採用されたパターンが一貫しているか
- 抽象化の維持: 設計で定義された抽象化が実装されているか
これにより、アーキテクチャの崩壊を防ぐことができます。
3. /doc-lifecycle - ドキュメントライフサイクル管理
/doc-lifecycleは、AI-DLCで生成されたドキュメントを整理整頓し、鮮度を維持するSkillです。
使い方:
# 今のドキュメント状況を確認 /doc-lifecycle # 継続管理用の構造をセットアップ /doc-lifecycle action=setup # 古いドキュメントをアーカイブ /doc-lifecycle action=archive
具体的な用例:
例えば、AI-DLCのInceptionフェーズで生成された大量のドキュメントがプロジェクトルートに散らばっており、開発が進むにつれて「どのドキュメントを更新すべきか」が分からなくなってしまったとします。
この時点で/doc-lifecycle action=setupを実行すると、ドキュメントが適切に分類され、継続管理しやすい構造が自動生成されます。
セットアップ時の動作:
/doc-lifecycle action=setupを実行すると、以下の構造が自動生成されます：
aidlc-docs/managed/
├── README.md # ドキュメント全体の案内
├── living/ # 常に最新に保つドキュメント
│ ├── ARCHITECTURE.md # システムアーキテクチャ
│ ├── IMPLEMENTATION-STATUS.md # 実装状況
│ └── AIDLC-DIFF.md # AI-DLC設計との差異
├── guides/ # 開発者向けガイド
│ ├── DEVELOPMENT.md # 環境構築手順
│ ├── TESTING.md # テスト方法
│ └── TROUBLESHOOTING.md # トラブルシューティング
└── archived/ # アーカイブ（参照のみ）
├── aidlc-inception/ # INCEPTION生成ドキュメント
└── aidlc-construction/ # CONSTRUCTION生成ドキュメント
各ディレクトリの役割:
- living/: 週1回以上更新するドキュメント（アーキテクチャ、実装状況など）
- guides/: 月1-2回更新するドキュメント（開発手順、テスト方法など）
- archived/: 更新しないドキュメント（AI-DLC生成の初期ドキュメント）
状況確認の実行例:
/doc-lifecycleを実行すると、以下のような結果が返ってきます：
# ドキュメント鮮度レポート ## 📄 常に最新に保つドキュメント（living/） - ✅ ARCHITECTURE.md - 最終更新: 2日前（良好） - ⚠️ IMPLEMENTATION-STATUS.md - 最終更新: 8日前（更新推奨） - ✅ AIDLC-DIFF.md - 最終更新: 1日前（良好） ## 📚 開発者ガイド（guides/） - ✅ DEVELOPMENT.md - 最終更新: 2週間前（良好） - ✅ TESTING.md - 最終更新: 1週間前（良好） - ⚠️ TROUBLESHOOTING.md - 最終更新: 1ヶ月前（追記可能な内容があるかもしれません） ## 推奨アクション 1. IMPLEMENTATION-STATUS.mdを更新（実装進捗を反映） 2. TROUBLESHOOTING.mdに新しい問題と解決策を追加
このように、どのドキュメントを更新すべきか一目で分かります。
Hooksによる自動通知
Skillsは手動で実行するツールでしたが、Hooksは自動的に通知してくれます。
以下は、私が実装したHooksの動作例です。
post-edit Hook
ファイルを編集したら、自動的に関連ドキュメントを提案します。
動作例:
あなた: PaymentService.tsを編集
↓
Hook : 「📝 以下のドキュメント更新を検討してください：
- README.md: 新しいサービスの説明を追加
- ARCHITECTURE.md: PaymentServiceをコンポーネント図に追加」
session-end-check Hook
Claude Codeを閉じるとき、今日の変更をまとめて確認します。
動作例:
Hook: 「📊 本日の変更サマリ：
- 変更ファイル: 3件
- 最終更新が古いドキュメント:
* README.md（最終更新: 3日前）
* ARCHITECTURE.md（最終更新: 1週間前）
/doc-sync で詳細な差分を確認できます。」
user-prompt-submit Hook
AI-DLCでドキュメントを生成した直後、次のアクションを提案します。
動作例:
Hook: 「✨ ドキュメント生成が完了しました。
推奨アクション：
1. /doc-lifecycle action=setup で継続管理構造をセットアップ
2. 生成されたドキュメントをレビュー
3. 実装開始後、/doc-sync で定期的に差分確認」
期待される効果と想定される課題
この機能を導入することで、以下のような効果が期待できます。
期待される効果
- ドキュメント更新の心理的ハードルが下がる:
/doc-syncで優先度付きリストが出るため、「何を更新すべきか」を考える時間が減ります - 新メンバーのオンボーディングがスムーズになる: ドキュメントとコードが一致していれば、自信を持って「まずドキュメントを読んでください」と案内できます
- 更新漏れを防げる: Hookの通知により、実装に集中していてもドキュメント更新を思い出すきっかけになります
- 設計の逸脱を早期発見できる:
/arch-validateで設計から外れた実装を早い段階で見つけ、修正できます
想定される課題
- 初期セットアップの判断が必要: ドキュメントをliving/とguides/のどちらに置くべきか、判断基準を決める必要があります
- 大規模プロジェクトでは通知が多くなる可能性: 特定のディレクトリをフィルタリングするなど、運用ルールの調整が必要かもしれません
- チームへの浸透には時間がかかる: 「週1回/doc-syncを実行する」といった習慣づけのための働きかけが必要です
- 実行時間: 大規模プロジェクトでは差異検出に時間がかかる可能性があります
これらの課題を踏まえつつ、実際の運用を通じて改善を続けていく予定です。
実装のポイント
設計思想：シンプルさ重視
複雑な自動化は避け、通知と道具を提供するアプローチを採用しました。
理由:
- ドキュメント更新は最終的に人間が判断すべき
- 過度な自動化は予期しない動作を引き起こす
- シンプルな仕組みの方が長く使える
技術構成
Hooks（Bashスクリプト）:
- 軽量で高速に動作
- 依存関係が少ない（jqのみ、かつエラーハンドリング済み）
- Claude Codeのイベント（ファイル編集、セッション終了など）に自動で反応
Skills（Markdownドキュメント）:
- Claude Codeの標準ツール（Glob, Grep, Read）のみ使用
- 外部コマンド不要で可搬性が高い
- LLMが読んで実行できる形式（Claude Codeが解釈して実行）
まとめ
本記事では、AI-DLCという開発手法において、AIが生成したドキュメントの継続管理を支援するために作成したClaude Code用のHooks・Skillについて解説しました。
できるようになったこと
Hooks（自動通知）で:
- コード変更時に即座に通知
- 更新漏れを防止
- 開発フローを妨げない
Skills（手動ツール）で:
- 必要な時に詳細な分析
- 優先度付きで効率的に対応
- ドキュメント構造の整理も可能
本質的な価値
AI-DLCという開発手法において、AIが生成したドキュメントが「作って終わり」から「継続的に価値を提供する資産」に変わります。
ドキュメントとコードの整合性を保つことで：
- 新しいメンバーのオンボーディングが楽になる
- プロジェクトの全体像を常に把握できる
- 設計意図を忘れず、不整合を防げる
