AWS製AI統合・仕様駆動型IDE「Kiro」.kiro作成ベストプラクティス

Last updated at 2026-01-02Posted at 2026-01-01

.kiro作成ベストプラクティス

AWS製AI統合仕様駆動型IDEのKiroの.kiroディレクトリを作りこむために必要なリファレンスのリンクと具体的な用意すると役に立つファイルを提示する記事です。

この記事のスタンス

本記事は、可能な限り公式ドキュメントに準拠しつつ、Geminiとの壁打ちを経て構成しました。現時点ではプロジェクトへの完全な実践投入前のため、一部に考慮漏れや甘い箇所がある可能性があります。そのため、実際に運用して得られた知見やフィードバックを元に、随時この記事を更新・ブラッシュアップしていく「進行形のベストプラクティス」としてご覧ください。

この記事で紹介してるファイル群を実際に導入するとこんな感じになる見取り図です。

.kiro/
├─ steering/ 　プロジェクト全体で適応される設定を定義する
│  ├─api-standards.md
│  ├─code-conventions.md
│  ├─deployment-workflow.md
│  ├─git-flow.md
│  ├─known-issues.md
│  ├─product.md
│  ├─style.md
│  ├─tech.md
│  ├─accessibility.md
│  ├─code-review.md
│  └─testing.md
│  
├─ hook/ 　特定のアクション時に発火するフックを設定する
│  ├─sync-source-to-docs.kiro.hook
│  ├─generate-changelog.kiro.hook
│  ├─auto-doc-generator.kiro.hook
│  ├─log-prompt-loki.kiro.hook
│  ├─security-scan-hook.kiro.hook
│  └─test-coverage-sync.kiro.hook
│  
└─ specs/　Kiroの代名詞の仕様駆動型開発を担う重要なファイル群
│  ├─requirements.md　ユーザーストーリーと受け入れ基準を構造化されたEARS表記法で記録します
│  ├─design.md 　技術アーキテクチャ、シーケンス図、実装上の考慮事項を文書化します
│  └─tasks.md　個別かつ追跡可能なタスクを含む詳細な実装計画を提供します

Steeringの作成

ステアリングは、マークダウンファイルを通じて、ワークスペースに関する継続的な情報をKiroに提供します。チャットごとに規約を説明する代わりに、ステアリングファイルを使用することで、Kiroは確立されたパターン、ライブラリ、標準に一貫して従うことが保証されます。

api-standards.md

APIの設計基準、エンドポイントの命名規則、レスポンス形式およびステータスコードの定義。

code-conventions.md

コーディング規約、リント設定、命名規則など、コード品質を保つための統一ルール。

deployment-workflow.md

本番環境へのデプロイ手順、CI/CDパイプラインの構成、リリースフロー。

git-flow.md

ブランチ戦略、コミットメッセージの記述ルール、プルリクエストの運用ガイドライン。

known-issues.md

現在把握しているバグ、機能の制限事項、将来対応予定の技術的負債。

product.md

プロダクトのビジョン、主要機能の仕様、ターゲットユーザーなどの製品要件。

structure.md

ディレクトリ構成の説明、主要ファイルの配置意図、モジュールの依存関係。

style.md

UI/UXのデザインガイドライン、カラーパレット、フォント、共通コンポーネントのスタイル定義。

tech.md

採用している技術スタック、ライブラリ、フレームワークのバージョンおよび選定理由。

accessibility.md

UIコンポーネントのアクセシビリティガイドライン

code-review.md

コードレビューのチェックリストとフィードバックの原則

testing.md

テスト標準とJest/RTL規約

Hooksの作成

エージェントフックは、IDEで特定のイベントが発生した際に、事前に定義されたエージェントアクションを自動的に実行することで開発ワークフローを効率化する強力な自動化ツールです。フックを使用することで、定型的なタスクを手動でリクエストする必要がなくなり、コードベース全体の一貫性を確保できます。

sync-source-to-docs.kiro.hook

ソースコードの変更内容をドキュメントファイルへ自動的に同期・反映させる。

generate-changelog.kiro.hook

プロジェクトの変更履歴（Changelog）を自動生成する。

auto-doc-generator.kiro.hook

新規作成されたTypeScriptファイル（.ts, .tsx）に対し、関数のシグネチャ、引数、戻り値のJSDocコメントや使用例をAIが自動で生成して追記する。

{
  "enabled": true,
  "name": "Auto Documentation Generator",
  "description": "Automatically generates comprehensive documentation for TypeScript/TSX files by extracting function and class signatures, documenting parameters and return types, providing usage examples, and updating README.md with new exports.",
  "version": "1",
  "when": {
    "type": "fileCreated",
    "patterns": [
      "*.ts",
      "*.tsx"
    ]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Generate comprehensive documentation for this file:\n1. Extract all function and class signatures\n2. Document parameters and return types with JSDoc comments\n3. Provide usage examples based on the code context\n4. If this exports new public APIs, update README.md with the new exports section\n5. Ensure documentation follows project standards and conventions\n\nAdd the documentation directly to the file as comments/JSDoc."
  }
}

