はじめに

Claude Codeとは: AnthropicのCLIベースのエージェントコーディングツール。SKILL.md という定義ファイルでカスタムの指示・手順・知識をパッケージ化し、Claudeの動作を拡張できる。

AnthropicのSKILL公式ガイドラインは「繰り返し実行するタスクの手順書」を想定している。この記事はその一歩手前——実装前の要件定義をSKILLとして書くという使い方を提案する。

開発は要件定義から始まる。その要件定義書をSKILLとして書く——基本アイデアはそれだけだ。本記事では、その具体的な実装パターンを解説する。最初は粗い定義でいい。AIに実装させ、結果をフィードバックしてSKILLを育てていくうちに、要件も実装も整ってくる。

この記事では、その具体的な設計パターンを整理する。入出力をスキーマで定義し、ドキュメントを分割し、evalで完了条件を決める。この設計にすると、同じSKILLから異なる技術スタックで実装を生成したり、OSSリポジトリから仕様を蒸留したりもできるようになる。

前提: AnthropicのClaude Code における「スキル」とは、SKILL.md を中心にAIへの指示・手順・品質基準をディレクトリ構造でまとめたものを指す。

要件先行でスキルを設計する

スキルを作るとき、いきなり SKILL.md に手順を書き始めるより、まず何を達成したいのかを定義しておくのがおすすめだ。なぜなら要件が揺れている段階で手順を固めると、後で全部書き直しになりがちだから。

例えば「プログラムを作成するスキル」を設計するなら、最初に考えるべきことはこうだ：

目的:    何を達成したいか
入力:    何を受け取るか
出力:    何を生成するか
品質基準: どんな状態を「成功」とするか
制約:    やってはいけないこと、範囲外のこと

この段階では技術スタックを固定しない方が、後で再利用しやすいことが多い。PythonかNode.jsか、というのは実装の詳細であって要件ではない。スキルを使う時点でパラメータとして渡す設計にすることで、同じスキルを異なる技術環境で再利用できる。

ポイント: 技術スタックをスキルに固定しないことで、「Python版」「Node.js版」「Go版」を同一の仕様から生成できる。仕様と実装の分離は、AIへの指示設計でも有効な原則だ。

入出力をスキーマで表現する

入出力の定義にJSONスキーマを使うのは、特にシンプルで強力なアプローチだ。自然言語の曖昧さを排除しつつ、人間にもAIにも同じように読める。

// schemas/input.json（※ // はJSONコメント拡張記法 JSONC での表記です）
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["requirements"],
  "properties": {
    "requirements": { "type": "string", "description": "作りたいものの説明" },
    "tech_stack":   { "type": "string", "description": "使用技術（省略可）" },
    "constraints":  { "type": "array", "items": { "type": "string" }, "description": "制約事項（省略可）" }
  }
}

// schemas/output.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["code_files", "how_to_run"],
  "properties": {
    "code_files":  { "type": "array", "items": { "type": "string" }, "description": "生成されたコードのファイルパス" },
    "how_to_run":  { "type": "string", "description": "実行方法" },
    "test_cases":  { "type": "array", "items": { "type": "string" }, "description": "テストコードのファイルパス（省略可）" }
  }
}

補足: このスキーマファイルはツール側が自動でバリデーションするものではなく、AIへの参照ドキュメントとして機能する。強制力はStructured Outputのような技術的なものではなく、明確な仕様を示すことによる「認知的な契約」に近い。それでも、曖昧な自然言語の指示と比べると一貫性は大幅に向上する。

スキーマを設計上の契約として扱うことで、SKILL.md の内部実装を変更しても入出力の互換性を保てる。スキーマさえ一致していれば、複数のスキルをパイプラインでつなぐことも自然になる。

要件定義スキル → コード生成スキル → テストスキル → レビュースキル

ディレクトリ構成が仕様書セットになる

スキルがディレクトリ構造を持てることの意義は大きい。従来のソフトウェア開発における「仕様書一式」と対応させるとこうなる：

my-product-requirements/
├── SKILL.md              ← エントリーポイント（薄く保つ）
├── schemas/
│   ├── input.json        ← 入力仕様
│   └── output.json       ← 出力仕様
├── docs/
│   ├── principles.md     ← 設計原則
│   ├── quality.md        ← 品質基準
│   └── error-handling.md ← エラー時の振る舞い
└── evals/
    ├── evals.json        ← テスト仕様
    └── files/            ← テストデータ

肝心の SKILL.md の中身はどう書くか。エントリーポイントとして薄く保ちつつ、スキーマと詳細ドキュメントへの参照を明示する：

---
name: my-product-requirements
description: この機能の要件定義書
---

## 入出力

入力仕様: schemas/input.json を参照
出力仕様: schemas/output.json を参照

## 手順

1. 入力の `requirements` を読み、達成すべきことを把握する
2. `tech_stack` が指定されていればそれに従う。なければ要件に最適なものを選ぶ
3. `docs/principles.md` の設計原則に従ってコードを設計する
4. `docs/quality.md` の品質基準をすべて満たすまでレビューする
5. エラーが起きた場合は `docs/error-handling.md` に従って対処する
6. 出力仕様の形式でファイルを生成する

本来であればこのファイルは REQUIREMENTS.md と呼びたいところだが、Claude Codeのフォーマットに乗るために SKILL.md として書いている。名前はともかく、中身は要件定義書だ。

重要なのは SKILL.md を薄いエントリーポイントとして保つことだ。全部を1ファイルに詰め込むと肥大化し、メンテナンスが困難になる。

