Kiroの設定、どこに書けばいい？～グローバル・ワークスペース・Powersの使い分け方～

はじめに：Kiroの設定階層とは

こんにちは。DXソリューション営業本部の松浦です。

Kiroを使い始めると、「Steering」「MCP」「Powers」など、様々な機能が登場します。
さらに、これらの設定を「どこに配置するか」によって、適用範囲や優先順位が変わってきます。

この記事では、Kiroの3つの設定階層（グローバル、ワークスペース、Powers）の違いと使い分けを、図解を交えて分かりやすく解説します。

この記事で学べること

• グローバル、ワークスペース、Powersの違いと適用範囲
• 設定の優先順位と上書きルール
• 個人設定、プロジェクト設定、タスク特化設定の使い分け
• チーム開発での効果的な設定管理方法
• 実践的な設定例とベストプラクティス

対象読者

• Kiroの設定方法に迷っている人
• 複数のプロジェクトでKiroを使い分けたい人
• チーム開発でKiroの設定を統一したい人
• Powersの使い方がよく分からない人

1. 3つの設定階層の全体像

Kiroには、設定を配置する場所によって3つの階層があります。それぞれ適用範囲と目的が異なります。

graph TB
    classDef globalBox fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef workspaceBox fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef powersBox fill:#e3f2fd,stroke:#1565c0,stroke-width:2px

    User["👤 ユーザー"]

    subgraph Global ["グローバル設定
（~/.kiro/）"]
        direction TB
        G1["全プロジェクト共通
・個人の好み
・よく使うMCP"]:::globalBox
    end

    subgraph Workspace ["ワークスペース設定
（プロジェクト/.kiro/）"]
        direction TB
        W1["プロジェクト共通
・チームルール
・プロジェクト用MCP"]:::workspaceBox
    end

    subgraph Powers ["Powers
（タスク特化）"]
        direction TB
        P1["キーワードで起動
・AWS開発用
・ドキュメント用"]:::powersBox
    end

    User --> Global
    User --> Workspace
    User --> Powers

    Global -.->|"常に適用"| Result["🎯 最終的な設定"]
    Workspace -.->|"プロジェクト内で適用"| Result
    Powers -.->|"キーワード検知で適用"| Result

3つの階層の比較

設定の種類と配置可能な階層

＜各ファイルの場所＞
・Steeringファイル：steering/ディレクトリ内に配置
・MCP：settings/mcp.jsonに設定
・参照ドキュメント：Powersの場合はdocs/ディレクトリ、ワークスペースの場合はプロジェクト内の任意の場所に配置。

2. グローバル設定：個人の共通設定

2-1. グローバル設定とは

グローバル設定は、全てのプロジェクトで共通して適用される個人の設定です。ホームディレクトリの~/.kiro/に配置します。

2-2. グローバル設定の配置場所

~/.kiro/
├── steering/
│   ├── personal-preferences.md    # 個人の好み設定
│   └── common-rules.md            # 全プロジェクト共通ルール
└── settings/
    └── mcp.json                   # グローバルMCP設定

2-3. グローバル設定に配置すべき内容

以下のような、全プロジェクトで共通して使いたい設定をグローバルに配置します：

2-4. グローバルSteeringの例

~/.kiro/steering/personal-preferences.mdの例：

# 個人設定

## 言語設定
- すべての回答は日本語で行うこと
- 日付は「YYYY年MM月DD日」形式で表記

## コーディングスタイル
- コメントは日本語で記述
- 変数名はキャメルケースを使用
- 関数には必ずJSDocコメントを付ける

## 回答スタイル
- 説明は簡潔に、コード例を多く含める
- 複雑な処理には必ずコメントを付ける

2-5. グローバルMCPの例

~/.kiro/settings/mcp.jsonの例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username"],
      "disabled": false
    }
  }
}

2-6. グローバル設定のメリット

• 一度設定すれば全プロジェクトで有効：新しいプロジェクトを開始しても、個人の好みは自動的に適用される
• プロジェクトごとの設定不要：共通の設定を毎回書く必要がない
• 個人の作業効率向上：自分に合った環境を全プロジェクトで維持できる

2-7. グローバル設定の注意点

チーム開発では注意：グローバル設定は個人のマシンにのみ存在するため、チームメンバーと共有されません。チーム全体で統一したいルールは、ワークスペース設定に配置しましょう。

3. ワークスペース設定：プロジェクトの共通設定

3-1. ワークスペース設定とは

ワークスペース設定は、特定のプロジェクト内で常に適用される設定です。プロジェクトルートの.kiro/ディレクトリに配置します。

3-2. ワークスペース設定の配置場所

my-project/
├── .kiro/
│   ├── steering/
│   │   ├── project-rules.md       # プロジェクト共通ルール
│   │   ├── coding-standards.md    # コーディング規約
│   │   └── architecture.md        # アーキテクチャ方針
│   └── settings/
│       └── mcp.json               # プロジェクト用MCP設定
├── src/
└── package.json

3-3. ワークスペース設定に配置すべき内容

以下のような、プロジェクト全体で統一したい設定をワークスペースに配置します：

3-4. ワークスペースSteeringの例

.kiro/steering/project-rules.mdの例：

# プロジェクト共通ルール

## プロジェクト概要
ECサイトのバックエンドAPI開発プロジェクト

## 技術スタック
- Node.js 20.x
- TypeScript 5.x
- Express 4.x
- PostgreSQL 16.x

## コミットメッセージ規約
- feat: 新機能追加
- fix: バグ修正
- docs: ドキュメント更新
- refactor: リファクタリング

## ディレクトリ構造
```
src/
├── controllers/    # リクエストハンドラ
├── services/       # ビジネスロジック
├── repositories/   # データアクセス
└── models/         # データモデル
```

## 命名規則
- ファイル名：ケバブケース（user-service.ts）
- クラス名：パスカルケース（UserService）
- 関数名：キャメルケース（getUserById）

3-5. ワークスペースMCPの例

.kiro/settings/mcp.jsonの例：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      },
      "disabled": false
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "mcp-server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-token-here"
      },
      "disabled": false
    }
  }
}

