Amazon Web Services ブログ

Kiro における負債にならない Spec ファイルの扱い方

こんにちは！ AWS でソリューションアーキテクトをしている鈴木です。

本ブログは Kiroweeeeeeek ( X: #kiroweeeeeeek ) の第 8 日目です。昨日のブログはしょぼちむさんの「イベントストーミングから要件・設計・タスクへ。Kiro を活用した仕様駆動開発」という内容でした。

本記事では、Kiro において中核をなす「Spec ファイル」の負債にならないための扱い方をお伝えします。なお、Kiro の一般提供に関しての総合的な情報は「Kiro が一般提供開始: IDE とターミナルでチームと共に開発」をお読みください。

Spec ファイルの概要

本題に入る前に Spec ファイルの概要と Spec ファイルによって開発者が得られる恩恵について記述します。
Kiro の Spec ファイルは「仕様駆動開発」を構成する要素です。仕様駆動開発とは、仕様を起点として設計・実装を進める開発手法で、仕様と実装の同期を保ちながら開発を進めることができます。
Spec ファイルは以下の 3 つのファイルで構成されています。

  • requirements.md：EARS (Easy Approach to Requirements Syntax) 記法での要件
  • design.md：構造やデータフローなど実装方針
  • tasks.md：要件と設計を基に Kiro が生成する実装タスク群

Kiro は Spec モードでの対話の中で、初めに requirements.md で要件を定義し、そこから design.md で実装方針や設計を作成し、最後に tasks.md で実装のためのタスクを作成していきます。そうして出来た tasks.md 内のタスクに沿ってコードを生成・更新していくことで実際に実装がされていく流れです。

このような形式を取ることで Kiro は仕様と実装の間で同期を保つことができます。これにより「仕様書の更新漏れ」や「仕様書と実装のイメージの乖離」といった問題を起こすことなく継続的に開発が可能です。

しかしながら正しく Spec ファイルを扱わないと上記のメリットを十分に享受することができず、むしろ負債になる可能性があります。今回は「Spec ファイルの切り方」「Spec ファイルの更新方法」「Spec ファイルの共有方法」の 3 つの視点から、負債にならないための工夫をお伝えします。

Spec ファイルの切り方

機能ごとに分離する

Kiro を使う中で負債になりがちな行為として、「プロジェクト全体を一つの大きな Spec ファイルで管理しようとする」というものが挙げられます。EC サイトの例を元に考えてみましょう。EC サイトは確かに一つのアプリケーションですが、その中では複数の機能、用途が組み合わさって構成されています。これらをすべて「EC サイト」という一つの Spec ファイルにまとめてしまうと、

  • 記載されている内容が多くなり、可読性が落ちる。
  • チームで開発する上でコンフリクトが生じやすくなり、開発のストレスが増大する。
  • 特定機能を更新したいだけなのに、Spec ファイル全体に影響が波及してしまう。

などの問題が生じてしまい、結果として Spec ファイルが機能しなくなり、Spec ファイルの内容と実装の間で同期が保たれなくなる危険性があります。そのため Kiro では巨大な一つの Spec ファイルを作成するのではなく、複数の Spec ファイルを機能ごとに作成することを推奨しています。

例えば EC サイトの場合、以下のように機能ごとに Spec ファイルを切ることが出来ます。

.kiro/specs/
├── user-authentication/ # ログイン, サインアップ, パスワードの変更
├── product-catalog/ # 商品のリスティング, 検索, フィルタリング
├── shopping-cart/ # カートに追加, 数量の更新, 会計
├── payment-processing/ # Payment gateway の統合, 注文の確認
└── admin-dashboard/ # 商品の管理, 顧客分析

切り方の粒度や観点には正解はないので、ご自身のアプリケーション要件やチームの状況、アーキテクチャ設計に応じて柔軟に決定いただくのが良いかと思います。

切り方については Kiro と Vibe モードを利用して、壁打ちをしながら進めていくことも可能です。初めに Kiro と会話をしながら要件を固めて「この固まった要件で機能ごとに Spec ファイルを分けてくれますか？」と聞いてみると添付の画像のように案を出してくれます。

Spec ファイルの更新

Spec ファイルは一度作って終わりではなく、定期的なメンテナンスが前提になっています。要件が追加されたり、設計方針が変わった場合は、Spec ファイルを更新することで Kiro が生成するタスクやコードにも変更を反映しましょう。注意点として、要件の変更があった場合に Spec ファイルに変更を適応しないで Vibe モードや手動でコードの変更を行うことは避けるべきです。Kiro のメリットである「仕様と実装の間で同期」が崩れてしまうためです。

requirements.md から変更を適応する

要件の追加・削除・修正があった場合は、以下のフローでコードの変更を行います。

  1. 要件の更新：requirements.md ファイルを直接修正するか、Spec モードを開始して Kiro に新しい要件や設計要素を追加するよう指示します。
  2. 設計の更新: 仕様の design.md ファイルに移動し、「Refine」を選択します。この操作により、設計ドキュメントと関連するタスクリストの両方が、修正された要件を反映して更新されます
  3. タスクの更新: tasks.mdファイルに移動し、「Update tasks」を選択します。これにより、新しい要件に対応する新しいタスクが作成されます。
  4. タスクの実装: 3 のプロセスで追加、修正されたタスクを実行することでコードに変更を適応する。

このように更新を行なっていくことで、「要件 → 設計 → タスク → 実装」の一貫性が保たれ、要件変更による「設計だけ古くなる」「タスクだけ古い」といったズレが発生しにくくなります。

Vibe から Spec に適応する

要件が変更された際には requirements.md から変更を適応するべきだということをお話ししましたが、実際に実装をしてみてから仕様を決定したいというニーズもあるかと思います。例えば、「UI の色味や挙動をみてから変更したい」などのボトムアップな実装を行いたい場合などです。

また、LLM との雑談ベースでの会話やブレインストーミングで整理した機能案から仕様を作成したいといったニーズもあるかと思います。そのような場合は、Vibe モードで実装してから Spec ファイルへの自動生成・適応することができます。

Kiro の Vibe モードをまずは立ち上げ、その中で会話や実装を行います。その後、Kiroに「ここまでの変更を Spec に変換して」というと、これまでのVibe モードのコンテキストから Spec ファイルを構築することが可能となります。特に実装の初期フェーズでは、言語化が固まりきっていない段階の「思考の断片」を Spec に落とし込める点が非常に便利です。

Spec ファイルの共有

Spec ファイル はバージョン管理を行なう

Spec ファイルはバージョン管理することが推奨されています。バージョン管理することで、実装と実装意図をまとめて管理することが可能となります。 また、バージョン管理することでチーム間での無駄なコミュニケーションを減らすことも可能となります。例えばフロントエンドチームがバックエンドチームの実装意図を知りたい場合、従来であれば開発者に聞くか仕様書を探索する必要がありました。バージョンを管理すれば、Kiro に実装の意図を聞くだけで Spec ファイルを参照して答えてくれます。

また、コードに対するレビューと同じように、Spec に対してもレビューを行うことで、

  • 要件の解釈がチーム内でズレない
  • 設計方針の合意形成が早い
  • 誤った前提でコードが実装されるリスクを軽減できる

といったメリットを受けることが出来ます。さらに、Spec ファイルがバージョン管理されていれば、その機能の背景や意図を理解しながらレビューでき、「なぜこの実装なのか？」という議論がスムーズになります。

アプリケーションを跨ぐ仕様は共有する

複数のアプリケーションを並行して開発している場合、認証部分の仕様などを共通化させたいニーズがあるかと思います。 そういった場合に、それぞれのアプリケーションごとに個別の Spec ファイルを作ってしまうと、本来共通であるべき仕様がアプリ間で徐々にズレていくという問題が発生します。

片方のアプリだけ認証フローを更新し、もう片方が古い仕様のまま残ってしまったり、エッジケースの扱いがアプリによって微妙に異なってしまったりと、どれが正しい仕様なのかが分からない状態になりやすいのです。

そこで重要なのが、共通仕様は 1 つの Spec ファイルとして切り出して共有するというアプローチです。 認証認可、決済、プロフィール設定など、複数アプリで跨って利用する部分は 専用の Spec リポジトリにまとめておくことで、

  • 仕様の更新が 1 箇所で完結する
  • アプリ間の仕様のズレを防げる
  • チーム間の前提が揃い、開発スピードが落ちない

といったメリットが得られます。Git Submodule などを用いることで複数プロジェクトから参照可能です。

添付画像は Git Submodule を用いて共通の Spec ファイルとアプリケーション固有の Spec ファイルを管理する例です。共通の Spec ファイルは/shared の下にアプリケーション固有の Spec ファイルは /local の下に配置することで実現しています。

共通仕様は 1 箇所で定義し、複数アプリがそれを参照するという構造を作ることで、仕様の一貫性を保ちつつ、長期的に負債化しづらい開発体制を維持できます。

まとめ

本記事では、Kiro の Spec ファイルを負債にしないための 3 つのポイントを解説しました。
３つのポイントを振り返ると、以下のようになります。

  • Spec ファイルの切り方：プロジェクト全体を一つの巨大な Spec ファイルで管理せず、機能ごとに分けることで可読性とメンテナンス性を向上させる。
  • Spec ファイルの更新：要件変更時は requirements.md → design.md → tasks.md → 実装の順での更新、もしくは Vibeモードから都度 Spec ファイルへの変換を行うことで、仕様と実装の同期を保つ。
  • Spec ファイルの共有：バージョン管理によりチーム内で Spec ファイルを共有することで実装と実装意図をまとめて管理できる。また、複数アプリ間の共通仕様は専用リポジトリで一元管理することでアプリ間の仕様のズレを防ぐことができる。

これらを実践していくことで Spec 機能の効果を最大限発揮することができ、Kiro がチーム開発における強力ツールとして力を発揮していくことができるかと思います。皆さんは Spec ファイルの扱いでどのような工夫をされていますでしょうか？是非、 X 上で #kiroweeeeeeekをつけて教えていただければと思います！

鈴木 智貴 (Tomoki Suzuki)
アマゾンウェブサービスジャパン合同会社 ソリューションアーキテクト
2025 年に新卒で入社した 1 年目の SA。大学時代に薬局向けのスタートアップで CTO を経験。好きなサービスは Kiro。好きなドラマは『SPEC ～警視庁公安部公安第五課 未詳事件特別対策係事件簿～』。
LinkedIn: https://www.linkedin.com/in/tomoki-suzuki-7a8457277/
X: https://x.com/tomozooooooonn?s=21