AI開発の品質をルールで担保する — AWSのKiroステアリングファイル実践ガイド

こんにちは。デジタルイノベーション推進室の戦闘員Oです。
※ ステアリングファイルの基本については Kiroのステアリングファイル入門 で解説しています。
※ 本記事のステアリングと Analyze Requirements を組み合わせると、品質管理がさらに強化されます。
今回は、Kiroの根幹機能であるステアリングファイルを、もう一段深く掘り下げます。

「ルールを書けば便利」という話ではなく、なぜステアリングが必要なのか、プロンプトとは何が違うのか、どこまでできて何ができないのか。その設計判断を語った上で、読者が持ち帰れる実践的な成果物をお渡しします。

Kiroを使い始めた人の多くは、こう思っています：
「全部チャットで指示すればいいでしょ？」

 

正直、自分も最初はそう思っていました。日本語化とフォルダ構成までは割とすぐできたのですが、プロジェクトが進むにつれて、ExcelやWordを毎回テキストファイルに変換してKiroに読ませる手間が増えたり、AIが迎合しすぎた「当たり障りのない結論」を出してきてミーティングで全く使えなかったりしました。
ステアリングに「曖昧な場合は確認を取る」「ユーザーの指示が不明確な場合は推測せず聞き返す」と明記してから、ようやく安定しました。ここにたどり着くまでに1ヶ月以上かかっています。
この記事では、自分が普段使っているステアリングファイル作成用の初期プロンプトを紹介します。

 

破綻のパターン

• 同じ指示を毎回書く — 「日本語で」「OUTPUTフォルダに」「前のファイルはBKUPに」
• 指示を忘れる — 昨日は言ったけど今日は言い忘れた。出力がブレる
• チームで共有できない — 自分の頭の中にあるルールを他のメンバーが知らない
• 品質が属人化する — ベテランが指示すると良い出力、新人だと微妙

これらは全部、暗黙知がプロンプトに閉じ込められているのが原因です。

1. 思想：プロンプト vs ステアリング — 本質的な違い
2. 実践：Before/Afterで見るステアリングの効果
3. 持ち帰り1：01_basic-rules.md（完成品）
4. 持ち帰り2：ソクラテス式ヒアリングプロンプト
5. 持ち帰り3：アンチパターン集
6. Hooksとの組み合わせ
7. まとめ

1-1. プロンプトは「その場の指示」

ユーザー：「AWSインフラの設計書を作って。日本語で。OUTPUTフォルダに置いて」
これは「今この瞬間の指示」です。次の会話では効力がありません。
 

1-2. ステアリングは「組織の暗黙知の形式知化」

ステアリングファイルに書くべきことは、チームの誰もが「当たり前」だと思っているけど、明文化されていないルールです。
例：

• 「うちのチームは成果物をOUTPUTに置く」（暗黙のルール）
• 「古いファイルは消さずにBKUPに残す」（暗黙のルール）
• 「顧客に見せる資料はPowerPointで作る」（暗黙のルール）

これらは人間同士なら「言わなくてもわかる」のですが、AIには言わないとわかりません。

 

1-3. なぜ「プロンプトに毎回書く」ではダメなのか

つまりステアリングファイルは「AIへの指示書」というよりも、チームの暗黙知をコードで管理する仕組みです。

1-4. ステアリングの限界

ステアリングファイルは万能ではありません。
できること：

• Kiroの振る舞いを方向づける
• 一貫したルールを適用する
• チーム内でルールを共有する

できないこと：

• 強制力はない（Kiroが100%従う保証はない）
• セキュリティの完全な担保（ステアリングだけでは不十分）
• 複雑な条件分岐（「もしAならBだがCの場合はD」は苦手）

なので：

• セキュリティ → ステアリング + Hooks + MCP設定の3層で守る
• 品質 → ステアリング + Analyze Requirements + 人間レビューの3層で守る
  • ステアリングは「第1防衛線」であって「唯一の防衛線」ではない

自分の場合、ステアリングファイルを入れる前は成果物とPythonスクリプトが同じフォルダに混在していて、「あのスクリプトどこだっけ？」「これは最新版？古い版？」と探し回る時間が発生していました。KiroToolフォルダを定義してからこの問題は消えています。
以下はシンプルな例ですが、同じ構造の問題がどのプロジェクトでも起きます。

2-1. Before（ステアリングなし）
同じ指示を2回出した場合の出力の違いを見てみます。

1回目の指示：
AWSインフラの要件をまとめて
Kiroの出力：

• 英語混じりの箇条書き
• ファイルはルートディレクトリに直置き
• ファイル名：aws_requirements.md

 

2回目の指示（翌日、別の会話）：
AWSインフラの要件をまとめて
Kiroの出力：

