Kiro SpecモードとCLIインストール・活用ガイド

Contents

1 1. Spec モードの概要とメリット
- 1.1 1‑1. パフォーマンス目標の根拠
2 2. Kiro CLI のインストールとプロジェクト初期化
- 2.1 2‑1. 推奨インストール手順（2026 年時点）
- 2.2 2‑2. プロジェクト雛形の作成
3 3. 要件・設計・タスクファイルの作成フロー
4 4. Steering と Hooks の活用ガイド
- 4.1 4‑1. 正式な YAML キー（公式ドキュメント参照）[^2]
- 4.2 4‑2. カスタム Hook の実装例（Node.js）
5 5. 生成コードのレビュー・テスト・デプロイ（IaC 連携）
6 6. ベストプラクティス集
7 7. FAQ（よくある質問）
8 8. まとめ
- 8.1 参考文献

スポンサードリンク

1. Spec モードの概要とメリット

項目	内容
目的	自然言語で書いた要件 → 設計 → タスクの 3 段階を AI が自動的に分解し、コード生成までを一貫して行うこと。
主な効果	- 要件抜け漏れの低減 - ドキュメントと実装の同期がリアルタイムで保たれる - チーム全体で同じ認識を共有できる
参考情報	Qiita 記事「Kiro で仕様駆動開発のコツを探ってみる」[^1]

ポイント
Spec モードは 「要件 → 設計 → タスク」 の流れを AI が解釈し、生成コードが要件に対して収束することを保証します。

1‑1. パフォーマンス目標の根拠

requirements.md に記載した 「500 ms 以下の応答時間」 は、以下の調査結果に基づく一般的な UI の期待値です。

Google が実施したユーザー体験調査で、ページ遷移や検索結果表示は 400–500 ms 以内が快適と判定された[^6]。
本プロジェクトではバックエンド API の 95 パーセンタイル応答時間を < 450 ms に抑えることを目標にしています（FastAPI + PostgreSQL のベンチマーク結果参照）。

2. Kiro CLI のインストールとプロジェクト初期化

2‑1. 推奨インストール手順（2026 年時点）

OS	コマンド例
macOS / Linux	`bash<br># Homebrew がインストール済みの場合<br>brew install kiro-cli<br>`
Windows (PowerShell 7+ )	`powershell<br# 最新の公式スクリプトを取得し実行<br>$url = 'https://kiro.dev/install.ps1'; Invoke-WebRequest -Uri $url -OutFile $env:TEMP\install.ps1; & $env:TEMP\install.ps1;<br>`

-UseBasicParsing は PowerShell 5.1 以前でのみ必要となり、PowerShell 7 系では非推奨です。

2‑2. プロジェクト雛形の作成

# 任意のディレクトリへ移動
cd ~/projects

# プロジェクト名を指定して初期化
kiro init my-awesome-app

# 作成された構造を確認（tree がインストールされていない場合は dir /s /b でも可）
tree my-awesome-app

# 任意のディレクトリへ移動

cd ~/projects

# プロジェクト名を指定して初期化

kiro init my-awesome-app

# 作成された構造を確認（tree がインストールされていない場合は dir /s /b でも可）

tree my-awesome-app

生成される主なファイル・ディレクトリ：

requirements.md、design.md、tasks.md（空テンプレート）
.kiro/steering.yml（プロジェクト固有設定）

ポイント
1 行のコマンドで環境構築が完了し、その後はドキュメントを書き進めるだけで AI が自動的にコード生成を行える状態になります。

3. 要件・設計・タスクファイルの作成フロー

3‑1. `requirements.md` の書き方例

# 要件定義 (requirements)

## ユーザーストーリー 1: 商品検索
- キーワード入力で商品リストをリアルタイムに絞り込む  
- 検索結果はページネーションで表示  
- **パフォーマンス目標**：500 ms 以下の応答時間（Google ユーザー体験調査参照）

## 非機能要件
- CI/CD パイプラインに組み込み可能なテストコード生成
- Terraform でインフラ構築を自動化

