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

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

• バックアップ一覧
• 差分 を表示
• 現在との差分 を表示
• ソース を表示
• 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 解説
• Phase/Stage/SubStage? 階層構造による大規模プロジェクト管理
• すぐに使えるテンプレート一式

SuperKiro? Power †

本記事で紹介するベストプラクティスは、Kiro Power として公開しています。

---

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: インフラ構築
• SuperKiro?: チーム開発のためのナレッジ蓄積・仕様駆動開発支援

---

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

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 との機能対応表 †

---

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",
  "enabled": true,
  "when": {
    "type": "fileEdited",
    "patterns": ["src/**/*.ts", "src/**/*.tsx", "!**/*.test.*"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "このファイルの変更内容を確認してください。もしエラー修正であれば、docs/troubleshooting/ に記録を追記することを提案してください。"
  }
}

レビューチェッカーフック †

// .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用） †

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 agents list

---

Phase/Stage/SubStage? 階層管理 †

大規模プロジェクト（レガシー移行など）では、階層的な進行管理が有効です。

階層構造 †

Phase (大分類: プロジェクトの大きな区切り)
└── Stage (中分類: 目的別の作業単位)
    └── SubStage (小分類: 具体的なタスク群)
        └── Feature (実装単位: PR単位)

具体例 †

Phase 1: 現状分析
  ├── Stage 1: 技術スタック調査
  │    ├── SubStage 1: フレームワーク依存の洗い出し
  │    └── SubStage 2: 外部連携の特定
  └── Stage 2: 移行リスク評価
       └── SubStage 1: リスク一覧作成

Phase 2: 設計
  ├── Stage 1: アーキテクチャ設計
  └── Stage 2: データ移行設計

現在位置の追跡 †

<!-- .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時代のドキュメント設計 †

Kiroがドキュメントを効果的に活用するには、AI可読な形式で書くことが重要です。

原則 †

YAMLフロントマターの活用 †

---
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（成果物）の分類 †

SubStage?で生成される成果物を分類して管理します。

詳細は ai-readable-docs.md を参照。

---

プロジェクト管理の実践例 †

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

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/

意思決定ログの例 †

# 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 を更新

振り返りの例 †

# Phase 1: 振り返り

## 完了日
2025-03-28

## 達成したこと
- [x] ユーザー登録・ログイン → 完了
- [x] 商品一覧・詳細 → 完了
- [x] カート機能 → 完了
- [x] 注文処理 → 完了

## うまくいったこと（Keep）
- Kiro Specs で要件が明確化され、手戻りが少なかった
- Hooks でトラブルシューティング記録が習慣化

## 改善点（Problem）
- 途中で要件変更があり、Specs の更新が追いつかなかった

## 次に試すこと（Try）
- 要件変更時は即座に Specs を更新する運用ルール

イテレーション記録の例 †

# 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 の設計判断が正しかった

---

命名規則 †

---

テンプレート集 †

_phase.md テンプレート †

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

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

# SubStage {{N}}: {{name}}

## 目的
<!-- このSubStageで達成すべきこと -->

## インプット
- 前提条件:
- 参照先: ../substage-{{N-1}}-xxx/output.md

## タスク
- [ ]
- [ ]

## アウトプット
- output.md: 発見事項・次への申し送り
- artifacts/: 該当する成果物

## 完了条件
- [ ] output.md が作成されている
- [ ] 次SubStageのインプットが明確

troubleshooting テンプレート †

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

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

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

## 解決方法

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

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

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

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

---

運用ルール †

いつ何を書くか †

完璧を求めない †

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

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

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

回帰テストのタイミング †

大規模移行では、各Stage完了時に回帰テストを実施することを推奨します。

Phase 2: 移行
  └── Stage 1: 基盤移行 → 回帰テスト実施 ✅
  └── Stage 2: 機能移行 → 回帰テスト実施 ✅
  └── Stage 3: 統合    → 回帰テスト実施 ✅

問題の早期発見と影響範囲の限定ができます。

週次振り返り †

毎週金曜日に15分：

# YYYY-Www 振り返り

## 今週学んだこと
-

## 今週解決した問題
- docs/troubleshooting/xxx

## ドキュメント更新
- [x] troubleshootingに追記した
- [ ] 新しいパターンをpatternsに追記した

---

SuperKiro? のインストール †

Kiro IDE（推奨） †

1. Kiro IDEで Manage Powers を開く
2. Add power from GitHub? をクリック
3. https://github.com/khayashi4337/SuperKiro を入力

手動インストール †

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/

初回設定 †

以下のファイルをプロジェクトに合わせて編集:

---

まとめ †

Claude Code の良さを活かしつつ、Kiro の強力な機能を組み合わせることで、「調べ直し」「聞き直し」のない開発体験を実現できます。

---

参考リンク †

SuperKiro? †

• SuperKiro - GitHub
• QuickStart.md
• FAQ.md
• BestPractices.md
• AI可読ドキュメントガイド

Kiro 公式 †

• 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.034 sec. skin apricot by hirokasa