KIROナレッジ蓄積フォルダ構成 のバックアップ(No.1)

[ トップ ]   [ 新規 | 一覧 | 単語検索 | 最終更新 | ヘルプ ]

• バックアップ一覧
• 差分 を表示
• 現在との差分 を表示
• ソース を表示
• KIROナレッジ蓄積フォルダ構成 へ行く。
  • 1 (2025-12-30 (火) 18:59:28)
  • 2 (2025-12-30 (火) 19:38:52)
  • 3 (2025-12-31 (水) 12:00:08)

---

Kiro × ナレッジ蓄積フォルダ構成のベストプラクティス †

はじめに †

Claude Codeで CLAUDE.md + Obsidian を使ったナレッジ管理をしている方も多いと思います。本記事では、その知見を活かしつつ、Kiro の強力な機能（Steering、Hooks、Specs、Powers、カスタムエージェント）を組み合わせたベストプラクティスを紹介します。

この記事で得られること †

• Kiroに最適化されたフォルダ構成
• 「調べ直し」「聞き直し」を自動化するHooks設定
• Claude Code Skills経験者向けの Kiro Powers 解説
• すぐに使えるテンプレート一式

---

Kiro Powers とは：「lazy import な Skills」 †

Claude Code の Skills を使ったことがある方なら、この例えが分かりやすいでしょう。

File not found: "python" at page "KIROナレッジ蓄積フォルダ構成";

# イメージで言うと...

# Claude Code Skills（eager） import skills.docx # 明示的にインポート

# Kiro Powers（lazy） if "database" in prompt:

   import powers.neon  # 自動的にインポート

}}

なぜ lazy が重要か †

従来のMCPサーバー設定では、6つのMCPサーバー（合計28ツール）を設定すると、単に「こんにちは！」と入力しただけでもコンテキストの数十％を消費していました。

Kiro Powers はプロンプトに応じて必要なMCPサーバーのみをアクティブ化するため、クレジットとコンテキストの消費を大幅に抑えられます。

現在利用可能なPowers †

• Figma: デザイン→コード変換、デザインシステムルール生成
• Stripe: 決済フロー実装のベストプラクティス
• Supabase / Neon: データベース連携
• Netlify: デプロイメント自動化
• AWS CDK: インフラ構築
• など

---

推奨フォルダ構成（完全版） †

#code{{ project-root/ ├── .kiro/ # Kiro設定（Git管理対象） │ │ │ ├── steering/ # 永続的な知識・ルール │ │ ├── product.md # プロダクト概要 │ │ ├── structure.md # ディレクトリ構成ルール │ │ ├── tech.md # 技術スタック │ │ ├── coding-standards.md # コーディング規約 │ │ └── review-rules.md # レビュー頻出指摘 │ │ │ ├── specs/ # 仕様書（Kiroが自動生成） │ │ └── {feature-name}/ │ │ ├── requirements.md # 要件定義（EARS記法） │ │ ├── design.md # 設計書 │ │ └── tasks.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/                 # テンプレート集
   ├── troubleshooting/            # エラー解決記録
   ├── reviews/                    # PRレビュー指摘
   ├── patterns/                   # 実装パターン集
   ├── libraries/                  # ライブラリ使用方法
   ├── features/                   # 機能別ドキュメント
   └── learning/                   # 振り返り・学習記録

}}

---

Claude Code との機能対応表 †

---

Steering：CLAUDE.md の進化形 †

基本設定 †

Claude Codeの CLAUDE.md に相当するのが .kiro/steering/ ディレクトリです。

#code{{

!-- .kiro/steering/product.md -->

# プロダクト概要

## サービス名 〇〇システム

## 目的 ...

## ターゲットユーザー ... }}

#code{{

!-- .kiro/steering/coding-standards.md -->

# コーディング規約

## 命名規則

### Boolean

• NG: const open = true
• OK: const isOpen = true

### 関数名

• 動詞で始める: getUserById?, createOrder

## エラーハンドリング

• try-catchは必ずログ出力を含める
• ユーザー向けエラーメッセージは日本語化する }}

自動生成機能 †

既存プロジェクトの場合、Generate Steering Docs をクリックすると、Kiroがコードベースを分析してSteering ドキュメントを自動生成します。

---

Hooks：「調べ直し地獄」からの自動解放 †

フック一覧 †

実装例：トラブルシューティング自動記録 †

File not found: "json" at page "KIROナレッジ蓄積フォルダ構成";

