Claude Codeでサブエージェントを使い始めたものの、ドキュメント生成がうまく自動化できずに悩んでいませんか？
「設計書を毎回手打ちで直している」「要件定義がすぐ属人化する」そんな悩みを抱えるエンジニアは多いはずです。
この記事では、サブエージェントを使ったドキュメント自動生成の仕組みづくりを、実際にハマったポイントを交えて解説します。
この記事でわかること
- サブエージェントとスキルの使い分け方がわかる
- ドキュメント自動生成の仕組みが構築できる
- 設計時にハマりやすい落とし穴が避けられる
【結論】サブエージェントとスキルは役割で使い分ける
結論から言うと、ドキュメント生成は「対話が必要かどうか」で仕組みを分けるべきです。
対話を伴う工程はスキルに、独立して完結する工程はサブエージェントに任せる。
このシンプルな線引きが、自動化の精度を大きく左右します。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む
サブエージェントとスキルの違いを整理する
まず前提として、Claude Codeには.claude/agents/に置くサブエージェントと、.claude/skills/に置くスキルという2つの仕組みがあります。
両者は似ているようで、実は得意分野がまったく異なります。
| 項目 | サブエージェント | スキル |
|---|---|---|
| 配置場所 | .claude/agents/ |
.claude/skills/ |
| 対話機能 | AskUserQuestionが使えない | 対話しながら進行できる |
| 得意な工程 | 独立して完結する生成作業 | ユーザーとの合意形成が必要な工程 |
| 呼び出し方 | Taskツール経由で委譲 | コマンド入力やキーワードで起動 |
ここで一番ハマりやすいのが「AskUserQuestionがサブエージェントでは使えない」という制約です。
私自身、最初は要件定義痩系書を作成することを自動化しようと、サブエージェント化しようとして、ユーザーへの確認が一切できずに詰まった経験があります。
結果的に、この2つはスキルへ移行し、実際にドキュメントを作成するものだけをサブエージェントとして残す構成に落ち着きました。
実際の仕組み：ドキュメント自動生成フロー
具体的な構成はこうです。
.claude/
skills/
plan.md # 要件確認をしながら計画を立てる
requirements.md # ユーザーと対話しながら要件を固める
agents/
design.md # 要件が固まった後、独立して設計書を生成
流れとしては、まずスキル側で要件を対話形式で固めます。
「この機能は必要ですか？」「優先度はどれくらいですか？」といったやり取りを重ね、要件が固まった時点で設計書生成をサブエージェントに委譲する形です。
なんだか二度手間に見えるかもしれませんが、実際にはこの分業が精度を大きく底上げしてくれます。
対話が必要な工程を無理にサブエージェント化すると、確認が取れないまま生成が進んでしまう
これが一番の注意点です。
設計書やテスト仕様書のように「材料さえ揃えば自動生成できる」工程は、迷わずサブエージェントに任せるのが正解でしょう。
Explore→Plan→Code→Verifyとの相性
この構成は、Claude Codeの基本フローであるExplore→Plan→Code→Verifyとも噛み合います。
Explore・Planの段階は対話が発生しやすいのでスキル向き。
Code・Verifyの段階は仕様が固まっているため、サブエージェントでの自動生成と相性が良いはずです。
私も最初はすべてをサブエージェントに寄せようとしていましたが、この住み分けに気づいてから生成の安定感が圧倒的に変わりました。
ハマりやすいポイント
サブエージェントにAskUserQuestionを含むスキル定義を渡すと、実行時にエラーになることがあります。対話が必要な処理は事前にスキル側で完結させておきましょう。
また、ドキュメントのフォーマットを固定したい場合は、サブエージェントのプロンプト内にテンプレートを直接埋め込んでおくと、出力のブレが少なくなります。
まとめ
- サブエージェントは独立して完結する生成作業に向いている
- 対話が必要な工程はスキルに任せる
- AskUserQuestionはサブエージェントで使えない点に注意する
- Explore→Plan→Code→Verifyのフローと組み合わせると精度が上がる
- テンプレートをプロンプトに埋め込むと出力が安定する
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む