* Kiro × ナレッジ蓄積フォルダ構成のベストプラクティス [#top]
CENTER:''Claude Code経験者のための Kiro 移行ガイド''
#contents
** はじめに [#intro]
Claude Codeで CLAUDE.md + Obsidian を使ったナレッジ管理をしている方も多いと思います。本記事では、その知見を活かしつつ、Kiro の強力な機能（Steering、Hooks、Specs、Powers、カスタムエージェント）を組み合わせた''ベストプラクティス''を紹介します。
*** この記事で得られること [#benefits]
- Kiroに最適化されたフォルダ構成
- 「調べ直し」「聞き直し」を自動化するHooks設定
- Claude Code Skills経験者向けの Kiro Powers 解説
- Phase/Stage/SubStage 階層構造による大規模プロジェクト管理
- すぐに使えるテンプレート一式
*** SuperKiro Power [#superkiro]
本記事で紹介するベストプラクティスは、Kiro Power として公開しています。
|~リポジトリ|[[SuperKiro - GitHub>https://github.com/khayashi4337/SuperKiro]]|
|~QuickStart|[[5分で始めるガイド>https://github.com/khayashi4337/SuperKiro/blob/main/QuickStart.md]]|
|~FAQ|[[よくある質問>https://github.com/khayashi4337/SuperKiro/blob/main/FAQ.md]]|
|~BestPractices|[[大規模プロジェクト向けTips>https://github.com/khayashi4337/SuperKiro/blob/main/BestPractices.md]]|
----
** Kiro Powers とは：「lazy import な Skills」 [#powers]
Claude Code の Skills を使ったことがある方なら、この例えが分かりやすいでしょう。
|~観点|~Claude Code Skills|~Kiro Powers|
|ロード方式|''Eager / 明示的''|''Lazy / 動的''|
|発火条件|view /mnt/skills/... で手動読み込み|キーワード（「database」「ui」等）で自動発火|
|コンテキスト消費|読み込んだ分だけ消費|必要になるまでゼロ|
|中身|Markdown手順書|MCP + Steering + Hooks のパッケージ|
# イメージで言うと...
# Claude Code Skills（eager）
import skills.docx # 明示的にインポート
# Kiro Powers（lazy）
if "database" in prompt:
import powers.neon # 自動的にインポート
*** なぜ lazy が重要か [#why-lazy]
従来のMCPサーバー設定では、6つのMCPサーバー（合計28ツール）を設定すると、単に「こんにちは！」と入力しただけでもコンテキストの数十％を消費していました。
Kiro Powers は''プロンプトに応じて必要なMCPサーバーのみをアクティブ化''するため、クレジットとコンテキストの消費を大幅に抑えられます。
*** 現在利用可能なPowers [#available-powers]
- ''Figma'': デザイン→コード変換、デザインシステムルール生成
- ''Stripe'': 決済フロー実装のベストプラクティス
- ''Supabase / Neon'': データベース連携
- ''Netlify'': デプロイメント自動化
- ''AWS CDK'': インフラ構築
- ''SuperKiro'': チーム開発のためのナレッジ蓄積・仕様駆動開発支援
----
** 推奨フォルダ構成（完全版） [#folder-structure]
project-root/
├── .kiro/ # Kiro設定（Git管理対象）
│ │
│ ├── steering/ # 永続的な知識・ルール
│ │ ├── product.md # プロダクト概要
│ │ ├── structure.md # ディレクトリ構成ルール
│ │ ├── tech.md # 技術スタック
│ │ ├── coding-standards.md # コーディング規約
│ │ ├── review-rules.md # レビュー頻出指摘
│ │ ├── project-structure.md # Phase/Stage/SubStage階層定義
│ │ └── current-stage.md # 現在位置の追跡
│ │
│ ├── specs/ # 仕様書（Kiroが自動生成）
│ │ └── {feature-name}/
│ │ ├── requirements.md # 要件定義（EARS記法）
│ │ ├── design.md # 設計書
│ │ ├── tasks.md # タスクリスト
│ │ └── investigation/ # 調査結果
│ │ ├── as-is-source.md
│ │ ├── as-is-behavior.md
│ │ └── interview-notes.md
│ │
│ ├── hooks/ # 自動化フック
│ │ ├── auto-test-update.json # テスト自動更新
│ │ ├── security-scan.json # セキュリティスキャン
│ │ ├── doc-sync.json # ドキュメント同期
│ │ └── troubleshooting-logger.json # エラー解決記録
│ │
│ ├── agents/ # カスタムエージェント（CLI用）
│ │ ├── backend-specialist.json
│ │ ├── code-reviewer.json
│ │ └── troubleshooter.json
│ │
│ └── settings/
│ └── mcp.json # MCP設定
│
└── docs/ # ナレッジ蓄積（手動 + Hooks自動追記）
├── _templates/ # テンプレート集
│ └── phase/ # Phase/Stage/SubStage用
│ ├── _phase.md
│ ├── _stage.md
│ └── _substage.md
├── project/ # プロジェクト全体管理
│ └── phases/ # フェーズ別進捗
│ └── phase-{N}-{name}/
│ └── stages/
│ └── stage-{N}-{name}/
│ └── substages/
├── troubleshooting/ # エラー解決記録
├── reviews/tags/ # PRレビュー指摘
├── patterns/ # 実装パターン集
├── libraries/ # ライブラリ使用方法
├── features/ # 機能別ドキュメント
├── learning/ # 振り返り・学習記録
└── design/ # 設計ドキュメント
├── artifacts.md # 成果物分類定義
└── ai-readable-docs.md # AI可読ドキュメントガイド
----
** Claude Code との機能対応表 [#comparison]
|~Claude Code|~Kiro|~Kiroの強み|
|CLAUDE.md|.kiro/steering/*.md|複数ファイルに分割可能、Generate Steering Docsで既存コードから自動生成|
|手動で docs/ 参照|''Hooks自動化''|ファイル保存時に自動でドキュメント追記・更新|
|docs/reviews/tags/|.kiro/steering/review-rules.md + ''Hooks''|保存時に自動でレビュー指摘チェック|
|手動でコピペ参照|''Specs自動生成''|要件→設計→タスクをAIが構造化|
|Skills（eager）|''Powers（lazy）''|必要時のみ動的ロード、コンテキスト節約|
|─|''カスタムエージェント''|タスク特化型サブエージェント（CLI）|
|─|''Phase/Stage/SubStage''|大規模プロジェクトの階層的進行管理|
----
** Steering：CLAUDE.md の進化形 [#steering]
*** 基本設定 [#steering-basic]
Claude Codeの CLAUDE.md に相当するのが .kiro/steering/ ディレクトリです。
<!-- .kiro/steering/product.md -->
# プロダクト概要
## サービス名
〇〇システム
## 目的
...
## ターゲットユーザー
...
<!-- .kiro/steering/coding-standards.md -->
# コーディング規約
## 命名規則
### Boolean
- NG: const open = true
- OK: const isOpen = true
### 関数名
- 動詞で始める: getUserById, createOrder
## エラーハンドリング
- try-catchは必ずログ出力を含める
- ユーザー向けエラーメッセージは日本語化する
*** 自動生成機能 [#steering-auto]
既存プロジェクトの場合、''Generate Steering Docs'' をクリックすると、Kiroがコードベースを分析してSteering ドキュメントを自動生成します。
----
** Hooks：「調べ直し地獄」からの自動解放 [#hooks]
*** フック一覧 [#hooks-list]
|~フック名|~トリガー|~用途|
|troubleshooting-logger|ファイル保存|エラー解決時に自動記録|
|auto-test-update|TypeScript保存|テストファイル自動更新|
|security-scan|コミット前|機密情報スキャン|
|doc-sync|API変更時|README自動更新|
|review-checker|保存時|レビュー頻出指摘を事前チェック|
*** トラブルシューティング記録フック [#hooks-troubleshooting]
// .kiro/hooks/troubleshooting-logger.json
{
"name": "Troubleshooting Logger",
"description": "エラー解決時に自動でdocs/troubleshooting/に記録を促す",
"version": "1",
"enabled": true,
"when": {
"type": "fileEdited",
"patterns": ["src/**/*.ts", "src/**/*.tsx", "!**/*.test.*"]
},
"then": {
"type": "askAgent",
"prompt": "このファイルの変更内容を確認してください。もしエラー修正であれば、docs/troubleshooting/ に記録を追記することを提案してください。"
}
}
*** レビューチェッカーフック [#hooks-review]
// .kiro/hooks/review-checker.json
{
"name": "Review Checker",
"description": "保存時にレビュー頻出指摘を事前チェック",
"version": "1",
"enabled": true,
"when": {
"type": "fileEdited",
"patterns": ["src/**/*.ts", "src/**/*.tsx"]
},
"then": {
"type": "askAgent",
"prompt": "steering/review-rules.md と docs/reviews/tags/ を参照し、このファイルにレビューで指摘されそうな問題がないかチェックしてください。"
}
}
----
** カスタムエージェント（CLI用） [#agents]
Kiro CLI を使うと、ターミナルからカスタムエージェントを呼び出せます。
*** トラブルシューター [#agent-troubleshooter]
// .kiro/agents/troubleshooter.json
{
"name": "troubleshooter",
"description": "過去のエラー解決記録を参照して問題を解決",
"prompt": "あなたはトラブルシューティングの専門家です。docs/troubleshooting/ の過去事例を必ず検索してから回答してください。",
"tools": ["read", "write", "shell"],
"allowedTools": ["read"],
"resources": [
"file://docs/troubleshooting/**/*.md",
"file://docs/patterns/**/*.md",
"file://.kiro/steering/**/*.md"
],
"model": "claude-sonnet-4"
}
*** コードレビュアー [#agent-reviewer]
// .kiro/agents/code-reviewer.json
{
"name": "code-reviewer",
"description": "PRレビュー観点でコードをチェック",
"prompt": "あなたはシニアエンジニアとしてコードレビューを行います。docs/reviews/tags/ の過去指摘パターンを参照し、同じ指摘が発生しないかチェックしてください。",
"tools": ["read"],
"resources": [
"file://docs/reviews/**/*.md",
"file://.kiro/steering/coding-standards.md",
"file://.kiro/steering/review-rules.md"
],
"model": "claude-sonnet-4"
}
*** CLIからの呼び出し [#agent-cli]
# トラブルシューターを起動
kiro-cli chat --agent troubleshooter "このエラーの解決方法は？"
# コードレビュアーを起動
kiro-cli chat --agent code-reviewer "src/features/auth/ をレビューして"
# エージェント一覧
kiro-cli agents list
----
** Phase/Stage/SubStage 階層管理 [#phase-stage-substage]
大規模プロジェクト（レガシー移行など）では、階層的な進行管理が有効です。
*** 階層構造 [#hierarchy]
Phase (大分類: プロジェクトの大きな区切り)
└── Stage (中分類: 目的別の作業単位)
└── SubStage (小分類: 具体的なタスク群)
└── Feature (実装単位: PR単位)
*** 具体例 [#hierarchy-example]
Phase 1: 現状分析
├── Stage 1: 技術スタック調査
│ ├── SubStage 1: フレームワーク依存の洗い出し
│ └── SubStage 2: 外部連携の特定
└── Stage 2: 移行リスク評価
└── SubStage 1: リスク一覧作成
Phase 2: 設計
├── Stage 1: アーキテクチャ設計
└── Stage 2: データ移行設計
*** 現在位置の追跡 [#current-stage]
<!-- .kiro/steering/current-stage.md -->
# Current Stage
## 現在位置
- **Phase**: 1 - 現状分析
- **Stage**: 1 - 技術スタック調査
- **SubStage**: 2 - 外部連携の特定
## 参照先
→ docs/project/phases/phase-1-analysis/stages/stage-1-tech-survey/substages/substage-2-integration/
----
** AI時代のドキュメント設計 [#ai-readable-docs]
Kiroがドキュメントを効果的に活用するには、AI可読な形式で書くことが重要です。
*** 原則 [#doc-principles]
|~推奨|~非推奨|
|Markdown|Excel|
|YAML/JSON|Word|
|PlantUML/Mermaid|PowerPoint|
*** YAMLフロントマターの活用 [#yaml-frontmatter]
---
type: requirements | design | investigation | interview
stage: phase-1/stage-2/substage-3
status: draft | review | approved
created: 2025-01-15
updated: 2025-01-20
---
# ドキュメント本文
*** artifacts（成果物）の分類 [#artifacts]
SubStageで生成される成果物を分類して管理します。
|~ファイル名|~内容|~情報源|
|as-is-source.md|ソースコードから読み取った仕様|コード解析|
|as-is-behavior.md|現行動作テストで判明した実態|入出力テスト|
|to-be.md|確定した要件|正式ドキュメント|
|interview-notes.md|ヒアリング議事録・部分的要望|顧客MTG|
|constraints.md|制約・前提条件|各種|
詳細は [[ai-readable-docs.md>https://github.com/khayashi4337/SuperKiro/blob/main/docs/design/ai-readable-docs.md]] を参照。
----
** プロジェクト管理の実践例 [#project-management]
*** 推奨構成：フェーズ × 機能 のマトリクス [#phase-structure]
project-root/
├── .kiro/
│ └── specs/ # Kiro自動生成の仕様書
│ ├── user-auth/
│ └── payment/
│
└── docs/
├── project/ # プロジェクト全体管理
│ └── phases/ # フェーズ別進捗
│ ├── phase-1-analysis/
│ │ ├── _phase.md # フェーズ定義
│ │ ├── goals.md # 目標
│ │ ├── decisions.md # 意思決定ログ
│ │ ├── retrospective.md # 振り返り
│ │ └── stages/
│ │ └── stage-1-tech-survey/
│ │ ├── _stage.md
│ │ └── substages/
│ │ └── substage-1-framework/
│ │ ├── _substage.md
│ │ ├── input.md
│ │ ├── output.md
│ │ └── artifacts/
│ ├── phase-2-design/
│ └── phase-3-implementation/
│
└── features/ # 機能別詳細
├── user-auth/
│ ├── README.md
│ ├── changelog.md
│ └── iterations/
└── payment/
*** 意思決定ログの例 [#example-decision]
# Phase 1: 意思決定ログ
## 2025-01-05: 認証方式の選定
### 背景
MVP フェーズでの認証実装方式を決める必要がある。
### 選択肢
1. NextAuth.js
2. 自前JWT
3. Auth0
### 決定
**NextAuth.js を採用**
### 理由
- Phase 1 では自前実装のコストを避けたい
- Phase 2 でソーシャルログイン追加予定 → NextAuth.js なら容易
- Auth0 は MVP にはオーバースペック
### 影響
- src/lib/auth/ に NextAuth 設定を配置
- docs/features/user-auth/README.md を更新
*** 振り返りの例 [#example-retro]
# Phase 1: 振り返り
## 完了日
2025-03-28
## 達成したこと
- [x] ユーザー登録・ログイン → 完了
- [x] 商品一覧・詳細 → 完了
- [x] カート機能 → 完了
- [x] 注文処理 → 完了
## うまくいったこと（Keep）
- Kiro Specs で要件が明確化され、手戻りが少なかった
- Hooks でトラブルシューティング記録が習慣化
## 改善点（Problem）
- 途中で要件変更があり、Specs の更新が追いつかなかった
## 次に試すこと（Try）
- 要件変更時は即座に Specs を更新する運用ルール
*** イテレーション記録の例 [#example-iteration]
# v0.2: OAuth認証追加
## 実装期間
2025-02-10 〜 2025-02-15
## 対応する Spec
- .kiro/specs/user-auth/requirements.md#REQ-002
## 実装内容
- Google OAuth 追加
- GitHub OAuth 追加
- セッション管理の改善
## スキーマ変更
ALTER TABLE users ADD COLUMN oauth_provider VARCHAR(255);
ALTER TABLE users ADD COLUMN oauth_id VARCHAR(255);
## Before / After
### Before（v0.1）
- メール + パスワードのみ
- 離脱率: 35%
### After（v0.2）
- メール + パスワード + Google OAuth + GitHub OAuth
- 離脱率: 18%（改善）
## 学び
- OAuth 追加で離脱率が大幅改善
- NextAuth.js の設計判断が正しかった
----
** 命名規則 [#naming]
|~種類|~パターン|~例|
|フェーズ|phase-{N}-{name}/|phase-1-analysis/|
|ステージ|stage-{N}-{name}/|stage-1-tech-survey/|
|サブステージ|substage-{N}-{name}/|substage-1-framework/|
|イテレーション|v{major}.{minor}-{description}.md|v0.2-oauth-added.md|
|トラブルシューティング|YYYY-MM-DD-{issue}.md|2025-01-15-nextauth-session.md|
|意思決定|decisions.md 内に日付セクション|## 2025-01-05: 認証方式の選定|
----
** テンプレート集 [#templates]
*** _phase.md テンプレート [#tpl-phase]
# Phase {{N}}: {{name}}
## 目的
<!-- このPhaseで達成すべき大目標 -->
## 期間
{{start-date}} 〜 {{end-date}}
## Stages
1. [Stage 1: {{name}}](./stages/stage-1-xxx/_stage.md)
2. [Stage 2: {{name}}](./stages/stage-2-xxx/_stage.md)
## 完了条件
- [ ] 全Stageが完了
- [ ] retrospective.md が記載済み
## 依存関係
- 前提: Phase {{N-1}} 完了
*** _stage.md テンプレート [#tpl-stage]
# Stage {{N}}: {{name}}
## 目的
<!-- このStageで達成すべきこと -->
## SubStages
1. [SubStage 1: {{name}}](./substages/substage-1-xxx/_substage.md)
2. [SubStage 2: {{name}}](./substages/substage-2-xxx/_substage.md)
## 遷移条件
| From | To | 条件 |
| SubStage 1 | SubStage 2 | output.md 作成済み |
## 完了条件
- [ ] 全SubStageのoutput.mdが作成済み
*** _substage.md テンプレート [#tpl-substage]
# SubStage {{N}}: {{name}}
## 目的
<!-- このSubStageで達成すべきこと -->
## インプット
- 前提条件:
- 参照先: ../substage-{{N-1}}-xxx/output.md
## タスク
- [ ]
- [ ]
## アウトプット
- output.md: 発見事項・次への申し送り
- artifacts/: 該当する成果物
## 完了条件
- [ ] output.md が作成されている
- [ ] 次SubStageのインプットが明確
*** troubleshooting テンプレート [#tpl-trouble]
# {{date}}: {{title}}
## 症状
<!-- どんなエラーが出たか、どんな挙動だったか -->
## 原因
<!-- なぜ起きたのか -->
## 解決方法
### Before
// 問題のコード
### After
// 修正後のコード
## 学び
<!-- 次から気をつけること、横展開すべきこと -->
## 関連
<!-- 関連するドキュメントへのリンク -->
----
** 運用ルール [#operation]
*** いつ何を書くか [#when-to-write]
|~タイミング|~書く場所|~自動化|
|エラーを解決したとき|docs/troubleshooting/|Hooks対応可|
|PRで指摘を受けたとき|docs/reviews/tags/|手動|
|新しいライブラリを導入|docs/libraries/|手動|
|再利用可能なパターン発見|docs/patterns/|手動|
|機能を実装・変更|docs/features/|Hooks対応可|
|SubStage完了時|docs/project/phases/.../output.md|手動|
|週末|docs/learning/|手動|
*** 完璧を求めない [#dont-be-perfect]
最初から完璧なドキュメントを書こうとしない。
## 原因
たぶんキャッシュ関連。あとで調べる。
これでいい。書かないよりマシ。後から修正すればいい。
*** 回帰テストのタイミング [#regression-testing]
大規模移行では、''各Stage完了時に回帰テストを実施''することを推奨します。
Phase 2: 移行
└── Stage 1: 基盤移行 → 回帰テスト実施 ✅
└── Stage 2: 機能移行 → 回帰テスト実施 ✅
└── Stage 3: 統合 → 回帰テスト実施 ✅
問題の早期発見と影響範囲の限定ができます。
*** 週次振り返り [#weekly-retro]
毎週金曜日に15分：
# YYYY-Www 振り返り
## 今週学んだこと
-
## 今週解決した問題
- docs/troubleshooting/xxx
## ドキュメント更新
- [x] troubleshootingに追記した
- [ ] 新しいパターンをpatternsに追記した
----
** SuperKiro のインストール [#installation]
*** Kiro IDE（推奨） [#install-kiro]
+ Kiro IDEで Manage Powers を開く
+ Add power from GitHub をクリック
+ https://github.com/khayashi4337/SuperKiro を入力
*** 手動インストール [#install-manual]
git clone https://github.com/khayashi4337/SuperKiro.git
cd SuperKiro
# プロジェクトにコピー
cp -r steering/* YOUR_PROJECT/.kiro/steering/
cp -r hooks/* YOUR_PROJECT/.kiro/hooks/
cp -r docs/* YOUR_PROJECT/docs/
*** 初回設定 [#initial-setup]
以下のファイルをプロジェクトに合わせて編集:
|~ファイル|~内容|
|steering/project-profile.md|言語、フレームワーク、チーム規模|
|steering/coding-standards.md|コーディング規約|
|steering/review-rules.md|レビューで指摘されがちなこと|
----
** まとめ [#summary]
|~やりたいこと|~使う機能|
|プロジェクトの知識を維持|Steering ディレクトリ|
|繰り返し作業を自動化|Hooks|
|要件→設計→タスクを構造化|Specs|
|外部ツール連携を効率化|Powers（lazy load）|
|特定タスクの専門家を呼ぶ|カスタムエージェント（CLI）|
|大規模プロジェクトの進行管理|Phase/Stage/SubStage階層|
|AI可読なドキュメント作成|YAML frontmatter + Markdown|
Claude Code の良さを活かしつつ、Kiro の強力な機能を組み合わせることで、''「調べ直し」「聞き直し」のない開発体験''を実現できます。
----
** 参考リンク [#references]
*** SuperKiro [#ref-superkiro]
- [[SuperKiro - GitHub>https://github.com/khayashi4337/SuperKiro]]
- [[QuickStart.md>https://github.com/khayashi4337/SuperKiro/blob/main/QuickStart.md]]
- [[FAQ.md>https://github.com/khayashi4337/SuperKiro/blob/main/FAQ.md]]
- [[BestPractices.md>https://github.com/khayashi4337/SuperKiro/blob/main/BestPractices.md]]
- [[AI可読ドキュメントガイド>https://github.com/khayashi4337/SuperKiro/blob/main/docs/design/ai-readable-docs.md]]
*** Kiro 公式 [#ref-kiro]
- [[Kiro 公式ドキュメント>https://kiro.dev/docs/]]
- [[Kiro powers の紹介 | AWS ブログ>https://aws.amazon.com/jp/blogs/news/introducing-powers/]]
- [[Kiro CLI の紹介 | AWS ブログ>https://aws.amazon.com/jp/blogs/news/introducing-kiro-cli/]]
- [[Kiro の AI エージェントフックで開発ワークフローを自動化する | AWS ブログ>https://aws.amazon.com/jp/blogs/news/automate-your-development-workflow-with-agent-hooks/]]