• 全部日本語
• ファイルはdocsフォルダに配置
• ファイル名：AWSインフラ要件定義.md

 

同じ指示なのに出力がブレます。これがプロジェクトで起きると混乱します。

 

2-2. After（ステアリングあり）
01_basic-rules.md を配置した状態で同じ指示を出すと、1回目も2回目も同じ出力になります。

• 日本語で記述
• OUTPUTフォルダに配置
• ファイル名：AWS_インフラ要件定義_20250520.md
• 既存ファイルがあればBKUPに移動

 

誰が、いつ、何回指示しても同じ振る舞いになります。これがステアリングの価値です。

2-3. 効果の定量化

以下をそのまま .kiro/steering/01_basic-rules.md にコピーしてください。これだけで「出力のブレ」と「ファイル散乱」が解消します。

---

inclusion: always

---

# 基本ルール

## コミュニケーション

- すべてのやり取りは日本語で行う

- ユーザーの指示が曖昧な場合は確認を取る

## フォルダ構成

- INPUT/：元資料・参照データ（読み取り専用。変更しない）

- OUTPUT/：最新の成果物のみ配置する

- BKUP/：過去バージョン（タイムスタンプ付きで保管）

- KiroTool/：自動化スクリプト（Python等）

## ファイル管理

- 新しい成果物を作成する際は、OUTPUT内の古いファイルをBKUPへ移動する

- BKUP移動時はファイル名末尾にタイムスタンプを付与する（例：report_20250520.md）

- OUTPUT には常に最新版のみを配置する

## 命名規則

- ファイル名にスペースは使わない（アンダースコアを使用）

- 日付形式はYYYYMMDDで統一

なぜこの内容かを説明します。

• 「日本語」— 指定しないと英語混じりになることがある
• 「フォルダ構成」— 指定しないとファイルが散らばる
• 「BKUP移動」— 指定しないと上書きされて過去版が消える
• 「命名規則」— 指定しないとファイル名がバラバラになる

ソクラテス式とは、答えを直接与えるのではなく、質問を重ねて相手から知識を引き出す対話手法です。Kiroに質問させることで、自分でも気づいていなかったプロジェクトの前提やルールが言語化されます。
01_basic-rules.md だけでは「品質」「セキュリティ」「出力形式」はカバーできません。でも、これらはプロジェクトごとに最適解が異なるので、完成品を配布しても合いません。
そこで、Kiroに質問させて、あなたのプロジェクトに最適化されたステアリングファイルを対話で生成するプロンプトを用意しました。

 

• プロンプト（これをKiroのチャットに貼る）

私のプロジェクトに最適なステアリングファイルを作りたい。

まず前提を確認してから、観点ごとに質問してください。

私の回答をもとに、.kiro/steering/ に配置するステアリングファイルを生成してください。

【まず最初に確認】

- Kiroで何をやりたいか？（以下から選択 or 自由記述）

a. インフラのIaC（CloudFormation/Terraform等）を作りたい

b. 要件定義〜設計の検討資料を作りたい

c. 要件定義〜テストまでフル工程で使いたい

d. ドキュメント作成・整理に使いたい

e. その他（自由記述）

- 開発スタイルは？（ウォーターフォール / アジャイル / 決まっていない）

上記の回答に応じて、以下の観点の質問内容を調整してください。

【質問の観点】

1. 品質管理（以下の4点を順に聞く）：

- 成果物の完了条件は何か？（レビュー済み？テスト通過？顧客承認？）

- どのタイミングでチェックするか？（作成後？コミット前？納品前？）

- AIの出力をそのまま使ってよい範囲と、人間の判断が必要な範囲はどこか？

- 品質基準は何か？（コーディング規約？設計書テンプレート準拠？既存の品質基準書がある？）

2. セキュリティ：扱うデータの機密度、接続先の外部サービス名、送信するデータの種類、認証方式を具体的に聞く。「ある」「ない」で終わらせず、具体名を必ず引き出す

3. 出力形式：成果物を読むのは誰か（開発者？顧客？経営層？）。どの形式（MD/Word/Excel/PowerPoint/PDF/HTML）で納品するか？

既存のテンプレート（設計書、仕様書、報告書等）があれば「テンプレート/」フォルダに置いてもらう。Kiroはそのテンプレートに合わせて出力する

4. ツール連携：Office（Word/Excel/PowerPoint）やPDFの読み書きは必要か？他に自動化したい定型作業はあるか？

【ルール】

- 1つの観点につき2〜3個の質問をしてください

- 私の回答が曖昧な場合は具体例を挙げて深掘りしてください

- 私が質問に答える代わりに、関連資料（ふりかえり資料、障害報告書、セキュリティポリシー等）をINPUTフォルダに置く場合があります。その場合はそこから読み取って判断してください