従来のドキュメント	スキルディレクトリ
要件定義書（人間が読む）	`SKILL.md`（人間＋AIが読む）
API仕様書	`schemas/input.json`, `output.json`
設計書・コーディング規約	`docs/principles.md`, `quality.md`
テスト仕様書	`evals/evals.json`

また、Gitで管理すれば仕様の変更履歴がそのままAIの振る舞いの変更履歴になる。チームでリポジトリを共有すれば、全員が同じスキルセットを利用できる。

人間とAI双方に読みやすい記述

スキル設計で最も重要な制約のひとつが「人間とAIの双方に分かりやすい記述」を実現することだ。

面白いことに、AIが解釈しやすいドキュメントは結果的に人間にも読みやすくなる傾向がある。その共通要素は：

曖昧さの排除 — 「適切に処理する」ではなく「エラー時はXを返す」
具体例とカウンター例 — やること・やらないことを明示する
条件の明示 — 「〜の場合は〜する」という形式
一貫した用語 — 同じ概念に同じ言葉を使う
意図（Why）の記述 — なぜそうするかを人間向けに書く

逆説的な恩恵: AIが読みやすいドキュメントを書こうとすると、チームのドキュメント文化自体が改善される副産物がある。曖昧な記述を排除し、構造化する習慣は、そもそも良い仕様書の条件でもある。

実行結果をスキルへフィードバックする

スキルの真価は継続的な整合性の維持にある。ゼロから作り直すのではなく、実行結果とSKILLの定義に齟齬が生じたときにAgentが差分を検出し、ドキュメントか実装のどちらかを部分修正するだけだ。

① スキルでプログラムを生成
         ↓
② 実際に実行・テスト
         ↓
③ 結果を評価（動いたか、品質は、エラーは）
         ↓
④ 改善知見を docs/ や SKILL.md に反映
         ↓
⑤ 新バージョンのスキルで再試行
         ↓
⑥ 旧バージョンと比較（Improve モード）
         ↓
     ↺ ① へ戻る

AnthropicがClaude Code向けに提供している skill-creator スキルは、このサイクルを「Improve モード」「Eval モード」として体系化している。内部には「盲検比較（Blind Compare）」という仕組みがあり、バージョンAとBのどちらが生成したかを評価者が知らない状態で比較することで、バイアスなく品質向上を測定できる。

補足 — skill-creator について: Improve モード・盲検比較はあくまで skill-creator スキル自体に組み込まれた機能であり、Claude Code の汎用コマンドとして独立しているわけではない。この改善サイクルを自分のスキルに適用するには、skill-creator を使ってワークフローを回す必要がある。

蓄積された知見は docs/error-handling.md や docs/quality.md に追記される。こうしてスキルは使うほど賢くなる。

OSSリポジトリからの蒸留

この思想を最も大胆に活用できるのが、GitHubの公開リポジトリからの仕様蒸留だ。

GitHub 公開リポジトリ（複数可）
         ↓
  Claude Code で解析
         ↓
「何をしているか」ではなく
「何を達成しようとしているか」を抽出
         ↓
SKILL.md + schemas/ として仕様化
         ↓
┌──────────────────────────────────┐
│ ✦ 別技術スタックで再実装         │
│ ✦ 複数OSSのベストプラクティスを  │
│   一つのスキルに蒸留             │
│ ✦ レガシーシステムの現代化       │
└──────────────────────────────────┘

ここで重要なのは抽象レベルの選択だ。コードをそのまま移植するのではなく、実装の癖や技術的負債を捨て、本質的な振る舞いと設計原則だけを抽出する。これは「蒸留」という言葉がよく表している。

特に有望なユースケース

最も安全で実務的なのが自社レガシーシステムの現代化だ。塩漬けになったCOBOLや古いJavaのコードベースから本質的な仕様を抽出して、GoやPythonで書き直す——という作業がスキルドリブンで回せる。自社資産であればライセンスの心配もない。

複数OSSの集合知蒸留も強力だ。同じ目的を持つ複数のリポジトリを横断解析して、それぞれのベストプラクティスを一つのスキルに統合する。ただしライセンスの確認は必須だ。

ライセンスについて: あくまで技術的なアイデアとして提示している。実用する際は対象リポジトリのライセンスを各自確認すること。

まとめ — 新しいソフトウェア開発の形

この記事で提案した設計思想を整理する：

思想	内容
スキルは要件定義書	AIへの指示と人間が読む仕様書を一つのドキュメントで兼ねる
技術スタックの外部化	スキルは技術非依存に保ち、使用時にパラメータとして渡す
スキーマによる契約	入出力をJSONスキーマで定義し、スキル間のパイプラインを可能にする
ディレクトリ構成が仕様書セット	`SKILL.md` は薄く保ち、詳細を分割ドキュメントに委ねる
改善サイクルの組み込み	実行結果をスキルにフィードバックし、継続的に品質向上する
OSSからの蒸留	既存の知識資産を技術非依存な仕様として再利用する

この思想が指し示すのは、コードと仕様書とAIへの指示が同じリポジトリで共存する開発スタイルだ。人間が書いた仕様をAIが実行し、AIの実行結果が仕様を更新していく。

まだ一般的とは言えないアプローチだが、.cursorrules や copilot-instructions.md といった動きと同じ方向性を持っており、今まさに形成されつつある領域だと感じている。スキルというフォーマットが、ソフトウェア開発における知識継承のあり方を変えていく可能性がある。

コード自動生成が当たり前になると、ソースコードは生成物になる。そのとき、要件定義書こそが本当の意味での「ソース」になる。SKILLをその器として設計しておくことは、その変化への自然な備えだ。