Claude SkillsでAI仕様駆動開発を始める完全ガイド

~/.claude/skills/
└── your-skill-name/
    ├── SKILL.md        # 必須：スキルの定義と指示
    └── resources/      # オプション：スクリプトやファイル

---
name: Your Skill Name
description: Claude uses this to decide when to invoke your skill
---

<strong># Your Skill Instructions</strong>

ここにスキルの詳細な指示を記述します。

# Claude Codeのバージョン確認
claude --version

claude skillsって作れる？

AI仕様駆動開発というのをフィールフロウで提唱していまして、
https://github.com/feel-flow/ai-spec-driven-development
こちらに公開しています。

詳しくは、
https://github.com/feel-flow/ai-spec-driven-development/blob/develop/ai_spec_driven_development.md
このファイルにもありますが、

仕様をちゃんと管理しつつ、開発できるようにAI仕様駆動開発スキルを作りたいです。

Claude Code用のスキルを作成したいです。

【目的】
AI仕様駆動開発の方法論に基づいて、プロジェクトのドキュメント構造を自動管理するスキルを作成

【参考資料】
- 公式リポジトリ: https://github.com/feel-flow/ai-spec-driven-development
- 方法論ドキュメント: https://github.com/feel-flow/ai-spec-driven-development/blob/develop/ai_spec_driven_development.md

【実装してほしい機能】
1. プロジェクト初期化（フォルダ構造の自動生成）
2. ドキュメント構造の検証と自動補修
3. 新規ドキュメントの適切な配置支援
4. ドキュメント更新時の影響度評価
5. MASTER.md索引の自動更新
6. Frontmatterメタデータの自動挿入
7. 用語集・決定記録の管理
8. コミット前の検証チェックリスト実行

【スキルが起動する条件】
- 「AI仕様駆動開発を導入したい」
- 「ドキュメント構造を検証したい」
- 「新しいドキュメントを追加したい」
- 「コミット前にチェックしたい」

お願いします！

Claude: まず、リポジトリの内容を確認させてください。
[GitHub URLからai_spec_driven_development.mdを取得]

Claude: スキルを作成します！
[~/.claude/skills/ai-spec-driven-development/ を作成]

~/.claude/skills/ai-spec-driven-development/
├── SKILL.md                         # メインスキル定義（14KB）
├── README.md                        # 使い方ガイド（5KB）
└── templates/                       # テンプレート集
    ├── MASTER.md                    # プロジェクト索引テンプレート
    ├── PROJECT.md                   # 要件定義テンプレート
    ├── frontmatter-template.yaml    # メタデータテンプレート
    └── validation-checklist.md      # 検証チェックリスト

---
name: AI Spec-Driven Development
description: Helps manage project documentation using AI Spec-Driven Development methodology with structured docs folder, MASTER.md index, and automated validation
---

<strong># AI Spec-Driven Development Skill</strong>

このスキルは、AI仕様駆動開発の方法論に基づいて、プロジェクトのドキュメント構造を初期化、検証、更新、管理するための支援を提供します。

<strong>## 概要</strong>
[...]

<strong>## スキルの機能</strong>
[...]

<strong>## 使用タイミング</strong>
[...]

# スキルディレクトリの確認
ls -la ~/.claude/skills/ai-spec-driven-development/

# 出力例:
# drwxr-xr-x  5 user  staff   160 Oct 20 11:05 .
# drwxr-xr-x  3 user  staff    96 Oct 20 11:00 ..
# -rw-r--r--  1 user  staff  5185 Oct 20 11:05 README.md
# -rw-r--r--  1 user  staff 14449 Oct 20 11:01 SKILL.md
# drwxr-xr-x  6 user  staff   192 Oct 20 11:04 templates

# SKILL.mdの内容確認
head -n 20 ~/.claude/skills/ai-spec-driven-development/SKILL.md

このプロジェクトにAI仕様駆動開発を導入したい

Claude: AI仕様駆動開発を導入します！
[ai-spec-driven-developmentスキルが起動]

1. 現在のプロジェクト構造を確認します...
   ✓ プロジェクトルート: /path/to/your/project