3-6. ワークスペース設定のメリット

• チーム全体で統一：Gitで管理することで、チームメンバー全員が同じ設定を共有できる
• プロジェクト固有の設定：プロジェクトごとに異なるルールを適用できる
• 新メンバーのオンボーディング：リポジトリをクローンするだけで、プロジェクトのルールが適用される

3-7. ワークスペース設定の注意点

Gitで管理：ワークスペース設定は.kiro/ディレクトリごとGitにコミットしましょう。ただし、個人のトークンなどの機密情報は.gitignoreに追加して除外します。

# .gitignoreの例
.kiro/settings/mcp.json  # トークンを含む場合は除外
.kiro/steering/personal-*.md  # 個人用Steeringは除外

4. Powers：タスク特化の設定パッケージ

4-1. Powersとは

Powersは、特定のタスクに特化した設定のパッケージです。Steering、MCP、ドキュメントをまとめて配布でき、キーワードを検知すると自動的に起動します。

例えば、「CloudFormationテンプレートを作成して」と指示すると、AWS開発用Powerのみを起動させるように設定することが可能です。ドキュメント用の設定は除外されるため、開発に必要な情報だけに集中できます。

graph LR
    User[👤 ユーザー] -->|「CloudFormation
テンプレートを作成して」| Kiro[🤖 Kiro]
    Kiro -->|キーワード検知| Switch{判定}

    %% 分岐処理
    Switch -.->|ヒットせず| DocPower[📝 ドキュメント用Power
❌ 起動しない]
    Switch ==>|「CloudFormation」にヒット| AWSPower[☁️ AWS開発用Power
✅ 起動]

    %% 適用結果へのフロー
    AWSPower --> Result[✅ 適用されるルール
・CloudFormation記述規約
・AWS Documentation MCP]

    %% スタイル定義
    classDef active fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000
    classDef inactive fill:#f9f9f9,stroke:#d0d0d0,stroke-width:1px,stroke-dasharray: 5 5,color:#aaaaaa
    classDef resultBox fill:#fff3e0,stroke:#ef6c00,stroke-width:2px

    %% クラス適用
    class DocPower inactive
    class AWSPower active
    class Result resultBox

このように、「その作業に必要な道具だけを、必要な瞬間に机の上に広げる」ことができるのがPowersの最大のメリットです。

4-2. Powersの構造

my-aws-power/
├── POWER.md              # Powerの説明書
├── mcp.json              # Power専用のMCP設定
├── steering/
│   ├── cloudformation.md # CloudFormation規約
│   └── lambda.md         # Lambda開発規約
└── docs/                 # 参照ドキュメント（任意）
    ├── architecture.md   # アーキテクチャガイド
    └── best-practices.md # ベストプラクティス

参照ドキュメントとは：Powersのdocs/ディレクトリに配置する、開発時に参照する資料のことです。設計書、ガイド、仕様書などを含めることで、Powerをアクティベートした時にこれらの情報も自動的にKiroのコンテキストに含まれます。

4-3. Powersに配置すべき内容

以下のような、特定のタスクでのみ必要な設定をPowersに配置します：

4-4. Powersの起動条件

Powersは、POWER.mdに定義されたキーワードを検知すると自動的に起動します。

POWER.mdの例：

---
name: AWS Development Power
keywords: aws, cloudformation, lambda, s3, dynamodb
description: AWS開発に特化した設定パッケージ
---

# AWS Development Power

このPowerは、AWS開発時に必要な設定をまとめたパッケージです。

## 含まれる設定
- CloudFormation記述規約
- Lambda開発ベストプラクティス
- AWS Documentation MCP

## 使い方
「CloudFormationテンプレートを作成して」などのプロンプトで自動起動します。

4-5. Powersの実践例

例1：AWS開発用Power

