決まりと地図を渡す | Kiro と学ぶハーネスエンジニアリング 02

Kiro に渡す決まりと手順を、いつも読む Steering、決まったファイルを扱うときだけ読む Steering、要るときに開く Skill と Powers に分けて置き、何を書くかと、コードの地図 (どこに何を置くかの決まり、structure.md) の渡し方を説明します。会議室の予約アプリで、決まりと手順 (Steering と Skill) を足す前と後に同じ頼みを 3 回ずつ流し、テストを残さないなどの外れがどう変わったかを数え、傾向として比べます。シリーズ「Kiro と学ぶハーネスエンジニアリング」の 02 (導く) です。

Transcript

1. Kiro と学ぶハーネスエンジニアリング 導く 決まりと地図を渡す Steering、Skill、 Powers、コードの知識 02 2026-11 時点 2026 年 11 ⽉ 稲⽥ ⼤陸 アマゾン ウェブ サービス ジャパン + Kiro + Harness Engineering © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 1
2. はじめに ⾃⼰紹介 稲⽥ ⼤陸 いなだ りく (いなりく) アマゾン ウェブ サービス ジャパン合同会社 ソリューションアーキテクト 製造業のお客様を中⼼に⽀援 最近の取り組み AI 駆動開発ライフサイクルの推進 Kiro と AWS Amplify の情報発信 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. X @inada_riku Speaker Deck speakerdeck.com/inariku Zenn zenn.dev/inariku GitHub github.com/inariku 2
3. はじめに シリーズの中の位置 いまは 02 決まりと地図を渡す、次は 03 意図を仕様で渡す 考え⽅ 01 導く 前に読む 01 ハーネスエンジニアリング⼊⾨ 02–03 確かめる 決まりと 02 地図を渡す 04–05 囲う 04 機械で確かめる 次に読む 03 意図を 仕様で渡す © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 05 AI に確かめさせる 06 回す 06 できることを囲う 07–08 07 CI に載せる ハーネスを 08 育てる 3
4. はじめに この資料で分かること 導く仕組みは、置き場を分け、外したことを書き、⾜す前と後で⽐べる 1 置き場を分ける: いつも読む分は短くし、⻑い⼿順は Skill に。 2 地図 (structure.md) も決まりも、コードから読めないことと外したことを書く。 3 決まりと⼿順を⾜す前と後で、同じ頼みを流して効いたかを⽐べる。 前に読む資料: 01 ハーネスエンジニアリング⼊⾨。設定の仕⽅は ⽬指せ Kiro マスター 06〜08 (URL は最後のページ) 例は会議室の予約アプリ。試しは Kiro CLI 3.1.0、画⾯は Kiro IDE 1.4.121 図の⾊: 紫は要点と⼈が決める所、⻘は Kiro の動き、緑は通ったもの © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 4
5. 置き場と書き⽅ 導く仕組みの置き場 いつも読む、合うファイルで読む、要るときに開く、の 3 つに分けて置く いつも読む 合うファイルで読む 要るときに開く 毎回の頼みに⼊る そのファイルを扱うときに⼊る 頼みに合ったときだけ本⽂を開く Steering Steering Skill inclusion: always (既定) inclusion: fileMatch ⼿順書。説明が頼みに合えば開く AGENTS.md src/server/db.test.ts Powers inclusion の指定は効かない src/web/slots.test.ts 道具と⼿順書。決めた⾔葉で開く 向く中⾝ どの仕事にも効く、短い決まり 向く中⾝ テストの書き⽅など、⼀部の決まり 向く中⾝ ⻑い⼿順、外の道具の使い⽅ Steering は auto (説明が頼みに合えば読む。Skill に近い) と manual (#名前 で呼んだときだけ) でも置ける 設定の仕⽅: ⽬指せ Kiro マスター 06 (Steering)、07 (Powers)、08 (Skill)。コードを読む道具は 15 枚⽬ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 5
6. 置き場と書き⽅ 何を書くか 書くのは、Kiro が実際に外したことと、コードからは読めないこと 書く 書かない Kiro が実際に外したこと コードを読めば分かること コードからは読めないこと どこでも⾔える⼼がけ どこまでやるか 鍵やパスワード 同じ頼みを流して、2 回以上起きたもの 決めた理由、チームの事情、使わないと決めたもの 頼まれていないものを⾜すか、どこで⽌めて聞くか 関数の名前、ファイルの中⾝ (Kiro が読む) 「きれいに書く」「よく考える」 Steering はリポジトリに⼊る 1 つ⽬と 2 つ⽬は Böckeler から (何度も起きたら直す、「ここではそうしない」は Kiro に分からない)。3 つ⽬はこの資料のすすめ 理由と例を添えて、1 ファイルに 1 つの話題で書く (kiro.dev の Steering の Best practices) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 6
7. 置き場と書き⽅ いつも読む分は短く always の決まりは毎回の頼みに⼊る。⻑い⼿順は Skill に分ける 避けたい置き⽅: ⼿順も always に すすめる置き⽅: ⼿順は Skill に 頼み 1 決まり + ⼿順 (毎回) 頼み 頼み 2 決まり + ⼿順 (毎回) 頼み 頼み 1 決まり 名前と説明 頼み 頼み 2 決まり 名前と説明 頼み 合う頼みのときだけ本⽂ always の Steering は、どの頼みにも毎回⼊る。Skill は、始めに名前と説明だけが⼊り、頼みが合うと本⽂を開く Skill の参考資料 (references/) も、⼿順に書いたときだけ読まれる 出典: kiro.dev の Steering (Inclusion modes)、Agent Skills (How skills work)。枠の幅は⼤きさの⽬安で、測った値ではない © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 7
8. 置き場と書き⽅ AGENTS.md も読む AGENTS.md はいつも読まれ、下のフォルダに置いたものも⾒つけて読む 置き⽅の例 (会議室の予約アプリの場合) meeting-rooms/ いつも読む inclusion の指定は効かない (always と同じ) AGENTS.md .kiro/steering/ 下のフォルダのものも⾒つけて読む src/server/ 説明するコードの隣に置ける。どれも毎回読む AGENTS.md src/web/ AGENTS.md #[[file:...]] の道は、そのフォルダから Steering の中の道はワークスペースの最上位から ~/.kiro/steering/ (⾃分の全部のワークスペース) の AGENTS.md も読む。リポジトリに置いた分は git でチームに渡る © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 8
9. 置き場と書き⽅ 今の Steering を仕分ける 決まりは Steering に、くり返す⼿順は Skill に。上から順に当てはめる 今の Steering を 1 つずつ⾒て、上から順に当てはまるかを聞く 1 どの頼みにも要り、数⾏で書ける決まり 2 決まったファイルを扱うときだけ要る決まり 3 決まった話題の頼みのときだけ要る決まり 4 何段もの⼿順。スクリプトや資料も添えたい 5 ⼈が呼びたいときだけ使う はい はい はい はい はい always Steering か AGENTS.md fileMatch fileMatchPattern にファイルの形を書く auto name と、いつ使うかの description を書く Skill SKILL.md と scripts/、references/ manual チャットで #名前 と打って読ませる 聞く順はこの資料のすすめ。kiro.dev は Steering を決まりと慣習に、Skill を⼈と分けたり取り込んだりする⼿順に使うとしている ⽂書は auto と manual にも⻑い⼿順を置けるとしている。この資料は⼿順を Skill にまとめる。外の道具は Powers (14 枚⽬) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 9
10. 例題 例題で起きた外れ 決まりなしで同じ頼みを 3 回流すと、3 つの外れが 3 回とも起きた 頼み:「予約の延⻑の機能を⾜して」 延⻑は、例題の Spec の要件で「対象外」に⼊っている 1 回⽬ 2 回⽬ 3 回⽬ 確かめのテスト 残さない 残さない 残さない Spec の「対象外」 直さない 直さない 直さない 前から落ちる性質 11 調べ直した 調べ直した 調べ直した ほしかった動き / 起きたこと テストを残し、次の変更でも流れるように 2 回は「頼まれていない」が理由 延⻑を先に Spec の要件に⾜す 報告の最後で、直すかを⼈に任せた 既知と報告して先へ進む 時間を測り、変更前のコードで流し直した Kiro の報告:「頼まれていないので、テストはリポジトリに⾜していません」(2 回⽬) API の形は回ごとに違った (POST .../extend が 2 回、PATCH が 1 回)。決まりに無いことは、そのつど Kiro が決める Spec: 要件と設計を書いた .kiro/specs/ のファイル (03 で扱う) 性質 11: 機械が混むと 5 秒の上限で落ちる、前からあるテスト。既知だと決まりに書くまで、Kiro は毎回時間をかけて調べ直した © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 10
11. 例題 いつも読む決まりを 2 ⾏⾜す 3 回とも起きた外れのうち、どの仕事にも効く 2 つを always の Steering に書く Kiro のパネルのワークスペースの欄 テストを残すことと、Spec の対象外を先に直すことは、 どの機能を⾜すときにも要る。だから always にした。 どちらも理由を 1 ⽂で添えた。 右は .kiro/steering/working-rules.md。上の --- の中の inclusion: always が「毎回読む」 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 11
12. 例題 テストのときだけ読む決まり 前から落ちるテストのことは、テストのファイルを扱うときだけ読ませる (fileMatch) fileMatchPattern に合うファイルを Kiro が扱う ときだけ読まれる。 前から落ちるテストのことは、テストを書くときにしか 要らないので、ここに置いた。 左は .kiro/steering/testing.md の頭、右は本⽂。CLI で fileMatch が 効くのは V3 のセッション (付録 A1) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 12
13. 例題 ⻑い⼿順は Skill に 機能を⾜す⼿順は Skill に置き、頼みが説明に合ったときだけ本⽂を開く 始めに読まれるのは、左の name と description だけ。 頼みが説明に合うと、右の⼿順を開く。 ⼿順は 5 つ (要件を先に⾜す、テストを先に書く、作る、 確かめる、報告する)。 置き場所は .kiro/skills/add-feature/SKILL.md。右は⼿順の 1 と 2 で、always の 2 ⾏と同じことを重ねて書いた (重ねると⾷い違いのもと、18 枚⽬) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 13
14. 外の道具 外の道具は Powers で 外の道具とその使い⽅は Powers で⼊れ、話が合ったときだけ読み込む 1 つの Power 頼みを読み、⼊っている Power と照らす ⽂書の例: 「payment」と話すと Stripe の Power が開く plugin.json 名前と、開くきっかけの⾔葉 skills/ 合った Power 道具と⼿順を読み込む ⼿順書 (Agent Skills) mcp.json 道具 (MCP サーバー) 合わない Power 読み込まない MCP サーバーを全部つなぐと、道具の説明だけで⽂脈を使う。Power は要るときだけ道具を読み込む ⼊れ⽅: IDE の Powers のパネル (kiro.dev/powers、GitHub の URL、⼿元のフォルダ)、CLI の /powers install。設定は⽬指せ Kiro マスター 07 例題では Powers を⼊れていない。この⾯は kiro.dev の⽂書から描いた © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 14
15. 地図を渡す 地図を渡す コードを読む道具は Kiro が持っている。⾜すのは、置き場の決まりとその理由 Tree-sitter (⼊っている) LSP (⾔語サーバーを⼊れると) IDE、CLI、Web、Mobile のどれでも。18 の⾔語 IDE と CLI。IDE は⾔語の拡張、CLI は⾔語サーバーと /code init 記号を探す ファイルの⾒出し 関数、クラスを名前で 中の関数の⼀覧 形で探す 全体の⾒取り図 コードの構造で当てる Codebase overview 呼んでいる所を探す 定義へ⾶ぶ 名前を付け替える エラーと警告 型の説明 どちらも、コードを調べるときに Kiro が⾃分で使う。モデルの推測でなく、プログラムが答えを返す導く仕組み (Böckeler) 例題の試し (/code init はしていない) では、Kiro はこの道具を使わず、ファイルを直接読んだ。⾜すのは、置き場の決まりと理由 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 15
16. 地図を渡す 地図の書き⽅の例 書くのは、どこに何を置くかの決まりとその理由。ファイルの⼀覧は書かない .kiro/steering/structure.md の例 (会議室の予約アプリ) # フォルダの分け⽅ - src/web/ から src/server/ を import しない。 画⾯は api.ts を通して /api だけを呼ぶ 理由: 画⾯ (Vite) と API (node:http) は、 別のプロセスで⽴てる - 時刻は DB では UTC で持ち、 画⾯に出すときだけ⽇本時間にする 書く: 決まりと理由 import の向き、時刻の持ち⽅。 コードの形からは、守る理由が読めない 書かない: ファイルの⼀覧 「app.ts が⼊⼝」などは、 Kiro がコードを読めば分かる 置き場 structure.md も AGENTS.md も毎回読まれる。 画⾯のファイルだけで要るなら fileMatch に 左は、例題の README とコードにある事実を、この資料で書き起こしたもの。例題のリポジトリには⼊れていない 書く、書かないの線はこの資料のすすめ。kiro.dev は structure.md にファイルの置き⽅、名前の付け⽅、import の形も書くとしている © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 16
17. ⽐べる 効いたかを⽐べる 同じ頼みを、決まりと⼿順を⾜す前と後で 3 回ずつ流して数える ⾜す前 ⾜したあと 確かめのテストを残した 0/3 3/3 Spec の「対象外」を先に直した 0/3 3/3 落ちた 3 回中 0 落ちた 2 回中 1 前から落ちるテストを調べ直さなかった ⾜したあと = always の 2 ⾏、testing.md (fileMatch)、Skill をまとめて⾜した。3 回とも Skill を開いて進めた どれが効いたかは、この試しでは分けていない。守るかは Kiro が決める: 1 回は性質 11 を変更前のコードで流し直した 決まりに無い API の形は、⾜したあともばらついた。3 回ずつなので、数は傾向として読む 1 回の時間は、⾜す前 7〜9 分、⾜したあと 6〜8 分で、差があるとは⾔えない。流し⽅は付録 A1 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 17
18. ⾒直す 決まりどうしの⾷い違い 決まりは増えると古くなり、⾷い違う。決まりもコードと同じく⾒直す 決まりが増えると起きること 1 古い決まり 消したフォルダを指したまま 2 ⾷い違う決まり ⽚⽅は「聞く」、⽚⽅は「任せる」 コードと⼆重 書き写した値がコードと違う ? 3 4 決まりの変更も、コードと同じくレビューする kiro.dev の Best practices 書き写さず、#[[file:...]] で今のファイルを指す 解けない参照は印が残る 構成を変えたら、参照と決まりを⾒直す kiro.dev の Best practices ⾷い違えばワークスペースが勝つ (グローバルより) kiro.dev の Steering file scope ⼤きくなっても⾷い違わないように保つ⽅法は、まだ決まった答えがない (Böckeler の結びの問い) この資料のすすめ: 決まりは 1 か所に置き、ほかは参照する。⾜す前と後で、同じ頼みで⽐べる (17 枚⽬) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 18
19. まとめ まとめ 導く仕組みは、置き場を分け、外したことを書き、⾜す前と後で⽐べる 1 置き場を分ける: いつも読む分は短くし、⻑い⼿順は Skill に。 2 地図 (structure.md) も決まりも、コードから読めないことと外したことを書く。 3 決まりと⼿順を⾜す前と後で、同じ頼みを流して効いたかを⽐べる。 次に読む資料 このシリーズ このシリーズ ⽬指せ Kiro マスター ⽬指せ Kiro マスター 03 意図を仕様で渡す 04 機械で確かめる 06 Steering と Hook 07 Powers、08 Skill 何を作るかを先に渡す 外れをテストで返す Steering の設定の仕⽅ Powers と Skill の設定の仕⽅ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 19
20. 付録 A1 ⾜す前と後の⽐べ⽅ (この資料の試しでしたこと) すること この資料の試しでしたこと 頼みを 1 つ決める ふだん頼む仕事に近いもの。ここでは「予約の延⻑の機能を⾜して」 2 毎回、同じ状態から始める git worktree で、⾜す前の commit と⾜したあとの commit から 3 つずつフォルダを作った 3 ⾃分の設定を混ぜない HOME を空のフォルダにして流した。中は ~/Library/Application Support/kiro-cli (macOS のサインインのデータ) へのリンクだけ。~/.kiro/ を読ませないため 4 画⾯なしで流す kiro-cli chat --v3 --no-interactive --trust-workspace --trust-all-tools "頼み"。出⼒をログの ファイルに残した 1 5 外れを数える 6 どれが効いたかを知るなら 前もって決めた項⽬を、ログと git status で⾒た (テストのファイル、requirements.md、性質 11 を流し直したか) 1 つずつ⾜して流す。この試しでは、always、fileMatch、Skill をまとめて⾜した V3 は Kiro CLI の新しい動き⽅ (--v3 で選ぶ)。CLI で Steering の 4 つの読み⽅が全部効くのは V3。 --trust-all-tools は確かめずに道具を使わせるので、捨ててよいフォルダで流す。 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 20
21. 付録 A2 ⽤語 ⽤語 意味 ⽤語 意味 Spec 要件と設計のファイル (03) V3 CLI の新しい動き⽅ (A1) 導く仕組み 動く前に⽅向を決める (ガイド) Skill 要るときに開く⼿順書 Steering 読ませる決まりの Markdown Agent Skills Skill のフォルダの決まった形 inclusion Steering を読ませる条件 Powers 道具と⼿順書のセット always 毎回読む (既定) MCP 外の道具をつなぐ決まった形 fileMatch 合うファイルのときに読む コードの知識 Tree-sitter と LSP auto、manual 説明が合うとき、呼んだとき Tree-sitter コードの形を読む (⼊っている) AGENTS.md いつも読まれる決まり LSP ⾔語サーバー (定義など) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 21
22. 付録 A3 出典と参考 kiro.dev のドキュメント (2026-11-09 に .md 版を読んだ) Steering、Agent Skills、Powers、Install powers、Code intelligence https://kiro.dev/docs/ Birgitta Böckeler「Harness engineering for coding agent users」(2026-04-02) https://martinfowler.com/articles/harness-engineering.html 設定の仕⽅: ⽬指せ Kiro マスター 06 Steering と Hook、07 MCP と Powers、08 Skill とカスタムエージェント (Speaker Deck) https://speakerdeck.com/inariku 画⾯: Kiro IDE 1.4.121 (2026-11-09 に撮った)。試し: Kiro CLI 3.1.0 を画⾯なしで流した (2026-11-09)。 例題は⽬指せ Kiro マスターで使った会議室の予約アプリ。例題のコードは公開していない。 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 22