2. docs/ フォルダ構造を生成します...
   ✓ docs/ 作成
   ✓ docs/01-context/ 作成
   ✓ docs/02-design/ 作成
   ✓ docs/03-implementation/ 作成
   ✓ docs/04-quality/ 作成
   ✓ docs/05-operations/ 作成
   ✓ docs/06-reference/ 作成
   ✓ docs/07-project-management/ 作成
   ✓ docs/08-knowledge/ 作成

3. 必須ドキュメントを生成します...
   ✓ docs/MASTER.md 作成（プロジェクト索引）
   ✓ docs/01-context/PROJECT.md 作成（ビジョンと要件）
   ✓ docs/02-design/ARCHITECTURE.md 作成（システム設計）
   ✓ docs/02-design/DOMAIN.md 作成（ビジネスロジック）
   ✓ docs/03-implementation/PATTERNS.md 作成（実装パターン）
   ✓ docs/04-quality/TESTING.md 作成（テスト戦略）
   ✓ docs/05-operations/DEPLOYMENT.md 作成（デプロイメント）
   ✓ docs/08-knowledge/LESSONS_LEARNED.md 作成（開発知見）

4. 各ファイルにFrontmatterを挿入しました。

AI仕様駆動開発の導入が完了しました！

【次のステップ】
1. docs/MASTER.md を確認し、プロジェクト情報を入力
2. docs/01-context/PROJECT.md にビジョンと要件を記載
3. docs/02-design/ARCHITECTURE.md にシステム設計を記載

何から始めますか？

your-project/
├── docs/
│   ├── MASTER.md                    # プロジェクト索引
│   ├── 01-context/
│   │   └── PROJECT.md               # ビジョンと要件
│   ├── 02-design/
│   │   ├── ARCHITECTURE.md          # システム設計
│   │   └── DOMAIN.md                # ビジネスロジック
│   ├── 03-implementation/
│   │   └── PATTERNS.md              # 実装パターン
│   ├── 04-quality/
│   │   └── TESTING.md               # テスト戦略
│   ├── 05-operations/
│   │   └── DEPLOYMENT.md            # デプロイメント
│   ├── 06-reference/
│   │   ├── GLOSSARY.md             # 用語集
│   │   └── DECISIONS.md            # アーキテクチャ決定記録
│   ├── 07-project-management/
│   │   └── ROADMAP.md              # ロードマップ
│   └── 08-knowledge/
│       └── LESSONS_LEARNED.md       # 開発知見
└── [your project files...]

データベース設計のドキュメントを追加したい

Claude: データベース設計ドキュメントを追加します！
[ai-spec-driven-developmentスキルが起動]

Decision Matrixを適用中...

質問: 「設計/構造」に関するドキュメントですか？
→ YES：02-design/ フォルダに配置

既存の docs/02-design/ARCHITECTURE.md を確認中...
→ 「データベース設計」セクションは未記載

【提案】
データベース設計は独立したトピックとして大きいため、
新規ファイル docs/02-design/DATABASE.md の作成を推奨します。

よろしいですか？(Y/n)Claude: データベース設計ドキュメントを追加します！<br><br>

Claude: docs/02-design/DATABASE.md を作成します...

✓ ファイル作成
✓ Frontmatter挿入
   - id: database-design
   - version: 1.0.0
   - status: draft
   - created: 2025-10-20
   - changeImpact: high

✓ テンプレート挿入
   - データベース設計の概要
   - ERダイアグラム
   - テーブル定義
   - インデックス設計
   - マイグレーション戦略

✓ docs/MASTER.md の索引を更新

完了しました！

DATABASE.md の編集を開始しますか？

ARCHITECTURE.mdのレイヤー構造を3層から4層に変更したい

Claude: ARCHITECTURE.mdのレイヤー構造を変更します。
[ai-spec-driven-developmentスキルが起動]

現在のARCHITECTURE.mdを確認中...
✓ Frontmatter読み込み
   - 現在のversion: 1.5.0
   - changeImpact: medium

変更内容を解析中...
→ 「既存概念の再定義」を検出
→ 影響度: HIGH

【変更の影響度評価】
┌─────────────────────────────────────┐
│ changeImpact: HIGH                  │
│ 理由: レイヤー構造の変更は既存の    │
│       アーキテクチャに大きく影響    │
└─────────────────────────────────────┘

