【Kiro】OCI未経験の私が、2ヶ月で設計書20本を書ききるまで

はじめに

AIエージェントに設計を丸投げするのではなく、「人間が設計判断を下し、AIをドキュメント生成エンジンとして完璧に制御する」。OCI未経験の私が、KiroのSteering機能を駆使して2ヶ月で20本の設計書を書き切った具体的なワークフローと失敗談を全公開します。

某業界向けの業務システム基盤をOCI（Oracle Cloud Infrastructure）上に構築するプロジェクトに、インフラ担当として参画しました。コンペを経て受注を獲得し、非機能要件定義（1ヶ月）と基本設計（1ヶ月）を1名体制で完遂しています。

こんな人におすすめ：

• 一人で膨大なドキュメント作成に追われているインフラエンジニア
• AIエージェントを導入したが、出力の制御に苦労している人
• クラウド設計ドキュメントをMarkdownでスマートに管理したい人

プロジェクト概要

項目	内容
基盤	OCI（Oracle Cloud Infrastructure）
主要サービス	OKE, Autonomous Database, OCI Queue, FLB/NLB, WAF, Object Storage 等
成果物	非機能要件定義書 1本 + 基本設計書 19本
体制	インフラ担当 1名（OCI未経験）
期間	要件定義 1ヶ月 + 基本設計 1ヶ月

基本設計書の一覧はこんな感じです：

01_はじめに / 02_命名規則 / 03_システム全体設計 / 04_性能・拡張設計
05_可用性設計 / 06_災害対策設計 / 07_セキュリティ設計 / 08_ネットワーク設計
09_コンテナ基盤（OKE）設計 / 10_ストレージ設計 / 11_データベース設計
12_バックアップ・リストア設計 / 13_ログ管理設計 / 14_監視設計 / 15_運用設計 / 16_名前解決設計
17_外部システム連携 / 18_環境設計 / 19_CI_CD設計

Kiroの活用ポイント

1. Steering：案件コンテキストの自動注入

Kiroには「Steering」という機能があり、.kiro/steering/ 配下にMarkdownファイルを置くことで、チャットにコンテキストを自動注入できます。フロントマターの inclusion で適用条件を制御できます。

3つの適用モード：

モード	説明	使いどころ
always	すべての会話に常時適用	プロジェクト共通ルール、用語集
fileMatch	特定ファイルパターンにマッチしたときだけ適用	ディレクトリ別の設計ルール
manual	ユーザーが # で明示的に指定したときだけ適用	参照頻度の低いガイドライン

fileMatchの例（基本設計ルール）：

design-rules.md

---
inclusion: fileMatch
fileMatchPattern: "design/**"
---
# 基本設計ルール

## 記述スタイル
- Markdown形式、表形式で記述、項番（No）を付与
- OCI公式用語に準拠

## QA管理
- design/QA/ ディレクトリ配下にて管理
- Markdownドキュメント内に直接質問を埋め込まない（※要協議などのマーカーは使用禁止）

## 修正プロセス
- 修正前に方針を提示し、承認を得てから実行
...

この設定により、design/ 配下のファイルをKiroが読み込んだときだけルールが適用されます。要件定義書を触っているときには基本設計ルールは読み込まれず、コンテキストを節約できます。

alwaysの例（OCI MCP連携）：

common.md

---
inclusion: always
---
# 共通ルール

- OCI公式用語に準拠する
- OCIサービスの仕様・制約を確認する際は、OCI Documentation MCP Serverを使用して公式ドキュメントを参照すること
- 質問・未決事項はMarkdownに直接埋め込まず、各ディレクトリのQAフォルダで管理する
- ファイル編集時は差分が確認できるツールを使用する（sed等は禁止）

KiroはMCP（Model Context Protocol）経由でOCI公式ドキュメントを直接検索・参照できます。Steeringに「MCPを使え」と書いておくことで、設計書作成時にKiroが自発的にOCIドキュメントを確認し、仕様に基づいた設計値を提案してくれます。「OKEのNode数上限は？」「ADBの自動スケーリングの倍率は？」といった確認を、人間がドキュメントを探す代わりにKiroが即座に解決してくれるのは大きな時短でした。