# 要件定義 (requirements)

## ユーザーストーリー 1: 商品検索

- キーワード入力で商品リストをリアルタイムに絞り込む

- 検索結果はページネーションで表示

- **パフォーマンス目標**：500 ms 以下の応答時間（Google ユーザー体験調査参照）

## 非機能要件

- CI/CD パイプラインに組み込み可能なテストコード生成

- Terraform でインフラ構築を自動化

根拠：パフォーマンス目標は前述の Google 調査[^6] を参照。

3‑2. `design.md` の構造例

# 設計書 (design)

## アーキテクチャ概要
- フロントエンド: React + TypeScript（Vite 4 使用）
- バックエンド: FastAPI (Python 3.11)
- データベース: PostgreSQL（RDS）＋ Terraform 管理

## コンポーネント分割
| コンポーネント | 責務 |
|---|---|
| SearchBar      | 入力受付・デバウンス処理 |
| ProductList    | API 呼び出し結果の表示 |
| Pagination     | ページ切り替えロジック |

# 設計書 (design)

## アーキテクチャ概要

- フロントエンド: React + TypeScript（Vite 4 使用）

- バックエンド: FastAPI (Python 3.11)

- データベース: PostgreSQL（RDS）＋ Terraform 管理

## コンポーネント分割

| コンポーネント | 責務 |

|---|---|

| SearchBar | 入力受付・デバウンス処理 |

| ProductList | API 呼び出し結果の表示 |

| Pagination | ページ切り替えロジック |

3‑3. `tasks.md` の落とし込み例

# タスク定義 (tasks)

## フロントエンド実装タスク
- [ ] SearchBar コンポーネント作成（React, debounce）
- [ ] ProductList に API 呼び出しロジックを組み込む
- [ ] Pagination のユニットテストを書く

## バックエンド実装タスク
- [ ] FastAPI エンドポイント `/search` を作成
- [ ] PostgreSQL スキーマ定義（Terraform で管理）

# タスク定義 (tasks)

## フロントエンド実装タスク

- [ ] SearchBar コンポーネント作成（React, debounce）

- [ ] ProductList に API 呼び出しロジックを組み込む

- [ ] Pagination のユニットテストを書く

## バックエンド実装タスク

- [ ] FastAPI エンドポイント `/search` を作成

- [ ] PostgreSQL スキーマ定義（Terraform で管理）

ポイント
3 ファイルが階層的に情報を整理できていれば、Kiro が生成するコードは要件と設計のギャップなく収束します。

4. Steering と Hooks の活用ガイド

4‑1. 正式な YAML キー（公式ドキュメント参照）[^2]

# .kiro/steering.yml (2026‑04版)
naming:
  class_prefix: &quot;App&quot;
  snake_to_camel: true          # スネークケース → キャメルケース自動変換

dependencies:
  python:
    - fastapi&gt;=0.95
    - sqlalchemy&gt;=2.0
    - uvicorn[standard]

lint:
  enable: true
  formatter: black
  max_line_length: 88

# .kiro/steering.yml (2026‑04版)

naming:

class_prefix: "App"

snake_to_camel: true # スネークケース → キャメルケース自動変換

dependencies:

python:

- fastapi>=0.95

- sqlalchemy>=2.0

- uvicorn[standard]

lint:

enable: true

formatter: black

max_line_length: 88

4‑2. カスタム Hook の実装例（Node.js）

// .kiro/hooks/post-generate.js
module.exports = async ({ generatedFiles }) =&gt; {
  const { execSync } = require('child_process');

  // Python ファイルに pytest 用スケルトンテストを自動追加
  generatedFiles
    .filter(f =&gt; f.endsWith('.py'))
    .forEach(file =&gt; {
      execSync(`python scripts/add_pytest_stub.py ${file}`, { stdio: 'inherit' });
    });

  console.log('&#x2705; post‑generate hook: pytest stubs added');
};

// .kiro/hooks/post-generate.js

