はじめに
開発の下流工程、つまり
実装 → テスト → レビュー → 修正
には、個人やチームごとの暗黙知が多く含まれています。
今回、チーム向けにその下流工程を標準化するため、Cursor の Slash Command / Skill を使った独自フローを試作しました。
最終的には、この独自フローは導入しませんでした。理由は、他チームがすでに利用している cc-sdd（Kiro） との統一性を優先したためです。
ただし、試作を通じて得られた知見は多かったため、記録として残しておきます。
背景
当初の課題は、AI に実装を任せる際の進め方が属人的になりやすいことでした。
例えば、以下のような問題があります。
- 仕様書を読んだ後、どこまでコード調査すべきかが曖昧
- 実装前に人間が判断すべき Decision が残ったまま進んでしまう
- STOP したときに、次に何をすればよいか分かりにくい
- レビューの品質や観点が人によってばらつく
そこで、下流工程を状態管理付きのフローとして制御する仕組みを試作しました。
試作したもの
試作では、以下のようなフローを構築しました。
/run
↓ explore-spec
↓ arch-impact
↓ plan-atomic
↓ /approve
↓ /implement
↓ tdd-loop
↓ /review
↓ review-sync
↓ fix-review（必要時）
中心に置いたのは agent/shop/executor.md です。
これは AI エージェントが次にどのフェーズを実行してよいかを判断するための、単一の制御仕様でした。
状態管理
状態は以下のファイルで管理しました。
agent/shop/state.json
agent/shop/context.md
agent/shop/progress.md
それぞれの役割は以下の通りです。
| ファイル | 役割 |
|---|---|
| state.json | 現在の phase、approved 状態、実行履歴 |
| context.md | 目的、制約、対象ファイル、テストコマンド |
| progress.md | 実行履歴、STOP 理由、復旧手順 |
成果物管理
各スキルの成果物は以下のように保存する設計にしました。
artifacts/<JIRA_KEY>/<skill-name>.<N>.md
例えば今回の試作では、以下のような成果物が生成されました。
artifacts/MENUENG-374/explore-spec.1.md
artifacts/MENUENG-374/arch-impact.2.md
artifacts/MENUENG-374/plan-atomic.3.md
artifacts/MENUENG-374/tdd-loop.4.md
artifacts/MENUENG-374/review-sync.5.md
良かった点
1. フェーズ境界が明確になった
explore → plan → implement → review → done
という状態遷移を明文化したことで、AI が勝手に次工程へ進むことを防げました。
特に、
plan → /approve → implement
という流れを必須にしたことで、人間が計画を確認するタイミングを作れました。
2. Decision を実装前に確定できた
plan-atomic では、未決事項を Decision として出力しました。
例：
D1: 並列化の単位
D2: しきい値の配置場所
これにより、
実装しながら何となく決める
のではなく、
実装前に人間が選択する
という形にできました。
後から /approve に Decision 確定ゲートを追加し、未決事項が残っている場合はチャット上で質問して解決する運用も試しました。
3. レビュー結果を成果物として残せた
/review の結果をチャットだけで終わらせず、review-sync の成果物として保存しました。
レビュー成果物には以下を含めました。
- security_check
- rule_proposals
- spec_diff
- code_review
これにより、
- レビュー観点
- 仕様との差分
- 修正要否
を後から追跡できるようになりました。
難しかった点
独自フローは強力だが、オンボーディングコストが高い
一方で、以下のような学習コストも発生します。
- /run
- /approve
- /implement
- /review
の意味を覚える必要がある
さらに、
state.json context.md progress.md
の役割を理解する必要もあります。
また、
- STOP したときの復旧方法
- 他チームとの運用差分
も学ぶ必要があります。
この時点で、
うちのチームだけ別フローを持つことが本当に良いのか
を再検討することになりました。
成果物が増えすぎる
今回の試作では、実行ログを丁寧に残すため、多くの成果物を生成しました。
これはトレーサビリティの面では有効です。
しかし実際の利用者視点では、知りたいことはもっとシンプルです。
1. 仕様を入れる
2. 計画を見る
3. 実装する
4. 検証する
この程度の操作感で済むのであれば、その方が使いやすいと感じました。
最終的に導入しなかった理由
最終的には、独自の店舗チーム向け Slash Command は導入しない判断をしました。
理由はシンプルで、
リポジトリにはすでに cc-sdd（Kiro）の標準フローが存在していた
ためです。
Kiro には以下の標準コマンドがあります。
/kiro/spec-init /
kiro/spec-requirements
/kiro/spec-design
/kiro/spec-tasks
/kiro/spec-impl
/kiro/validate-impl
PM の仕様書を requirements.md に反映し、この標準フローに乗せれば、他チームと同じ進め方ができます。
つまり、店舗チームだけが独自の
/run /approve
を持つ必要はありませんでした。
それでも残った学び
導入しなかったとはいえ、今回の試作には大きな意味がありました。
特に以下の考え方は、今後も活かせると感じています。
- 実装前に Decision を明示する
- レビュー結果をチャットだけで終わらせない
- STOP 時には次の情報を必ず残す
- 理由
- 確認ファイル
- 修正項目
- 次に実行するコマンド
- 暗黙知は独自コマンドではなく Kiro の Steering / Rules に蓄積する
独自コマンドとしては採用しませんでしたが、考え方そのものは Kiro 運用に吸収できます。
まとめ
今回作った「下流工程改善エージェント」は、最終的には導入しませんでした。
しかし試作を通じて、
AI に任せる工程で何を固定すべきか
がかなり明確になりました。
特に重要だったのは、コマンドそのものではなく、以下の考え方です。
- 状態を持つ
- フェーズを分ける
- 人間の承認点を作る
- 判断を実装前に確定する
- チーム横断で同じ運用に寄せる
独自化によって便利になる部分もありますが、チーム全体で使う仕組みでは、
統一性とオンボーディングのしやすさ
も同じくらい重要です。