前回はSteeringファイルやAgent Hooksまわりを触って、「Kiroに前提知識を持たせておくと生成物の質が変わる」という話を書きました。で、その勢いで小さめの社内ツール開発に持ち込んだら、自分ひとりで遊んでいたときには見えなかった問題が一気に噴き出しまして。シリーズ最終回はその後始末というか、実践してわかったことの総まとめです。
ちなみに「仕様駆動開発（Spec-Driven Development）」自体はKiro専用の概念ではなくて、GitHubのSpec Kitみたいなテンプレート系のアプローチもあります。ただKiroはrequirements.md / design.md / tasks.mdという3段構えがIDEに組み込まれているので、フローに乗るのは一番ラクだと個人的には思っています。
チーム運用でハマった落とし穴
1. .kiro/ をどこまでGitに入れるか問題
Steeringファイルは「Git管理下に置いてチーム全員で共有する」のが基本形です。ここは異論なしで、.kiro/steering/ をコミットするだけでコーディング規約がチーム全体に効きます。問題は .kiro/specs/ のほう。
自分は最初、specも全部コミットしていました。そうしたら、2人が別ブランチで同じ機能のspecを更新して、tasks.mdのチェックボックスがコンフリクト。Markdownのコンフリクトって、コードと違って「どっちが正しいか」が機械的に判断できないのでけっこう面倒です。今は「specは1機能1人が持つ」という運用にして、レビューはPRのdiffで見るようにしています。もっといい方法がある気がしますが、今のところこれで平和です。
2. Steeringが肥大化して効かなくなる
これが一番地味に効いてくる落とし穴でした。みんなが「これも書いとこう」とルールを足していった結果、Steeringが数千行になって、Kiroの回答が明らかにブレるようになりました。全部 inclusion: always にしていたのが原因です。
front matterで読み込みタイミングを制御できるので、今はこう分けています。
---
inclusion: fileMatch
fileMatchPattern: "**/*.tf"
---
# Terraform規約
- モジュールは modules/ 配下に配置
- variable には必ず description を書く
inclusionには always / fileMatch / manual / auto の4モードがあります。常に効かせたいのはプロジェクトの前提とアーキテクチャの決定事項だけ。言語やレイヤー固有のルールはfileMatchに落とす。これだけでレスポンスも体感で軽くなりました。
あと、ファイル名を 00-project.md 10-python.md みたいに数字プレフィックスで並べると、レビューのときに「どのレイヤーのルールか」が一目でわかって便利です。
3. 優先順位を勘違いしていた
ユーザーレベル（~/.kiro/steering/）とワークスペースレベル（.kiro/steering/）が競合すると、ワークスペース側が勝ちます。つまり個人の好みよりプロジェクトのルールが優先される。これは正しい挙動なんですが、自分は「自分のグローバル設定が効いてない！」と30分くらい悩みました。マルチルートワークスペースだと、後から追加したワークスペースのほうが優先度が高いらしいです。モノレポでフロント・バックを別フォルダで開いている人は要注意かもしれません。
Hooksのデバッグはどうやるのが正解なのか
Agent Hooksは「ファイル保存時にテストを更新」みたいなイベント駆動の自動化で、基本的にはイベントに反応する形で動くのがポイントです。便利なんですが、動かないときの原因切り分けがめちゃくちゃしづらい。
あと補足すると、IDE内のHooksとは別に、Kiro Web側にはAutomations（Cloud automations）みたいなスケジュール実行（Hourly/Daily/CRON）もあるので、「定期実行したい」系の要件はそっちで逃がせる場面もあります。
Hooksが動かない理由、自分が踏んだのはだいたいこの3つでした。
- ファイルパターンが合っていない（
*.pyと**/*.pyは別物） - プロンプトが曖昧で、Kiroが「何もしない」を選択している
- Hook自体が無効化されていた（パネルのトグルを切ったのを忘れる）
で、GUIでポチポチ試すのが辛くなってきたのでCLI側に寄せました。ローカルでペイロードを流し込んでシミュレートできる、という話を見かけたので、こんな感じで試していました。
kiro hook simulate --file .kiro/hooks/pr-review.kiro.hook \
--payload examples/pr-opened.json
kiro logs tail --agent my-agent # 別ターミナルで流しておく
CIで構文チェックもかけられます。Hookの定義ファイルはJSONとして扱われることが多い印象で、壊れたままマージされると全員の環境で静かに死ぬのが怖くて入れました。
- name: Validate Kiro hooks
run: kiro validate --dir .kiro/hooksもうひとつ、これは事故った話なんですが、「テストファイルを更新するHook」がテストファイルの保存イベントにも反応して無限ループしかけたことがあります。パターンから tests/ を除外して解決しましたが、Hookを書くときは「自分の出力が自分のトリガーを踏まないか」を先に考えたほうがいいです。地味に大事。
結局こう使うと良かった、という運用パターン
4か月くらい回した結果、落ち着いたのはこんな形です。
- specは「1機能・半日〜2日で終わる粒度」に切る。大きすぎるとdesign.mdが総論的になって、実装フェーズで結局手戻りする
- requirements.mdのレビューだけは人間が本気でやる。ここが曲がっていると後工程が全部曲がるので、逆にdesign以降は多少ゆるくてもリカバリできる
- Hooksは「品質の下限を上げる」用途に限定する。テスト同期、docstring追記、命名チェックあたり。ロジックの実装をHookに任せると挙動が読めなくなる
- CIとHooksの役割を分ける。Hooksは書きながらの即時フィードバック、CIは絶対に通さないゲート。両方でlintを回すと二重に怒られて誰も見なくなります
効率の話でよく見かける「要件定義が短縮」みたいな謳い文句は、正直そこまでは実感していないです。ただ「設計書を書く」という行為のハードルが下がったのは確かで、以前は面倒で省略していたドキュメントが残るようになりました。学習期間として2〜3週間は見ておいたほうがいい、という話もあって、これは体感と合っています。
仕様駆動が効かない場面もある
ここは正直に書いておきます。プロトタイプを1時間で作りたいときにspecを書くのは完全に遠回りでした。requirements書いてる間に手で書き終わる。あと、既存の巨大なレガシーコードに機能を足すケースも微妙で、design.mdが現状のコードベースを正しく把握してくれないと嘘の設計が出てきます。この場合はSteeringに「現状のディレクトリ構成と禁止事項」を先に叩き込んでからのほうがマシでした。
逆に一番効いたのは、複数人で並行して同じサービスを触るとき。仕様がファイルとして残っているので、「なんでこの実装になってるの？」の答えがdesign.mdにあるのは想像以上に助かりました。AIのためのドキュメントというより、人間のための副産物という感じ。
4回分を振り返って
第1回でSpecモードの3ファイル構成を触って、第2回で実際に小さいアプリを作って、第3回でSteeringとHooksに手を出して、今回はチームに持ち込んで転んだ話。書いてみると、結局「AIに指示を出す技術」より「前提を整える技術」の話ばかりでした。仕様駆動開発という名前がついていますが、やっていることの半分はコンテキスト管理なんじゃないかと思っています。
余談ですが、このシリーズを書いている間にKiro側のアップデートが何度も入って、書いた内容が古くなるのを追いかけるのが大変でした。CLIまわりは特に動きが速いので、詰まったら公式ドキュメントを見るのが一番早いです。
ところで、みなさんはspecファイルってGitに入れてますか。ここの正解、まだ自分の中で固まっていません。