{

 "name": "Troubleshooting Logger",
 "description": "エラー解決時に自動でdocs/troubleshooting/に記録",
 "version": "1",
 "when": {
   "type": "fileEdited",
   "patterns": ["**/*.ts", "**/*.tsx", "!**/*.test.*"]
 },
 "then": {
   "type": "askAgent",
   "prompt": "このファイルの変更がエラー修正である場合、docs/troubleshooting/ に解決記録を追記してください。"
 }

} }}

実装例：レビュー指摘事前チェック †

File not found: "json" at page "KIROナレッジ蓄積フォルダ構成";

{

 "name": "Review Checker",
 "description": "保存時にレビュー頻出指摘をチェック",
 "version": "1",
 "when": {
   "type": "fileEdited",
   "patterns": ["src/**/*.ts", "src/**/*.tsx"]
 },
 "then": {
   "type": "askAgent",
   "prompt": "docs/reviews/tags/ と .kiro/steering/review-rules.md を参照し、このファイルにレビューで指摘されそうな問題がないかチェックしてください。"
 }

} }}

チームへの共有 †

Hooksは .kiro/hooks/ ディレクトリに保存され、Gitにコミットすることでチーム全体で共有できます。一人のメンバーが作成したHooksを全員が利用できます。

---

カスタムエージェント（CLI用） †

Kiro CLI では、タスクに特化したサブエージェントを定義できます。

トラブルシューター †

File not found: "json" at page "KIROナレッジ蓄積フォルダ構成";

{

 "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"

} }}

コードレビュアー †

File not found: "json" at page "KIROナレッジ蓄積フォルダ構成";

{

 "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からの呼び出し †

File not found: "bash" at page "KIROナレッジ蓄積フォルダ構成";

# トラブルシューターを起動 kiro-cli chat --agent troubleshooter "このエラーの解決方法は？"

# コードレビュアーを起動 kiro-cli chat --agent code-reviewer "src/features/auth/ をレビューして"

# エージェント一覧 kiro-cli agent list

# エージェント切り替え（対話中）

/agent swap }}

---

Specs：仕様駆動開発 †

Kiro独自の強力な機能です。プロンプトから自動で以下を生成します：

1. requirements.md: EARS記法によるユーザーストーリーと受け入れ基準
2. design.md: アーキテクチャ、技術スタック、コンポーネント設計
3. tasks.md: 実装タスクリスト（依存関係順）

生成されるファイル例 †

#code{{

!-- .kiro/specs/shopping-cart/requirements.md -->

# 要件定義書

## 要件1: カートへの商品追加

ユーザーストーリー:** †

ユーザーとして、商品をカートに追加したい。

### 受け入れ基準 1. WHEN 商品詳細ページで「カートに追加」ボタンをクリック

  THEN 商品がカートに追加される

2. WHEN 同じ商品を複数回追加

  THEN 数量が増加する（重複追加されない）

}}

---

プロジェクト進行に沿った成果物管理 †

プロジェクトを段階的に進める際、成果物をどのように格納するかの見本です。

推奨構成：フェーズ × 機能 のマトリクス †

#code{{ project-root/ ├── .kiro/ │ └── specs/ # Kiro自動生成の仕様書 │ ├── user-auth/ │ │ ├── requirements.md │ │ ├── design.md │ │ └── tasks.md │ └── payment/ │ └── docs/

   ├── project/                    # プロジェクト全体管理
   │   ├── README.md               # プロジェクト概要
   │   ├── roadmap.md              # ロードマップ
   │   └── phases/                 # フェーズ別進捗
   │       ├── phase-1-mvp/
   │       │   ├── goals.md        # フェーズ目標
   │       │   ├── scope.md        # スコープ定義
   │       │   ├── decisions.md    # 意思決定ログ
   │       │   └── retrospective.md # 振り返り
   │       ├── phase-2-beta/
   │       └── phase-3-release/
   │
   └── features/                   # 機能別詳細
       ├── user-auth/
       │   ├── README.md           # 機能概要
       │   ├── changelog.md        # 変更履歴
       │   ├── iterations/         # イテレーション記録
       │   │   ├── v0.1-basic-login.md
       │   │   ├── v0.2-oauth-added.md
       │   │   └── v0.3-2fa-implemented.md
       │   └── tests/
       │       └── test-report.md
       └── payment/

}}

具体例：ECサイト開発プロジェクト †

* goals.md †

#code{{

# Phase 1: MVP Goals

## 期間 2025-01-01 〜 2025-03-31

## 目標

