Claude CodeとCoworkで要件定義書をSkill化する手順

Claude CodeのSkillsで要件定義書を作る仕組み

Claude CodeのSkillsは、SKILL.mdという1つのMarkdownファイルに手順を書いておくと、Claudeがそれをツールキットとして読み込む仕組みです。/skill-nameで自分から呼び出すことも、会話の内容に合わせてClaudeが自動で選ぶこともできます。

要件定義書はこの仕組みと相性が良い作業です。背景整理・スコープ確定・機能要件の洗い出し・受け入れ基準の作成という決まった手順を、毎回チャットに書き直すのではなくSKILL.mdに1回だけ固定できます。手順が長くても、Skillの本文は呼び出されたときだけ読み込まれるため、無関係な作業のセッションでコストを払うことはありません。

Skillsと同じ拡張の枠には、サブエージェントやHooks、MCPもあります。4つの機構の役割の違いはClaude Code SkillsとMCPの違いで扱っていますが、要件定義のような「手順を再利用したい」ケースの第一候補はSkillsです。

要件定義書Skillを作る前提条件

保存場所によって、Skillが使える範囲が変わります。個人用の~/.claude/skills/に置けば自分の全プロジェクトで使え、プロジェクトの.claude/skills/にコミットすればチーム全員が同じSkillを使えます。要件定義書のように組織のフォーマットを揃えたい成果物は、プロジェクト側への配置が向いています。

Skillsそのものに専用料金はありません。課金が発生するとすれば実行環境側のプラン料金で、Claude.ai・Claude Code・APIで構造が異なります。詳しい条件はClaude Skills料金にまとめています。

CoworkでSkillsを使う場合は前提が1つ増えます。Coworkが読み込むSkillの範囲はClaude CodeのCLIとは別物で、詳しい条件は手順4で扱います。

要件定義書の作成自体は、ファイルを読んだり書いたりするツールが無くても成立します。既存の資料を見ずに会話の内容だけから作るなら、フロントマターにallowed-toolsを書かない最小構成でも動きます。ツール権限を絞る運用は、手順3・手順4で具体的に扱います。

手順1: SKILL.mdの雛形を作成する

まず、プロジェクトの.claude/skills/配下にディレクトリを作ります。

mkdir -p .claude/skills/requirements-doc

次にSKILL.md本体を作ります。フロントマターのdescriptionには、実際にユーザーが使いそうな言い回しを含めておくと、Claudeが自動で選びやすくなります。

---
name: requirements-doc
description: 要件定義書を作成する手順。新機能や新規プロジェクトの要件定義書を書きたいとき、仕様を整理したいときに使う。
argument-hint: [機能名またはプロジェクト名]
---
 
## 要件定義の手順
 
（ここに手順本文を書く。手順2で詳しく作る）

argument-hintは必須ではありませんが、/requirements-doc ログイン機能のように呼び出すときの補完ヒントとして表示されます。

手順2: 要件定義の手順を本文に落とし込む

SKILL.mdの本体には、要件定義書を書くときに毎回たどる順番をそのまま書きます。以下は最小構成の例です。

## 要件定義の手順
 
対象: $ARGUMENTS
 
1. **背景と目的**を1〜2段落で書く。なぜこの機能・プロジェクトが必要かを明記する
2. **スコープ**をDoing(やること)とNot Doing(やらないこと)に分けて箇条書きにする
3. **ステークホルダー**を一覧化し、それぞれの関心事を1行で添える
4. **機能要件**をユーザーストーリー形式(「〜として、〜したい。なぜなら〜」)で列挙する
5. **非機能要件**(性能・セキュリティ・可用性など)を該当する項目だけ書く。該当なしなら「対象外」と明記する
6. **受け入れ基準**を、各機能要件に対応する形でチェックリスト化する
7. **用語集**に、ドメイン固有の語だけを補足する
 
出力はMarkdown形式で、上記の見出し構成をそのまま使う。

$ARGUMENTSは、/requirements-doc ログイン機能のように渡した引数に置き換わるプレースホルダーです。呼び出しのたびに対象が本文へ差し込まれるので、同じSkillを機能ごとに使い回せます。