module.exports = async ({ generatedFiles }) => {

const { execSync } = require('child_process');

// Python ファイルに pytest 用スケルトンテストを自動追加

generatedFiles

.filter(f => f.endsWith('.py'))

.forEach(file => {

execSync(`python scripts/add_pytest_stub.py ${file}`, { stdio: 'inherit' });

});

console.log('✅ post‑generate hook: pytest stubs added');

};

フック種別	実行タイミング	主な活用例
`pre-generate`	ファイル生成前	環境変数・認証情報のチェック
`post-generate`	ファイル生成後	コードフォーマット、テスト雛形自動作成
`on-error`	エラー発生時	Slack / Teams へエラーログ通知

ポイント
Steering が 「プロジェクト全体の設定」 を、Hooks が 「生成プロセスごとのカスタマイズ」 を担い、CI/CD とシームレスに統合できます。

5. 生成コードのレビュー・テスト・デプロイ（IaC 連携）

5‑1. GitHub Actions + Terraform の典型的パイプライン

name: CI / CD

on:
  pull_request:
    branches: [ main ]

jobs:
  test-and-plan:
    runs-on: ubuntu-latest
    env:
      TF_VAR_env: dev               # 環境変数でデプロイ先を切り替え

    steps:
      - uses: actions/checkout@v3

      # ---- Python 環境セットアップ ----
      - name: Set up Python 3.11
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run pytest
        run: pytest -q

      # ---- Terraform 実行 (IaC) ----
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2

      - name: Terraform Init &amp; Plan
        working-directory: infra
        run: |
          terraform init -input=false
          terraform plan -out=tfplan.out

name: CI / CD

on:

pull_request:

branches: [ main ]

jobs:

test-and-plan:

runs-on: ubuntu-latest

env:

TF_VAR_env: dev # 環境変数でデプロイ先を切り替え

steps:

- uses: actions/checkout@v3

# ---- Python 環境セットアップ ----

- name: Set up Python 3.11

uses: actions/setup-python@v4

with:

python-version: '3.11'

- name: Install dependencies

run: pip install -r requirements.txt

- name: Run pytest

run: pytest -q

# ---- Terraform 実行 (IaC) ----

- name: Setup Terraform

uses: hashicorp/setup-terraform@v2

- name: Terraform Init & Plan

working-directory: infra

run: |

terraform init -input=false

terraform plan -out=tfplan.out

5‑2. IaC と Spec の結びつき

Spec 側記述	Kiro が生成する IaC
`requirements.md` に「AWS Lambda を Terraform でデプロイ」	`infra/main.tf` に `aws_lambda_function` リソースの雛形を自動作成
データベース要件（PostgreSQL, VPC）	VPC、サブネット、RDS インスタンス用モジュールが生成される

注意点
- プロバイダーやモジュールは必ず design.md に明記し、terraform init が失敗しないようにすること。
- 環境ごとの変数は Steering で terraform_module_path を統一し、GitHub Actions の TF_VAR_ 系環境変数だけ差し替えると管理が楽です。

5‑3. よくあるエラーと対処法

エラー	原因例	推奨対策
`Spec parsing error: unknown key`	YAML のインデントミス、キー名のスペルミス	VS Code の YAML Linter で事前検証。公式ドキュメントのキー一覧を必ず参照[^2]
`Generated code fails lint`	プロジェクト独自の ESLint 設定と `Steering.lint.formatter` が不一致	`Steering.lint` にプロジェクトの Linter 設定 (`eslint`, `prettier`) を反映
`Terraform plan fails: Provider not found`	`requirements.md` に未記載のクラウドプロバイダーを書いた	`design.md` の「インフラ構成」セクションに必ず provider ブロックを追加し、`terraform init` を実行

ポイント
エラーの多くは設定ファイル（YAML/Markdown）の整合性が原因です。変更後は必ず kiro validate コマンドで検証しましょう。

6. ベストプラクティス集

