実践！仕様書駆動開発 ②仕様作成編 — AIに渡す要件・設計・タスクを対話で作って Issue にする

ZenChAIne·2026年5月25日

Agent SkillsSpec-Driven DevelopmentClaude Code

はじめに

agent-skills（ZenChAIne がオープンソース公開している Spec 駆動開発スキル集）実践ガイドの第 2 回（仕様作成編）です。第 1 回（セットアップ編）でプロジェクトの 「動き方・書き方・レビュー基準」 を spec-workflow-init と spec-rules-init で作りました。今回はその土台の上で、AI に何をさせるか を伝える「要件・設計・タスク」の 3 点セットを生成・検証・Issue 化する 3 スキルを取り上げます。

この記事のポイント

spec-generator は対話形式で .specs/{project}/ に requirement.md / design.md / tasks.md を生成。--quick / --analyze / --deep などのオプションで生成スタイルを切り替え
要件 ID 体系（[REQ-XXX] 機能要件、[NFR-XXX] 非機能、[CON-XXX] 制約、[ASM-XXX] 前提、[T-XXX] タスク）で 3 ファイル間のトレーサビリティを担保
spec-inspect は 15 種類 の品質チェック（CRITICAL / WARNING / INFO）で ID 整合・矛盾・曖昧表現・プロジェクトルール準拠まで検証し、inspection-report.md を生成
spec-to-issue は .specs/{feature}/ を読み取り、gh issue create でチェックリスト付きの構造化 Feature Issue を生成
3 つは「生成 → 検査 → Issue 化」のフローを ポストアクションで次のステップを提案 する設計（ユーザーが選択すれば連続実行できる）
第 1 回で作った coding-rules.md を spec-generator の design フェーズと spec-inspect の Check 13 が自動参照
次回（第 3 回・実装編）へ続く

なぜ 3 ドキュメント（要件・設計・タスク）が必要なのか？

AIエージェントに「何を実装するか」を伝えるとき、自然言語の指示だけだと 解釈の幅 が大きすぎます。同じ「ユーザー管理機能」でも、要件と設計とタスクのどこを切るかで、出来上がるコードが全然違ったものになります。

agent-skills の spec 系スキルは、この曖昧さを 3 つのファイルで段階的に削っていく設計です。

ファイル	内容	役割
`requirement.md`	機能要件・非機能・制約・前提を ID 付きで列挙	何を作るか
`design.md`	アーキテクチャ・技術スタック・データモデル・API 設計	どう作るか
`tasks.md`	実装タスクを優先度・依存付きで分解	どう進めるか

3 ファイルは要件 ID（[REQ-XXX] など）でリンクされ、後段の spec-implement がこのリンクを辿って実装します。

spec-generator: AIと対話で 3 点セットを作るには？

spec-generator は 対話形式または --quick モード で .specs/{project}/ 配下に 3 点セットを生成します。

インストールと起動

bash

npx skills add anyoneanderson/agent-skills --skill spec-generator -g -y

要件定義を作って
# or
Create requirements for a todo app

起動直後にスキルは 現在ディレクトリと既存 .specs/ を自動検出 し、新規プロジェクトか既存追加かをユーザーに確認します。

4 つのフェーズ

フェーズ	出力	トリガー例
`init`	`requirement.md`	「要件定義を作って」
`design`	`design.md`	「設計書を作って」
`tasks`	`tasks.md`	「タスクリストを作って」
`full`	上記 3 つ	「仕様を全部まとめて」

full モードは順次連結で実行されます。requirement.md を生成 → それを読んで design.md を生成 → それを読んで tasks.md を生成、という形で各フェーズが前段の出力を入力として使います。

要件 ID 体系

3 ファイルのトレーサビリティを担保するため、以下の ID 体系が共通で使われます。

[REQ-XXX]: 機能要件
[NFR-XXX]: 非機能要件
[CON-XXX]: 制約
[ASM-XXX]: 前提
[T-XXX]: タスク

design.md は [REQ-001] を踏まえてアーキテクチャを書き、tasks.md は [REQ-001] と [T-005] をリンクします。後段の spec-inspect がこの ID 整合性を CRITICAL でチェックします。

主なオプション

オプション	効果	対象フェーズ
`--quick`	対話なしで簡潔な仕様を即生成	`init`
`--deep`	ソクラテス式の深掘り対話で要件を精緻化	`init`
`--personas`	複数視点（ペルソナ）での分析・レビュー	`init`, `design`
`--analyze`	既存コードベースを解析してから生成	`init`, `design`, `tasks`
`--visual`	Mermaid 図を強化	`design`
`--estimate`	見積もりとリスク評価を追加	`tasks`
`--hierarchy`	Epic / Story / Task の階層構造	`tasks`

