こんにちは。ENECHANGEの川野邉です。
コードは日々進化していくのに、仕様書やドキュメントが過去に取り残される。 これは多くの開発現場で起きている課題ではないでしょうか。
- コードは更新されるのに、仕様書は追いつかない
- クライアントや非エンジニアに説明のたびにコードを読み直す
- ドキュメントを書いても、次の改修で更新されず陳腐化する
仕様書やドキュメントの重要性は分かっていても、開発が忙しいとどうしても後回しになりがちです。
そこで今回、コード変更のタイミングで仕様書を自動生成・更新する仕組み を作れないかと考えました。 本記事では、Claude Code の Skills 機能 を使って試してみた取り組みを紹介します。
Skillの作成
Claude Code には Skill Creator という、スキルを作るためのスキルが組み込まれています。
「仕様書を自動生成するスキルを作りたい」と伝えると、対話的にヒアリングしながら SKILL.md の雛形を生成してくれます。
私もこの Skill Creator で骨格を作り、実際に使いながらテンプレートやルールを調整して今の形に落ち着きました。
仕様書生成スキルの仕組み
今回作ったスキルは、1 つの機能に対して 2 種類の仕様書をセットで生成 します。
| 種類 | ファイル名 | 対象読者 | 内容 |
|---|---|---|---|
| 概要書 | overview.md |
クライアント・非エンジニア | 機能の説明、業務ルール、運用方法 |
| 技術仕様書 | spec.md |
エンジニア | アーキテクチャ、型定義、処理フロー |
なぜ 2 種類に分けたかというと、読者によって必要な情報の粒度が違う からです。
クライアントに「TypeScript の型定義がこうなっていて…」と説明しても伝わりません。 逆に、エンジニアには「ディレクトリ構成」や「データの流れ」まで書いてほしい。
この 2 つをセットで管理することで、 「クライアント向けの説明資料」と「開発者向けのリファレンス」を同時にメンテナンスできます。
スキルの構成
実際のスキルは以下のような構成です。 ここからは実際のコードを公開しながら紹介します。
.claude/skills/spec-doc/
├── SKILL.md # スキル本体（ワークフロー定義）
└── references/
├── template-overview.md # 概要書のテンプレート
└── template.md # 技術仕様書のテンプレート
SKILL.md（スキル本体）
スキルの中核となるファイルです。 frontmatter にトリガー条件を、本文にワークフローとルールを定義しています。
SKILL.md の全文を見る
--- name: spec-doc description: リポジトリのコード変更や依頼内容から、仕様書ドキュメント（Markdown）を 作成・更新するスキル。概要書（overview.md：PM・クライアント向け）と技術仕様書 （spec.md：エンジニア向け）の2種類をセットで管理する。 「仕様書を作って」「specを書いて」「ドキュメントを更新して」「仕様をまとめて」 「docsを作って」などのリクエストでトリガーする。 また、CLAUDE.mdのルールにより、コード修正時にも自動的に呼び出される。 --- # 仕様書ドキュメント作成・更新スキル リポジトリのコードや依頼内容を分析し、`docs/` ディレクトリに概要書と技術仕様書を セットで作成・維持管理する。 ## ドキュメントの種類 仕様書は常に**概要書と技術仕様書のセット**で作成・管理する。 | 種類 | ファイル名 | 対象読者 | 配置場所 | |------|-----------|---------|---------| | 概要書 | `overview.md` | PM・クライアント | `docs/[機能名]/overview.md` | | 技術仕様書 | `spec.md` | エンジニア | `docs/[機能名]/spec.md` | ## ワークフロー ### 1. 入力の種類を判定する **コード変更から作成する場合** → 「コード分析ワークフロー」へ **依頼内容から作成する場合** → 「依頼分析ワークフロー」へ **既存仕様書の更新の場合** → 「更新ワークフロー」へ ### 2. コード分析ワークフロー a. 対象のコード変更（diff、PR、コミット）を読み取る b. 変更されたファイルとその周辺コードを分析する c. ディレクトリ構成、データ型、ビジネスロジックを把握する d. `docs/[機能名]/` 内に該当する仕様書が既にあるか確認する e. なければ概要書・技術仕様書をセットで新規作成、あれば更新ワークフローへ ### 3. 依頼分析ワークフロー a. 依頼内容（テキスト）を読み取り、要件を整理する b. 関連するコードベースを探索して実装状況を確認する c. `docs/[機能名]/` 内に該当する仕様書が既にあるか確認する d. なければ概要書・技術仕様書をセットで新規作成、あれば更新ワークフローへ ### 4. 更新ワークフロー a. 既存の概要書・技術仕様書を読み込む b. コード変更や依頼内容と照らし合わせて差分を特定する c. 該当セクションのみを更新する（無関係なセクションは変更しない） d. 更新履歴に記録を追加する e. **概要書と技術仕様書の両方**に影響がないか確認し、両方を更新する ### 5. 作成・更新の順序 1. **概要書（overview.md）を先に作成・更新する** - コード分析結果を平易な言葉でまとめる - 技術的な詳細は含めず、機能の全体像を記載する 2. **技術仕様書（spec.md）を次に作成・更新する** - 概要書の内容と整合性を保ちつつ、技術的な詳細を記載する ## ルール ### 共通ルール - 言語は**日本語**で記述する - 仕様書は `docs/[機能名]/` ディレクトリに配置する - **概要書と技術仕様書は常にセットで作成・更新する** - 既存の仕様書がある場合は上書きではなく**差分更新**する - 更新時は必ず更新履歴セクションに記録を追加する - コードから読み取れる事実を記載し、推測は明記する ### 概要書（overview.md）固有ルール - **含めてはいけないもの**: コードブロック、TypeScript型定義、ファイルパス、 コンポーネント名、APIエンドポイント - **含めてよいもの**: 概念的なフロー図（Mermaid）、表、箇条書き - 専門用語を使う場合は必ず平易な説明を添える ### 技術仕様書（spec.md）固有ルール - Mermaid記法でフロー図やシーケンス図を積極的に活用する - 型定義、ファイルパス、コードブロックを含めてよい - 更新履歴には対応PR/コミットを記載する ## コード分析のポイント コードを分析する際は以下に注目する： - **型定義・インターフェース**: 型定義、スキーマ、APIレスポンス型など - **ルーティング・エンドポイント**: 画面遷移やAPIパスの構造 - **状態管理**: store、context、グローバル状態の定義と遷移 - **計算・変換ロジック**: データ変換、集計処理、業務計算など - **バリデーション**: 入力検証ルール、エラーハンドリング - **外部連携**: API呼び出し、外部サービスとの通信
ポイントは以下の 3 つです。
- frontmatter の
descriptionにトリガーとなるキーワードを列挙している - ワークフローを分岐で定義 し、新規作成・依頼ベース・差分更新の 3 パターンに対応している
- 概要書と技術仕様書で「含めてよいもの / いけないもの」を明確に分けている
特に 3 が重要で、 これがないと Claude が概要書にコードブロックや型定義を書いてしまいます。
references/template-overview.md（概要書テンプレート）
クライアント・非エンジニア向けの概要書のテンプレートです。
template-overview.md の全文を見る
# 概要書テンプレート（非エンジニア向け） 以下のテンプレート構造を基本とし、機能の内容に応じてセクションを調整する。 コードブロック、TypeScript型、ファイルパス、コンポーネント名、APIエンドポイントは 含めない。専門用語を使う場合は平易な説明を添える。 --- # [機能名] 概要書 ## 1. 機能概要 ### 1.1 この機能について [この機能が何をするか、誰のためのものかを、技術用語を使わずに簡潔に説明] ### 1.2 対象ユーザー [この機能を利用するユーザーの種類] ### 1.3 関連ドキュメント - [関連する他の概要書へのリンク] ## 2. 機能詳細 ### 2.1 できること [この機能で実現できることを箇条書きで記載] ### 2.2 画面・表示内容 [ユーザーが目にする画面や表示内容の説明。スクリーンショットや図を活用] ### 2.3 データの見方 [表示されるデータの読み方、各項目の意味を平易に記載] ## 3. 業務ルール ### 3.1 対象範囲 [この機能が対応する範囲・条件の一覧] ### 3.2 処理の考え方 [主要な処理や判定の基本的な考え方を、数式ではなく日本語で説明] ### 3.3 注意事項・制約 [利用上の注意事項や制約条件] ## 4. 運用 ### 4.1 更新タイミング [データや設定がいつ・どのような条件で更新されるか] ### 4.2 更新に必要な作業 [更新時に必要な作業があれば記載（担当者向け）] ## 5. 更新履歴 | 日付 | 内容 | |------|------| | YYYY-MM-DD | 初版作成 |
references/template.md（技術仕様書テンプレート）
エンジニア向けの技術仕様書テンプレートです。
template.md の全文を見る
# 技術仕様書テンプレート（エンジニア向け：spec.md） 以下のテンプレート構造を基本とし、プロジェクトの内容に応じてセクションを調整する。 概要書（非エンジニア向け：overview.md）のテンプレートは template-overview.md を参照。 --- # [機能名 / モジュール名] 仕様書 ## 1. 概要 ### 1.1 目的 [この機能・モジュールが何を実現するか、なぜ必要かを簡潔に記載] ### 1.2 対象範囲 [この仕様書がカバーする範囲と、カバーしない範囲を明記] ### 1.3 関連ドキュメント - [関連する他の仕様書やドキュメントへのリンク] ## 2. アーキテクチャ・設計 ### 2.1 全体構成 [システム・機能の全体的なアーキテクチャを説明] ### 2.2 ディレクトリ構成 [関連するディレクトリ・ファイル構成を記載] ### 2.3 主要コンポーネント [主要なコンポーネント・モジュールの役割と関係を説明] ### 2.4 処理フロー [主要な処理の流れを記載。Mermaidでシーケンス図やフローチャートを記述] ## 3. データ仕様 ### 3.1 データ構造 [主要なデータ型・インターフェース・スキーマを記載] ### 3.2 API・インターフェース [外部/内部APIのエンドポイント、リクエスト/レスポンス形式を記載] ### 3.3 状態管理 [状態の定義、遷移条件を記載（該当する場合）] ## 4. ビジネスロジック ### 4.1 業務ルール [適用される業務ルール・制約条件を記載] ### 4.2 計算ロジック [計算式や変換ロジックの詳細を記載] ### 4.3 バリデーション [入力値の検証ルール、エラー条件を記載] ### 4.4 エッジケース [考慮すべき境界値や例外的なケースを記載] ## 5. 更新履歴 | 日付 | 内容 | 対応PR/コミット | |------|------|----------------| | YYYY-MM-DD | 初版作成 | - |
概要書テンプレートと技術仕様書テンプレートの違いを見ると、 同じ機能でも読者によって書き分ける という設計思想が分かると思います。
概要書には「処理の考え方」を日本語で、 技術仕様書には「計算ロジック」をコード付きで ── という棲み分けです。
実際の生成フロー
実運用では、CLAUDE.md（プロジェクトルール）に以下のルールを追加しています。
コミット依頼を受けたら、即座にコミットせず以下の順番で実行する： 1. 仕様書の更新が必要か判断する（軽微な修正を除く） 2. 必要な場合は spec-doc スキルで仕様書を作成・更新する 3. ビルドとバリデーションを実行して成功することを確認する 4. 仕様書の内容をユーザーに提示し、確認を取る 5. 承認を得てからコミットする
つまり、「コミットして」と言うだけで、仕様書の更新が必要かどうかを自動判断し、 必要なら生成してからコミットする という流れです。
具体的な流れ
- 開発者がコードを変更する
- 「コミットして」と Claude Code に指示
- Claude Code が変更差分を分析
- 仕様書更新が必要と判断 → スキルが発動
- コードを読み取り、概要書 → 技術仕様書の順で生成・更新
- 生成結果を開発者に提示
- 開発者が内容を確認・承認
- コード変更と仕様書を同じコミットに含める
軽微な修正（typo 修正、フォーマット変更など）の場合は、 スキルが「更新不要」と判断してスキップします。
生成される仕様書のイメージ
たとえば、ある一覧表示機能の技術仕様書では、こんな内容が自動生成されます。
- 全体構成: Mermaid 記法のフロー図（データソース → 変換スクリプト → JSON → フロントエンド）
- ディレクトリ構成: 関連ファイルのツリー構造
- 処理フロー: シーケンス図（ユーザー操作 → ルーティング → データ取得 → 表示）
- データ仕様: TypeScript の型定義、テーブル形式のフィールド説明
- ビジネスロジック: 判定ルールや特殊ケースの説明
概要書の方では、同じ機能を コードなし・図と表と日本語だけ で説明する形になります。
使ってみた感想
よかった点
1. 仕様書の初期コストがほぼゼロになった
新機能を作ったとき、「仕様書も書かなきゃ…」というプレッシャーがなくなりました。 コミット時に自動で生成されるので、意識しなくても仕様書が作られます。
2. システムの全体像のキャッチアップコストが早くなった
メンバーが機能を理解する際に、技術仕様書が参考になります。 Mermaid の図や型定義が載っているので、コードを読む前に全体像を掴めます。
今後の展望
Hooksの活用
現状は CLAUDE.md にルールを書くことで「コミット時にスキルを発動させる」という仕組みにしていますが、
これはあくまで Claude Code への指示ベースです。
今後は Hooks（Claude Code のイベントフック機能）を活用して、
コミットやファイル変更といったイベントに対してスキルを自動的に発火させる仕組みに移行していきたいと考えています。
CLAUDE.md に書くルールは減らし、より宣言的にワークフローを組めるようにするのが理想です。
ドキュメント構成の見直し
また、概要書・技術仕様書という 2 層構造自体の見直し も検討しています。
現状は「クライアント向け」と「エンジニア向け」で分けていますが、 実際に運用してみると、読者の境界は必ずしもきれいに分かれないケースもあります。 要件定義書・基本設計・詳細設計のように粒度で分けた構成にしていくことも検討しています。
スキルの自動更新
もう一つ取り組みたいのが、スキル定義自体の自動ブラッシュアップ です。
現在はスキルの改善は手動で行っていますが、
生成された仕様書のレビュー結果や修正内容をフィードバックとして取り込み、
SKILL.md やテンプレートを自動的に改善していく仕組みが作れると面白いと思っています。
スキルがスキル自身を育てていく ── そんなサイクルを回せたら、メンテナンスコストはさらに下がるはずです。
