機械で確かめる | Kiro と学ぶハーネスエンジニアリング 04

Kiro CLI の Hook で、型とテストのように機械で流せる確かめを答えて止まるとき (Agent Stop) に流し、テストのファイルを消す操作を道具を使う前 (Pre Tool Use) に止めて、落ちた理由と直し方を Kiro に返す方法を説明する配布資料です。構造のテスト (どのコードが何を呼ぶかの確かめ) の書き方も扱います。会議室の予約アプリの例題で、Hook の無いまま頼みを 4 回流した記録と、Hook を足して同じ頼みを流した画面、人が「消して」と頼んで Pre Tool Use の Hook が止めた画面を載せています。シリーズ「Kiro と学ぶハーネスエンジニアリング」の 04 (確かめる) です。

Transcript

1. Kiro と学ぶハーネスエンジニアリング 確かめる 機械で確かめる テスト、型、lint を Hook で返す 2026-11 時点 2026 年 11 ⽉ 稲⽥ ⼤陸 アマゾン ウェブ サービス ジャパン 04 + 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. はじめに シリーズの中の位置 いまは 04 機械で確かめる、次は 05 AI に確かめさせる 考え⽅ 01 導く 前に読む 01 ハーネスエンジニアリング⼊⾨ 02–03 確かめる 決まりと 02 地図を渡す 意図を 03 仕様で渡す © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 04–05 囲う 04 機械で確かめる 次に読む 05 AI に確かめさせる 06 回す 06 できることを囲う 07–08 07 CI に載せる ハーネスを 08 育てる 3
4. はじめに この資料で分かること 決まった結果を返す確かめを、Kiro が終える前に Hook で流し、直し⽅つきで返す 1 機械の確かめ (テスト、型、lint、構造のテスト) が⾒るもの。 2 Kiro が⽌まる前と道具を使う前に、Hook で確かめを流す⽅法。 3 Kiro が読んで直せるように、落ちた理由を返す書き⽅。 前に読むとよい資料: 01 ハーネスエンジニアリング⼊⾨。Hook の作り⽅は ⽬指せ Kiro マスター 06 Steering と Hook 例は会議室の予約アプリ (⽬指せ Kiro マスターと同じもの)。画⾯は Kiro CLI 3.1.0 で撮った 図の⾊: 紫は要点と⼈が決める所、⻘は Kiro の動き、緑は通ったもの © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 4
5. 考え⽅ 機械の確かめ テスト、型、lint、構造のテストは、速く、毎回同じ結果を返す 画⾯ 10:00 : 時刻 DB テスト 型 lint 構造のテスト 頼んだとおりに動くか 値の形が合っているか 書き⽅の決まりに合うか どのコードが何を呼ぶか 例題: Vitest 100 件、約 9 秒 例題: tsc --noEmit、約 4 秒 例題には⼊れていない 例題に 1 つ⾜す (12 枚⽬) どれも CPU が決まった結果を返す。速く、同じ⼊⼒には毎回同じ答え 意味を⾒る確かめ (AI のレビュー) は揺れるが、機械では⾒られないものを⾒る。資料 05 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 5
6. 考え⽅ Hook の出番 Kiro の 1 回の番のうち、頼み、道具の前と後、ファイルの変更、⽌まる前で流せる ⼈の頼み 道具を使う ファイルを変える 答えて⽌まる 道具とファイルの変更を何度もくり返す Prompt Submit Pre Tool Use File Save など Agent Stop 頼みが届いたとき 道具を使う前 Kiro がファイルを変えたとき 答えて⽌まるとき 頼みに⽂脈を⾜す exit 2 で道具を⽌める ⼈の保存では動かない Kiro を続けさせられる (CLI) ◆ が Hook のきっかけ (主なもの)。紫は⽌めたり続けさせたりできるもの。Post Tool Use は道具のすぐあと IDE と CLI で動き、Kiro Web のセッションでは動かない。File の 3 つは Kiro が変えたときだけ動く (Hook types の File Create、File Save)。きっかけの⼀覧は 付録 A1 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 6
7. 例題 Hook を⾜す前の試し 決まりも Hook も無い例題に、同じ頼みを流して起きたことを記録した 頼み Kiro がしたこと Kiro の最後の報告で落ちたテスト 部屋で絞り込む 作らずに 1 つ聞いた (頼みがあいまい) — (作っていない) 参加⼈数と定員 型とテストを⾃分で流して終えた 117 件のうち 1 件 予約の取り消し 型とテストを⾃分で流して終えた 108 件のうち 1 件 参加⼈数と定員 (2 回⽬) 型とテストを⾃分で流して終えた なし (118 件とも通った) 落ちたのは前からある遅いテスト (ファイルの DB に 100 回書く性質のテストが、5 秒の時間切れ)。Kiro は報告に 「落ちています」と書いたが、番は「終わった」で閉じた。流すか、落ちたらどうするかは毎回 Kiro の判断 参加⼈数を、1 回⽬は任意、2 回⽬は必須にした。どちらも型とテストは通る (意味の違いは機械では⾒えない。資料 05) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 7
8. 例題 ⽌まる前に型とテスト Agent Stop の Hook で型とテストを流し、落ちたら理由をつけて Kiro を続けさせる Kiro がもう⼀度動く .kiro/hooks/check-before-stop.json 答えて⽌まる { "version": "v1", "hooks": [{ "name": "⽌まる前に型とテスト", "trigger": "Stop", "action": {"type": "command", "command": "node .kiro/hooks/check-before-stop.mjs"}, "timeout": 180 }] 落ちた 理由と直し⽅ Agent Stop の Hook を返す 型 (tsc) → テスト (Vitest) 通った 終わる 続けさせるのは 3 回まで (例題の決め) 試しの 1 回では、続けた番の終わりに Hook は動かなかった © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. } 落ちたら STDOUT に {"decision": "block", "reason": ...} を出 して exit 0。Kiro CLI は reason を読んで次の番を始める。 名前は block だが、Stop では「続けさせる」の意味。この続け⽅は Kiro CLI の ⽂書の動きで、例題も CLI で確かめた。IDE で次の番が始まるかは⽂書に書か れていない。スクリプトの要点は付録 A2 8
9. 例題 落ちたら Kiro が直す Hook が落ちたテストを返すと、Kiro はその理由を読んで直し、もう⼀度確かめた ① 1 回⽬の答え。性質 11 の落ちは「今回の変更とは別」 ③ 続けた番の終わりの答え ② Stop の Hook が落ちを返し、Kiro は時間を測り始めた 頼みと落ちたテストは 7 枚⽬と同じ。Kiro はテストを変えずに DB の作り⽅を直した。続けた番の終わりに Hook はもう⼀度は動かず、2 回⽬の確かめは Kiro が⾃分で流した (121 件が通ることは私も確かめた)。会話を開き直して撮った画⾯なので、Hook の⾏は出ない © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 9
10. 例題 道具の前で⽌める Pre Tool Use の Hook で、テストのファイルを消す操作を⽌める 「src/server/app.test.ts を消して」と頼んだとき app.test.ts を消す (書き込みの道具か rm) Pre Tool Use テストを消す? exit 2 消さない 理由が Kiro に ほかの道具は exit 0 で、そのまま動く ⽌めたい形は⾃分で並べる (例: git rm も) 試しの 5 回で、Kiro がテストを消そうとしたことは無い。画⾯は⼈が頼んで撮った。⽌まったのは名前に delete を含む書き込みの道具 (matcher の write に当 たる)。⽌めるには exit 2 を使う (STDERR が Kiro に返る)。CLI では、ほかの exit コードは警告だけで道具は動く © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 10
11. 例題 Kiro に読ませる⾔葉 何が悪く、どう直すかを、テストと lint の出⼒に書く 落ちたことしか分からない 何が悪く、どう直すかまで書く AssertionError: 画⾯のコードは src/server を読まない。 expected [ '../server/rooms.ts' ] 部屋や予約は api.ts の関数で /api から取る to deeply equal [] src/web/App.tsx が ../server/rooms.ts を読んで… 何が悪く、どう直すかは書いていない。 直す場所と直し⽅が、⽂から分かる Kiro は出⼒から推し量るしかない (落ちた画⾯は 12 枚⽬) テストや lint のメッセージは、Kiro が読む指⽰にもなる。直し⽅を 1 ⾏で書く 左の⽂は Vitest の既定の形 (例として書いた)。右は例題の構造のテストの⽂ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 11
12. 例題 構造のテスト 「画⾯のコードから src/server を読まない」を、テストで確かめる src/web/structure.test.ts (要点) App.tsx に src/server の import をわざと 1 ⾏⾜した it("画⾯は src/server を読まない", () => { const found = []; for (const file of sources(WEB)) for (const m of importsOf(file)) if (/(^|\/)server(\/|$)/.test(m)) found.push(`${file} が ${m} を読んでいる`); expect(found, [ "画⾯のコードは src/server を読まない。…", "⾜りない関数は api.ts に⾜す。", ...found, ].join("\n")).toEqual([]); }); Vitest の普通のテストとして書いたので、npm test と Agent Stop の Hook でそのまま流れる。試しの 5 回で、画⾯のコードが src/server を読んだことは無い。 画⾯は、⼈がわざと壊して撮った © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 12
13. 選び⽅ 速い順に並べる 数秒で終わるものは Kiro が書いたその場で、重いものは CI と定期の仕事で Kiro が書いたとき Kiro が⽌まる前 PR を出したとき 毎⽇や毎週 File Save の Hook Agent Stop の Hook CI (資料 07) 定期の仕事 (資料 08) 速い 遅い lint、整形など 型 4 秒 + テスト 9 秒 全部のテスト、 依存の古さ、 1 ファイルで済むもの (例題で測った) 画⾯を動かす確かめ 使われないコード 速く終わるものほど前に置き、Kiro が書いたその場で返す。重いものは後ろで、⼈より先に © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 13
14. 選び⽅ 確かめやすいコード 型のある⾔語やはっきりした境界は、機械の確かめを作りやすい 確かめを作りやすい 確かめを作りにくい 型のある⾔語 型が無い 境界がはっきり どこからでも呼べる 決まった作り 作りがまちまち 型の確かめがそのまま使える 「何が何を呼ぶか」をテストにできる 置き場所の決まりを書ける 値の形は動かすまで分からない 境界の決まりを書きようがない 決まりの例外ばかりになる 例題は TypeScript で、画⾯ (src/web) と API (src/server) の境界がある。確かめが要るのは、右のようなコードのほう © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 14
15. 選び⽅ 鳴らない確かめ ⼀度も落ちない確かめは、わざと壊して鳴ることを⾒る どちらか分からない ① 決まりが守られている ② 確かめが⾒落としている ⼀度も鳴らない確かめ 例: 構造のテスト ? わざと 1 か所壊して、 鳴ることを⾒る ⾒たら元に戻す 例題では、画⾯のコードに src/server の import を 1 ⾏⾜し、構造のテストが落ちるのを⾒てから戻した 問いは Böckeler の記事から。確かめ⽅はこの資料のすすめ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 15
16. まとめ まとめ 決まった結果を返す確かめを、Kiro が終える前に Hook で流し、直し⽅つきで返す 1 テスト、型、lint、構造のテストは、速く毎回同じ結果を返す。 2 Agent Stop の Hook で⽌まる前に流し、Pre Tool Use の Hook で消す操作を⽌める。 3 落ちたときの⽂に直し⽅を書く。鳴らない確かめは、わざと壊して鳴るかを⾒る。 明⽇からの 1 ⼿: いま⼿で流しているテストと型の確かめを、Agent Stop の Hook に置く (付録 A2、Kiro CLI で確かめた形) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 16
17. まとめ 次に読む資料 意味を⾒る確かめは 05、重い確かめを PR で流すのは 07 このシリーズ 05 このシリーズ 07 ⽬指せ Kiro マスター 06 AI に確かめさせる CI に載せる Steering と Hook 意味を⾒るレビュー役 重い確かめを PR で Hook の作り⽅と画⾯ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 17
18. 付録 A1 Hook のきっかけの⼀覧 きっかけ JSON の trigger IDE CLI きっかけ JSON の trigger IDE CLI Prompt Submit UserPromptSubmit ◦ ◦ Post Tool Use PostToolUse ◦ ◦ Agent Stop Stop ◦ ◦ File Create PostFileCreate ◦ V3 Session Start SessionStart ◦ V3 File Save PostFileSave ◦ V3 Agent Spawn AgentSpawn — 2.x、 V3 別名 File Delete PostFileDelete ◦ V3 Session End SessionEnd — V3 Pre Task Execution PreTaskExec ◦ V3 Pre Compaction PreCompact ◦ V3 (3.1.0) Post Task Execution PostTaskExec ◦ V3 Post Compaction PostCompact ◦ V3 (3.1.0) Manual Manual — V3 ⼀覧のみ Pre Tool Use PreToolUse ◦ ◦ Legacy Manual Hook (IDE 0.x) 旧版のみ — Web のセッションでは、どのきっかけも動かない。⽌められるのは Pre Tool Use と Pre Task Execution (exit 2)、Pre Compaction (exit 2 で要約を取り消す)、 IDE の Prompt Submit。 CLI の Agent Stop は⽌めるのではなく、Kiro をもう⼀度動かす (decision block か exit 1)。File の 3 つは Kiro が変えたときだけ。 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 18
19. 付録 A2 例題の Hook のスクリプト (要点) .kiro/hooks/check-before-stop.mjs const checks = [ ["型", "npm", ["run", "--silent", "typecheck"]], ["テスト", "npx", ["vitest", "run"]], ]; const fails = checks.filter(落ちたもの); if (fails.length === 0) process.exit(0); // tries: session_id ごとに⼀時ファイルで数える if (tries >= 3) process.exit(0); // ⼈に任せる process.stdout.write(JSON.stringify({ decision: "block", reason: "答える前に直す。テストを消す、" + "skip、期待を書き換える、では通さない" + 落ちた所の要約, })); .kiro/hooks/guard-tests.mjs const event = JSON.parse(STDIN); const input = JSON.stringify(event.tool_input); const hit = input.match(/[\w./-]*\.test\.tsx?/); const deleting = /delete/i.test(event.tool_name) || /(^|[\s;&|("'])(rm|unlink|git\s+rm|mv)\s/ .test(input); if (hit && deleting) { console.error("テストのファイルは消さない。" + "落ちるならコードを直す"); process.exit(2); // 道具を⽌める } process.exit(0); どちらも Node.js の標準の機能だけで書き、Kiro CLI 3.1.0 で確かめた。guard-tests.json は trigger が PreToolUse の Hook を 2 つ並べ、matcher を "shell" と "write" に 1 つずつ書いた。 書き込みの本⽂に「 rm 」のような語があると、テストのファイルの書き換えも⽌まることがある。例題のコードは公開していない。ここに載せたのは要点。 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 19
20. 付録 A3 ⽤語 ⽤語 意味 ⽤語 機械の確かめ CPU が決まった結果を返す確かめ Agent Stop lint 書き⽅の決まりを⾒る道具 Pre Tool Use 道具を使う前のきっかけ matcher Hook の対象の条件 型の確かめ 値の形が合うかを⾒る (tsc など) 意味 Kiro が答えて⽌まるときの きっかけ 構造のテスト どのコードが何を呼ぶかの確かめ exit 2 道具の前の Hook が⽌める合図 Hook きっかけで動く処理 decision block Stop の Hook が続けさせる合図 確かめやすさ 確かめを作りやすいコードの性質 STDIN、STDOUT Hook に渡る⼊⼒と、返す出⼒ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 20
21. 付録 A4 出典と参考 Birgitta Böckeler「Harness engineering for coding agent users」(martinfowler.com、2026-04-02) https://martinfowler.com/articles/harness-engineering.html kiro.dev のドキュメント (2026-11-09 に .md 版を読んだ): Hooks、Hook types、Hook actions、Hook best practices、Hook management、What's new in IDE 1.0: Hooks https://kiro.dev/docs/hooks/ 画⾯: Kiro CLI 3.1.0 (2026-11-09 に撮った)。例題は ⽬指せ Kiro マスターの会議室の予約アプリの写し (公開していない)。 9 枚⽬は Hook のある試しの会話を開き直した画⾯、10 枚⽬は⼈が消してと頼んだ画⾯、12 枚⽬はわざと壊した画⾯。 試しの記録 (7 枚⽬) は、Steering と Hook の無い例題に、組み込みの道具だけのエージェントで同じ頼みを流したもの。 時間はこの Mac で測った値で、⽬安。 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 21