📄

仕様駆動開発を自分なりにカスタマイズしてみた

2025/09/16に公開

作成したテンプレート

このテンプレートを作成するにあたり、仕様駆動開発のベースとして以下のリポジトリを参考にしております。

https://github.com/gotalab/cc-sdd

以下に、このテンプレートの意図や、カスタマイズした部分を簡単に書いていきます。

ディレクトリ構成

.kiro/
  ├─ specs/
  │   ├─ requirements.md      # 要件（EARS 準拠）
  │   ├─ design.md            # 設計
  │   ├─ tasks.md             # 開発全体で必要なタスク（機能全体の計画）
  │   ├─ spec.json            # メタデータ/承認状態
  │   ├─ sow/                 # 各ブランチ実装のSOW（詳細タスク: 実装手順/チェック）
  │   │   └─ <n>_<feature>.md or <feature>.<branch>.md
  │   └─ dev_log/             # 実装ログ（PR 前後のまとめ、任意）
  └─ steering/                # プロダクト/技術/構造のステアリング
      ├─ product.md
      ├─ tech.md
      ├─ structure.md
      ├─ branch_rule.md       # ブランチ命名規則
      └─ logging.md           # ロギングポリシー

.claude/commands/kiro/        # Claude Code で使うコマンド定義
  ├─ spec-init.md
  ├─ spec-requirements.md
  ├─ spec-design.md
  ├─ spec-tasks.md
  ├─ sow.md
  ├─ spec-status.md
  ├─ spec-impl.md
  └─ steering.md

CLAUDE.md                      # 運用の補足（SOW・ブランチ命名など）
README.md                      # このテンプレートの説明

大きな流れ

スラッシュコマンドベースで開発の流れを記載していきます。

プロジェクトメモリとコンテキストを作成&仕様を初期化
※ steeringは小規模な開発ではなくてもいいかもしれません

/kiro:steering
/kiro:spec-init <開発したい内容を記述>

要件を作成・承認

/kiro:spec-requirements <prj-name>

設計を作成・承認

/kiro:spec-design <prj-name>

機能全体のタスクを生成

/kiro:spec-tasks <prj-name>

変更点

元々はここで生成されるtasks.mdに詳細なタスクを書くような設計でしたが、このテンプレートではtasks.mdは大きな粒度のタスクの記載に留め、ブランチ作成ごとにSOWを作成するように変更しています。
意図として、実際に開発していると最初に決めたtasksから細かい部分が変わることが多く、であれば細かい部分は毎回SOWとして別で作成し、tasksは全体観を掴むために使う方がいいのではと思ったのがあります。

5. 各ブランチ実装の SOW を作成

/kiro:sow <prj-name> --title <sowのタイトル>

変更点

元々はなかった工程を追加しています。
SOWは作業明細書という意味で、一時的な作業書のようなイメージです。AIに「SOWを作って」と指示するだけで通じ、一定の品質で作業書を書いてくれます。
新しくブランチを切って実装するごとにこのコマンドを使います。

参考記事：

意図：上述のtasksでの課題感から。毎回SOWを作る方が人間も状況を把握しやすく方針転換にも強い気がしています。

実装を TDD で進める

/kiro:spec-impl <prj-name>

ここもブランチごとです。

進捗を確認

/kiro:spec-status <prj-name>

このコマンドは確認したい時に適宜使うイメージです。

他にカスタマイズしているところ

ドキュメント類を日本語に

筆者が日本語ネイティブなので、可読性を重視し日本語にしています。
個人的に顕著に性能が落ちない＆日本語にするとメンテナンスや確認がしやすいことを重視しています。

CLAUDE.md

自分の開発スタイルになるように追記しています。

主な追記箇所

リビングドキュメント宣言： このプロジェクトでのすべてのドキュメントは「リビングドキュメント」として扱い、定期的に見直し、更新される前提で扱う。
- 開発していると細かな変化を逐一更新して綺麗に保つのが結構難しく、少しでもAIに意識してもらおうと思い記載しました
プロジェクト全体のガイドライン： Claude Code Actionや使用するMCPサーバーの説明を追記しています
開発の流れを追記
- SOW：上述の通り
- dev_log記載：ブランチごとに開発内容をdev_log/に記載
  - 毎回ログを明記するようにして透明化を意識しています
- プルリク前にドキュメント更新する旨を明記
開発ルールの追記：ブランチ戦略やプルリク作成、ネクストアクションの書き方を追記しています
- ネクストアクションは、途中で開発を中断して終わりたい時に書き方を統一したいという意図が強いです

ステアリングドキュメントをデフォルトで追加

以下の2ファイルを追加してます。

branch_rule.md：ブランチルールや命名規則、プルリクエストのフォーマットを記載しています
logging.md：vibeloggerというライブラリでログを取るよう記載しています
- vibeloggerはAIが読みやすいようなログ出力をしてくれるライブラリ
- 参考： https://github.com/fladdict/vibe-logger/blob/main/README.md

おわりに

最近ではGitHubが「Spec Kit」を出したりと、kiro以外のテンプレートも出てきていて、仕様駆動開発は注目の領域だと思います。

https://github.com/github/spec-kit

確かに仕様駆動開発を実践してみると適当にバイブコーディングをやるよりも筋よく作りたいものが作れるような感覚があり、優れているなと感じています。
その一方で、公式のテンプレートをそのまま流用するだけだと自分の開発スタイルに100%合致はしなかったので、テンプレートの意図を理解して自分なりにカスタマイズするのは今後も必要にな気がしました。

今回のカスタマイズは大きく分けると毎実装のSOW作成と、自分のスタイルに合うようドキュメントを拡充という二つの方針で行っています。

おそらく作りたいものや技術スタック、開発規模にもよってもカスタマイズの仕方は全然変わってくると思います。

優れたテンプレートの動向をウォッチしつつ、自分の開発の中で実践してカスタマイズの肌感を身につけていければと思っています。