ポイントは、ルールの量に応じて適用モードを使い分けることです。軽量な共通ルールは always、重い詳細ルールは fileMatch で必要なときだけ読み込む。これでコンテキストの圧迫を防ぎつつ、必要な場面では確実にルールが適用されます。

2. Steeringに書くべきルールの具体例

fileMatchで適用するルールには、具体的に何を書くべきか。実際に効果が大きかったルールを紹介します。

基本設計用Steering（fileMatch: design/**）に書いたルール

design-rules.md

---
inclusion: fileMatch
fileMatchPattern: "design/**"
---
# 基本設計ルール

## 記述スタイルの統一
- H1: ドキュメントタイトル / H2: 大項目（章）/ H3: 中項目（節）
- 設計項目は表形式で記述。項番（No）を付与し、一意に参照可能にする
- OCI公式用語に準拠（×アベイラビリティドメイン → ○Availability Domain）

## 質問・未決事項の管理
- design/QA/ ディレクトリ配下にて管理
- QAは設計書ごとに1ファイル（例: データベース設計_QA.md）
- Markdownドキュメント内に直接質問を埋め込まない（※要協議などのマーカーは使用禁止）

## トレーサビリティの確保
- 設計項目には対応する要件定義の項番を明記

## 修正プロセス
- 修正を実行する前に修正方針を提示し、ユーザーの承認を得てから修正を開始

## 準拠ガイドライン
- 設計レビュー観点はOCI Well-Architected Frameworkに準拠する
- 設計プロセス・成果物の構成はIPA「システム構築の上流工程強化」を参考にする
- セキュリティ設計の観点はIPA「つながる世界のセーフティ＆セキュリティ設計入門」を参考にする

## ビルドパイプライン
- 設計書テンプレートは design/src/*.md を編集する
- design/ 直下の生成済みファイルを直接編集しない（_build.py で上書きされる）
- テンプレートにCSSを記述しない（_styles.css から自動挿入される）

基本設計ではIPA非機能要求グレードよりも、OCI Well-Architected Frameworkの方が実効性が高いです。クラウド固有の設計原則（可用性、セキュリティ、コスト最適化等）に沿ってKiroがレビュー観点を提示してくれるので、設計書のセルフレビューが捗りました。IPAのガイドラインは設計プロセスの骨格として参考にしつつ、具体的な設計判断はOCI WAFに寄せる形です。

非機能要件定義用Steering（fileMatch: requirements/**）に書いたルール

nfr-rules.md

---
inclusion: fileMatch
fileMatchPattern: "requirements/**"
---
# 非機能要件定義ルール

- Markdown形式、表形式で記述、項番（No）を付与
- OCI公式用語に準拠
- 質問事項は requirements/QA/ 配下で管理（Markdown内に埋め込まない）
- 非機能要件の分類・網羅性はIPA「非機能要求グレード」に準拠する
  - 大項目: 可用性、性能・拡張性、運用・保守性、移行性、セキュリティ、システム環境・エコロジー
  - 各項目の設計レベル（段階）を意識し、プロジェクトの要求水準に応じて選定する

両方のSteeringを通じて、特に効いたルールは以下の4つです：

• IPAガイドラインの準拠: 非機能要件定義ではIPA「非機能要求グレード」の6大項目をルールに書いておくだけで、Kiroが抜け漏れを指摘してくれます。基本設計ではIPA「システム構築の上流工程強化」とOCI Well-Architected Frameworkを組み合わせ、設計プロセスとレビュー観点の両方をカバーしました
• QA管理の分離: 「※要協議」のようなマーカーをドキュメント内に埋め込まないルール。これがないとKiroが設計書内に質問を書き始めてしまい、納品物としてのクリーンさが損なわれます
• 修正の事前承認: Kiroが勝手に設計値を変更しないよう、修正前に方針提示を義務付けました。AIに任せきりにしない仕組みです
• 用語統一: OCI公式用語への準拠を明記することで、「コンパートメント」と「Compartment」が混在する問題を防止

3. 変数展開による手戻り防止

複数の設計書にまたがって登場する値（今回はリソース命名規則）を変数として一元管理し、ビルドスクリプトで展開する仕組みを作りました。変更が入りそうな箇所を変数にしておくことで、修正時に全ファイルを手作業で直す手戻りを防げます。

src/*.md（テンプレート：{{変数名}} で参照）
  + _variables.yaml（変数定義）
  + _styles.css（共通スタイル）
  ↓ python _build.py
design/*.md（変数展開済み + CSS挿入済み）

Kiroにはこのビルドパイプラインの存在をルールで教えてあるので、「design/ 直下の生成済みファイルを直接編集しないでください」「テンプレートにCSSを記述しないでください」といった制約も守ってくれます。

4. 設計根拠（rationale）の蓄積

設計書を順番に作成していく中で、「まだ設計書は書かないけど、今の議論で決まった方針は記録しておきたい」という場面が頻繁にありました。

そこで design/rationale/ ディレクトリを設け、トピックごとに設計判断の根拠を蓄積するルールを作りました：

design/rationale/
├── OKE_CNI選定.md          # VCN-Native Pod Networking採用の根拠
├── OKE_Node_Pool構成.md    # 5 Node Pool分割の根拠
├── OKE_デプロイ方式.md     # デプロイ方式採用の根拠
├── Webサーバ選定.md        # Nginx採用の根拠
├── ADB_ストレージ容量.md   # ストレージ容量選定の根拠
└── ...

各ファイルは「背景・課題 → 検討した選択肢 → 採用した方針 → 関連する設計書」の構造で統一。設計書作成時にKiroが自動的にrationaleを参照し、設計書に反映してくれます。

5. PDF出力の自動化

設計書はMarkdownで書き、PDF化して納品します。PDF出力時のスタイルも一元管理しています：

共通CSS（_styles.css）：

_styles.css

/* H2（章）で自動改ページ */
h2 {
  page-break-before: always;
}

