目次
spec kitを一周触ってみて、便利なのは分かったけど「これ専用ツールに乗っかってるだけで、中でやってることは要求・設計・タスクの3つの仕様書を順番に書かせてるだけでは」と思った人向けの記事です。実際そのとおりで、3層の仕様書さえ用意できれば spec kit がなくても仕様駆動開発は回せます。生成される .specify/ 配下の大量のファイルや、ツールのバージョン追従に疲れてきたなら、手元のAIエージェントだけで完結させる方がむしろ身軽です。
3層仕様書そのものの中身は別記事で書いたので、ここでは前提として軽く触れるだけにして、「spec kitに頼らず Claude Code・Codex CLI・Copilot CLI の上でその3層をどう運用するか」に絞ります。
仕様駆動開発は3層の仕様書でできている
おさらいです。spec kit でも Kiro でも、仕様駆動開発の骨格は3つの仕様書を抽象から具体へ降りていくことで成り立っています。
- 要求(requirements / spec)：ユーザー視点で「何を」作るかを書く。実装手段は書かない
- 設計(design / plan)：その要求を「どう」作るか、アーキテクチャやデータモデルに翻訳する
- タスク(tasks)：設計を、終了条件が明確な離散的な作業単位に割る
各層で一度立ち止まって人間がレビューするから、実装の都合で要求が侵食されずに済む、というのが肝でした。詳しい書き方は仕様駆動開発で用意する3種類の仕様書に書いています。
spec kit がやっているのは、この3層を生成するスラッシュコマンド(/specify /plan /tasks)とテンプレートを配ってくれること、それだけです。逆に言えば、同じことを自分のカスタムコマンドで用意すれば、ツールは要りません。
AIエージェントごとにカスタムコマンドの置き場が違う
自前で回すうえで最初にぶつかるのが、エージェントごとにカスタムコマンド(再利用できる定型プロンプト)の仕組みと置き場がバラバラ、という点です。手元の3つを横断で並べると、対応状況にけっこう差があります。
| エージェント | 定型プロンプトの仕組み | 置き場 | 呼び出し |
|---|---|---|---|
| Claude Code | カスタムスラッシュコマンド / スキル | .claude/commands/(プロジェクト)・~/.claude/commands/(ユーザー)、スキルは .claude/skills/<name>/SKILL.md |
/<ファイル名> |
| Codex CLI | カスタムプロンプト(deprecated)/ スキル | プロンプトは ~/.codex/prompts/ のみ、スキルは .codex/skills/<name>/SKILL.md(プロジェクト)・~/.codex/skills/ |
/prompts:<名前> |
| Copilot CLI | カスタムエージェント | .github/agents/<name>.agent.md(プロジェクト)・~/.copilot/agents/(ユーザー) |
/agent で選択 |
注意点がいくつかあります。
Claude Code は .claude/commands/ にマークダウンを置けばファイル名がそのまま /specify のようなコマンドになり、本文に $ARGUMENTS を書けば引数を受け取れます。プロジェクト配下に置けるのでリポジトリにコミットしてチームで共有できます。
Codex CLI のカスタムプロンプトは ~/.codex/prompts/ に置くと /prompts:specify のように呼べますが、ここはユーザーのホーム配下だけでリポジトリにコミットして共有できません。しかも公式ドキュメントでは custom prompts は「Deprecated. Use skills for reusable prompts」と明記され、スキルへの移行が推奨されています[1]。
Copilot CLI は事情が違って、VS Code 拡張にある .github/prompts/*.prompt.md 形式のカスタムプロンプトはCLIではまだ読み込めません(要望は Issue として挙がっていますが未実装です)[2]。代わりに .github/agents/<name>.agent.md というカスタムエージェントを定義し、/agent で選んで使う形になります[3]。
チームで揃えるならスキルに寄せる
ここまで見ると、3エージェントで「カスタムスラッシュコマンド」の作法を完全に統一するのは無理だと分かります。Codex のプロンプトは共有できないし、Copilot CLI はプロンプト自体がありません。
横断の最大公約数を取るなら、いま使えるのは**スキル(SKILL.md)**です。Claude Code(.claude/skills/)も Codex CLI(.codex/skills/)も、プロジェクト直下のスキルフォルダに SKILL.md を置けばリポジトリにコミットでき、クローンしたメンバー全員に同じワークフローが配られます[4]。Copilot CLI もスキル・カスタムエージェントをリポジトリ内(.github/)に置けます。
私は自分のプロジェクトでは、requirements / design / tasks の3つを生成するスキルをリポジトリに入れて、Claude Code と Codex CLI の両方から同じ SKILL.md を読ませる運用に落ち着きました。ユーザー個人のホーム配下に置くと「自分の環境では動くのにレビュアーの手元では使えない」が起きるので、共有できる置き場を最初に選ぶのが地味に効きます。
---
name: spec-requirements
description: 機能の要求仕様書(requirements.md)を作る。ユーザー視点で何を作るかだけを書き、実装手段は書かない。
---
# 要求仕様書を作る
`docs/specs/<feature>/requirements.md` を作成する。
- ユーザーストーリーと、EARS形式(When/Then)の受け入れ基準で書く
- 不明な点は推測で埋めず `[NEEDS CLARIFICATION]` を残す
- 実装方法・技術選定には触れない(それは design 層の仕事)
設計とタスクも同じ粒度で spec-design spec-tasks を用意し、3つを順番に呼ぶだけです。spec kit のテンプレートを写経する必要はなく、自分のチームの言葉で書けるのがむしろ利点でした。
ベストプラクティスはカスタムコマンド1つで完結させること
もう一つ、自前で回すときに踏みやすい落とし穴があります。「要求を作るエージェント」「設計を作るエージェント」のように工程ごとに SubAgent を立てて委譲する構成です。一見きれいなのですが、仕様駆動開発とは相性が悪いと考えています。
理由は、各層のレビューを人間が挟むことが仕様駆動開発の本体だからです。SubAgent に丸ごと委譲すると、要求から設計、タスクまでが一気に裏で進んでしまい、人間が立ち止まる隙が消えます。生成された3つを後からまとめてレビューする羽目になり、それなら spec kit の自動生成と変わりません。
なので、各層は独立したカスタムスラッシュコマンド(またはスキル)1つで完結させ、人間が /spec-requirements → レビュー → /spec-design → レビュー、と手で次を叩く形にしています。委譲しないことで「層と層のあいだに必ず人間が入る」が構造的に保証されます。
SubAgent は、1つの層の中で並列に走らせても破綻しない作業(複数ファイルの横断調査など)に使うと効きます。工程の縦の分割(要求→設計→タスク)には使わない、という切り分けです。
仕様書はリポジトリに置いてレビュー対象にする
最後に、自前で回すと忘れがちな運用を一つ。生成した3つの仕様書は docs/specs/<feature>/ のようにリポジトリへコミットして、コードと同じく Pull Request のレビュー対象にしておくと効きます。
spec kit は .specify/ 配下に状態を持ちますが、自前なら置き場も命名も自由です。要求が変わったらまず requirements.md を直し、その差分を起点に design・tasks を作り直します。仕様書が git の履歴に残るので、「なぜこの実装になったか」を後から要求まで遡れます。
docs/specs/
└── user-export/
├── requirements.md
├── design.md
└── tasks.md
spec kit を外したからといって仕様駆動開発をやめるわけではなく、3層の仕様書をリポジトリで管理する芯だけ残して、生成手段を手元のエージェントに寄せます。これが今のところ一番身軽でした。専用ツールのアップデートに振り回されなくなったのが、思っていたより楽です。