第6章：実践記 ― ドキュメント駆動開発からSKILLSシステムへ
はじめに：この章について
本章では、筆者がClaude Codeを活用した開発ワークフローを進化させてきた過程を、体験談として記述します。
最初に採用していた「ドキュメント駆動開発」から、本書で解説した「SKILLSシステム」への移行。その過程で直面した課題、試行錯誤、そして得られた学びを共有します。
これは一つの事例に過ぎませんが、読者の皆さんが自身のワークフローを改善する際のヒントになれば幸いです。
フェーズ1：手探りの始まり
最初のアプローチ
Claude Codeを使い始めた当初、筆者には明確なワークフローがありませんでした。
「こんなアプリを作りたい」とClaudeに伝え、出てきたコードをなんとなく確認し、動けばOK。典型的な「丸投げアプローチ」です。
小さなスクリプトやプロトタイプなら、これでも十分でした。しかし、ある程度の規模のWebアプリケーションを作ろうとしたとき、問題が噴出しました。
直面した問題
問題1：意図と異なる実装の連続
「ユーザー認証機能を作って」と指示すると、Claudeは確かに動く認証機能を作ってくれました。しかし、セッション管理の方式が想定と違う、パスワードのハッシュ化方式が古い、エラーメッセージが英語になっている——細かい「違い」が積み重なり、修正に追われる日々でした。
問題2：プロジェクトの全体像をClaudeが把握していない
新しいセッションを開始するたびに、「このプロジェクトはNext.jsを使っていて、認証はSupabaseで、スタイリングはTailwindで...」と説明し直す必要がありました。説明を忘れると、プロジェクトの方針と異なるコードが生成されます。
問題3：同じミスの繰り返し
「APIのレスポンス形式は{ data, error }で統一して」と何度指示しても、次のセッションでは忘れています。同じ指摘を繰り返す自分に疲弊していきました。
フェーズ2：ドキュメント駆動開発の採用
転機：「先にドキュメントを書く」
この状況を打破するため、筆者は「ドキュメント駆動開発」を採用しました。
コードを書く前に、まずドキュメントを整備する。具体的には：
- 要件定義書をClaudeと壁打ちしながら作成
- ARCHITECTURE.mdをフロントエンド、バックエンド、データベースごとに分離して作成
- SECURITY.mdでセキュリティ方針を明文化
- すべて揃ってから「実装を開始してください」と指示
効果と手応え
このアプローチは、明らかに効果がありました。
Claudeに「まずARCHITECTURE.mdを読んで」と指示すれば、プロジェクトの全体像を把握した状態で実装を始めてくれます。意図と異なる実装は大幅に減りました。
また、SECURITY.mdを参照させることで、セキュリティ面での見落としも減りました。
PROGRESS.mdを導入して進捗管理を始めたのもこの頃です。「今日はここまで完了した」「次はこの機能を実装する」という記録を残すことで、セッションをまたいだ開発がスムーズになりました。
当時のディレクトリ構成
my-project/
├── docs/
│ ├── requirements.md # 要件定義書
│ ├── frontend-ARCHITECTURE.md # フロントエンド設計
│ ├── backend-ARCHITECTURE.md # バックエンド設計
│ ├── db-ARCHITECTURE.md # データベース設計
│ ├── SECURITY.md # セキュリティ方針
│ └── PROGRESS.md # 進捗管理
└── src/
残っていた課題
しかし、いくつかの課題は解決されないままでした。
課題1：毎回「ドキュメントを読んで」と指示する必要がある
セッション開始時に「docs/以下のドキュメントを読んでからコードを書いて」と毎回指示していました。忘れると、ドキュメントを無視した実装が始まってしまいます。
課題2：すべてのドキュメントを読ませるとコンテキストを圧迫する
「全部読んで」と指示すると、すべてのドキュメントがコンテキストウィンドウを埋め尽くします。肝心の実装時に「文脈が足りない」状態になることがありました。
課題3：同じミスの繰り返しは依然として発生
ドキュメントに書いていない暗黙のルール——「このプロジェクトではconsole.logを本番コードに残さない」「このライブラリは使わない」など——は、相変わらず毎回指摘する必要がありました。
フェーズ3：LESSONS.md（学習ログ）の導入
学びを記録する仕組み
課題3（同じミスの繰り返し）を解決するため、LESSONS.mdというファイルを導入しました。
Claudeが方向性を間違えたとき、その内容と正しい方法をLESSONS.mdに記録します。次のセッションでは「まずLESSONS.mdを読んで」と指示することで、過去の学びを引き継げます。
LESSONS.mdの構成
# 学習ログ（Lessons Learned）
## 認証・認可
### 2024-12-15: LocalStorageへのトークン保存
**状況**: JWTトークンの保存先としてLocalStorageを使おうとした
**問題**: XSS攻撃に脆弱
**正しい方法**: HTTPOnly Cookieを使用する
### 2024-12-18: 認証チェックの漏れ
**状況**: /api/users/[id] に認証なしでアクセスできた
**問題**: 他人の情報が見えてしまう
**正しい方法**: すべてのAPIエンドポイントにauthMiddlewareを適用
## コーディング規約
### 2024-12-20: console.logの残留
**状況**: デバッグ用のconsole.logが本番コードに残っていた
**問題**: セキュリティリスク、パフォーマンス低下
**正しい方法**: デバッグ後は必ず削除。必要ならlogger使用
### 2024-12-22: any型の使用
**状況**: TypeScriptでany型を使おうとした
**問題**: 型安全性が失われる
**正しい方法**: unknownを使い、型ガードで絞り込む
効果
LESSONS.mdの効果は絶大でした。
同じミスを指摘する回数が激減しました。特に「このプロジェクト固有のルール」を学習させる効果が高く、セッションを重ねるごとにClaudeの出力品質が向上していく感覚がありました。
「学習を蓄積できる」——これはvibe codingにおける最も重要な発見の一つでした。
フェーズ4：CLAUDE.mdとの出会い
自動で読み込まれるファイル
ある日、Anthropicのドキュメントを読んでいて、CLAUDE.mdという仕組みを知りました。
プロジェクトルートにCLAUDE.mdを配置すると、Claude Codeがセッション開始時に自動で読み込む。つまり、毎回「このドキュメントを読んで」と指示する必要がなくなります。
これは革命でした。
移行作業
早速、CLAUDE.mdを作成しました。内容は、これまで毎回口頭で伝えていた指示をまとめたものです：
# My Project
Next.js + Supabase で構築するタスク管理アプリ
## 実装前に必ず確認
- docs/LESSONS.md（過去のミスと教訓）
- 該当する ARCHITECTURE.md
## 絶対ルール
- any型禁止
- console.log本番禁止
- mainブランチ直接コミット禁止
効果
セッション開始時の「儀式」がなくなりました。
以前は毎回「まずdocs/以下を読んで、特にLESSONS.mdは必ず確認して...」と伝えていましたが、その必要がなくなりました。Claudeは最初から「このプロジェクトのルール」を把握した状態で会話を始めてくれます。
フェーズ5：SKILLSシステムへの移行
新たな課題：コンテキストの効率
CLAUDE.mdとLESSONS.mdの組み合わせで、多くの問題は解決しました。しかし、プロジェクトが大きくなるにつれ、新たな課題が浮上しました。
コンテキストウィンドウの圧迫です。
ARCHITECTURE.mdが3つ（フロントエンド、バックエンド、DB）、SECURITY.md、LESSONS.md——これらを全部読み込むと、かなりのトークンを消費します。フロントエンドの作業をしているときに、バックエンドやDBの設計情報は不要なのに、コンテキストを占有している状態でした。
SKILLSという解決策
Anthropicが発表したSKILLSシステムは、この課題を解決する仕組みでした。
SKILLSの核心は「段階的開示（Progressive Disclosure）」です：
- セッション開始時には、全スキルの「名前」と「説明」だけを読み込む（軽量）
- 実際のタスクに関連するスキルだけ、その時点で本文を読み込む
- 不要なスキルはコンテキストを占有しない
つまり、「フロントエンドの作業をしている」とClaudeが判断したら、フロントエンド関連のスキルだけを詳しく読む。バックエンドやDBの情報は、必要になるまで読み込まない。
移行作業
既存のドキュメントをSKILLS形式に変換しました。
Before（従来のドキュメント構成）：
docs/
├── frontend-ARCHITECTURE.md
├── backend-ARCHITECTURE.md
├── db-ARCHITECTURE.md
├── SECURITY.md
└── LESSONS.md
After（SKILLS形式）：
.claude/
└── skills/
├── frontend-architecture/
│ └── SKILL.md
├── backend-architecture/
│ └── SKILL.md
├── database-architecture/
│ └── SKILL.md
└── security-guidelines/
└── SKILL.md
各SKILL.mdには、YAML Frontmatterで「このスキルがいつ使われるべきか」を明示します：
---
name: frontend-architecture
description: フロントエンドのアーキテクチャ設計パターン。
Reactコンポーネントの設計、状態管理、スタイリングの
ベストプラクティスを提供。フロントエンドのコードを
書くとき、UIコンポーネントを作成するときに参照。
---
# Frontend Architecture
## When to Use
- 新しいReactコンポーネントを作成するとき
- 状態管理を実装するとき
- スタイリングを適用するとき
## Core Patterns
...
移行の効果
移行後、明確な改善を実感しました。
コンテキストの効率化：フロントエンドの作業中はフロントエンドの知識だけがロードされ、他の情報がコンテキストを圧迫しなくなりました。
自動的なスキル選択：「ログイン画面を作って」と指示すると、Claudeは自動でfrontend-architectureとsecurity-guidelinesのスキルを参照します。毎回「このドキュメントを見て」と指示する必要がありません。
スキルの再利用性：一度作ったスキルは、他のプロジェクトでも使い回せます。グローバルスキル（~/.claude/skills/）として配置すれば、すべてのプロジェクトで利用可能です。
フェーズ6：Hooksによる自動化
人間のミスを防ぐ
SKILLSシステムで「Claudeのミス」は減りました。しかし、「人間のミス」は依然として発生していました。
- mainブランチで作業を始めてしまう
- lintを実行し忘れてPRを出す
- LESSONS.mdの更新を忘れる
これらは、Claude CodeのHooks機能で自動化できることを知りました。
導入したHooks
.claude/settings.jsonに以下を設定しました：
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": ".claude/hooks/check-branch.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npm run lint:fix --silent || true"
}
]
}
]
}
}
SessionStart Hook：セッション開始時にブランチをチェックし、mainブランチなら警告を出す。
PostToolUse Hook：ファイルを編集するたびに自動でlintを実行。
効果
「うっかりミス」がほぼゼロになりました。
特にブランチチェックは強力です。以前は「あ、mainで作業してた...」と気づいてから慌ててブランチを切り直すことがありましたが、今はセッション開始時に自動で警告されます。
現在のワークフロー
フェーズ1から6を経て、現在のワークフローは以下のようになっています。
ディレクトリ構成
my-project/
├── CLAUDE.md # 自動読み込み
├── .claude/
│ ├── settings.json # Hooks設定
│ ├── commands/ # カスタムコマンド
│ │ ├── start-task.md
│ │ └── finish-task.md
│ └── skills/ # 専門知識
│ ├── frontend-architecture/
│ ├── backend-architecture/
│ ├── database-architecture/
│ └── security-guidelines/
├── docs/
│ ├── PROGRESS.md # 進捗管理
│ ├── LESSONS.md # 学習ログ
│ └── plans/ # 計画ファイル
└── src/
日常の開発フロー
-
セッション開始
- Hooks: 自動でブランチチェック
- CLAUDE.md: 自動で読み込み
-
タスク開始
/project:start-task ユーザープロフィール編集- 計画ファイルを作成、関連スキルを確認
-
実装
- 小さいステップで実装
- Hooks: ファイル編集ごとに自動lint
-
タスク完了
/project:finish-task- PROGRESS.md更新、LESSONS.mdに学び追記、コミット
得られたもの
この進化を経て、得られたものは大きいです。
開発速度の向上：セットアップや繰り返しの指示にかかる時間が激減。本質的な開発に集中できる。
品質の安定：SKILLSとHooksにより、一定水準の品質が自動で担保される。
学習の蓄積：LESSONS.mdにより、プロジェクト固有の知識が蓄積され、Claudeの出力が継続的に改善される。
再現性：ワークフローがファイルとして定義されているため、他のプロジェクトにも横展開できる。
読者へのアドバイス
最後に、筆者の経験から得たアドバイスをいくつか共有します。
1. 段階的に導入する
本書で紹介したすべての機能を一度に導入する必要はありません。
筆者も、フェーズ1から6まで数ヶ月かけて段階的に進化させてきました。まずはCLAUDE.mdから始め、必要性を感じたらLESSONS.md、SKILLSと追加していくのがお勧めです。
2. LESSONS.mdを軽視しない
SKILLSやHooksは「かっこいい」機能ですが、最も投資対効果が高いのはLESSONS.mdだと感じています。
設定不要、特別なツール不要、ただMarkdownファイルを作るだけ。それだけで「Claudeの学習を蓄積する」という、vibe codingの根本的な課題を解決できます。
3. 完璧を求めない
ワークフローは「完成」しません。
プロジェクトの性質、チームの構成、使用する技術——これらが変われば、最適なワークフローも変わります。本書で紹介した方法も、数ヶ月後には古くなっているかもしれません。
大切なのは、継続的に改善する姿勢です。うまくいかないことがあれば修正し、新しい機能が出れば試してみる。その繰り返しが、あなただけの最適なワークフローを作り上げていきます。
4. 楽しむこと
vibe codingは、プログラミングの新しい形です。
AIと対話しながらソフトウェアを作る。アイデアが形になるまでの時間が劇的に短くなる。これは、純粋に楽しい体験です。
ワークフローの最適化に追われて、その楽しさを忘れないでください。
おわりに
本章では、筆者がドキュメント駆動開発からSKILLSシステムへ移行した過程を共有しました。
この道のりは、決して一直線ではありませんでした。試行錯誤、失敗、学び直しの連続でした。しかし、その過程で得た知見が本書の内容となり、読者の皆さんの参考になれば、これ以上の喜びはありません。
vibe codingの世界は、まだ始まったばかりです。AIの進化とともに、新しいプラクティスが次々と生まれてくるでしょう。本書がその旅の第一歩として、読者の皆さんの役に立てば幸いです。
Happy Vibe Coding! 🎵