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

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

• バックアップ一覧
• 差分 を表示
• 現在との差分 を表示
• ソース を表示
• 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 を使ったことがある方なら、この例えが分かりやすいでしょう。

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

# 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: インフラ構築
• など

---

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

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/ ディレクトリです。

<!-- .kiro/steering/product.md -->
# プロダクト概要

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

## 目的
...

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

<!-- .kiro/steering/coding-standards.md -->
# コーディング規約

## 命名規則

### Boolean
- NG: const open = true
- OK: const isOpen = true

### 関数名
- 動詞で始める: getUserById, createOrder

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

自動生成機能 †

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

---

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

フック一覧 †

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

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

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

// .kiro/hooks/review-checker.json
{
  "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 では、タスクに特化したサブエージェントを定義できます。

トラブルシューター †

// .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"
}

コードレビュアー †

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

# トラブルシューターを起動
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: 実装タスクリスト（依存関係順）

生成されるファイル例 †

<!-- .kiro/specs/shopping-cart/requirements.md -->
# 要件定義書

## 要件1: カートへの商品追加
**ユーザーストーリー:** 
ユーザーとして、商品をカートに追加したい。

### 受け入れ基準
1. WHEN 商品詳細ページで「カートに追加」ボタンをクリック
   THEN 商品がカートに追加される
2. WHEN 同じ商品を複数回追加
   THEN 数量が増加する（重複追加されない）

---

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

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

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

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 †

# Phase 1: MVP Goals

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

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

## 成功指標
- 100人のテストユーザーが注文完了できる
- レスポンスタイム < 2秒

## 対象外（Phase 2以降）
- ソーシャルログイン
- 複数決済手段
- レビュー機能

* decisions.md †

# 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 †

# 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 の冪等性対応が必要
- 商品検索のインデックス最適化

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

# 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 との連携 †

┌─────────────────────────────────────────────────────────┐
│  .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 テンプレート †

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

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

## 目標
- [ ] 
- [ ] 

## 成功指標
- 

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

## 依存関係
- 前提: Phase {{N-1}} 完了
- ブロッカー: 

phase decisions テンプレート †

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

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

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

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

### 決定
**{{選択した選択肢}}**

### 理由
- 

### 影響
- 変更が必要なファイル/設定
- 関連ドキュメント: [[xxx]]

### 再検討条件
<!-- どういう状況になったらこの決定を見直すか -->

phase retrospective テンプレート †

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

## 完了日
{{date}}

## 達成したこと
- [x] 
- [ ] （未完了 → Phase {{N+1}} へ）

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

## 改善点（Problem）
- 
  - → [[troubleshooting/xxx]] 参照

## 次に試すこと（Try）
- 

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

iteration テンプレート †

# 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 テンプレート †

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

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

## 原因
<!-- なぜ起きたのか -->

## 解決方法

### Before
// 問題のコード

### After
// 修正後のコード

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

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

library テンプレート †

# {{library-name}}

## 基本的な使い方
// 基本例

## プロジェクトでの使用例
- src/features/XXX/ で使用

## 注意点・落とし穴
- 

## よくあるエラーと対処
| エラー | 原因 | 対処 |
| | | |

## Kiroへの指示
> このライブラリを使用する際は上記の注意点を必ず確認すること

---

運用ルール †

いつ何を書くか †

完璧を求めない †

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

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

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

週次振り返り †

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

# 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.029 sec. skin apricot by hirokasa