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

エージェントが一度に見られる文脈は限りある資源です。この資料では、Kiro に渡す決まりと手順を、いつも読む Steering と AGENTS.md、合うファイルを扱うときだけ読む Steering、要るときに開く Skill と Powers の 3 つの置き場に分けること、Skill は名前と説明を先に渡すこと、書くのは Kiro が実際に外したこととコードから読めない決まり (コードの地図) にすることを、Anthropic や OpenAI などの公開の記事を元にイメージ図で説明します。説明用に作った小さな会議室の予約アプリで、決まりと手順を足す前と後に同じ頼みを 3 回ずつ流して、頼みどおりにできなかった所 (外れ) を数え、足した Steering と Skill を Kiro IDE の本物の画面で見せます。シリーズ「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 意図を 仕様で渡す 05 AI に確かめさせる 06 回す 06 できることを囲う 07–10 07 CI に載せる ハーネスを 08 育てる ⻑い仕事を 09 回でつなぐ ハーネスが 10 効いたかを測る © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 3
4. はじめに この資料で分かること ⽂脈は限りある。置き場を分け、名前と説明を先に渡し、外したことを書く 1 ⽂脈は限りある資源。いつも読む決まりは短くし、詳しい所は指す 2 置き場は 3 つ: いつも読む、合うファイルで読む、要るときに開く 3 書くのは外したことと、コードから読めない決まり (地図)。前と後で⽐べる 前に読むとよい資料: 01 ハーネスエンジニアリング⼊⾨。設定の仕⽅は別のシリーズ 「⽬指せ Kiro マスター」の 06〜08 説明⽤に作った⼩さな会議室の予約アプリで 試す (Kiro CLI 3.1.0 と Kiro IDE 1.4.121。コードは公開していない) 外れは、Kiro が頼みどおりにできなかったこと。絵のお化けは Kiro 図の⾊: 紫は要点と⼈が決める所、⻘は Kiro の動き © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 4
5. 考え⽅ ⽂脈は限りある資源 ⽂脈が⻑いほど思い出す⼒は落ちる。いつも読む分を⾜すほど、仕事に使える分が減る イメージ図 全部⼊り 要る分だけ Chroma の試し: どのモデルも、要る部分だけ (約 300 トークン) の⽅が⻑い⼊⼒ (約 113,000) より良かった Anthropic は、⽂脈を限りある資源として扱い、要る情報だけを渡すよう勧める © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 5
6. 考え⽅ ⼤きな 1 枚が外れる理由 ⼤きな 1 枚の指⽰は外れる。約 100 ⾏の⽬次にして、詳しい所は docs/ を指す イメージ図 百科事典 ⽬次 (約 100 ⾏) docs/ OpenAI が挙げた理由: 仕事とコードを⽂脈から押し出す。全部⼤事だと、何も⼤事でなくなる すぐ古くなり、機械で確かめにくい。Kiro なら、毎回読む always の Steering と AGENTS.md を⽬次にする © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 6
7. 置き場と書き⽅ 導く仕組みの置き場 いつも読む、合うファイルで読む、要るときに開く、の 3 つに分けて置く イメージ図 合うファイルで読む いつも読む 要るときに開く いつも読む: always の Steering と AGENTS.md。合うファイルで読む: fileMatch の Steering 要るときに開く: Skill と Powers。auto と manual の Steering もこちら (⽤語は付録 A2) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 7
8. 置き場と書き⽅ いつも読む分は短く always の決まりは毎回の頼みに⼊る。⻑い⼿順は Skill に分ける ⼿順も always に 避けたい ⼿順は Skill に すすめる 頼み 1 決まり + ⼿順 (毎回) 頼み 頼み 2 決まり + ⼿順 (毎回) 頼み 頼み 1 決まり 名前と説明 頼み 頼み 2 決まり 名前と説明 頼み 合う頼みだけ本⽂ 枠の幅は⼤きさの⽬安で、測った値ではない always の Steering はどの頼みにも毎回⼊る。Skill は名前と説明だけが⼊り、合うと本⽂を開く 毎回読む分は⼩さく保つ。⻑い指⽰のファイルほど守られにくい (Anthropic) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 8
9. 置き場と書き⽅ 名前と説明だけを先に渡す Skill は名前と説明だけを先に⾒せ、要るときに本⽂を開く。似た道具を並べすぎない イメージ図 1 名前と説明 2 本⽂ 3 追加のファイル 道具の定義でも同じ。Anthropic の記事の例では、MCP サーバー 5 つ、道具 58 個の定義だけで約 55K トークン 後から探す形にすると、残る⽂脈が 122,800 から 191,300 トークンに増えた。道具が重なると迷う (OpenAI) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 9
10. 置き場と書き⽅ Skill の説明は振り分けの決まり 説明には「何をするか」より「いつ使うか、いつ使わないか」を書く 広すぎる説明 いつ使うかが分かる説明 description: 予約アプリの description: 会議室の予約アプリに機能を コードを変えるときに使う。 ⾜すときの⼿順。予約の延⻑、取り消し、変更の ように、API や画⾯に新しい操作を⾜す頼みで使う。 コードに触る頼みなら、 どれでも開かれやすい ⾜すとよい⾏: 使わないとき (例: バグの直し) 右は予約アプリの Skill (add-feature) の説明。点線の⾏はこの資料の案で、試していない 広い説明や、ほかと⾷い違う説明は、関係のない仕事でも開かれる (OpenAI)。確かめ⽅は資料 10 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 10
11. 置き場と書き⽅ 何を書くか 書くのは、Kiro が実際に外したことと、コードからは読めないこと 書く 書かない Kiro が実際に外したこと コードを読めば分かること 同じ頼みを流して、2 回以上起きたもの 関数の名前、ファイルの中⾝ コードからは読めないこと どこでも⾔える⼼がけ 理由、チームの事情、使わないと決めたもの 「きれいに書く」「よく考える」 どこまでやるか 鍵やパスワード 頼まれていないものを⾜すか、どこで聞くか Steering はリポジトリに⼊る 1 つ⽬: 各⾏は実際の悪いふるまいから書く (Hashimoto)。何度も起きたら直す (Thoughtworks の Böckeler) 2 つ⽬:「ここではそうしない」は coding agent には分からない (Böckeler)。3 つ⽬はこの資料のすすめ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 11
12. 置き場と書き⽅ ⾒えない知識は無いのと同じ チャットや⼈の頭の中で決めたことは、リポジトリに書くまで Kiro には無い イメージ図 チャットや頭の中 リポジトリに書いた紙 エージェントが仕事の中で読めないものは、無いのと同じ (OpenAI) Kiro なら、決めたことと理由を docs/ や Steering に書く (この資料の当てはめ)。git でチームにも渡る © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 12
13. 置き場と書き⽅ AGENTS.md も読む AGENTS.md はいつも読まれ、下のフォルダに置いたものも⾒つけて読む 置き⽅の例 (会議室の予約アプリ) meeting-rooms/ AGENTS.md src/server/ AGENTS.md src/web/ AGENTS.md いつも読む inclusion の指定は効かない 下のフォルダのものも⾒つけて読む 説明するコードの隣に置ける #[[file:パス]] の起点はそのフォルダ IDE と CLI V3。Steering では最上位 下のフォルダの AGENTS.md も毎回読まれる。そのフォルダを触るときだけ要る決まりは fileMatch に 右の 3 つ⽬は、ほかのファイルを読ませる参照の書き⽅。~/.kiro/steering/ の AGENTS.md も読む © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 13
14. 置き場と書き⽅ 今の Steering を仕分ける 決まりは Steering に、くり返す⼿順は Skill に。上から順に当てはめる 今の Steering を 1 つずつ⾒て、上から順に聞く。当てはまったら右へ 0 例外なく守らせたい決まり Hook 許可の設定も (資料 04、06) 1 どの頼みにも要り、数⾏で書ける決まり always Steering か AGENTS.md 2 決まったファイルを扱うときだけ要る決まり fileMatch fileMatchPattern を書く 3 決まった話題の頼みのときだけ要る決まり auto いつ使うかの説明を書く 4 何段もの⼿順。スクリプトや資料も添えたい Skill SKILL.md と scripts/ など 5 ⼈が呼びたいときだけ使う manual チャットで #名前 と打つ 聞く順はこの資料のすすめ。0 の例は「⽣成したファイルに触らない」。外の道具は Powers (19 枚⽬) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 14
15. 予約アプリで試す 予約アプリで起きた外れ 決まりなしで同じ頼みを 3 回流すと、3 つの外れが 3 回とも起きた 頼み:「予約の延⻑の機能を⾜して」 1 回⽬ 延⻑は Spec で対象外の「予約の変更」 2 回⽬ 3 回⽬ ほしかった動き / 起きたこと 確かめのテスト テストを残し、次の変更でも流れるように 2 回は「頼まれていない」が理由 Spec の「対象外」 延⻑を先に Spec の要件に⾜す 報告の最後で、直すかを⼈に任せた 前から落ちる性質 11 既知と報告して先へ進む 時間を測り、変更前のコードで流し直した Kiro の報告:「頼まれていないので、テストはリポジトリに⾜していません」。Spec は要件と設計 (資料 03) 性質 11 は、機械が混むと落ちる前からのテスト。調べ直すと、関係のない確かめに毎回時間を使う © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 15
16. 予約アプリで試す いつも読む決まりを 2 つ⾜す 3 回とも起きた外れのうち、どの仕事にも効く 2 つを always の Steering に書く どの機能を⾜すときにも要る 2 つなので、always にした。 どちらにも理由を 1 ⽂で添えた。 上はパネル (add-feature は Skill)。 右は working-rules.md の 1〜3、 6、7 ⾏⽬ © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 16
17. 予約アプリで試す テストのときだけ読む決まり 前から落ちるテストのことは、テストのファイルを扱うときだけ読ませる (fileMatch) fileMatchPattern に合う ファイルを Kiro が扱う ときだけ読まれる。 前から落ちるテストのことは、 テストを書くときにしか 要らないので、ここに置いた。 右は .kiro/steering/testing.md の頭と 8 ⾏⽬。CLI で fileMatch が効くのは V3 (CLI の新しい動き⽅、付録 A1) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 17
18. 予約アプリで試す ⻑い⼿順は Skill に 機能を⾜す⼿順は Skill に置き、頼みが説明に合ったときだけ本⽂を開く 始めに読まれるのは、右の name と description だけ。 頼みが説明に合うと、本⽂の ⼿順を開く。 ⼿順は 5 つ: 要件を先に⾜す、テストを先に書く、作る、確かめる、報告する ⾜したあとの 3 回のログには、どれも「Load skill: add-feature」の⾏があった ⼿順 1、2 は always の 2 ⾏と同じ中⾝。ふだんは⽚⽅に書き、もう⽚⽅は参照で指す (23 枚⽬) 毎回同じになるべき処理 (確かめなど) は、Skill の scripts/ にスクリプトで置く (kiro.dev、Anthropic) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 18
19. 外の道具 外の道具は Powers で 外の道具とその使い⽅は Powers で⼊れ、話が合ったときだけ読み込む 1 つの Power plugin.json 名前と、開くきっかけの⾔葉 skills/ ⼿順書 (Agent Skills) mcp.json 道具 (MCP サーバー) 頼みを読み、⼊っている Power と照らす kiro.dev の例: payment と話すと Stripe の Power 合った Power 道具と⼿順を読み込む 合わない Power 読み込まない MCP サーバーを全部つなぐと、道具の説明だけで⽂脈を使う。Power は要るときだけ道具を読み込む ⼊れ⽅は Powers のパネルか CLI (V3) の /powers install。信頼できる所から⼊れ、中⾝を読む (06) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 19
20. 地図を渡す 地図を渡す コードを読む道具は Kiro が持っている。⾜すのは、コードの置き⽅の決まりとその理由 Tree-sitter (⼊っている) LSP (⾔語サーバーを⼊れると) IDE、CLI、Web、Mobile。18 の⾔語 IDE は⾔語の拡張、CLI は /code init シンボルを探す ファイルの⾒出し 関数やクラスを名前で 中の関数の⼀覧 形で探す 全体の⾒取り図 コードの構造で当てる Codebase overview 呼んでいる所を探す 定義へ⾶ぶ 名前を付け替える エラーと警告 型の説明 どちらも、コードを調べるときに Kiro が⾃分で使う。推測でなく、プログラムが答えを返す (Böckeler) 予約アプリの試しでは、Kiro はこの道具を使わず、ファイルを直接読んだ (LSP は⼊れていない) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 20
21. 地図を渡す 地図の書き⽅の例 書くのは、どこに何を置くかの決まりとその理由。ファイルの⼀覧は書かない .kiro/steering/structure.md の例 # フォルダの分け⽅ - src/web/ から src/server/ を import しない。 画⾯は api.ts を通して /api だけを呼ぶ 理由: 画⾯と API は、別のプロセスで⽴てる - 時刻は DB では UTC で持ち、 API が返すときに⽇本時間 (+09:00) にする 書く: 決まりと理由 コードの形からは、守る理由が読めない 書かない: ファイルの⼀覧 Kiro がコードを読めば分かる 読まれ⽅: 毎回読まれる 画⾯だけで要るなら fileMatch に 左は予約アプリの事実から書いた例。kiro.dev は名前の付け⽅や import の形も書くとする ⽂書は場⾯に結んで指す。例:「スキーマを変えるときは database.md を読む」(OpenAI) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 21
22. ⽐べる 効いたかを⽐べる 同じ頼みを、決まりと⼿順を⾜す前と後で 3 回ずつ流して数える ⾜す前 ⾜したあと 確かめのテストを残した 0/3 3/3 Spec の「対象外」を先に直した 0/3 3/3 落ちた 3 回中 0 落ちた 2 回中 1 前から落ちるテストを調べ直さなかった ⾜す前の 3 回は混雑で⽌まり、続きから流し直した。項⽬は、⾜す前に 3 回とも起きた外れを選んだ ⾜したのは always の 2 ⾏、testing.md、Skill。どれが効いたかは分けていない。数は傾向として読む 守るかは Kiro が決める。必ず守らせるなら機械で確かめる (資料 04)。測り⽅は資料 10 © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 22
23. ⾒直す 決まりどうしの⾷い違い 決まりは増えると古くなり、⾷い違う。決まりもコードと同じく⾒直す イメージ図 ⾷い違う決まり 古い決まりを外して減らす 決まりの変更もレビューし、書き写さずに参照で指す (kiro.dev)。毎回読む分の誤りは毎回に効く レビューの決まりも、消して結果が変わらないものは書かず、的外れを⽣むものは狭める (OpenAI) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 23
24. まとめ まとめ ⽂脈は限りある。置き場を分け、名前と説明を先に渡し、外したことを書いて⽐べる 1 ⽂脈は限りある資源。いつも読む決まりは短くし、詳しい所は指す 2 置き場は 3 つ: いつも読む、合うファイルで読む、要るときに開く 3 書くのは外したことと、コードから読めない決まり (地図)。前と後で⽐べる 明⽇から: 今の Steering を 14 枚⽬の順で仕分ける。無ければ外したことを 1 つ書く Kiro が外したら 1 ⾏で記録し、同じ外れが 2 度⽬なら決まりか⼿順にする (資料 01) ⾜したら、同じ頼みを数回流して⽐べる (22 枚⽬) © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 24
25. まとめ 次に読む資料 次は資料 03。⻑い仕事は 09、効いたかを測るのは 10 次に読む資料 ⻑い仕事なら 03 効いたかを測るなら 09 10 意図を仕様で渡す ⻑い仕事を回でつなぐ ハーネスが効いたかを測る Spec、計画、性質のテスト 仕様、計画、状況をファイルに 課題、試⾏、採点役で⽐べる 設定の仕⽅は⽬指せ Kiro マスター 06 (Steering と Hook)、07 (MCP と Powers)、 08 (Skill とカスタムエージェント) シリーズの資料は speakerdeck.com/inariku に載せている © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 25
26. 付録 A1 ⾜す前と後の⽐べ⽅ (この資料の試しでしたこと) すること この資料の試しでしたこと 1 頼みを 1 つ決める ふだん頼む仕事に近いもの。ここでは「予約の延⻑の機能を⾜して」 2 同じ状態から始める ⾜す前と後の commit から、git worktree でフォルダを 3 つずつ作った 3 ⾃分の設定を混ぜない HOME を空のフォルダにして、~/.kiro/ を読ませない 4 画⾯なしで流す 下の命令で流し、出⼒をログに残した 5 外れを数える ⾜す前に 3 回とも起きた外れを項⽬にし、ログと git status で⾒た 6 効いたものを知るなら 1 つずつ⾜して流す。この試しでは 3 つをまとめて⾜した kiro-cli chat --v3 --no-interactive --trust-workspace --trust-all-tools "頼み" 空の HOME には、サインインのデータへのリンクだけを置いた。V3 は CLI の新しい動き⽅ (--v3) ⾜す前の 3 回は混雑で⽌まり、「混雑で⽌まったので、続きから進めて」の頼みで続きから流した --trust-all-tools は確かめずに道具を使うので、捨ててよいフォルダで流す © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 26
27. 付録 A2 ⽤語 ⽤語 意味 ⽤語 意味 ⽂脈 Kiro が 1 回の頼みで読む分 Skill 要るときに開く⼿順書 トークン ⽂脈の⻑さの単位 Agent Skills Skill のフォルダの決まった形 ⽬次 詳しい所を指す短い 1 枚 Powers 道具と⼿順書のセット Spec 要件と設計のファイル (03) MCP 外の道具をつなぐ決まった形 導く仕組み 動く前に⽅向を決める (ガイド) V3 CLI の新しい動き⽅ (A1) Steering 読ませる決まりの Markdown コードの知識 Tree-sitter と LSP inclusion Steering を読ませる条件 Tree-sitter コードの形を読む (⼊っている) LSP ⾔語サーバー (定義など) AGENTS.md いつも読まれる決まり 毎回 (既定)、合う always、fileMatch auto、manual ファイルのとき 説明が合うとき、呼んだとき © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 27
28. 付録 A3 出典と参考 Chroma、2025-07、⼊⼒が⻑いと性能が落ちる (Context Rot) https://research.trychroma.com/context-rot Anthropic、2025-09、エージェントの⽂脈の設計 https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents OpenAI、2026-02、harness engineering (⼈がコードを書かずに製品を作ったハーネス) https://openai.com/index/harness-engineering/ Anthropic、2025-10、Agent Skills (⼿順をフォルダにまとめて段階的に読ませる) https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills Anthropic、2025-11、道具を後から探す、コードから呼ぶ、呼び⽅の例の 3 つの機能 https://www.anthropic.com/engineering/advanced-tool-use OpenAI、2026-09、新しいモデルに合わせて Skill と指⽰のファイルを⾒直す記事 https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra OpenAI、2026-02、Skill、shell、圧縮で⻑く⾛るエージェントのこつ https://developers.openai.com/blog/skills-shell-tips © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 28
29. 付録 A4 出典と参考 OpenAI、2026-01、社内のデータのエージェントの作り https://openai.com/index/inside-our-in-house-data-agent/ Anthropic、2026-11、エージェントの記憶の階層 https://www.anthropic.com/engineering/components-of-agent-memory OpenAI、2026-07、レビューの決まりを指⽰のファイルに書いて AI のレビューに使わせる記事 developers.openai.com/blog の記事 (この記事だけは URL を書かない) martinfowler.com (Thoughtworks の Birgitta Böckeler)、2026-04、coding agent を使う⼈のハーネス https://martinfowler.com/articles/harness-engineering.html Mitchell Hashimoto の個⼈ブログ、2026-02、AI を取り⼊れてきた歩み https://mitchellh.com/writing/my-ai-adoption-journey Kiro、2026-11-09 に読んだ版、ドキュメント https://kiro.dev/docs/ (Steering、Agent Skills、Powers、Install powers、Code intelligence) 数はどれも記事を出した会社の値。どれも 2026-11-09 に本⽂を読み、11-10 に読み直した © 2026, Amazon Web Services, Inc. or its affiliates. All rights reserved. 29