各ステップに評価語や結論を付けず、「何を書くか」だけを指示するのがポイントです。Skillの本文は一度読み込まれると会話に残り続けるため、冗長な説明を書くほど以後のターンのcontextを圧迫します。

呼び出し方法を選ぶ — 自動か手動か

デフォルトでは、/requirements-docと自分で入力することも、会話の流れからClaudeが自動で選ぶこともできます。要件定義書の作成は「思い立ったときに指示したい」作業になりやすいので、自動起動を避けたいならフロントマターにdisable-model-invocation: trueを追加します。こうするとClaudeは自動では呼び出さず、明示的に/requirements-docと打ったときだけ動きます。

逆に、issueや会話の内容から要件定義書を書いてほしい場面が多いプロジェクトでは、デフォルトのままdescriptionを具体的にしておくほうが手間は減ります。どちらを選ぶかは、Skillの呼び出しに副作用があるかどうかで判断するのが目安です。次の手順のようにファイルへの保存まで自動で行わせるなら、手動起動に寄せたほうが安全です。

生成した要件定義書をファイルに保存する

手順2の本文だけでは、要件定義書はチャットの返答として表示されるだけです。docs/requirements/のようなディレクトリにファイルとして残したい場合は、SKILL.mdの指示に保存先を明記し、allowed-toolsで書き込みを許可します。

