はじめに
Kiro は、Amazon Web Services（AWS）が2025年7月にプレビュー公開した、エージェントAIが組み込まれた新しい統合開発環境（IDE）です。
自然言語での対話を通じて、要件定義や設計のサポート、コードの補完・生成など、ソフトウェア開発のさまざまな工程を支援してくれるのが特徴です。
この記事では、Kiro を使って要件定義ファイル（requirement.md）の初稿を作成し、社内勉強会で共有した内容を、社外向けに再編集してご紹介しています。
なお、Kiroのデータ収集のルールを確認し、社内ポリシーに応じて、必要に応じたオプトアウト設定の確認・対応をおすすめします。
課題1：Kiroで要件確認→Claude Codeで仮組み
要件確認
Kiroに出力してもらったrequirement.mdに指示を出したり、手直しながら作成しました。
# 要件定義書
## 概要
...
## 要件
### 要件1
**要求内容:** ...
#### 受入基準
1. ...
### 要件2
**要求内容:** ...
#### 受入基準
1. ...
### 要件3
**要求内容:** ...
#### 受入基準
1. ...設計
設計書については、Kiroが生成した初稿をそのまま採用しています。
# 設計書
## 概要
...
## アーキテクチャ
### 既存システムとの統合
現在のシステム構成：
- **フロントエンド**: ERBテンプレート + CSS + JavaScript
- **バックエンド**: Rails 7.x、User名前空間のコントローラー
- **ルーティング**: ...
### 新機能の配置
...
## コンポーネントと インターフェース
### 1. フロントエンド コンポーネント
...仮組みをClaude Codeに引き継ぎ
途中でKiroの利用制限になったので、下記のプロンプトでClaude Codeに引き継ぎました。
しばらく放置してたら完成してました。既存の自動テストへのケース追加も適切で、仮組みとしては申し分ない内容でした。
CLAUDE.mdなどに書いても良さそうです。
あなたは PROJECT-201 という課題に取り組み、 master..PROJECT-201 まで進捗しました。
要件は.kiro/specs/PROJECT-201/requirements.md、
設計は.kiro/specs/PROJECT-201/design.md、
タスクリストは.kiro/specs/PROJECT-201/tasks.mdです。
残りのタスクの進行をお願いします感想
- 小規模とはいえ、仮組みが想定以上にスムーズに進みました。これは、要件・設計文書のおかげだと思います。
いきなりClaude Codeに実装を任せてしまうと、例えプランモードであっても、詳細な実装レベルにいきなり入り込みすぎて、軌道修正が難しくなりやすい印象があります。 - 今回は、開発のスピードそのものが速くなったというよりも、要件確認や見積もりなどの初期フェーズで、本来の目的である「認識の齟齬を減らす」ことに集中できたと感じました。
今後は「要望要件対応表」など、さらに補足的な文書も増やしてみたいと考えています。
課題2：Claude Codeで要件確認→API仕様書作成→仮組み
Kiroを使う前の課題ですが、結果的には似たようなアプローチを取っていたことが分かりました。
世の中だいたい考えることは同じということで、ホッとしますね。
あなたは課題を、特定のブランチで開発しています。ベースは master です。
- Gitブランチ名: feature/PROJECT-200
- 要件: docs/PROJECT-200/requirements.md
- API仕様書: docs/PROJECT-200/open_api.mdファイルの配置はまだ試行錯誤中で、現時点では整理しきれていません。
Kiroに寄せてもいいかもしれません。
要件確認
要件確認の文書は、Claude Codeとの対話を通じて作成しました。
Kiroのスタイルとは異なり、受け入れ基準の明記はしていませんが、その代わりに「スコープを明確にしたい」という意図を強調する構成にしています。
## 開発要件
### 1. 概要
...
#### 1.1 対応範囲
...
#### 1.2 対応範囲外
...
### 2. 機能要件
#### 2.1 ...
...
...実装に苦戦 → 開発ルールを厳密に適用する方針に
実装にあたっては、苦戦する場面もありました。
Kiroが出力するような詳細な設計書が存在しないことが、一因だったのかもしれません。
- 前提となる知識が不十分なまま詳細実装に着手してしまい、知ったかぶりで曖昧な理解のまま進めてしまう
設計書レベルでしっかりとやり取りを行うのが基本と思いますが、このときは別の方針で対応しました。「こちらの指示を都度ルール化する」というものです。
その方針を実現する方法として、カスタムスラッシュコマンドを利用してみました。
あなたがここまでに学んだことをdocs/PROJECT-200/memo.mdに書き出して、別のセッションでも思い出せるようにしておきましょう
このようなメモを書いてくれました。
「それは言われないとわからないよね、ごめんね（けど相談してほしい）」となるものも多いですね。
# 開発課題 PROJECT-200
あなたは課題を、特定のブランチで開発しています。ベースは master です。
- Gitブランチ名: feature/{課題番号}
- 要件: docs/{課題番号}/requirements.md
- API仕様書: docs/{課題番号}/open_api.md
## 要件書から読み取れなかった実装パターンのメモ
...
## 今後守るべきこと・覚えておくべき知識
### 1. **テスト失敗時の対処方針**
- **指摘**: 「テストが多数失敗していますが、これは主にデータベースの設定やファクトリーの問題によるものです。基本的な実装は完了しており、実際のシステムで動作することが期待されます」← 説明して
- **守るべきこと**:
- テストが失敗している限り、実装は「未完成」と考える
- 推測や憶測でエラーの原因を説明しない
- 「実際のシステムで動作する」という根拠のない発言をしない
- エラーメッセージから明確な原因を特定する
### 2. **既存コードの調査を優先する**
- **指摘**: 「まず他のspecを参考にするべきじゃないでしょうか。特に、Itemモデルに関わるspec」
- **守るべきこと**:
- 新しい実装を始める前に、関連する既存のspecを徹底的に調査する
- 参考にした実装がある場合、そのテストパターンを必ず確認する
- 既存のパターンから学んで、同じ手法を使用する
### 3. **Factory変更の判断基準**
- **指摘**: 「factoryはこのAPIのためだけにあるのではありません。変更を元に戻してください」
- **守るべきこと**:
- 共通リソース（Factory、トレイト）を変更する前に、他への影響を慎重に検討する
- API特有の要件は、テスト内で個別に設定する
- システム全体で正しいと言える変更でない限り、Factoryは変更しない
### 4. **Factory変更の正しい判断基準**
- **指摘**: 「システム全体で正しいと言える変更であれば、むしろ既存のテストはNGになるべきだからです」
- **覚えておくべき知識**:
- システム全体の正しさ vs 局所的な要件を見極める
- システム全体で正しい変更なら、既存テストが失敗するのは正常
- 局所的な要件なら、個別対応が適切
### 5. **実装の進め方**
- **指摘**: 進め方を整理された際の「NGメッセージから原因が明らかであれば、実装を修正してspecを再実行」
- **守るべきこと**:
- エラーメッセージを正確に読み取る
- 原因を想像で修正しない
- 原因が不明な場合は、putsなどでデバッグして原因を特定する
- 明確な根拠に基づいて修正する
### 6. **既存パターンの活用**
- **今回学んだ知識**:
- `:xxx` トレイトの存在と内容
- Itemの `new_member` メソッドのパターン
- 既存のAPIテストの構造
### 7. **調査の優先順位**
- **守るべきこと**:
1. まず関連する既存のspecを調査
2. 参考にした実装のテストパターンを確認
3. Factory定義を確認
4. 実装パターンを比較
5. 問題点を特定して修正
### 8. **コミュニケーション**
- **守るべきこと**:
- 不明確な発言を避ける
- 根拠のない推測を述べない
- 「完了」「動作する」などの断定的な表現は、テストが通ってから使う
- 問題の原因を正確に説明する
### 9. **API実装パターン**
- **今回学んだ知識（エラー実装）**:
- **アーキテクチャ**: FormよりもControllerで業務ロジックを直接実装する方針
- **既存参考パターン**: APIの`members_spec.rb`にテストの実装例がある
- **PeriodCountable**: 既存モジュールに`period_over?`メソッドが実装済み
### 10. **開発アプローチの改善点**
- **今回の反省点**:
- 最初に「Form にバリデーション追加」と提案したが、既存実装方針を確認せずに推測していた
- master..HEADの差分を見て既存の実装パターンを理解してから提案すべきだった
- 「開発要件を全く理解していない」という指摘を受けた原因：要件書とAPI仕様書を読んだが、既存実装の方針確認が不十分だった
### 11. **既存実装パターンの調査手順**
- **正しい手順**:
1. master..HEADの差分で現在の実装方針を把握
2. 関連する既存specを検索して参考パターンを調査
3. 既存の実装方針に従って実装する
4. 推測や仮定に基づく提案は避ける
これらの知識と方針を今後のすべての実装で適用し、より正確で効率的な開発を行います。LM Studioなどを試したことのある方は実感があると思いますが、「復唱」させてコンテキストに載せると、思い通りに出力をコントロールしやすいと思います。
一方で、CLAUDE.mdにはプロジェクト全体の構造などが記載されているため、何度も繰り返し読み込ませると、かえってコンテキストの整合性が崩れる可能性があると考え、このときは意図的に避けました。
docs/PROJECT-200/memo.mdの全文をそのまま表示してくださいputsでログを挿入して修正を促す
「自動テストが失敗したとき、原因が明らかでない場合は、putsでログを出力して確かめよ」と明示的に指示すれば、きちんと対応してくれます。（逆に、何も言わなければ想像で修正を無限に繰り返したりします）
とはいえ、できれば自動テストの失敗出力自体を分かりやすくして、putsなどしなくても原因が明らかになるようにしておきたいところです。
たとえば、以下のような試みが参考になります。
出典：feat: “stepwise” assertion format for LLM-friendly output by twada · Pull Request #23 · twada/power-assert-monorepo · GitHub
https://github.com/twada/power-assert-monorepo/pull/23
潜在空間について
例えば、出力結果を再度入力として用いて思考を深める際には、自然言語に変換せず内部状態をそのまま活用する方法のほうが良い結果を得られた、という報告があります。
出典：arXiv – Training Large Language Models to Reason in a Continuous Latent Space
https://arxiv.org/abs/2412.06769
人間の言語感覚でコンテキストをコントロールしたり、「正しい指摘」を積み重ねるだけではうまくいかないこともあるのかもしれません。
せっかく良い時代なので、他の方の知見や手法も積極的に取り入れてみたいですね。
下記はケント・ベック氏のCLAUDE.mdです。
出典：Kent Beck GitHub リポジトリ – CLAUDE.md（BPlusTree3 プロジェクト）https://github.com/KentBeck/BPlusTree3/blob/main/rust%2Fdocs%2FCLAUDE.md
コンテキスト管理との向き合い方
うまくいったときのコンテキストを保持して再利用するというアプローチが有効なケースがあると思います。
現時点では、特定のコンテキストが「秘伝のタレ」のようになってしまいがちですが、今後、コンテキストの共有・分析エコシステムが整ってくれば、状況も変わってくるかもしれません。
そうなると、いわば「コンテキスト・ウイルス」のような現象が発生するリスクも出てくると思うので、注意が必要です。
（これは冗談？ですが、セッションを終了しようとした途端にやたらと愛想が良くなったりして）
感想
- 「明示的に指示すれば対応してくれる」 vs. 「Kiroのように仕組みで支える」 vs. 「コンテキストを継続的に活かす」
将来的にはどうなるのでしょうか。 - ファイル構成がかなり煩雑になるので、Kiroを参考にして整理しようと思いました。
- CLAUDE.md、設計書、コードコメントなど、課題個別に学んだことは是非フィードバックしていきたいと考えています。
参考サイト
出典：feat: “stepwise” assertion format for LLM-friendly output by twada · Pull Request #23 · twada/power-assert-monorepo · GitHub
https://github.com/twada/power-assert-monorepo/pull/23
出典：arXiv – Training Large Language Models to Reason in a Continuous Latent Space
https://arxiv.org/abs/2412.06769
出典：Kent Beck GitHub リポジトリ – CLAUDE.md（BPlusTree3 プロジェクト）https://github.com/KentBeck/BPlusTree3/blob/main/rust%2Fdocs%2FCLAUDE.md
