実践！仕様書駆動開発 ①セットアップ編 — AIが守るべきルールを作ってプロジェクトの土台を作る
はじめに
agent-skills（ZenChAIne がオープンソース公開している Spec 駆動開発スキル集）の spec 系スキルを「何のために、どう使うか」が分かる実践ガイド、第1回です。本記事では、開発フロー全体を生成する spec-workflow-init と、コーディングルール・レビュー基準を抽出する spec-rules-init を取り上げ、Spec 駆動開発の 最初に整えるべき 2 つのドキュメント を作る方法を解説します。
Agent Skills の基礎は Agent Skills とは何か と agent-skills オープンソース公開記事 で説明しているので、本記事はそこから一歩踏み込んだ「実際にプロジェクトで運用する」レベルを扱います。
この記事のポイント
- agent-skills には spec 系スキルが 9 つあり、ワークフローの段階別に役割が決まっている
- 最初に整えるのは
docs/issue-to-pr-workflow.md（開発フロー）とdocs/coding-rules.md/docs/review_rules.md（品質ルール）の 3 ドキュメント spec-workflow-initは最大 8 ラウンドの対話でブランチ戦略・品質ゲート・開発スタイルを決め、ワークフロー本文と任意で Claude/Codex のサブエージェント定義まで生成spec-rules-initは CLAUDE.md / AGENTS.md / package.json / 既存コード / インストール済みスキルから規約を抽出し、[MUST]/[SHOULD]/[MAY]の重大度付きで coding-rules.md / review_rules.md を出力- 2 つを併用すると、後段の spec-implement が「どう動くか」「どう書くか」「どうレビューするか」を 1 ファイルずつ参照できる状態になる
- 第 2 回（仕様作成編）・第 3 回（実装編）へ続く
なぜ Spec 駆動開発のスキルが必要なのか？
AI エージェントに開発を任せると、最初に困るのは「同じプロジェクトでも、エージェントごとにアウトプットの粒度や規約が揺れる」点です。Issue→PR の手順、テストの書き方、コミットメッセージの言語、import 順序などが、対話のたびに変わってしまいます。
これは AI エージェントを 1 人の開発者として迎え入れるとき、プロジェクトの暗黙知をどのように共有するか という運用課題です。Spec 駆動開発のスキルは、この暗黙知を 3 つのドキュメントに抽出し、後段のエージェントが必ず参照する仕組みにする、という考え方で設計されています。
agent-skills が想定している 3 ドキュメントは以下です。
| ドキュメント | 役割 | 主な生成スキル |
|---|---|---|
docs/issue-to-pr-workflow.md | ブランチ戦略・品質ゲート・開発スタイル・ロール分担 | spec-workflow-init |
docs/coding-rules.md | 実装時の品質ゲート（[MUST]/[SHOULD]/[MAY]） | spec-rules-init |
docs/review_rules.md | コードレビュー基準・重大度別出力方針 | spec-rules-init |
第 1 回（セットアップ編）はこの 3 ドキュメントを生成します。
agent-skills の全体マップ（spec 系 9 スキル）
spec 系スキルは 9 個あり、Issue から PR までを次のように分担します。
| 段階 | スキル | 役割 |
|---|---|---|
| 0. 準備 | spec-workflow-init | issue-to-pr-workflow.md を生成 |
| 0. 準備 | spec-rules-init | coding-rules.md / review_rules.md を生成 |
| 1. 仕様化 | spec-generator | 要件・設計・タスクの 3 点セット |
| 1. 仕様化 | spec-inspect | 仕様の整合・矛盾・欠落チェック |
| 2. Issue 化 | spec-to-issue | .specs/ → GitHub Issue |
| 3. 実装 | spec-code | 単一タスクを自律実装 |
| 3. 実装 | spec-review | rule × file マトリクスでレビュー |
| 3. 実装 | spec-test | 完了条件からテスト生成 |
| 3. 実装 | spec-implement | code → review → test → PR をオーケストレーション |
本記事はこのうち「0. 準備」段階を担当する 2 スキルに集中します。
あわせて使える周辺スキル
agent-skills には spec 系以外にも、ワークフロー全体を支える周辺スキルがあります。本記事の流れに直接関係するものを先に紹介します。
| スキル | 役割 | 本記事での扱い |
|---|---|---|
skill-suggest | プロジェクトの技術スタック（package.json / Cargo.toml / go.mod 等）を解析し、skills.sh からベストプラクティススキルを提案・インストール。インストール結果は spec-rules-init の Priority 3 抽出ソースに直結 | 後段の spec-rules-init セクションで詳しく扱う |
cmux-fork / cmux-delegate / cmux-second-opinion | cmux ターミナル上で会話のフォーク・別ペインへの委任・別 AI によるセカンドオピニオンを実現 | 詳細は cmux 系スキル解説記事 を参照 |
handover | セッションをまたいだコンテキスト引き継ぎ | 本連載の対象外（別途解説予定） |
mcp-convert | Claude Code の MCP 設定を Codex CLI 向けに変換 | 同上 |
skill-suggest は spec-rules-init のルール抽出を厚くする補完スキル、cmux 系 3 スキルは マルチエージェント運用時の補完スキル として、本記事の以降の節で都度触れていきます。
spec-workflow-init: プロジェクトの開発フローを生成するには？
spec-workflow-init は、プロジェクト固有の issue-to-pr-workflow.md を 対話形式で最大 8 ラウンド に分けて生成するスキルです。
このファイルは 「Issue を受け取り → 仕様書を読み → 実装 → レビュー → テスト → PR 作成」までの全工程を AI が踏むためのプレイブック です。後段の spec-implement がこれを読み込んで、各工程を順番に実行します。プレイブックに書き込めるルールは多岐にわたります。
- ブランチ戦略: Git Flow / GitHub Flow / Trunk-based のどれを採用するか、ブランチ命名規則
- 開発スタイル: 実装ファースト / TDD（テストを先に書く） / BDD（E2E シナリオを先に書く）など、お馴染みの開発工程を AI に踏ませられる
- 品質ゲート: テスト全パス、Lint、Typecheck、カバレッジ基準など PR 前に通すべきチェック
- コードレビューの粒度: rule × file マトリクスで全ルールを全ファイルに照合、セカンドオピニオン実施有無
- E2E テストの範囲: API レベルのみか、Playwright での Browser E2E まで含めるか
- エージェントの役割分担: 単独の Claude Code / Codex で全工程を回すのではなく、「実装は Codex、レビューは Claude Code、テストは Codex」のように工程ごとに得意なエージェントを割り当てられる（マルチエージェント / マルチエージェント(cmux) 選択時）
つまり、Claude Code か Codex のどちらかを選ぶのではなく 両方を使い分けて開発工程ごとに最適化 できる、というのが spec-workflow-init が生成するプレイブックの強みです。最初にこれを言語化しておくと、AI が「いま何の工程にいて、次に何をすべきか」迷わなくなります。
インストールは npm の skills CLI 経由で行います。
npx skills add anyoneanderson/agent-skills --skill spec-workflow-init -g -y実行は自然言語トリガーで起動できます（プロジェクトルート CWD で実行）。
ワークフローを生成して
# or
Generate development workflow
スキルは起動直後に 環境自動検出 を行います。
- パッケージマネージャ:
pnpm-lock.yaml/yarn.lock/package-lock.json/bun.lockb - コンテナ:
docker-compose.yml/Dockerfile - CI/CD:
.github/workflows//.gitlab-ci.yml/.circleci/ - ブランチ情報:
git branch -r - 言語・フレームワーク・scripts:
package.json/go.mod/requirements.txt/pyproject.toml - DB:
prisma/schema.prisma/ docker-compose.yml のpostgres等の記述 - Lint:
.eslintrc*/biome.json - 既存の
coding-rules.md/review_rules.md - cmux 環境変数 (
CMUX_SOCKET_PATH)
検出結果はサマリ表で提示され、ユーザー確認後に対話に入ります。対話は次のラウンドで構成されます。
| ラウンド | 内容 |
|---|---|
| 1 | 出力先（docs/issue-to-pr-workflow.md 推奨） |
| 2 | ブランチ戦略（Git Flow / GitHub Flow / Trunk-based）と命名規則 |
| 3 | 品質ゲート（テスト全パス / Lint・Typecheck / カバレッジ） |
| 4 | 開発スタイル（Implementation First / TDD / BDD） |
| 5 | E2E テスト範囲（API のみ / API + Browser） |
| 6 | 実行戦略（単独 / マルチエージェント / マルチエージェント(cmux)） |
| 7 | サブエージェント定義の生成対象（Claude / Codex / 両方 / なし） |
| 8 | 各ロールへの AI 割り当て（マルチエージェント時のみ） |
マルチエージェントを選んだ場合は、workflow-implementer.md / workflow-reviewer.md / workflow-tester.md を .claude/agents/ または .codex/agents/ に書き出します（Codex 側は TOML 形式 + .codex/config.toml の更新まで自動）。
最後に、生成されたワークフロー本文への参照を AGENTS.md / CLAUDE.md の末尾に追記するか確認されます。これにより後段のエージェントが起動時に自動的にワークフローへ辿り着けます。
実例: agent-skills repo 自身もこのスキルで生成された docs/issue-to-pr-workflow.md を使っています（dogfooding）。
spec-rules-init: コーディングルールとレビュー基準を生成するには？
spec-rules-init は、プロジェクトの既存規約からルールを抽出し、docs/coding-rules.md（実装品質ゲート）と docs/review_rules.md（レビュー基準）を生成するスキルです。
インストールと起動:
npx skills add anyoneanderson/agent-skills --skill spec-rules-init -g -yコーディングルールを生成して
# or
Generate coding rules
抽出ソースは 3 段階の優先度 で扱われます。
ここで Priority 3 として登場する「インストール済みスキル」は、agent-skills 自身のスキル群だけではありません。Vercel が公開している vercel-react-best-practices のような他社製のベストプラクティス系スキル も、インストールしておけば抽出ソースとして自動的に使われます。技術スタックに合うベストプラクティススキルを skill-suggest（後述）で導入しておけば、それらの知見が spec-rules-init の Priority 3 ルールとしてまるごと取り込まれます。
| 優先度 | ソース | 主な扱い |
|---|---|---|
| 1 | CLAUDE.md / AGENTS.md / .claude/ 配下 | 既定で [MUST] |
| 2 | コードベース解析（命名規則 60%+ 多数派、shared utility、ライブラリ検出） | 60%+ 多数派は [MUST]、その他は [SHOULD] |
| 3 | インストール済みスキル（agent-skills 自身、vercel-react-best-practices など他社製含む）から抽出したベストプラクティス | [SHOULD] または [MAY] |
抽出カテゴリは 6 つです: Testing Standards / Code Quality / Error Handling / Documentation / Security / Git。各ルールにはカテゴリ・重大度・出典ファイル・行参照が記録されます。
Priority 3 を底上げしたい場合は skill-suggest の併用がおすすめ です。skill-suggest は同じ agent-skills repo にあるスキルで、package.json / Cargo.toml / go.mod などのマニフェストを解析し、skills.sh レジストリから技術スタックに合うベストプラクティススキルを提案・インストールしてくれます。インストールされたスキルは spec-rules-init の Priority 3 として自動的にルール抽出対象になるため、2 つを組み合わせると 「技術スタック検出 → ベストプラクティススキル導入 → ルール抽出」 が一気通貫で回ります。
npx skills add anyoneanderson/agent-skills --skill skill-suggest -g -y「おすすめスキルを教えて」と話しかけると、検出された技術スタックに合うスキルを提案してくれます。
抽出が終わるとサマリが提示されます。
Extraction Results:
Testing Standards: 8 rules
Code Quality: 12 rules
Error Handling: 5 rules
Documentation: 4 rules
Security: 3 rules
Git: 4 rules
Total: 36 rules (Priority 1: 14, Priority 2: 18, Priority 3: 4)その後、出力先選択、不足カテゴリの補強ダイアログ、最後に review_rules.md も一緒に生成するか を問われます。--with-review-rules で対話スキップ可能、--no-review-rules で生成スキップも可能です。
生成後、agent-skills の他スキルが自動的に参照する仕組みになっています。
spec-generator: design フェーズで設計制約として参照spec-inspect: Check 13（プロジェクトルール準拠）で[MUST]ルールを照合spec-implement: 実装時の品質ゲートとして参照spec-workflow-init: ワークフローのレビュー Phase で参照cmux-second-opinion: セカンドオピニオン実行時に参照（cmux 系 3 スキルの使い方は 別記事 で解説）- GitHub Actions:
claude-review.ymlから参照可能
実例: agent-skills repo 自身の docs/coding-rules.md と docs/review_rules.md がこのスキルで生成されています。
2 つを併用すると何が変わるのか？
spec-workflow-init と spec-rules-init を併用すると、後段のエージェントが 「どう動くか・どう書くか・どうレビューするか」を 3 ファイルで参照できる状態 になります。
.
├── AGENTS.md ← 起動時にエージェントが読む
├── docs/
│ ├── issue-to-pr-workflow.md ← 動き方
│ ├── coding-rules.md ← 書き方
│ └── review_rules.md ← レビュー基準
└── .claude/agents/ ← マルチエージェント時のロール定義特に重要なのは、AGENTS.md / CLAUDE.md の末尾に 2 つのスキルが追記するセクションです。
## Development Workflow
開発フロー（Issue → 実装 → PR）は以下のファイルに従ってください:
- [docs/issue-to-pr-workflow.md](docs/issue-to-pr-workflow.md) — spec-workflow-init で生成された開発ワークフロー
## コーディングルール
実装時のコーディングルールは以下のファイルに従ってください:
- [docs/coding-rules.md](docs/coding-rules.md) — spec-rules-init で生成された品質ルール集
- [docs/review_rules.md](docs/review_rules.md) — コードレビュー・セカンドオピニオン用のレビュー基準このセクションが入ることで、後段のエージェント（spec-implement / spec-code / spec-review / cmux-second-opinion）はファイル名を覚えていなくても、起動時に AGENTS.md を読むだけで必要な参照先に辿り着けます。
2 つのスキルは どちらを先に実行しても動作 しますが、spec-workflow-init が coding-rules.md の存在を検出してワークフロー本文に「品質ゲートとして参照する」記述を埋め込むため、spec-rules-init を先に実行するのが推奨 です。spec-rules-init 完了直後のポストアクションでも、次に spec-workflow-init を実行するよう案内されます。
よくある質問
Q. プロジェクトに既存の CLAUDE.md / AGENTS.md がない場合は使えますか？
A. 使えます。spec-rules-init は規約ファイルが見つからない場合、対話のみモードに自動切り替えし、カテゴリ別に必要なルールを聞き取ります。spec-workflow-init も同様に環境検出に失敗した項目は対話で補完します。
Q. 既存の issue-to-pr-workflow.md / coding-rules.md を後から更新できますか？
A. できます。再実行すると既存ファイル検出ダイアログが表示され、上書き・差分マージ・キャンセルから選べます。--force オプションで対話スキップも可能です。
Q. Claude Code 以外のエージェントでも動きますか？
A. 動きます。SKILL.md フォーマットに対応していれば Claude Code / Codex / Cursor / Gemini CLI / OpenCode などで利用可能です。spec-workflow-init は Claude 用・Codex 用のサブエージェントテンプレートを両方持っており、対話で生成対象を選べます。
Q. coding-rules.md と review_rules.md は何が違いますか？
A. coding-rules.md は実装エージェント（spec-code 等）が「書きながら参照する」品質ルール集、review_rules.md はレビューエージェント（spec-review、cmux-second-opinion、GitHub Actions）が「書かれた結果をチェックする」レビュー基準集です。重大度別の出力方針（CI / レビューゲート / セカンドオピニオン）が後者で定義されます。
Q. cmux がない環境でもセットアップ編は完結しますか？
A. 完結します。spec-workflow-init の Round 6（実行戦略）で「単独 / マルチエージェント」の 2 択になり、cmux 関連の選択肢は自動的に非表示になります。spec-rules-init は cmux に依存しません。
Q. 生成されたルールやワークフローは育てていくべきですか？
A. はい、むしろ育てていくのが推奨です。coding-rules.md / review_rules.md / issue-to-pr-workflow.md は初期生成後、レポジトリ固有のルール（このプロジェクトでは Hook をこう使う、この命名は禁止、コミットメッセージはこのフォーマット、ライセンスヘッダ必須、など）を手動で追記していくのが本来の使い方です。Git で管理して PR レビューで揉めば、後段の spec-implement などが毎回これらを読み直すため、ルールが厚くなるほど自動化の品質も上がっていきます。最初は薄くても、運用しながら独自ルールをコツコツ足していきましょう。
Q. .claude/agents/ や .codex/agents/ のロール定義はカスタマイズできますか？
A. むしろカスタマイズ前提です。spec-workflow-init が生成する workflow-implementer.md / workflow-reviewer.md / workflow-tester.md は 出発点としてのテンプレート です。プロジェクトの特性に合わせて自由に編集してください（例: NestJS なら DI 指針を実装担当に追加、レビュー担当には特定の脆弱性パターンを必須チェック項目として追加、テスト担当には Playwright のページオブジェクト規約を指定、など）。Markdown / TOML として直接編集できるので、プロジェクトの「好み」をどんどん反映していくとエージェントの出力が安定します。
まとめと次回予告
spec-workflow-init と spec-rules-init は、agent-skills が想定する 「最初の 2 段階のドキュメント」 を自動生成するスキルです。プロジェクトの開発フローと品質ルールを 1 つのコマンドで言語化することで、後段の Spec 駆動開発スキル群が同じ参照点を共有できる状態を作れます。
ZenChAIne でも、agent-skills repo 自身の docs/issue-to-pr-workflow.md / docs/coding-rules.md / docs/review_rules.md を dogfooding しており、新しい記事ブランチを切るたびにこれらが効いています。
次回（第 2 回・仕様作成編）では、spec-generator / spec-inspect / spec-to-issue を取り上げ、対話で仕様を引き出し、品質チェックし、GitHub Issue に変換するまでの流れを解説します。
参考ソース
- agent-skills - GitHub
- spec-workflow-init SKILL.md
- spec-rules-init SKILL.md
- agent-skills - docs/issue-to-pr-workflow.md（dogfooding 例）
- agent-skills - docs/coding-rules.md（dogfooding 例）
- agent-skills - docs/review_rules.md（dogfooding 例）
- Agent Skills とは何か - ZenChAIne
- agent-skills オープンソース公開 - ZenChAIne
- skills.sh