YAGNI 原則と coding-rules.md 連携

spec-generator は YAGNI 原則 を組み込んでおり、明示的に指示されない限り、多言語化・複雑な権限管理・リアルタイム通知・管理画面などの「ありがち過剰機能」を要件に含めません。

また、第 1 回で作った docs/coding-rules.md を design フェーズで自動的に読み込み、命名規則が [MUST] ルールに準拠する、テスト戦略がカバレッジ要件を満たす、技術選定が推奨ライブラリと整合する、ディレクトリ構造が検出パターンに沿う、という方向で設計が整えられます。

spec-inspect: 仕様の品質をどう検証するのか？

spec-generator の出力をそのまま spec-to-issue に渡す前に、spec-inspect で品質チェックを通すのが推奨フローです。

bash

npx skills add anyoneanderson/agent-skills --skill spec-inspect -g -y

仕様書を検査
# or
inspect specs

15 種類のチェック（重大度別）

spec-inspect は 3 つの仕様書を読み込み、以下 15 種類 のチェックを実行します。

#	チェック	重大度
1	要件 ID 整合（定義 / 参照 / カバレッジ）	CRITICAL / WARNING / INFO
2	必須セクションの欠落	WARNING
3	仕様間の矛盾（技術スタック・数値・API）	WARNING
4	曖昧表現（「適切に」「ある程度」「高速に」など）	INFO
5	ターミノロジー一貫性（user vs member 等）	WARNING
6	Design-to-Task カバレッジ	WARNING
7	タスク依存の妥当性（循環・未定義）	WARNING
8	実現可能性の警告	WARNING
9	欠落要件の検出（認証→セキュリティ要件など）	WARNING
10	ネーミング規約の一貫性	INFO
11	ディレクトリ構造の一貫性	INFO
12	再発明の検出（ライブラリで済むのに独自実装）	INFO
13	プロジェクトルール準拠（`coding-rules.md` の `[MUST]` 違反）	WARNING
14	API / UI 命名規約（REST 単複・パス casing 等）	WARNING
15	ドキュメント更新分析（README / CLAUDE.md 等）	INFO

検査結果は .specs/{project}/inspection-report.md に Markdown で書き出され、コンソールには CRITICAL / WARNING / INFO の件数サマリが表示されます。

`coding-rules.md` 連携

Check 13（プロジェクトルール準拠）は、第 1 回で生成した docs/coding-rules.md の [MUST] ルール を仕様書に照合します。例えば「TypeScript strict mode 必須」「Prisma を使う」「JWT 認証必須」のような [MUST] が design.md に反映されていなければ WARNING を出します。

CRITICAL が 1 件でも残った状態で実装に進むのは危険 です。spec-inspect のポストアクションは「修正して再実行」「スキップして Issue 登録」「キャンセル」の 3 択を提示します。基本は「修正して再実行」を選び、CRITICAL ゼロまで仕様を直してから次へ進むのが推奨です。

spec-to-issue: 仕様を GitHub Issue にするには？

spec-to-issue は .specs/{feature}/ を読み取り、gh issue create で チェックリスト付きの構造化 Feature Issue を生成します。requirement.md が必須、tasks.md は推奨、design.md は任意で、spec-generator の full モード後なら通常 3 ファイルが揃った状態で実行できます。

bash

npx skills add anyoneanderson/agent-skills --skill spec-to-issue -g -y

仕様書をIssueにして
# or
Create issue from spec

設定の解決順序

ラベル・ベースブランチ・アサインなどのデフォルトは以下の優先順位で解決されます。

text

コマンド引数 > .specs/.config.yml > CLAUDE.md > 組み込みデフォルト

.specs/.config.yml の例:

yaml

default-branch: develop
default-labels: [feature, spec-generated]
project-number: 7
assignee: username

生成される Issue の主な構成

タイトル: requirement.md の最初の # 行から抽出
概要: ## 概要 セクション
Spec Documents: .specs/{feature}/ 配下 3 ファイルへの直リンク（指定ブランチで）
主要機能: ### 1. 〜のセクションを一覧化
実装チェックリスト: tasks.md の Phase ごとのタスクを GitHub Issue のチェックボックスに変換
技術スタック: ## Technology Stack セクション（あれば）
完了条件: ## 完了の定義 / ## Definition of Done セクション
注意事項: ## Notes / ## 注意事項 セクション（あれば）