---
name: requirements-doc
description: 要件定義書を作成する手順。新機能や新規プロジェクトの要件定義書を書きたいとき、仕様を整理したいときに使う。
argument-hint: [機能名またはプロジェクト名]
allowed-tools: Bash(git log:*), Edit(docs/requirements/**)
---
 
（手順2の本文に続けて）
 
最後に、生成した内容を docs/requirements/$ARGUMENTS.md として保存する。

ここでWrite(docs/requirements/**)と書きたくなりますが、Claude Codeはファイルパスの照合をEditとReadのルールでしか行いません。Writeにパス付きルールを書いても起動時に警告が出るだけで、実際の許可判定には使われないため、ファイル書き込みを許可したいときはEdit(path)の形で書きます。

手順3: プロジェクト情報を動的に注入する

!`command`という書き方を使うと、Skillが呼び出された瞬間にシェルコマンドを実行し、その出力を本文へ差し込めます。既存のREADMEや直近のコミット履歴を要件定義の材料として自動で読み込ませる用途に使えます。

---
name: requirements-doc
description: 要件定義書を作成する手順。新機能や新規プロジェクトの要件定義書を書きたいとき、仕様を整理したいときに使う。
argument-hint: [機能名またはプロジェクト名]
allowed-tools: Bash(git log:*)
---
 
## プロジェクトの直近の変更
!`git log --oneline -10`
 
## 既存のREADME概要
!`head -n 30 README.md`
 
## 要件定義の手順
 
対象: $ARGUMENTS
 
（手順2の本文をここに続ける）

このコマンドはClaude Codeのセッション内、つまりローカルの.claude/skills/から呼び出したときにだけ実行されます。コマンドが失敗すると、そのSkill呼び出し全体が中断され、Claudeには本文が渡りません。エラーは[stderr]付きで表示されるので、git logが使えないディレクトリで試すと原因がすぐ分かります。

手順4: チーム・Coworkへ共有範囲を広げる

プロジェクトの.claude/skills/にコミットすれば、Claude CodeのCLIを使うメンバー全員が同じSkillをすぐ使えます。バージョン管理を通じて配布されるので、要件定義のフォーマットをチームで統一したいときはこの置き場所が基本になります。

Coworkだけは扱いが別です。Coworkセッションはマシン上の~/.claude/skills/を読まず、claude.aiアカウント側で有効化したSkillをセッション開始時に同期して使います。Desktopアプリのサイドバーにある「Customize」か、claude.aiのSkills設定からSkillを有効化すると、次回のCoworkセッションからその内容が使えるようになります。なお、プロジェクトの.claude/skills/を追加で読み込むのはクラウドセッション(routineなど)の側で、リポジトリにコミットしたSkillがそのまま使われます。

有効化の際に、もう1点だけ注意が必要です。CoworkはSkillの本文をアカウント経由でダウンロードして使うため、!`command`で書いた行は実行されず、プレースホルダーに置き換わります。手順3で作ったコマンド注入つきのSkillをそのままCoworkで使っても、git logやREADME.mdの中身は本文に入りません。Coworkでは、そうした前提情報を対象の指定や会話の中で直接与える運用になります。

出力例: 最小構成で生成される要件定義書

手順2の本文だけを使い、/requirements-doc ログイン機能と呼び出すと、対象の機能名が$ARGUMENTSに差し込まれた状態で本文が渡り、Claudeは指定した7項目の見出し構成に沿って返答します。背景と目的から用語集まで同じ順番で埋まるため、担当者が変わっても要件定義書の構成が揃います。プロジェクトごとに項目を増減したい場合は、手順2のリストに書き足すだけで、次回の呼び出しから反映されます。

CLAUDE.md・手動プロンプトとの使い分け早見表

要件定義書の作成を毎回どう指示するか、3つの方法で比較します。

CLAUDE.mdとSkillsのコスト構造の違いはCLAUDE.mdをSkillsに移行してコストを削減する方法で詳しく扱っています。要件定義のように「特定のタスクでだけ使う長い手順」は、CLAUDE.mdよりSkillへ寄せるのが基本です。

よくあるつまずきと対処

descriptionが曖昧でSkillが自動で呼ばれない。「要件定義」「仕様整理」のように、ユーザーが実際に使いそうな言葉をdescriptionに含めます。呼ばれているかは/skillsで一覧を確認できます。使い方はClaude Code /skillsコマンドの使い方にまとめています。

フロントマターのYAMLが壊れている。パースに失敗するとdescriptionが空になり、/requirements-doc自体は動いてもClaudeの自動判定からは外れます。--debug起動でパースエラーを確認できます。

編集がそのセッションに反映される条件。~/.claude/skills/・プロジェクトの.claude/skills/・--add-dirで追加したディレクトリ配下のSKILL.mdを編集・追加・削除すると、bare modeを除き再起動なしで現在のセッションに反映されます。例外は、セッション開始時に存在しなかったトップレベルのskillsディレクトリを新規に作った場合だけで、このときは監視対象に入らないため再起動が必要です。反映されるのはSKILL.md本文のみで、同じフォルダがplugin構成を兼ねる場合のhooks/や.mcp.jsonの変更には/reload-pluginsが別途必要です。すでに会話に読み込まれた本文そのものは、その場では書き換わらず次回の呼び出しから新しい内容になります。

手順が長くなりすぎる。SKILL.mdは500行未満を目安にします。用語集やサンプル文例のような詳細はreference.mdのような別ファイルに切り出し、SKILL.mdからは参照だけを書きます。

Skillの数が増えると自動判定が緩む。手持ちのSkillが多いプロジェクトでは、一覧の文字数予算を超えた分からdescriptionが省略され、呼び出し頻度の低いSkillほど自動判定に使われにくくなります。要件定義書Skillをよく使うなら、優先度が下がらないよう定期的に呼び出しておくか、/doctorで一覧のコスト見積もりを確認します。

allowed-toolsにWrite(path)と書いても効かない。手順3で触れた通り、Claude Codeがファイルパスを照合するのはEditとReadのルールだけです。WriteやNotebookEditにパス付きルールを書いても警告が出るだけで判定には使われないので、書き込み先を絞りたいときはEdit(path)を使います。

まとめ

要件定義書の作成は、背景整理から受け入れ基準までの手順が毎回ほぼ同じという点で、Skill化に向いた作業です。.claude/skills/にコミットすればClaude Codeを使うチーム全員がすぐ使え、Coworkで使うにはclaude.aiアカウント側での有効化が別途必要になります。まずは手順2の最小構成で1つ作り、実際の案件で使いながら足りない項目を足していく進め方が実用的です。