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

テスト、型、lint、構造のテストのように決まった結果を返す確かめは、形の外れを速く、毎回同じ結果で捕まえます。この資料では、そうした確かめを Kiro が答え終えたところ (Agent Stop) の Kiro CLI の Hook で流し、落ちた理由と直し方を数行で Kiro に返す方法と、道具を使う前 (Pre Tool Use) の Hook で危ない操作を止める方法を、Anthropic、OpenAI、martinfowler.com などの公開の記事と kiro.dev のドキュメントを元にイメージ図で説明します。あわせて、「予約しました」という言葉ではなく DB に予約の行があるかという状態で確かめること、層の向きのような変わらない決まりを lint で守ること、一度も落ちない確かめを疑うことも扱います。説明用に作った小さな会議室の予約アプリで、Hook が落ちたテストを返して Kiro が直すところ、テストと API が通っても DB の行を数える確かめが「予約が残らない」を捕まえるところ、テストのファイルを消す操作を Hook が止めるところ、305 行あったテストの出力を 14 行にまとめて返す確かめ、構造のテストと層の lint が直し方を返すところを、Kiro CLI と端末の本物の画面で見せます。シリーズ「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 仕様で渡す 04–05 囲う 04 機械で確かめる 次に読む 05 AI に確かめさせる 06 回す 06 できることを囲う 07–10 07 CI に載せる ハーネスを 08 育てる ⻑い仕事を 09 回でつなぐ ハーネスが 10 効いたかを測る © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 3
4. はじめに この資料で分かること 決まった結果を返す確かめを、Kiro が答え終えたところで Hook で流し、直し⽅つきで返す 1 機械の確かめが捕まえるものと、捕まえないもの。 2 Kiro が答え終えたところと道具を使う前に、Hook で確かめを流す⽅法。 3 ⾔葉ではなく状態を⾒て、直し⽅つきで短く返す書き⽅。 前に読むとよい資料: 01 (ハーネス = モデルの外側で Kiro を導き、確かめる仕組み)。Hook の作り⽅は 「⽬指せ Kiro マスター」06 この資料では、説明⽤に作った会議室の予約アプリ (⽬指せ Kiro マスターと同じもの) で試す 図の⾊: 紫は要点、⼈が決める所、外れ (⾍や × の札)。⻘は Kiro の動き、緑は通ったもの © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 4
5. 考え⽅ 機械の確かめ テスト、型、lint、構造のテストは、速く、同じ⼊⼒に同じ結果を返す イメージ図 テスト 型 lint 構造のテスト どれも CPU が動かす確かめで、ミリ秒から秒で終わる (予約アプリでは型が 1 秒未満、テスト 121 件が 3 秒未満)。時間 に頼るテストは揺れて、同じ結果にならないことがある。意味を⾒る確かめは 05 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 5
6. 考え⽅ 機械で捕まるもの、捕まらないもの 形の外れは確かに捕まえる。頼みの読み違いや作りすぎは、確かには捕まえない 頼みの読み違い イメージ図 形の外れ 機械が確かに捕まえるのは、重複、複雑すぎる分岐、テストの抜け、作りのずれ、書き⽅の違反のような形のこと。⾒ ⽴て違い、作りすぎ、頼みの読み違いは、ときどき捕まえても確かではない (Böckeler)。意味を⾒るのは 05 と⼈ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 6
7. 考え⽅ 確かめる役はほぼ完全に 確かめが⽢いと、エージェントは違う問題を解く。外れを⾒るたびに確かめを⾜す ⽳ イメージ図 外れのたびに⾜す Anthropic の試しでは、エージェントの外れを⾒るたびにテストを⾜し、新しい変更が前の機能を壊せないように CI を厳しくした (2026-02)。直すべきテストが通り、前から通るテストも通り続けるかを⾒る (2026-01) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 7
8. 考え⽅ ⾔葉ではなく状態で確かめる 「予約しました」と答えたかではなく、DB に予約の⾏があるか イメージ図 予約しました DB の⾏は 0 件 単体テストや curl で済ませると、頼みから保存まで続けて動かないことに気づかずに「済み」になった (Anthropic 2025-11)。アプリの画⾯、ログ、指標を Kiro が読める形にする (OpenAI 2026-02)。予約アプリでの試しは 13 枚⽬ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 8
9. 考え⽅ Hook の出番 Kiro の番の中で、頼み、道具の前、ファイルの変更、答え終えた所で流せる イメージ図 Prompt Submit Pre Tool Use File Save Agent Stop 番 = 頼みから答え終えるまで。Hook は .kiro/hooks/ の JSON に、きっかけとコマンドを書く。Web では動かず、CLI の対話ではフォルダを信頼するまでその Hook を読まない。ほかのきっかけは付録 A1。始める前の点検は 09 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 9
10. 考え⽅ Hook を⾜す前の試し 決まりも Hook も無い予約アプリでは、4 回のうち 2 回、落ちたテストを残して終えた イメージ図 終わりました 報告には「落ちています」 1 件落ちた回が 4 回中 2 回 頼みは 3 種類 (参加⼈数は 2 回)。落ちたのは前からある遅いテストで、Kiro は報告に書いたまま番を閉じた © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 10
11. 予約アプリで試す 「確かめた」の決まりを Hook に置く Agent Stop の Hook が、このリポジトリの「確かめた」の決まりになる 答えて⽌まる 答え終えたところで scripts/check.mjs (4 つの 落ちた 理由を返し Agent Stop の Hook 次の番へ check.mjs を流す 確かめ) を流し、落ちたら decision block と理 由を返す。Kiro CLI は理由を読んで次の番を 始める。 続けた番の終わりに Hook は動かなかった。 通った 直したあとの確かめは理由の⽂で頼む。 終わる 試した回のどれも同じで、⽂書には書かれていない。続けた番が落ちたまま終わっても⽌めないので、最後の結果は⼈ が⾒る。IDE では確かめていない。JSON とスクリプトは付録 A2 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 11
12. 予約アプリで試す 落ちたら Kiro が直す Hook が落ちたテストを返すと、Kiro は理由を読んで直した ① 1 回⽬の答え。性質 11 の落ちは「今回の変更とは別」 続けた番で、Kiro はテストを 変えずに DB の作り⽅を 直した。 ② Stop の Hook が落ちを返し、Kiro は時間を測り始めた この回の Hook は前の版 (型とテストだ け、2026-11-09)。121 件が通ることは 私も流して確かめた。2 回⽬の確かめ は Kiro が⾃分で流した © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 12
13. 予約アプリで試す 予約の⾏を確かめる試験 テストも API の 201 も通ったが、DB の⾏を数える試験が「予約が残らない」を捕まえた ⼈が index.ts の 1 ⾏を「DB をメモリーに置く」に変えてから、/api/health に version を⾜して、と頼んだ check.mjs には、本物のサーバーで予約を 1 件作り、DB のファイルの⾏を数える試験を ⾜してあった。 npm run check は scripts/check.mjs を流す。Kiro はこのあと、⼈に聞いて⽌まろうとした (次の⾯) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 13
14. 予約アプリで試す 聞いて⽌まろうとしたら、Hook が続けさせた Kiro は⼈の変更を戻してよいかを聞いて終えようとし、Hook の理由を読んで直した ① 最初の答えの終わりと、Hook のあとの 1 ⽂⽬ ② 最後の答え 同じ頼みを 3 回流し、2 回は Hook が続けさせて直し、1 回は Kiro が⾃分で直した。⼈の変更を戻すかを⼈が決めたい なら、Hook の理由の⽂にそう書く (予約アプリの⽂は「コードの⽅を直す」) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 14
15. 予約アプリで試す Kiro が読みやすいテストの出⼒ 画⾯には数⾏、詳しくはログに。ERROR と理由を同じ⾏に、件数は先に数える 前: npx vitest run の出⼒は 305 ⾏ (⼈が重なりの確かめの < を <= に変え、9 件落とした) 後: node scripts/check.mjs の出⼒は 14 ⾏ (全部の出⼒はログのファイルへ) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 15
16. 予約アプリで試す 道具の前で⽌める Pre Tool Use の Hook で、テストのファイルを消す操作を⽌める 「src/server/app.test.ts を消して」と頼んだとき 書き込みの道具が⽌まり、 Kiro は回り道をせず、 消す理由を⼈に尋ねた。 ⽌めるには exit 2 (STDERR が Kiro に 返る)。⽌めているのは消す操作だけで、 期待の書き換え、skip、確かめのスク リプトの書き換えは捕まらない。通っ たら差分でそこを⾒る (囲うのは 06)。 画⾯は⼈が頼んで撮った © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 16
17. 予約アプリで試す Kiro に読ませる⾔葉 何が悪く、どう直すかを、テストと lint の出⼒に書く 落ちたことしか分からない AssertionError: expected [ '../server/rooms.ts' ] to deeply equal [] 何が悪く、どう直すかまで書く 画⾯のコードは src/server を読まない。 部屋や予約は api.ts の関数で /api から取る 何が悪く、どう直すかは 直す場所と直し⽅が 出⼒から推し量るしかない ⽂から分かる 左は Vitest の既定の形 (例として書いた)、右は予約アプリの構造のテストの⽂ (18 枚⽬)。直し⽅を書いた lint の⽂を、 Böckeler は良い意味のプロンプトの注⼊と呼ぶ。Böckeler の試しで AI が上限を上げて済ませがちだったのは、直し⽅ の⽂が無かった循環的複雑度の決まりだった。決まりを⾜しすぎると、合図に追われて作りすぎるおそれもある © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 17
18. 予約アプリで試す 構造のテスト 「画⾯のコードから src/server を読まない」を、テストで確かめる App.tsx に src/server の import をわざと 1 ⾏⾜した src/web のファイルの import を読み、 src/server を指すものが あれば、直し⽅つきの⽂で 落ちる。 Vitest の普通のテストなので、 npm test と Agent Stop の Hook で そのまま流れる。画⾯は、⼈が わざと壊して撮った © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 18
19. 予約アプリで試す 不変の決まりを守らせ、細部は任せる 層の向きのような決まりは機械で守り、書き⽅の細部は Kiro に任せる 部屋の中は任せる 前向きだけ イメージ図 逆向きは⽌める OpenAI の記事では、層を決めて依存は前向きだけにし、独⾃の lint と構造のテストで守った。境界でデータの形を確 かめることは求め、どのライブラリで書くかは決めなかった © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 19
20. 予約アプリで試す 層の lint の⾔葉 前の層が後ろの層を読むと、lint が層の並びと直し⽅を返す ⼈が db.ts に app.ts の import を 1 ⾏⾜し、node scripts/lint-layers.mjs を流した 予約アプリの層は 基本 → 決まり → 保存 → API → 起動。後ろの層は前の層を読めるが、 前の層は後ろの層を読まない。 Böckeler の試しでも、層の決まりを⼊れたあと、エージェントは何度か破り、その⽂を読んで⾃分で直した。この形 の lint が⾒るのは import とファイル名とフォルダまでで、中⾝の正しさはテストで⾒る © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 20
21. 選び⽅ 速い順に並べる 数秒の確かめは Kiro が書いたその場で、重いものは CI で、ずれは定期の仕事で イメージ図 書いたその場 (数秒) CI (数分) 定期の仕事 時間の感覚が無いエージェントに、ランダムに選んだ 1% か 10% だけを流す --fast を⽤意した (Anthropic 2026-02)。重 いものは統合のあとのパイプライン、ずれ (使われないコード、依存の古さ) は定期の仕事で (Böckeler) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 21
22. 選び⽅ 確かめやすいコード 型とはっきりした境界のあるコードは、確かめを作りやすい イメージ図 型と境界 古いコード 型の強い⾔語は型の確かめを、はっきりした境界は作りの決まりを置ける。古いコードは、ハーネスが⼀番要る所ほど 作るのが難しい (Böckeler)。予約アプリは TypeScript で、画⾯と API の境界がある © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 22
23. 選び⽅ 鳴らない確かめ ⼀度も落ちない確かめは、わざと壊して落ちることを⾒る ⼀度も鳴らない網 イメージ図 わざと⼊れた変異 わざと壊して落ちるかを⾃動でたくさん⾒るのが、ミューテーションテスト (mutation testing、詳しくは 03)。⽂の網 羅率 100% でも、13 の変異が⽣き残ったファイルがある (Böckeler 2026-05)。効いたかを測るのは 10 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 23
24. まとめ まとめ 決まった結果を返す確かめを、Kiro が答え終えたところで Hook で流し、直し⽅つきで返す 1 機械の確かめは形の外れを速く同じ結果で捕まえる。意味は 05 で⾒る。 2 Agent Stop の Hook に「確かめた」の決まりを置き、⾔葉ではなく DB の⾏のような 状態を⾒る。 3 出⼒は数⾏にして直し⽅を書く。通ったら、確かめ⾃体が書き換えられていないかを 差分で⾒る。 明⽇からの 1 ⼿: いま⼿で流しているテストと型の確かめを 1 つのスクリプトにまとめ、Agent Stop の Hook から呼ぶ (付録 A2、Kiro CLI で試した形) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 24
25. まとめ 次に読む資料 意味を⾒る確かめは 05、重い確かめを PR で流すのは 07、効いたかを測るのは 10 このシリーズ 05 このシリーズ 07 このシリーズ 10 AI に確かめさせる CI に載せる ハーネスが効いたかを測る 意味を⾒るレビュー役 重い確かめを PR で 課題を流して⽐べる Hook の作り⽅と画⾯は ⽬指せ Kiro マスター 06 Steering と Hook。⻑い仕事を回でつなぐのは 09 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 25
26. 付録 A1 Hook のきっかけの⼀覧 きっかけ JSON の trigger IDE CLI きっかけ JSON の trigger IDE CLI Prompt Submit UserPromptSubmit ◦ ◦ Pre Tool Use PreToolUse ◦ ◦ Agent Stop Stop ◦ ◦ Post Tool Use PostToolUse ◦ ◦ Session Start SessionStart ◦ V3 File Create PostFileCreate ◦ V3 Agent Spawn AgentSpawn — 2.x、 File Save PostFileSave ◦ V3 V3 別名 File Delete PostFileDelete ◦ V3 Session End SessionEnd — V3 Pre Task Exec. PreTaskExec V3 Pre Compaction PreCompact ◦ ◦ V3 Post Task Exec. PostTaskExec V3 Post Compaction PostCompact ◦ ◦ V3 ⽌められるのは Pre Tool Use、Pre Task Execution、Pre Compaction (どれも exit 2) と IDE の Prompt Submit。CLI の Agent Stop は Kiro をもう⼀度動かす (decision block か exit 1)。Web では動かない。V3 は Kiro CLI 3.x の形。 Compaction の 2 つは CLI 3.1.0 と IDE 1.4.121 から © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 26
27. 付録 A2 予約アプリの⽌まる前の確かめ (要点) .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 }] } .kiro/hooks/check-before-stop.mjs const r = spawnSync("node", ["scripts/check.mjs"]); if (r.status === 0) exit(0); // tries: 続けさせた回数 (session_id ごと) const why = tries >= 3 ? "まだ落ちている確かめを書いて終える" : "直してから確かめを流し直して答える"; process.stdout.write(JSON.stringify( { decision: "block", reason: why + r.stdout })); check.mjs は 4 つの確かめを流し、結果と落ちた所 (ERROR、8 ⾏まで) を 1 ⾏ずつ出す。理由の⽂は要点だけ写した (本物は skip や期待の書き換えも禁じる)。回数は同じ会話で頼むたびに増え、3 回続けさせたあとは、まだ落ちている と答えに書かせる (この分かれ道は node で確かめた)。IDE では確かめていない © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 27
28. 付録 A3 ⽤語 ⽤語 意味 ⽤語 機械の確かめ CPU が決まった結果を返す確かめ Agent Stop lint 書き⽅の決まりを⾒る道具 Pre Tool Use 道具を使う前のきっかけ 型の確かめ 値の形が合うかを⾒る matcher Hook の対象の条件 構造のテスト どのコードが何を読むかの確かめ exit 2 道具の前の Hook が⽌める合図 層 コードの置き場の段 decision block Stop の Hook が続けさせる合図 状態で確かめる DB などに残った結果を⾒る STDIN、STDOUT Hook に渡る⼊⼒と、返す出⼒ 確かめやすさ 確かめを作りやすいコードの性質 ミューテーション 本番のコードを⾃動で少しずつ テスト 変え、テストが落ちるかを⾒る © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 意味 Kiro が答え終えるときの きっかけ 28
29. 付録 A4 出典と参考 Anthropic (2026-02) 並列のエージェントで C コンパイラーを作ったハーネスの記事 https://www.anthropic.com/engineering/building-c-compiler Anthropic (2025-11) ⻑い仕事のハーネスの記事 (Effective harnesses for long-running agents) https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents Anthropic (2026-01) エージェントの評価の作り⽅の記事 (Demystifying evals for AI agents) https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents OpenAI (2026-02) harness engineering の記事 https://openai.com/index/harness-engineering/ OpenAI (2026-03) モデルの API にコンピューターの環境を持たせた記事 https://openai.com/index/equip-responses-api-computer-environment/ OpenAI (2026-03) Skill と指⽰のファイルで OSS の SDK の保守を回す記事 https://developers.openai.com/blog/skills-agents-sdk OpenAI (2026-09) 新しいモデルに合わせて Skill と指⽰のファイルを⾒直す記事 https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 29
30. 付録 A5 出典と参考 (続き) OpenAI (2026-03) 社内のコーディングエージェントの外れを⾒張る記事 https://openai.com/index/how-we-monitor-internal-coding-agents-misalignment/ Birgitta Böckeler (2026-04) Harness engineering for coding agent users (martinfowler.com) https://martinfowler.com/articles/harness-engineering.html Birgitta Böckeler (2026-05) Maintainability sensors for coding agents (martinfowler.com) https://martinfowler.com/articles/sensors-for-coding-agents.html kiro.dev のドキュメント Hooks、Hook types、Hook actions、 Best practices (2026-11-10 に .md 版を読んだ) と変更履歴 https://kiro.dev/docs/hooks/ 、https://kiro.dev/changelog/ Stryker Mutator のドキュメント「What is mutation testing?」 https://stryker-mutator.io/docs/ 画⾯: Kiro CLI 3.1.0 (12、16、18 枚⽬は 2026-11-09、13〜15、20 枚⽬は 2026-11-10)。予約アプリは 公開していない。 記事の数は、記事を出した会社や著者が⾃分で測った値。時間はこの Mac で測った値で、⽬安。 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 30