- すべての情報が揃ってから、ステアリングファイルを生成してください

- 生成するファイルには具体的な判断基準を含めてください（「適切に」「必要に応じて」は禁止）

- 観点ごとに別ファイルとして生成してください（02_quality-gate.md、03_security.md、04_output-format.md、05_tool-config.md）

- 各ファイルは30行以内に収めてください

4-1. 実際の対話例

第5回ではAWSインフラの例を使いましたが、今回はあえて別のシナリオで試しています。ステアリングファイルはインフラに限らず、どんなプロジェクトでも使えるということを示すためです。
このプロンプトを投げると、Kiroはまず前提を確認してきます。

Kiro：
まず前提を確認させてください。
1. Kiroで何をやりたいですか？
   a. インフラのIaC（CloudFormation/Terraform等）を作りたい
   b. 要件定義〜設計の検討資料を作りたい
   c. 要件定義〜テストまでフル工程で使いたい
   d. ドキュメント作成・整理に使いたい
   e. その他
2. 開発スタイルは？（ウォーターフォール / アジャイル / 決まっていない）

 

ユーザー：
1. Javaフレームワーク変換を行いたい。古いSeasar2から新しいSpring Bootに変える
2. ウォーターフォール

• ラウンド1：品質管理

Kiro：
Seasar2 → Spring Bootのフレームワーク移行 + ウォーターフォールですね。品質管理について質問します。
1. 変換後のコードの完了条件は何ですか？（既存テスト全件通過？手動テスト完了？コードレビュー済み？顧客承認？）
2. どのタイミングでチェックしますか？（1クラスごと？機能単位？全量変換後？）
3. AIが生成した変換コードをそのまま使ってよい範囲は？人間の確認が必要な範囲は？
4. 品質基準はありますか？（コーディング規約？SonarQubeルール？レビューチェックリスト？）
関連資料（既存のテスト仕様書、コーディング規約等）があればINPUTフォルダに置いていただければ読み取ります。

ユーザー：
1. UTはJUnitでAI自動テスト実施。結合テストは現新比較テストを行うのでテストケース作成が必要
2. ソースコードを読み込み段階的な変換計画を立てる。段階ごとにUT完了条件を定義しAIで自動実施
3. 基本的に現と新が同じ動作をすることを確認したい。AIで対応できないことがあれば教えてほしい
4. コーディング規約は事前にないのでこれから作る

• ラウンド2：セキュリティ

Kiro：
セキュリティについて質問します。
1. 既存のSeasar2アプリケーションで扱うデータの中で、最も機密度が高いものは何ですか？
2. ソースコードの管理場所はどこですか？MCP連携で外部サービスに接続していますか？具体的なサービス名と送信データを教えてください。
3. 既存コードの中に認証情報（DBパスワード、APIキー等）がハードコードされている箇所はありますか？

ユーザー：
1. ユーザー情報テーブルがある。個人情報に該当
2. SRCフォルダをローカルに用意する。現行はsrc_org、新規はsrcフォルダで管理。外部サービス連携なし
3. 現状は設定ファイルにある。環境変数等に変えられれば提案してほしい

• ラウンド3〜4：出力形式・ツール連携

同様に、出力形式（成果物を誰が読むか、納品形式、テンプレートの有無）とツール連携（Excel自動生成、CI/CD、human-in-the-loop）についてもヒアリングが続きます。

 

• 生成結果

すべての回答が揃うと、Kiroが観点別にステアリングファイルを生成します：

生成される 02_quality-gate.md の例：

---

inclusion: always

---

# 品質管理

## フォルダ構成

- src_org/：現行Seasar2ソースコード（読み取り専用。変更しない）

- src/：変換後Spring Bootソースコード

## 変換プロセス

- ソースコードを読み込み、段階的な変換計画を作成する

- 変換計画書は顧客承認後に開発に着手する

- 段階ごとにUT完了条件を定義し、JUnitで自動実行する

## 完了条件

- Gate 1：JUnit自動テスト全件通過（段階ごと）

- Gate 2：結合テスト（現新比較）通過

- Gate 3：顧客承認

## AI生成物の扱い

- 基本方針：現行と新規が同じ動作をすることを確認する

- AIで対応できない箇所（Seasar2固有のDI挙動、暗黙的な型変換等）は明示的に報告する

- 人間の判断が必要な箇所は問いを出して確認を取る（human-in-the-loop）

## 品質基準

- コーディング規約はプロジェクト開始時に策定する（別途作成）

- 規約策定までは Spring Boot公式のベストプラクティスに準拠する

このように、対話の回答内容がそのまま具体的なルールとしてステアリングファイルに反映されます。「適切に」「必要に応じて」は一切入りません。

 

