【第1回】Kiro 仕様駆動開発実践入門 — Hooks・Steering・Agentsの基本概念とPython自動化環境のセットアップ

最近 AWS が出した agentic IDE「Kiro」を触り始めたんですが、Cursor や VS Code の拡張とは設計思想がかなり違って、最初は「え、これどういう使い方するやつ？」となりました。特に Hooks・Steering・Agents（AgentSkills）の三つが独特で、ドキュメントを読んでも最初はピンとこなかったので、自分なりに整理しながらシリーズ記事にまとめることにしました。

全4回の予定で、今回はその第1回。概念の整理と Python プロジェクトでの環境セットアップがメインです。

この記事でわかること
Kiro とはなにか
三つの主要機能を整理する
Python プロジェクトのセットアップ
Kiro で変わる開発フローのイメージ
まとめ

この記事でわかること

Kiro の「仕様駆動開発」という設計思想
Hooks・Steering・AgentSkills それぞれの役割と使い分け
Python プロジェクトで Kiro を使い始めるための最低限の設定
ファイル保存時の自動テスト・ドキュメント生成といった実践的な活用例

第1回（今回）：Hooks・Steering・Agents の基本概念＋ Python 自動化環境のセットアップ
第2回：Specs（仕様書）を使った要件定義 → 設計 → タスク分解の実践
第3回：Hooks を使った自動化レシピ集（テスト・ドキュメント・翻訳など）
第4回：Steering と AgentSkills を組み合わせたチーム開発向け設定

Kiro とはなにか

Kiro は AWS の agentic IDE で、少なくとも 2025 年には発表されているツールです。ベースは VS Code 系（Code OSS）なので見た目はほぼ見慣れた感じなんですが、コンセプトが「仕様駆動開発（Spec-Driven Development）」という点で他のツールと一線を画しています。

Cursor や GitHub Copilot は「プロンプトを投げたらコードが出てくる」という体験ですが、Kiro は少し違います。いきなりコードを書き始めるのではなく、まず要件（Requirements）を定義して、設計書（Design）を作って、タスクに分解（Tasks）してから実装する——という流れを IDE 側が構造として持っています。

この構造を支える三本柱が Specs・Steering・Hooks（＋ AgentSkills）です。

三つの主要機能を整理する

Hooks — イベント駆動の自動化トリガー

Agent hooks は、IDE 内で特定のイベントが発生したときにエージェントのプロンプトまたはシェルコマンドを実行する自動化トリガーです。いちいち「テスト書いて」「ドキュメント更新して」と手動で頼まなくても、ファイルを保存した瞬間に勝手にやってくれるイメージです。

トリガーの種類はいくつかあって、ファイルが保存されたとき、新しいファイルが作成されたとき、エージェントがツールを呼び出す前後（Pre Tool Use / Post Tool Use）、エージェントがターンを終えたとき（Agent Stop）などが対応しています。さらに spec のタスク実行前後にフックする「Pre Task Execution」「Post Task Execution」もサポートされています。

アクションは二種類。「エージェントプロンプト」と「シェルコマンド」が選べます。エージェントプロンプトでは、フックが発火するたびにそのプロンプトがエージェントへ送信されます。シェルコマンドは、コマンドが終了コード 0 で成功した場合、その stdout 出力がエージェントのコンテキストに追加されます。

Steering — エージェントへの永続的な指示書

Steering は「AI にこういう振る舞いをしてほしい」という指示を Markdown ファイルで書いておく仕組みです。チャットのたびにシステムプロンプトを書かなくていい、という理解が一番近いかもしれません。

ファイルの読み込みタイミングは YAML フロントマターで制御できます。Kiro は複数のインクルードモードをサポートしています。「Always」はすべてのインタラクションで読み込まれるデフォルト。「Manual」はチャットで `#steering-file-name` と参照したときだけ読み込まれます。「Conditional（fileMatch）」は、コンテキストに一致するファイルがあるときだけ読み込まれます。加えて「Auto（inclusion: auto）」もあり、description に基づいて自動的に含めることもできます。

ちなみに fileMatch は現時点でワークスペース専用の機能で、グローバルステアリング（`~/.kiro/steering/`）では動作しないという話もあるようです。グローバルに条件付きで読み込みたい場合は `inclusion: auto` で代替する、みたいなワークアラウンドが語られることもあります。このあたりはまだ発展途上感がありますね。