【必要なアクション】
1. ✓ バージョンを 1.5.0 → 2.0.0 に更新（major bump）
2. ✓ FrontmatterのchangeImpactをhighに設定
3. ⚠ CHANGELOGへの記載が必要
4. ✓ Revision Historyに更新行を追加
5. ⚠ MASTER.mdのアーキテクチャ概要も更新が必要

変更を実行しますか？(Y/n)

Claude: 変更を実行します...

✓ ARCHITECTURE.md を更新
✓ Frontmatterを更新
   - version: 1.5.0 → 2.0.0
   - updated: 2025-10-20
   - changeImpact: high

✓ Revision Historyに追加
   | 2025-10-20 | developer | 2.0.0 | high | レイヤー構造を3層から4層に変更 |

✓ MASTER.mdのアーキテクチャ概要を更新

⚠ CHANGELOGへの記載をお願いします：

   ## [2.0.0] - 2025-10-20
   ### Changed
   - docs: ARCHITECTURE.md レイヤー構造を3層から4層に変更
     - 新規レイヤー: Domain Layer を追加
     - 影響範囲: すべてのサービス実装

完了しました！CHANGELOGに記載してください。

コミット前にドキュメントをチェックしたい

Claude: ドキュメント構造を検証します！
[ai-spec-driven-developmentスキルが起動]

【完全性チェック】
✓ docs/ フォルダ存在
✓ docs/01-context/ 存在
✓ docs/02-design/ 存在
✓ docs/03-implementation/ 存在
✓ docs/04-quality/ 存在
✓ docs/05-operations/ 存在
✓ docs/06-reference/ 存在
✓ docs/07-project-management/ 存在
✓ docs/08-knowledge/ 存在

【必須ファイルチェック】
✓ docs/MASTER.md 存在
✓ docs/01-context/PROJECT.md 存在
✓ docs/02-design/ARCHITECTURE.md 存在
✓ docs/02-design/DOMAIN.md 存在
✓ docs/03-implementation/PATTERNS.md 存在
✓ docs/04-quality/TESTING.md 存在
✓ docs/05-operations/DEPLOYMENT.md 存在
✓ docs/08-knowledge/LESSONS_LEARNED.md 存在

【メタデータチェック】
✓ すべてのファイルにFrontmatter存在
✓ YAML構文正常
✓ 日付形式（YYYY-MM-DD）正常
✓ status値正常（draft/active/deprecated）
✓ changeImpact値正常（low/medium/high）

【命名規約チェック】
✓ ファイル名が大文字（MASTER.md等）
✓ フォルダ名が小文字とハイフン
✓ ID形式がkebab-case

【整合性チェック】
✓ MASTER.mdの索引が最新
✓ リンク切れなし
⚠ GLOSSARY.mdに未定義の用語を検出: 3件
   - "マイクロサービス" (ARCHITECTURE.md:45)
   - "イベント駆動" (ARCHITECTURE.md:78)
   - "ドメインイベント" (DOMAIN.md:123)

【変更影響度チェック】
✓ changeImpact=highの変更: 2件
   - ARCHITECTURE.md: CHANGELOG記載済み
   - DATABASE.md: CHANGELOG記載済み

【Revision Historyチェック】
✓ すべてのファイルにRevision History存在
✓ 最新の更新が記録されている

┌─────────────────────────────────────┐
│ 検証結果: ⚠ WARNING                 │
│                                     │
│ 軽微な問題が検出されました。        │
│ GLOSSARYへの用語追加を推奨します。 │
│                                     │
│ コミット可能: YES                   │
└─────────────────────────────────────┘

用語をGLOSSARYに追加しますか？(Y/n)

Helps manage project documentation using AI Spec-Driven Development
methodology with structured docs folder, MASTER.md index, and
automated validation

ドキュメント作って

AI仕様駆動開発の構造で、データベース設計のドキュメントを追加したい

AI仕様駆動開発の構造で、以下の内容を含むデータベース設計ドキュメントを追加したい：
- ERダイアグラム
- テーブル定義（カラム、型、制約）
- インデックス設計
- マイグレーション戦略

どこに配置すべきか提案してください。

レイヤー構造を変更したい

ARCHITECTURE.mdのレイヤー構造を3層から4層に変更したい。
Domain Layerを追加する予定です。影響度を評価してください。

プロジェクト全体のドキュメントを作成して、すべての内容を埋めてください