log-prompt-loki.kiro.hook

ユーザーが送信したプロンプトの内容を、ログ管理システム「Grafana Loki」へCURLコマンドで送信し、利用状況を記録・監視する。

{
  "enabled": true,
  "name": "Log user prompt to Grafana Loki",
  "description": "Sends user prompts to Grafana Loki for centralized logging and monitoring of user interactions with the kiro app",
  "version": "1",
  "when": {
    "type": "promptSubmit"
  },
  "then": {
    "type": "runCommand",
    "command": "curl -H \"Content-Type: application/json\" -XPOST \"http://loghost/loki/api/v1/push\" --data-raw \"{'streams': [{'stream': { 'app': 'kiro', 'user': \\\"${USER}\\\"  }, 'values': [ [\\\"$(date +%s%N)\\\", \\\"${USER_PROMPT}\\\"] ] }]}\""
  }
}

security-scan-hook.kiro.hook

ファイル編集時に、APIキー、パスワード、秘密鍵などの機密情報や脆弱性がコードに含まれていないかAIがスキャンし、リスクがあれば警告と修正案を提示する。

{
  "enabled": true,
  "name": "Security Vulnerability Scanner",
  "description": "Scans changed files for security vulnerabilities including API keys, tokens, credentials, private keys, encryption keys, certificates, authentication tokens, passwords, secrets, IP addresses, hardcoded URLs, and database credentials. Provides specific risk highlights, secure alternatives, and security best practices.",
  "version": "1",
  "when": {
    "type": "fileEdited",
    "patterns": [
      "*.ts",
      "*.tsx",
      "*.js",
      "*.jsx",
      "*.json",
      "*.env",
      "*.env.*",
      "*.config.js",
      "*.config.ts",
      "*.yml",
      "*.yaml",
      "*.xml",
      "*.properties",
      "*.conf",
      "*.cfg"
    ]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Review this file for security vulnerabilities. Check for:\n1. API keys, tokens, or credentials in source code\n2. Private keys or sensitive credentials\n3. Encryption keys or certificates\n4. Authentication tokens or session IDs\n5. Passwords or secrets in configuration files\n6. IP addresses containing sensitive data\n7. Hardcoded internal URLs\n8. Database connection credentials\n\nFor each issue found:\n1. Highlight the specific security risk and its severity\n2. Suggest a secure alternative approach\n3. Recommend security best practices for handling this type of secret\n\nIf no issues are found, confirm the file is secure."
  }
}

test-coverage-sync.kiro.hook

ソースコード編集時に、変更箇所のテストが存在するか確認し、不足していればAIがテストケースを自動生成・実行してカバレッジレポートを更新する。

{
  "enabled": true,
  "name": "Test Coverage Sync",
  "description": "Automatically identifies new or modified functions and methods in source files, checks for corresponding test coverage, generates missing test cases, runs tests, and updates coverage reports.",
  "version": "1",
  "when": {
    "type": "fileEdited",
    "patterns": [
      "app/**/*.tsx",
      "app/**/*.ts",
      "components/**/*.tsx",
      "components/**/*.ts",
      "lib/**/*.ts",
      "utils/**/*.ts"
    ]
  },
  "then": {
    "type": "askAgent",
    "prompt": "A source file has been modified. Please:\n1. Identify all new or modified functions and methods in this file\n2. Check if corresponding test files exist in __tests__ directory and review their coverage\n3. For any new or modified code without adequate test coverage, generate comprehensive test cases\n4. Run the test suite with `npm test` or `yarn test` to verify all tests pass\n5. Generate or update coverage reports by running `npm run test:coverage` or equivalent\n6. Provide a summary of coverage changes and any new tests created"
  }
}

Hooksの具体例

Specsの作成

vibe又はSpecsか最初に聞かれるのでSpecsを選択すると以下のファイルが自動生成されます。

(vibe = バイブコーディング(雰囲気コーディング))
(Specs = 仕様駆動型開発)

requirements.md - ユーザーストーリーと受け入れ基準を構造化されたEARS表記法で記録します
design.md - 技術アーキテクチャ、シーケンス図、実装上の考慮事項を文書化します
tasks.md - 個別かつ追跡可能なタスクを含む詳細な実装計画を提供します

ワークフロー

以下のワークフローに従ってkiroがナビゲーションしてくれます

要件フェーズ（左端のセクション）：構造化されたEARS表記法でユーザーストーリーと受け入れ基準を定義する
設計フェーズ（第2セクション）：技術アーキテクチャ、シーケンス図、実装上の考慮事項を文書化する
実施計画（第3セクション）：作業を明確な説明と結果を伴う個別の追跡可能なタスクに分割する
実行フェーズ（右端のセクション）：タスクの完了時に進捗状況を追跡し、必要に応じて仕様を更新および改良する機能

公式ドキュメント

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up