要件は「誰が・何を・いつ」まで具体的に
「検索結果はページネーションで表示」だけでなく、「1 ページあたり最大 20 件」 と数値化すると AI が最適な実装を選びやすくなる。
設計段階で外部サービスのバージョンを固定
design.md に FastAPI==0.95.* のように明示し、Kiro が生成する requirements.txt と齟齬が出ないようにする。
Steering は「チーム全体の規則」だけでなく「CI のトリガー」も管理
例：lint.enable: true と同時に ci.trigger: push, pull_request を設定し、生成コードが自動的に CI に組み込まれるようにする。
Hooks は最小限に保ち、テストは必ず独立したスクリプトで
生成後の処理は 「副作用を持たない」 スクリプトとして切り出すと、デバッグが容易になる。
定期的に kiro upgrade で CLI と AI モデルを最新化
2026 年 4 月時点では新しいモデルが毎月リリースされ、コード品質やプロンプト解釈精度が向上しています。

7. FAQ（よくある質問）

Q	A
Spec モードは大型プロジェクトでも使えますか？	はい。機能単位で `requirements.md` を分割し、ディレクトリ構造を `specs/feature‑X/` のように整理すれば、Kiro が並列処理できるようになります（公式ガイド[^3]）。
Windows で PowerShell が利用不可の場合は？	Windows Subsystem for Linux (WSL) をインストールし、macOS/Linux と同様の `brew` コマンドか `apt` パッケージから `kiro-cli` を導入できます。
生成されたコードに脆弱性が混入したら？	`Steering.lint.enable: true` と併せて、`bandit`（Python）や `npm audit`（Node.js）を CI に組み込むことで自動検出・ブロックできます。
Kiro が生成した Terraform が期待と違う場合の対処は？	`kiro generate --dry-run design.md` で中間成果物を確認し、必要なら `design.md` の「インフラ構成」を修正して再生成します。
AI の出力が不安定になることがありますか？	モデルの温度パラメータ (`temperature`) が高すぎると創造的過ぎる結果になります。Steering に `generation.temperature: 0.2` を設定すると、再現性が向上します（公式リファレンス[^4]）。

8. まとめ

Spec モード は 要件 → 設計 → タスク の三層構造を AI が自動的に解釈し、コード生成まで一貫して支援します。
Kiro CLI のインストールは数行で完了し、kiro init ですぐに開発雛形が得られます。
Markdown ファイル (requirements.md, design.md, tasks.md) を具体的かつ定量的に記述すれば、高品質なコードが自動生成されます。
Steering と Hooks によってプロジェクト固有の命名規則・テストテンプレート・CI 連携を実装でき、チーム標準と統合しやすくなります。
レビュー・テスト・デプロイ は GitHub Actions + Terraform のパイプラインで自動化可能です。エラーは主に設定ファイルの整合性に起因するため、kiro validate で事前チェックを行うと安心です。

これらの手順とベストプラクティスを自プロジェクトへ取り入れれば、Kiro 仕様駆動開発（SDD） を実務レベルで効果的に活用でき、開発速度・品質ともに大幅に向上します。

参考文献

番号	タイトル・リンク
[^1]	「Kiro で仕様駆動開発のコツを探ってみる」 – Qiita (2025‑12‑23) https://qiita.com/example/kiro-spec
[^2]	Kiro 公式ドキュメント – Steering & Hook 設定ガイド (2026‑04) https://docs.kiro.dev/configuration/
[^3]	「Kiro 入門 – 大規模プロジェクトでの Spec 分割」 – Kiro Academy (2025‑11‑10) https://academy.kiro.dev/big-projects
[^4]	AI Generation Parameters – Kiro API Reference (2026‑03) https://api.kiro.dev/v1/generation#parameters
[^5]	Mamezou Tech ブログ – 「Kiro と Terraform の統合事例」 (2025‑12‑30) https://tech.mamezou.com/kiro-terraform/
[^6]	Google Research – User Experience Benchmarks (2024) https://research.google/pubs/user-experience-benchmarks