ステップ1: AI仕様駆動開発の構造を初期化してください

[完了後]

ステップ2: MASTER.mdにプロジェクト情報を記載してください
- プロジェクト名: FlowNote AI
- 技術スタック: Next.js, TypeScript, Supabase
[...]

[完了後]

ステップ3: PROJECT.mdにビジョンと要件を記載してください
[...]

プロンプト例:
「MVPフェーズとして、最小限の7文書でAI仕様駆動開発を開始したい」

プロンプト例:
「成長フェーズに移行するため、GLOSSARY.md、DECISIONS.md、ROADMAP.mdを追加したい」

ユーザー: AI仕様駆動開発を導入したい
Claude: [通常の応答。スキルが起動していない]

スキルディレクトリの確認

ls -la ~/.claude/skills/ai-spec-driven-development/
SKILL.mdの存在確認

cat ~/.claude/skills/ai-spec-driven-development/SKILL.md | head -n 10
Frontmatterの確認

---
name: AI Spec-Driven Development
description: Helps manage project documentation [...]
---

ユーザー: ドキュメントを追加したい
Claude: [別のドキュメント作成スキルが起動]

❌ 曖昧: 「ドキュメントを追加したい」
✅ 明確: 「AI仕様駆動開発の構造でドキュメントを追加したい」
✅ より明確: 「AI仕様駆動開発スキルを使って、データベース設計ドキュメントを追加したい」

Claude: データベース設計ドキュメントを 01-context/ に配置しました
[正しくは 02-design/ に配置すべき]

データベース設計のドキュメントを追加したい。

Decision Matrixで判断してください：
- ビジネス価値/背景か？ → NO
- 設計/構造か？ → YES

したがって、02-design/ に配置すべきですよね？

DATABASE.mdを作成する際、以下のFrontmatterを挿入してください：

---
id: database-design
title: データベース設計
version: 1.0.0
status: draft
created: 2025-10-20
updated: 2025-10-20
owner: backend-team
phase: mvp
tags: [database, design, sql]
references:
   - docs/MASTER.md
   - docs/02-design/ARCHITECTURE.md
changeImpact: high
---

ARCHITECTURE.mdのレイヤー構造を3層から4層に変更します。

これは以下の理由でchangeImpact: HIGHです：
- 既存のアーキテクチャの根本的な変更
- すべてのサービス実装に影響
- 開発者全員が理解する必要がある

影響度をhighとして、必要なアクション（バージョン更新、CHANGELOG記載）を実行してください。

プロジェクトA/ → AI仕様駆動開発スキル使用可能
プロジェクトB/ → AI仕様駆動開発スキル使用可能
プロジェクトC/ → AI仕様駆動開発スキル使用可能

プロンプト例:
「既存のREADME.mdとARCHITECTURE.mdがあるプロジェクトに、
AI仕様駆動開発を導入したい。既存ファイルは残しつつ、
不足しているファイルを追加してください。」

# スキルディレクトリをコピー
cp -r ~/.claude/skills/ai-spec-driven-development /path/to/shared/location

# 各メンバーが自分の環境にコピー
cp -r /path/to/shared/location/ai-spec-driven-development ~/.claude/skills/

# スキルをリポジトリに追加
cd ~/.claude/skills/
git init
git add ai-spec-driven-development/
git commit -m "Add AI Spec-Driven Development skill"
git remote add origin <your-repo-url>
git push

# 他のメンバーがクローン
git clone <your-repo-url> ~/.claude/skills/

# エディタで編集
code ~/.claude/skills/ai-spec-driven-development/SKILL.md

プロンプト例:
「AI仕様駆動開発スキルが正しくインストールされているかテストしたい」

# プロジェクト初期化
「このプロジェクトにAI仕様駆動開発を導入したい」

# 新規ドキュメント追加
「AI仕様駆動開発の構造で[トピック]のドキュメントを追加したい」

# ドキュメント更新
「[ファイル名]の[内容]を変更したい。影響度を評価してください」

# 構造検証
「コミット前にドキュメント構造を検証したい」

# MASTER.md更新
「MASTER.mdの索引を最新に更新したい」

# 用語追加
「GLOSSARY.mdに以下の用語を追加したい: [用語]」

# 決定記録
「[決定内容]をDECISIONS.mdに記録したい」