• [ ] ユーザー登録・ログイン機能
• [ ] 商品一覧・詳細表示
• [ ] カート機能（基本）
• [ ] 注文処理（クレジットカードのみ）

## 成功指標

• 100人のテストユーザーが注文完了できる
• レスポンスタイム < 2秒

## 対象外（Phase 2以降）

• ソーシャルログイン
• 複数決済手段
• レビュー機能 }}

* decisions.md †

#code{{

# Phase 1: 意思決定ログ

## 2025-01-05: 認証方式の選定

### 背景 ユーザー認証の実装方式を決定する必要がある

### 選択肢 1. 自前実装（JWT） 2. NextAuth?.js 3. Auth0

### 決定

NextAuth?.js を採用** †

### 理由

• Phase 1 では自前実装のコストを避けたい
• Phase 2 でソーシャルログイン追加予定 → NextAuth?.js なら容易
• Auth0 は MVP にはオーバースペック

### 影響

• src/lib/auth/ に NextAuth? 設定を配置
• features/user-auth/README? を更新 }}

* retrospective.md †

#code{{

# Phase 1: 振り返り

## 完了日 2025-03-28

## 達成したこと

• [x] ユーザー登録・ログイン → 完了
• [x] 商品一覧・詳細 → 完了
• [x] カート機能 → 完了
• [x] 注文処理 → 完了

## うまくいったこと（Keep）

• Kiro Specs で要件が明確化され、手戻りが少なかった
• Hooks による自動テスト更新で品質を維持できた

## 改善点（Problem）

• 決済周りのエラーハンドリングが甘かった

   - → [[troubleshooting/2025-03-20-stripe-webhook-error]] 参照

• パフォーマンステストが後回しになった

## 次に試すこと（Try）

• Phase 2 ではパフォーマンステストを早期に実施

## Phase 2 への申し送り

• Stripe Webhook の冪等性対応が必要
• 商品検索のインデックス最適化 }}

機能別イテレーション記録 †

#code{{

# v0.2: OAuth ログイン追加

## 実装期間 2025-02-01 〜 2025-02-15

## 対応する Spec

• [[.kiro/specs/user-auth/requirements.md#要件3]]

## 実装内容

### 変更したファイル

• src/app/api/auth/[...nextauth]/route.ts

   - Google, GitHub プロバイダー追加

### 環境変数追加

GOOGLE_CLIENT_ID=xxx
GOOGLE_CLIENT_SECRET=xxx
GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx

### スキーマ変更

ALTER TABLE users ADD COLUMN provider VARCHAR(50);
ALTER TABLE users ADD COLUMN provider_id VARCHAR(255);

## Before / After

### Before（v0.1）

• メール + パスワードのみ
• 離脱率: 35%

### After（v0.2）

• メール + パスワード + Google OAuth + GitHub? OAuth
• 離脱率: 18%（改善）

## 学び

• OAuth 追加で離脱率が大幅改善
• NextAuth?.js の設計判断が正しかった }}

Kiro Specs との連携 †

#code{{ ┌─────────────────────────────────────────────────────────┐ │ .kiro/specs/user-auth/ │ │ ├── requirements.md ← Kiro生成（EARS記法） │ │ ├── design.md ← Kiro生成（アーキテクチャ） │ │ └── tasks.md ← Kiro生成（実装タスク） │ └─────────────────────────────────────────────────────────┘

                         │
                         │ 参照・リンク
                         ▼

┌─────────────────────────────────────────────────────────┐ │ docs/features/user-auth/ │ │ ├── README.md ← 機能概要（人間が補足） │ │ ├── changelog.md ← 変更履歴（人間が記録） │ │ └── iterations/ ← イテレーション記録（人間が記録）│ └─────────────────────────────────────────────────────────┘

                         │
                         │ 問題発生時に参照
                         ▼

┌─────────────────────────────────────────────────────────┐ │ docs/troubleshooting/ │ │ └── 2025-01-15-nextauth-session-issue.md │ └─────────────────────────────────────────────────────────┘ }}

ファイル命名規則 †

---

テンプレート集 †

phase goals テンプレート †

#code{{

# Phase {{N}}: {{name}} Goals

## 期間 {{start-date}} 〜 {{end-date}}

## 目標

• [ ]
• [ ]

## 成功指標

## 対象外（次フェーズ以降）

## 依存関係

• 前提: Phase {{N-1}} 完了
• ブロッカー: }}

phase decisions テンプレート †

#code{{

# Phase {{N}}: 意思決定ログ