また、Kiro は AGENTS.md 標準もサポートしています。AGENTS.md はインクルードモードをサポートしない点を除けばステアリングファイルと同様の Markdown 形式で、ワークスペースルートや `~/.kiro/steering/` に置くと自動的に読み込まれます。

AgentSkills — 再利用可能なスキルパッケージ

AgentSkills は 2026 年 2 月中旬ごろの Kiro IDE のアップデートで入ってきた機能です。一見すると既存の Steering 機能と似ているように見えますが、設計思想と使い方が異なります。

大雑把に言うと、Steering は「このワークスペースの AI はこう振る舞え」というプロジェクト固有のルールで、AgentSkills は「この作業（コードレビュー、テスト、ドキュメント翻訳など）をするときのやり方」を SKILL.md に書いたポータブルなパッケージです。Steering はプロジェクトに紐づき、Skills はプロジェクト間で使い回せるイメージです。

Python プロジェクトのセットアップ

では実際に Python プロジェクトで Kiro を使い始めるための最低限の設定を入れてみます。ディレクトリ構成はこんな感じを想定します。

my-python-app/
├── .kiro/
│   ├── steering/
│   │   ├── project.md       # プロジェクト全体のルール
│   │   └── python-rules.md  # Python 固有のルール（fileMatch）
│   └── hooks/
│       └── auto-test.json   # ファイル保存時に自動テスト
├── src/
│   └── main.py
├── tests/
│   └── test_main.py
└── pyproject.toml

Steering ファイルを作る

まずプロジェクト全体に常時適用するステアリングファイルです。

# .kiro/steering/project.md
---
inclusion: always
---

# プロジェクト概要

このリポジトリは〇〇を行う Python アプリです。

## 基本ルール

- Python 3.12 以上を使用
- パッケージ管理は uv を使う
- テストは pytest で書く
- 型ヒントは必ず付ける（mypy strict モード想定）

次に Python ファイルを編集しているときだけ読み込む条件付きステアリングです。

# .kiro/steering/python-rules.md
---
inclusion: fileMatch
fileMatchPattern: "**/*.py"
---

## Python コーディング規約

- docstring は Google スタイルで書く
- 関数の行数は 30 行を目安に分割を検討する
- `print()` デバッグは絶対に残さない（logger を使う）
- 例外は素の `Exception` を catch しない

Hooks でファイル保存時に自動テストを走らせる

Hooks の設定は `.kiro/hooks/` 以下に JSON ファイルで置きます。ファイルを保存するたびに pytest を走らせるシンプルなフックです。

{
  "hooks": [
    {
      "name": "auto-pytest",
      "description": "src 配下の .py が保存されたら pytest を実行",
      "event": {
        "type": "file-saved",
        "filePattern": "src/**/*.py"
      },
      "action": {
        "type": "shell-command",
        "command": "uv run pytest tests/ -q --tb=short 2>&1 | tail -20"
      }
    }
  ]
}

コマンドが終了コード 0 で成功すれば stdout がエージェントのコンテキストに追加されるので、テスト結果を Kiro が把握して「3件失敗してますね、直しますか？」みたいな流れにつなげられます。

もう少し AI らしい使い方をするなら、アクションを `agent-prompt` に変えてこんな感じにもできます。

{
  "hooks": [
    {
      "name": "docstring-check",
      "description": "Python ファイル保存時に docstring の欠落をチェック",
      "event": {
        "type": "file-saved",
        "filePattern": "src/**/*.py"
      },
      "action": {
        "type": "agent-prompt",
        "prompt": "保存されたファイルを確認して、public な関数・クラスで docstring が抜けているものがあれば指摘してください。自動修正はしないでリストアップだけしてください。"
      }
    }
  ]
}

余談ですが、フックをうっかり全ファイルに広く設定すると、ちょっとした編集のたびにエージェントが走って思ったより重くなります。`filePattern` は絞るのがコツっぽいです。（自分は最初これで「なんか重い…」となりました）

ロケール翻訳フックの活用例

公式ドキュメントのサンプルが参考になるので紹介します。英語ロケールファイルが更新されたら翻訳を同期させるフックの例です。トリガーは `src/locales/en/*.json` へのファイル保存で、エージェントプロンプトで「追加・変更されたキーを他言語ファイルに反映し、未翻訳は `NEEDS_TRANSLATION` マーカーを付ける」という指示を送ります。こういった繰り返し発生する定型作業との相性は抜群です。