キーワード：aws, cloudformation, lambda

Steering（steering/cloudformation.md）：

# CloudFormation規約

## リソース命名規則
- スタック名：{ProjectName}-{Environment}-{Purpose}
- リソース名：{ResourceType}{Purpose}

## 必須タグ
- Project: プロジェクト名
- Environment: dev/stg/prod
- ManagedBy: CloudFormation

## テンプレート構造
- Parameters: 環境ごとの変数
- Resources: AWSリソース定義
- Outputs: 他スタックへの出力

MCP（mcp.json）：

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "disabled": false
    }
  }
}

例2：ドキュメント作成用Power

キーワード：設計書, 仕様書, ドキュメント

Steering（steering/document-rules.md）：

# ドキュメント記述規約

## 文書構造
1. 概要
2. 目的
3. 詳細
4. 補足

## フォーマット
- 見出しは階層的に使用
- 箇条書きで簡潔に
- 図表を積極的に活用

## 文末表現
- すべての文書の末尾に「以上」を記載

4-6. Powersのメリット

• 必要な時だけ適用：キーワード検知で自動起動するため、不要な設定が常時適用されない
• 設定のパッケージ化：関連する設定をまとめて管理・配布できる
• チーム共有が容易：Powerをインストールするだけで、チーム全体で同じ環境を構築できる
• コンテキストの最適化：タスクに関連する情報だけが読み込まれるため、AIの回答精度が向上

4-7. Powersの注意点

キーワードの設計が重要：適切なキーワードを設定しないと、必要な時に起動しなかったり、不要な時に起動したりします。キーワードは具体的かつ明確に設定しましょう。

5. 優先順位と設定の上書きルール

5-1. 設定の適用順序

複数の階層に同じ設定がある場合、以下の優先順位で適用されます：

graph LR
    classDef lowPriority fill:#f9f9f9,stroke:#999,stroke-width:1px
    classDef midPriority fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef highPriority fill:#e3f2fd,stroke:#1565c0,stroke-width:3px

    Global["グローバル
（優先度：低）"]:::lowPriority
    Workspace["ワークスペース
（優先度：中）"]:::midPriority
    Powers["Powers
（優先度：高）"]:::highPriority

    Global -->|上書き| Workspace
    Workspace -->|上書き| Powers
    Powers --> Result["最終的な設定"]

5-2. 上書きの具体例

例1：コメントスタイルの上書き

グローバル設定：

# コメントは日本語で記述

ワークスペース設定：

# コメントは英語で記述（国際チームのため）

結果：ワークスペース設定が優先され、コメントは英語で記述されます。

例2：MCPの追加

グローバルMCP：

{
  "mcpServers": {
    "filesystem": { ... }
  }
}

ワークスペースMCP：

{
  "mcpServers": {
    "github": { ... }
  }
}

結果：両方のMCPが有効になります（filesystemとgithub）。

例3：Powersによる一時的な上書き

ワークスペース設定：

# 変数名はキャメルケース

AWS開発用Power：

# CloudFormationリソース名はパスカルケース

結果：AWS開発時のみ、Powerの設定が優先されます。Powerが非アクティブな時は、ワークスペース設定が適用されます。

まとめ：設定階層を理解して開発効率を最大化

この記事では、Kiroの3つの設定階層（グローバル、ワークスペース、Powers）の違いと使い分けを解説しました。

3つの階層の使い分け

優先順位の理解

設定の優先順位は、Powers > ワークスペース > グローバルです。この順序を理解することで、適切な場所に設定を配置できます。

実践のポイント

1. 個人設定はグローバルに：全プロジェクトで共通の個人の好みはグローバル設定に配置
2. チーム設定はワークスペースに：プロジェクト固有のルールはワークスペース設定に配置し、Gitで管理
3. タスク特化はPowersに：特定のタスクでのみ必要な設定はPowersにまとめて配布
4. 設定の重複を避ける：同じ設定を複数の階層に配置しない
5. 定期的な見直し：設定が適切か定期的にレビューする

最後に

Kiroの設定階層を理解することで、個人開発でもチーム開発でも、効率的な開発環境を構築できます。グローバル、ワークスペース、Powersを適切に使い分けて、Kiroの真価を発揮しましょう！

 ↓QESではKiroについて積極的に情報発信していきますので是非ご覧ください！

もし「このサービスについて知りたい」「AWS環境の構築、移行」などのリクエストがございましたら、弊社お問合せフォームまでお気軽にご連絡ください。複雑な内容に関するお問い合わせの場合には直接営業からご連絡を差し上げます。また、よろしければ以下のリンクもご覧ください！
＜QES関連ソリューション/ブログ＞

＜QESが参画しているAWSのセキュリティ推進コンソーシアムがホワイトペーパーを公開しました＞

※Amazon Web Services、"Powered by Amazon Web Services"ロゴ、およびブログで使用されるその他のAWS商標は、米国その他の諸国における、Amazon.com, Inc.またはその関連会社の商標です。