• 注意：生成されるのは「初版」

このプロンプトで生成されるステアリングファイルは「初版」です。プロジェクトが進むにつれて詳細化が必要になります。
例えば、「テンプレート/」ディレクトリにExcelテンプレートを配置した後：

テンプレート/変換計画書.xlsx の構造を読み取って、05_tool-config.md を詳細化してください。
シートごとの列構成やマッピングルールを追記してください。

とKiroに指示すれば、テンプレートの実際の構造に基づいた具体的なルールに更新されます。
ステアリングファイルは「一度作って終わり」ではなくて、プロジェクトの進行に合わせて育てていくものです。

 

4-2. なぜソクラテス式なのか
完成品を配布しない理由を説明します：

• 「Seasar2固有のDI挙動チェック」はフレームワーク移行でなければ不要
• 「現新比較テスト」はレガシー移行でなければ不要
• 「src_org / src のフォルダ分離」も移行プロジェクト固有の構成
• 汎用的に書くと抽象的になって、効果が薄れる

 

対話で生成する利点：

• あなたの「過去の痛み」に基づくので、的確なルールになる
• 具体的な判断基準が入る（「適切に」ではなく「SecurityGroupとIAMPolicyは人間確認」）
• プロジェクトの文脈を反映できる（フレームワーク移行なのかIaCなのかで質問が変わる）

 

4-3. うまくいかないケースと対処

• 失敗パターン1：質問が抽象的すぎる

Kiroが「品質管理で重要なことは何ですか？」のような漠然とした質問をしてきた場合：
もっと具体的に聞いてください。
「過去に実際に起きた問題」と「その原因」を聞いてください。

 

• 失敗パターン2：生成されたルールが「お気持ち」レベル

生成結果に「適切に確認する」「必要に応じてチェックする」が含まれていた場合：
「適切に」「必要に応じて」を具体的な条件に書き換えてください。
例：「RDSの可用性設定を変更した場合は、コスト試算を再実行する」

 

• 失敗パターン3：ルールが多すぎる

20個以上のルールが生成された場合：
ルールを重要度順に並べて、上位5つだけ残してください。
残りは別ファイル（inclusion: manual）にしてください。

ステアリングファイルに書いてはいけないことを知っておくと、無駄なルールを避けられます。

 

書いても効果がないもの

書くと逆効果なもの

良いステアリングの特徴

• 具体的な判断基準がある（「〜の場合は〜する」）
• 短い（1ファイル30行以内が目安）
• 検証可能（ルールに従っているか第三者が確認できる）
• 理由が書いてある（なぜこのルールが必要か）

ステアリングは「第1防衛線」です。Hooksを加えると「自動化された第2防衛線」になります。

ステアリングとHooksの役割分担

ステアリング（常時適用）
  → Kiroが常にルールを意識して作業する

 

Hook（トリガーで発動）
  → 特定のタイミングで追加チェックを自動実行する

Hook生成プロンプト（コピー＆ペーストで利用可能）

以下のHookを作成してください：

- requirements.mdが保存されたら、ステアリングファイルの品質ゲートに従って

矛盾・曖昧さがないか自動チェックする

- 問題があればチャットで報告する

ステアリングだけでは守れないもの

ステアリングだけでは守れないもの

今回の要点

1. ステアリングは「暗黙知の形式知化」 — プロンプトとは根っこから違う
2. 限界を知る — ステアリングだけでは守れないものがある。Hooks/MCP設定と3層で守る
3. 具体的に書く — 「適切に」「必要に応じて」は書いても意味がない
4. 最小から始める — 01_basic-rules.md だけで十分効果がある

 

なぜこの設計にしたのか

持ち帰りチェックリスト

• [ ] 01_basic-rules.md をプロジェクトにコピーする（5分）
• [ ] 1週間使ってみて、出力のブレが減ったか確認する
• [ ] ソクラテス式プロンプトで、プロジェクト固有のルールを生成する（15分）
• [ ] Hookを1つ設定して、自動チェックを体験する（5分）

 

関連記事

ステアリングファイルの基本的な書き方やKiro Powerとの連携については、上記の記事で解説しています。

• Kiro Specsの新機能「Analyze Requirements」でAWSインフラ要件の矛盾を見つけよう
• Kiroのステアリングファイル入門：ブログ執筆を効率化する対話型ルール作成
• KiroPower：ステアリングファイルとの違いを理解する（IaC検証Powerの実装）
• 実践編：ステアリングファイルとKiro Powerで実現するIaC品質管理
• AWS KiroでJavaアプリを作ってみた

 

参考リンク

• Kiro公式サイト
• Kiroドキュメント - Steering
• Kiroドキュメント - Hooks
• Kiroドキュメント - Analyze Requirements