ステアリングファイル

ステアリングファイルは、プロジェクトの知識を Kiro に永続的に伝えるマークダウンファイルです。毎回同じ説明をする必要がなくなり、一貫した動作を実現します。

ステアリングファイルの配置

ステアリングファイルには2つのスコープがあります。

スコープ	場所	適用範囲
ワークスペース	.kiro/steering/	現在のプロジェクトのみ
グローバル	~/.kiro/steering/	すべてのプロジェクト

ワークスペースステアリングがグローバルステアリングと競合した場合、ワークスペースが優先されます。

基盤となる3ファイル

すべてのプロジェクトで用意すべき3つの基本ファイルがあります。

product.md — ビジネスコンテキスト

# Product Overview

## Purpose
An e-commerce platform for handmade crafts.

## Target Users
- Craft artisans selling their products
- Customers looking for unique handmade items

## Key Features
- Product listing with image galleries
- Shopping cart and checkout
- Seller dashboard with analytics

## Business Goals
- Support 1,000 active sellers by Q3
- Achieve 99.9% uptime for checkout flow

tech.md — 技術選定と制約

# Technology Stack

## Frontend
- React 19 with TypeScript
- Tailwind CSS for styling
- Vite for build tooling

## Backend
- Node.js with Express
- PostgreSQL for data storage
- Redis for caching

## Constraints
- All API responses must be under 200ms
- Support for IE11 is NOT required
- Use ESM modules exclusively

structure.md — コード構成パターン

# Project Structure

## Directory Layout
- `src/components/` — React UI components
- `src/hooks/` — Custom React hooks
- `src/api/` — API client functions
- `src/pages/` — Route page components
- `src/utils/` — Shared utility functions

## Naming Conventions
- Components: PascalCase (e.g., `UserProfile.tsx`)
- Hooks: camelCase with `use` prefix (e.g., `useAuth.ts`)
- Utils: camelCase (e.g., `formatDate.ts`)
- Tests: `*.test.ts` colocated with source files

カスタムステアリングファイル

プロジェクト固有のルールやガイドラインを追加のステアリングファイルで定義します。

.kiro/steering/
├── product.md          # ビジネスコンテキスト
├── tech.md             # 技術スタック
├── structure.md        # コード構成
├── api-standards.md    # REST API 規約
├── testing-standards.md # テスト方針
├── security-policies.md # セキュリティポリシー
└── code-conventions.md  # コーディング規約

AGENTS.md サポート

Kiro CLI は AGENTS.md 標準にも対応しています。~/.kiro/steering/ やワークスペースルートに AGENTS.md を配置すると、自動的にロードされます。

カスタムエージェントでの注意

重要: ステアリングファイルはカスタムエージェントでは自動ロードされません。エージェント設定の resources フィールドで明示的に指定する必要があります。

{
  "resources": ["file://.kiro/steering/**/*.md"]
}

ベストプラクティス

原則	説明
単一責任	1ファイルに1つのドメイン
説明的な名前	ファイル名で内容がわかるように
「なぜ」を書く	ルールだけでなく理由も説明
コード例を含める	具体的な例があると精度が上がる
機密情報を含めない	APIキーやパスワードは絶対に書かない
レビュー対象	コードと同様にレビューを実施

コンテキスト管理

Kiro CLI は4つの異なるコンテキスト管理アプローチを提供しています。タスクの性質に応じて最適な方法を選びます。

4つのアプローチ

方法	トークン消費	永続性	最適な用途
Agent Resources	常時（毎リクエスト）	セッション横断	必須のプロジェクトファイル
Skills	オンデマンド	セッション横断	大きなガイド・リファレンス
Session Context	常時（毎リクエスト）	セッション限定	一時的なファイル、実験
Knowledge Bases	検索時のみ	セッション横断	大規模コードベース、大量ドキュメント

選択のフローチャート

flowchart TB
    Start["コンテキストを追加したい"] --> Size{"10MB超 or<br/>数千ファイル？"}
    Size -->|Yes| KB["Knowledge Base"]
    Size -->|No| Frequency{"毎回の会話で<br/>必要？"}
    Frequency -->|Yes| Persistent{"セッション横断で<br/>必要？"}
    Frequency -->|No| Session["Session Context"]
    Persistent -->|Yes| AgentRes["Agent Resources"]
    Persistent -->|No| Session
    style KB fill:#ef4444,color:#fff
    style AgentRes fill:#3b82f6,color:#fff
    style Session fill:#22c55e,color:#fff
    style Start fill:#8b5cf6,color:#fff

Session Context の操作

一時的にファイルをコンテキストに追加する方法です。

> /context add README.md

> /context add docs/*.md

> /context show

> /context remove README.md

> /context clear

/context show はカテゴリ別・ファイル別のトークン消費状況を表示します。コンテキストウィンドウの使用率を監視するのに便利です。

コンテキストウィンドウの管理

コンテキストファイルはすべてのリクエストでトークンを消費します。使わないファイルでもコンテキストに含まれていればトークンが消費されるため、管理が重要です。

制限: コンテキストファイルはモデルのコンテキストウィンドウの75%に制限されています。超過した場合、自動的にファイルが除外されます。

会話の圧縮

長い会話はコンテキストウィンドウを圧迫します。手動または自動で圧縮できます。

> /compact

古いメッセージが要約され、最近のメッセージは保持されます。

自動圧縮の設定:

# 圧縮時に保持する最小メッセージペア数（デフォルト: 2）
kiro-cli settings compaction.excludeMessages 3

# 圧縮時に保持するコンテキストウィンドウの最小%（デフォルト: 2）
kiro-cli settings compaction.excludeContextWindowPercent 5

# 自動圧縮を無効化
kiro-cli settings chat.disableAutoCompaction true

Context Usage Indicator

コンテキストウィンドウの使用率をリアルタイムで表示する実験的機能です。

kiro-cli settings chat.enableContextUsageIndicator true

色分けで状態がわかります。

• 緑: 50% 未満（余裕あり）
• 黄: 50-89%（注意）
• 赤: 90-100%（圧縮を推奨）

チーム向けステアリング配布

組織全体でステアリングファイルを統一する方法です。

Git リポジトリ共有

ステアリングファイルを .kiro/steering/ に配置してバージョン管理します。

.kiro/
└── steering/
    ├── product.md
    ├── tech.md
    ├── structure.md
    ├── api-standards.md
    └── security-policies.md

リポジトリをクローンした全員が同じステアリングファイルを使用できます。

MDM / グループポリシー

グローバルステアリング（~/.kiro/steering/）を MDM ソリューションやグループポリシーで配布し、組織全体の一貫性を確保します。

まとめ

項目	内容
ステアリングファイル	.kiro/steering/ にマークダウンで配置
基盤ファイル	product.md, tech.md, structure.md
スコープ	ワークスペース（優先）とグローバル
コンテキスト管理	Agent Resources, Skills, Session Context, Knowledge Bases
/context	セッション中のコンテキスト操作
/compact	会話の手動圧縮
チーム配布	Git リポジトリ共有、MDM

Day 8 では、MCP 連携とナレッジ管理を学びます。