## {{date}}: {{title}}

### 背景

!-- なぜこの決定が必要だったか -->

### 選択肢 1. 2. 3.

### 決定

{{選択した選択肢}}** †

### 理由

### 影響

• 変更が必要なファイル/設定
• 関連ドキュメント: xxx?

### 再検討条件

!-- どういう状況になったらこの決定を見直すか --> }}

phase retrospective テンプレート †

#code{{

# Phase {{N}}: 振り返り

## 完了日 {{date}}

## 達成したこと

• [x]
• [ ] （未完了 → Phase {{N+1}} へ）

## うまくいったこと（Keep）

## 改善点（Problem）

•  - → [[troubleshooting/xxx]] 参照

## 次に試すこと（Try）

## Phase {{N+1}} への申し送り

• }}

iteration テンプレート †

#code{{

# v{{X}}.{{Y}}: {{description}}

## 実装期間 {{start-date}} 〜 {{end-date}}

## 対応する Spec

• [[.kiro/specs/{feature}/requirements.md#要件X]]

## 実装内容

### 追加/変更したファイル

• src/xxx/yyy.ts -

### スキーマ変更（あれば）

• 変更内容

### 環境変数（あれば） NEW_VAR=xxx

## Before / After

### Before

!-- 変更前の状態、コード、指標など -->

### After

!-- 変更後の状態、コード、指標など -->

## テスト結果

• 単体テスト: X/Y pass
• E2E: X/Y pass
• カバレッジ: XX%

## 発生した問題と解決

• troubleshooting/YYYY-MM-DD-xxx?

## 学び

!-- このイテレーションで得た知見 -->

## 次のイテレーションへの課題

• }}

troubleshooting テンプレート †

#code{{

# {{date}}: {{title}}

## 症状

!-- どんなエラーが出たか、どんな挙動だったか -->

## 原因

!-- なぜ起きたのか -->

## 解決方法

### Before

### After

## 学び

!-- 次から気をつけること、横展開すべきこと -->

## 関連

!-- 関連するドキュメントへのリンク --> }}

library テンプレート †

#code{{

# {{library-name}}

## 基本的な使い方

## プロジェクトでの使用例

• src/features/XXX/ で使用

## 注意点・落とし穴

## よくあるエラーと対処

## Kiroへの指示

このライブラリを使用する際は上記の注意点を必ず確認すること }}

---

運用ルール †

いつ何を書くか †

完璧を求めない †

最初から完璧なドキュメントを書こうとしない。

#code{{

## 原因 たぶんキャッシュ関連。あとで調べる。 }}

これでいい。書かないよりマシ。後から修正すればいい。

週次振り返り †

毎週金曜日に15分だけ振り返りの時間を取る。

#code{{

# 2025-W01 振り返り

## 今週学んだこと

• Prismaのconnection poolingの設定

## 今週解決した問題

• troubleshooting/2025-01-15-prisma-connection?

## ドキュメント更新

• [x] troubleshootingに追記した
• [ ] 新しいパターンをpatternsに追記した ← 来週やる }}

---

まとめ †

Claude Code から Kiro への移行ポイント †

1. CLAUDE.md → .kiro/steering/: 複数ファイルに分割、自動生成機能あり
2. 手動参照 → Hooks: ファイル保存時に自動でドキュメント参照・更新
3. Skills → Powers: lazy import でコンテキスト節約
4. ─ → カスタムエージェント: タスク特化型サブエージェント

やるべきこと †

1. .kiro/steering/ にプロジェクトルールを設定
2. docs/ でナレッジを蓄積（従来通り）
3. Hooks で自動化を設定（解決したらすぐ書くを自動化）
4. 必要に応じて Powers をインストール
5. CLI用にカスタムエージェントを定義

期待できる効果 †

• 「調べ直し」時間の90%削減
• PRレビュー指摘の事前回避
• チームナレッジの資産化
• コンテキスト消費の最適化（Powers）

---

参考リンク †

• Kiro 公式ドキュメント
• Kiro powers の紹介 | AWS ブログ
• Kiro CLI の紹介 | AWS ブログ
• Kiro の AI エージェントフックで開発ワークフローを自動化する | AWS ブログ

     

Web Master: hayashi_kuniyuki

PukiWiki 1.4.7 Copyright © 2001-2006 PukiWiki Developers Team. License is GPL.
Based on "PukiWiki" 1.3 by yu-ji. Powered by PHP 5.3.29. HTML convert time: 0.048 sec. skin apricot by hirokasa