/* テーブルのスタイル統一 */
table {
  border-collapse: collapse;
  width: 100%;
  font-size: 9pt;
}

th {
  background-color: #f0f8ff;
}

ヘッダー・フッター設定もルールに記録：

<!-- Header -->
<div style="font-size: 9px; ...">
  <span>基本設計書（インフラ構成定義書）</span>
  <span>XXXXX 開発</span>
</div>

<!-- Footer -->
<div style="font-size: 9px; ...">
  <span>&copy; XXXXX, Inc.</span>
  <span>Page <span class="pageNumber"></span> / <span class="totalPages"></span></span>
</div>

これらの設定値もSteeringに記録しておくことで、新しい設計書を作成する際にKiroが自動的に同じフォーマットを適用してくれます。

実際のワークフロー

設計書作成の流れ

1. Kiroに設計書の作成を依頼
   → ルール・テンプレート・rationaleを自動参照

2. Kiroが src/*.md にテンプレートベースで下書きを生成

3. 内容をレビューし、修正を指示
   → Kiroは修正方針を提示してから実行（ルールで義務付け）

4. 疑問点が出たらQAディレクトリに記録
   → 設計書本体には埋め込まない

5. python _build.py で変数展開 + CSS挿入

6. PDF出力して最終確認

プロンプト例

設計書の新規作成時：

08_ネットワーク設計を作成してください。
要件定義書の7章（ネットワーク）と1章（システム構成）を参照してください。
rationaleディレクトリに関連する根拠があれば反映してください。

既存設計書の修正時：

03_システム全体設計のコンポーネント一覧にOCI Queueが抜けています。
命名規則（02）を参照して追加してください。

Kiroは修正前に「こう直しますがよいですか？」と確認してくれるので、意図しない変更が入りません。

Markdownで設計書を管理するメリット

要件定義書と基本設計書をすべてMarkdownで作成し、Kiroのワークスペース内に置いたことで、設計書の「作成」だけでなく「活用」の幅が大きく広がりました。

設計書がテキストファイルとしてAIの管理下にあるので、設計内容についてすぐに質問できます。「この環境で使うOCIリソースの一覧を作って」と頼めば、全設計書を横断して機器一覧を生成してくれます。「本番環境のOCI利用料金を試算して」と言えば、設計書から構成情報を読み取ってコスト計算してくれます。

ExcelやWordで設計書を管理していたら、こうはいきません。AIが中身を読めない、あるいは読めても構造化されていないので、横断的な情報抽出が困難です。Markdownという構造化されたテキストで管理しているからこそ、設計書が「書いて終わり」ではなく「問い合わせ可能なナレッジベース」として機能します。

実際にプロジェクトで活用した例：

• 全設計書からOCIリソースを抽出して機器一覧を自動生成
• 設計値をもとにOCI利用料金の月額試算を作成
• 「この構成でDR切り替え時に影響を受けるコンポーネントは？」といった横断的な質問への即答
• 設計書間の整合性チェック（命名規則の統一、参照先の存在確認等）

設計書をMarkdownで書くこと自体は目新しくありませんが、AIエージェントと組み合わせることで、設計書が「生きたドキュメント」になるのは想定以上の効果でした。

失敗談・苦労した点

1. 用語のブレ

初期はルールが甘く、Kiroが「アベイラビリティドメイン」と「Availability Domain」を混在させることがありました。OCI公式用語への準拠をルールに明記してからは解消。

2. sed禁止の経緯

Kiroがファイル編集に sed コマンドを使うことがあり、変更内容の追跡が困難になりました。「差分が確認できるツールを使用する」「sed等は禁止」と明記して解決。

3. QAの混入

設計書内に「※要確認」「※要協議」といったマーカーが混入したことがあります。QA管理をディレクトリ分離するルールを追加して防止。

4. 設計値の勝手な変更

Kiroが「こっちの方が良さそう」と判断して設計値を変更してしまうケースがありました。修正前の事前承認ルールを追加して、人間が最終判断する仕組みにしました。

5. コンテキストの消失

長い会話を続けるとKiroのコンテキストが溢れ、過去の議論内容を忘れることがあります。重要な決定事項はrationaleやQAに記録し、会話に依存しない設計にすることで対処しました。

ディレクトリ構成（最終形）

project/
├── .kiro/
│   └── steering/
│       ├── common.md               # 共通ルール（always: OCI用語、MCP連携、sed禁止等）
│       ├── design-rules.md         # 基本設計ルール（fileMatch: design/**）
│       └── nfr-rules.md            # 非機能要件定義ルール（fileMatch: requirements/**）
├── requirements/
│   ├── 非機能要件定義書.md
│   └── QA/                         # 要件定義のQA管理
├── design/
│   ├── src/                        # テンプレート（編集対象）
│   │   ├── _template.md            # 設計書テンプレート
│   │   ├── _styles.css             # 共通CSS
│   │   ├── 01_はじめに.md
│   │   ├── 02_命名規則.md
│   │   └── ...
│   ├── _variables.yaml             # 変数定義（命名規則の一元管理）
│   ├── _build.py                   # ビルドスクリプト
│   ├── QA/                         # 設計のQA管理
│   ├── rationale/                  # 設計根拠の蓄積
│   ├── 01_はじめに.md              # ← ビルド生成物（直接編集禁止）
│   └── ...
└── memo/                           # 議事録・検討メモ

まとめ

Kiroを活用する上で最も重要だったのは、「AIに何を守らせるか」を明文化することです。

• Steeringの fileMatch / always で案件固有のルールを必要な場面だけ注入
• IPAガイドライン・OCI Well-Architected Frameworkへの準拠をルール化し、網羅性とレビュー品質を担保
• 変数展開で命名規則の一貫性を自動担保
• QA管理の分離で納品物のクリーンさを維持
• 修正の事前承認で人間が最終判断を保持
• rationaleで設計判断の根拠を蓄積・再利用
• Markdownで設計書を管理することで、機器一覧の自動生成やコスト試算など「書いた後の活用」も実現

AIエージェントは「賢いけど、ルールを教えないと好き勝手やる」存在です。逆に言えば、ルールさえ整備すれば驚くほど正確に、大量のドキュメントを一貫したフォーマットで生成してくれます。

1人で2ヶ月という期間は、正直AIなしでは不可能でした。ただし、AIに丸投げしたわけではなく、「人間が設計判断し、AIが文書化する」という役割分担が機能した結果です。