主なオプション

オプション	効果
`--preview`	Issue 本文を表示し、確認後に作成
`--label "label1,label2"`	カンマ区切りでラベル指定
`--project 7`	GitHub Project に追加（`gh project item-add`）
`--branch develop`	spec ファイルへのリンクのベースブランチ
`--assignee username`	アサインを指定

3 つを連携させた標準フロー

3 つのスキルは、完了後のポストアクションで次のステップを提案する設計です。ユーザーが選択すれば、提示された次のスキルへそのまま連続実行できます（無人で進む完全自動ではなく、各ステップで確認が入る点に注意）。

text

spec-generator (full)
  ↓ ポストアクションで「Run spec-inspect」を提示
spec-inspect
  ↓ ポストアクションで「Register Issue」を提示（CRITICAL ゼロ前提）
spec-to-issue
  ↓ Issue 番号が確定 → spec-implement へ

実行コマンドはチャットで自然言語を打つだけです。

ECサイトの仕様を全部作って
# → requirement / design / tasks 生成
# → spec-inspect 実行を提案 → 検査 → CRITICAL ゼロを確認
# → spec-to-issue 実行を提案 → Issue 作成

第 3 回（実装編）で取り上げる spec-implement は、ここで作った Issue 番号と .specs/{feature}/ を入力として、PR まで自走します。

よくある質問

Q. `spec-generator` の `--quick` と通常モードはどう使い分けますか？

A. --quick は「とりあえずたたき台が欲しい」場合に使います（対話なし、ベストプラクティスから推測）。社内向けや要件が曖昧な新規企画では通常モード（対話）または --deep（深掘り）が推奨です。--analyze は既存コードからリバースエンジニアリングする場面で使います。

Q. 既存の `.specs/{project}/` を更新できますか？

A. できます。spec-generator は起動時に既存プロジェクトを検出し、「既存を選ぶ / 新規作成」を尋ねます。既存を選ぶと前回の requirement.md などをコンテキストとしてロードし、追加・修正を対話で進められます。

Q. `spec-inspect` の CRITICAL は無視できますか？

A. ポストアクションで「Skip to Issue registration」を選べば進めますが推奨しません。CRITICAL は主に 要件 ID 不整合（design.md で [REQ-005] を参照しているのに requirement.md に定義がない等）なので、後段の spec-implement が「存在しない要件を実装しようとする」リスクに直結します。

Q. `spec-to-issue` で `gh` の認証が通らない場合は？

A. スキル側でエラーを検知し、gh auth login を案内します。複数アカウントを使い分けている場合は、必要に応じて GitHub CLI 側でアカウントを切り替えてから再実行してください。

Q. `coding-rules.md` がない状態でも使えますか？

A. 使えます。spec-generator は coding-rules.md が無くてもデフォルト規約で生成します。spec-inspect の Check 13 については coding-rules.md 由来の [MUST] 照合は行われません が、CLAUDE.md / AGENTS.md / .claude/ などにプロジェクトルールがあれば、Check 13 はそれらを参照します。あとから第 1 回の spec-rules-init を走らせて coding-rules.md を作り、再 spec-inspect すると [MUST] 照合まで含めたフルチェックになります。

Q. `.specs/` は Git で管理するべきですか？

A. 推奨です。requirement.md / design.md / tasks.md は PR レビューで揉んで育てるドキュメントなので、Git 管理しチームで共有する方がメリットが大きいです。inspection-report.md は再生成可能なので、チーム運用次第では .gitignore 候補にできます（履歴を追跡したい場合は管理対象に残しても可）。

まとめと次回予告

spec-generator / spec-inspect / spec-to-issue は、AI エージェントに「何を、どう、どの順序で実装させるか」を 対話 → 品質チェック → Issue 化 の流れで構造化するスキルです。3 つは要件 ID 体系で結ばれ、ポストアクションで連鎖するため、一度走らせれば「ECサイトの仕様を全部作って」程度の指示から Issue まで到達できます。

第 1 回で作った coding-rules.md と issue-to-pr-workflow.md が、本記事の spec-generator の設計フェーズと spec-inspect のプロジェクトルール準拠チェックで活きてきます。これが Spec 駆動開発の 「ドキュメントを育てるほど自動化が強くなる」 構造の中核です。

次回（第 3 回・実装編）では、spec-implement / spec-code / spec-review / spec-test を取り上げ、ここで作った Issue から PR まで自走させる 仕組みを解説します。

参考ソース

🇺🇸 Read in English