背景・目的
普段からKiroに触れる機会が多いのですが、あらためて基本的なことを理解したく整理します。
概要
steering
What is steering?
- Steeringは、.kiro/steering/フォルダ内のマークダウンファイルを通じて、Kiroにプロジェクトに関する永続的な知識を提供する機能
- 毎回の会話で規約を説明する代わりに、Steeringファイルによって確立されたパターン、ライブラリ、標準に一貫して従うことができる
Key benefits
- 一貫したコード生成
- すべてのコンポーネント、APIエンドポイント、テストがチームの確立されたパターンと規約に従う
- 繰り返しの削減
- 各会話でプロジェクト標準を説明する必要がない
- チームの整合性
- 新規開発者もベテラン開発者も同じ標準で作業
- スケーラブルなプロジェクト知識
- コードベースとともに成長するドキュメント
Steering file scope
Workspace steering
- .kiro/steering/に配置し、特定のワークスペースにのみ適用
Global steering
- ~/.kiro/steering/に配置し、すべてのワークスペースに適用
- 競合する場合はワークスペースSteeringが優先
Team steering
- グローバルSteering機能を使用して、MDMソリューションやグループポリシー経由でチーム全体に配布可能
Foundational steering files
基本的なSteeringファイルは、下記の通り
- product.md
- 製品の目的、ターゲットユーザー、主要機能
- tech.md
- フレームワーク、ライブラリ、開発ツール
- structure.md
- ファイル構成、命名規則、アーキテクチャ決定
Creating custom steering files
- プロジェクト固有のニーズに合わせた専門的なガイダンスでKiroの理解を拡張できる
- .kiro/steering/に新しい.mdファイルを作成
- 説明的なファイル名を選択（例：api-standards.md）
- 標準的なマークダウン構文を使用してガイダンスを記述
- 自然言語で要件を記述
Steering with custom agents
- カスタムエージェントを使用する場合、Steeringファイルは自動的には含まれない
- Steeringコンテキストを読み込むには、エージェントのリソース設定に明示的に追加する必要がある
- カスタムエージェントにすべてのSteeringファイルを含めるには、エージェント設定に以下を追加する
{
"resources": ["file://.kiro/steering/**/*.md"]
}
AGENTS.md
- 設定不要で常に読み込まれるシンプルなステアリング
- AGENTS.mdファイルは以下の場所に追加でき、Kiroが自動的に読み込む
~/.kiro/steering/
- 明示的な設定なしで常に読み込まれるため、プロジェクト全体で必ず適用したいディレクティブに適している
Best practices
-
Keep Files Focused
- ファイルは1つのドメインに集中
- API設計、テスト、デプロイメント手順など、1ファイル1ドメインで管理
- 明確なファイル名を使用
-
Use Clear Names
- 明確なファイル名を使用
- api-rest-conventions.md - REST API標準
- testing-unit-patterns.md - ユニットテストのアプローチ
- components-form-validation.md - フォームコンポーネント標準
- 明確なファイル名を使用
-
Include Context
- コンテキストを含める
- 標準が「何か」だけでなく、「なぜ」その決定がなされたかを説明
-
Provide Examples
- 例を提供
- コードスニペットやbefore/afterの比較を使用して標準を実証
-
Security First
- APIキー、パスワード、機密データは絶対に含めない
- Steeringファイルはコードベースの一部として扱う
-
Maintain Regularly
- スプリント計画やアーキテクチャ変更時にレビュー
- リストラクチャリング後はファイル参照をテスト
- Steeringの変更はコード変更と同様に扱い、レビューを必須とする
Common steering file strategie
- 一般的なSteeringファイル戦略
- API標準 (api-standards.md)
- REST規約、エラーレスポンス形式、認証フロー、バージョニング戦略
- テストアプローチ (testing-standards.md)
- ユニットテストパターン、統合テスト戦略、モッキング手法
- コードスタイル (code-conventions.md)
- 命名パターン、ファイル構成、インポート順序
- セキュリティガイドライン (security-policies.md)
- 認証要件、データ検証ルール、入力サニタイゼーション
- デプロイメントプロセス (deployment-workflow.md)
- ビルド手順、環境設定、CI/CDパイプライン詳細
- API標準 (api-standards.md)
考察
Steeringは指示書のようなもので、毎回コンテキストを伝え直す手間がなくなることと理解しました。
まずはproduct.md・tech.md・structure.mdの3ファイルから始めてみようと思います。次回はInclusion モードやAGENTS.mdとの使い分けも試してみようと思います。
参考