Claude Codeにスキルを追加してみたものの、「設計書生成が思ったとおりに動かない」「毎回微妙に出力形式がブレる」と感じたことはありませんか？
設計書のようにフォーマットが厳密に求められるドキュメントほど、スキル定義の甘さがそのまま出力の質に直結します。
この記事では、実際に設計書用スキルを運用しながら見えてきた、定義のコツを5つに絞って紹介します。
この記事でわかること
- 設計書用スキルの構成の作り方がわかる
- 出力のブレを抑える定義方法がわかる
- サブエージェントとスキルの使い分けができる
結論：設計書スキルは「型」「粒度」「参照先」の3つを固定すると安定します
設計書生成でありがちな失敗は、指示文を頑張って詳しく書いているのに、毎回微妙に違うアウトプットが返ってくることです。
原因の多くは、スキル側で「出力の型」が固定されておらず、Claudeがそのつど自由に構成を考えてしまっている点にあります。
逆に言えば、型・粒度・参照先の3点をスキル定義の中で明示しておけば、再現性は大きく上がります。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立った本もあります👇
→記事を読む
方法1：description欄にトリガー条件を具体的に書く
SKILL.mdのフロントマターにあるdescriptionは、単なる説明文ではありません。
Claudeが「このスキルを使うべきかどうか」を判断する唯一の手がかりです。
「設計書を作るスキルです」のような曖昧な書き方だと、似た依頼のときに発動しなかったり、逆に関係ない場面で呼ばれたりします。
トリガーになる依頼文の具体例を2〜3パターン、descriptionの中に列挙しておくのがコツです。
たとえば「設計書を書いて」「〇〇のdesign.mdを作成して」「要件から設計に落として」など、実際にユーザーが使いそうな言い回しをそのまま書いておくと、判定精度がぐっと上がります。
方法2：出力構成を見出しレベルまで固定する
設計書は、章立てがバラつくと後工程のレビューがしづらくなります。
「概要・目的・全体構成・詳細設計・懸念事項」のように、見出しの順番と粒度をSKILL.md内にテンプレートとして直接書き込んでおきましょう。
自然文で説明するより、Markdownのコードブロックでテンプレートをそのまま貼り付けたほうが再現性は高いです。
## 概要
## 目的
## 全体構成
## 詳細設計
## 懸念事項・リスク
このレベルまで固定しておくと、Claudeが章の順番を入れ替えたり、勝手に見出しを増減させたりする揺れがほぼなくなります。
方法3：サブエージェントとスキルの役割を分ける
設計書生成でよくあるのが、1つのスキルに「要件整理」「設計方針決定」「文書化」を全部詰め込んでしまうパターンです。
これをやると、指示が複雑になるほどClaudeの出力精度は下がっていきます。
requirements.mdを扱うサブエージェント、design.mdを扱うサブエージェントのように役割を分割し、スキル側は「どのエージェントをどの順番で呼ぶか」の制御に徹するほうが安定します。
複数ファイルを横断する設計プロセスなら、スキルは司令塔、サブエージェントは実行担当という分業がハマりやすいんですよね。
方法4：参照ドキュメントのパスを明示する
設計書は既存の要件定義書やAPI仕様など、他ドキュメントを参照しながら書くケースがほとんどです。
ここで「文脈から推測してね」とClaudeに任せると、参照漏れや古い情報の引用が起きやすくなります。
.claude/配下に参照先のパスをあらかじめ固定で書いておく、もしくはスキル内で「まず該当ファイルをreadしてから設計に着手する」という手順を明記しておくと、参照漏れがかなり減ります。
参照ファイルが存在しない場合の挙動（スキップするのか、ユーザーに確認するのか）まで書いておかないと、存在しないファイルを前提に設計書を書き始めてしまうことがあります。
方法5：Explore→Plan→Codeのサイクルを設計書生成にも適用する
コード生成で使われるExplore→Plan→Code→Verifyの考え方は、設計書作成にもそのまま応用できます。
いきなり本文を書かせるのではなく、まず既存コードやドキュメントを調査させ（Explore）、構成案を先に出させ（Plan）、承認を得てから本文生成に入る（Code）流れをスキルの手順として組み込むと、手戻りが大幅に減ります。
特に大規模な設計書ほど、いきなり全文生成させるより「章立て案だけ先に出して」と一度立ち止まらせるほうが、結果的に早く仕上がる印象があります。
| フェーズ | 設計書生成での役割 |
|---|---|
| Explore | 既存要件・関連コードの調査 |
| Plan | 章立て・構成案の提示 |
| Code | 設計書本文の生成 |
| Verify | 記載漏れ・矛盾のチェック |
まとめ
- descriptionにトリガー文言を具体的に書くと発動精度が上がる
- 出力構成は見出しレベルまでテンプレート化する
- サブエージェントとスキルで役割を分けると精度が安定する
- 参照ドキュメントのパスと欠損時の挙動を明示する
- Explore→Plan→Codeのサイクルを設計書生成にも取り入れる
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立った本もあります👇
→記事を読む