座学編
概念の地図とハーネス設計の実演

01 エージェンティックエンジニアリングの範囲

エージェンティックエンジニアリングは、モデルへの指示文を磨く仕事ではありません。モデルの外側にある、渡す情報・与える権限・進ませる手順・確かめ方・残す記録を組み立てる仕事です。同じモデルを使っていても、この外側が違えば結果は変わります。

第1回（2026年5月）では、Hooks・Skills・サブエージェントの3つを、Nginx 風のログから 5xx の多発原因を要約するエージェントという題材で1つずつ動かしました。部品の作り方を扱った回です。今夜はその部品を支える側、つまり部品に何を読ませ、どこで止めるかという設計に進みます。

02 今夜の概念地図

今夜出てくる言葉は、下の4つの層のどこかに属します。デモやハンズオンでファイル名が出てきたら、それがどの層のものかをこの図で確かめてください。

今夜さわるのは真ん中の帯だけです。モデルの選択も、プロンプトの言い回しも扱いません。

03 今夜の到達点

• プロンプトエンジニアリングとコンテキストエンジニアリングの違いを、自分の言葉で他人に説明できる
• LLM wiki・ツールユース・MCP が、それぞれどの層の話なのかを取り違えない
• 止め方に2種類（自然言語のルールと機械的なゲート）があり、どちらをどこに置くかを判断できる
• 自分の業務の語彙で LLM wiki を書き始められる。テンプレートは配布ファイルに入っています

参加の型は事前セットアップガイドの冒頭で決めていただいています。まだ決めていない場合は、いま決めてください。

01 プロンプトエンジニアリングとコンテキストエンジニアリング

2つの違いは、書いたものが1回で消えるか、以降ずっと効き続けるかです。プロンプトは1回のやりとりごとに書き直しますが、コンテキストは一度置けば、次の実行にも、来週の実行にも、他の人の実行にも効きます。

出力が気に入らないとき、どちらを直すかで手間が変わります。文体や長さが気に入らないならプロンプトかテンプレート、書いてある内容が事実として間違っているならコンテキストです。ここを取り違えると、事実の誤りをプロンプトの言い回しで直そうとして、毎回書き直す羽目になります。

02 LLM wiki・ツールユース・MCP の役割

この3つは並べて比べる対象ではありません。層が違います。LLM wiki は渡す中身、ツールユース はモデル側の能力、MCP はその能力へツールを供給する規格です。

MCP を使わなくてもツールユースは成立します。同じツールを複数のAIツールへ配りたくなったときに MCP が効いてきます。ツールの数と説明文もコンテキストの一部を占めますので、接続すること自体がコストになる点は押さえてください。

03 コンテキストの整備とハーネス設計

ハーネスは、モデルの外側にあるものをまとめた呼び方です。決めることは5つあります。

コンテキストの整備は、このうち入口の話です。ただし入口を決めると、検証で何を見るかも自動的に決まります。「一次回答で完結してよい条件」を rules.md に書いた瞬間、その条件に照らして判定する役が必要になるからです。

LLM wiki の初期テンプレート

4ファイルで足ります。業務ドメインが変わっても、この4つの役割分担は変わりません。配布ファイルの context/ に、そのまま書き始められる形で入れてあります。

context/
  glossary.md          社内呼称と正式名。略語、通称、部署の呼び方
  rules.md             判断ルール。一次回答で完結してよい条件、人間の承認が必要な操作
  systems.md           システム台帳。名前、認証方式、問い合わせ窓口、よくある詰まり
  templates/reply.md   出力様式。件名、本文、二次対応の要否という3欄

書く分量の目安は、4ファイル合わせて最初は30行前後です。完成した社内 wiki を先に作ろうとすると着手できません。1件動かして、返ってきた質問に答える形で足していくと、必要なものが必要な順に埋まります。

04 Hooks・Skills・サブエージェントの連携

3つとも「AIに何かをさせる」仕組みに見えますが、確実に実行されるかどうかが違います。ここを揃えて考えると、どれをどこに使うかで迷わなくなります。それぞれの定義は補足ページの用語集（Hooks、Skills、サブエージェント）に置いています。

絶対に越えさせたくない線は Hooks に置いてください。Skills に「送信前に必ず確認すること」と書いても、読むかどうかはAIが判断します。読まれない可能性のある場所に最後の一線を置くと、事故が起きたときに原因を追えません。

サブエージェントを分ける理由は品質ではありません。分けると、そのサブエージェントが読んだファイルの全文が向こう側で完結し、親には結論だけが返ります。3件、4件と連続で処理したときに前の案件の情報が混ざらないのは、この分離が効いているためです。件数が少ないうちは1体でも動きます。

01 自然言語での Hook ガードレール [4min]

Hook の設定を手で書かず、Claude Code に頼んで作らせます。送信するのは次の1文だけです。

out/ 配下に URL やサーバーパスを含む文書を書き込もうとしたときに止まる PreToolUse フックを
作ってください。承認記録が .claude/audit/approvals.log にある場合だけ通してください。
設定と、フックが実行するスクリプトの両方を作って、内容を見せてから書き込んでください。

返ってくるのは .claude/settings.json への追記と、シェルスクリプト1本です。設定側は次の形になります。matcher で対象のツールを絞り、command にスクリプトのパスを書く構造です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "bash hooks/approval-gate.sh" }
        ]
      }
    ]
  }
}

実務での使いどころは、既存プロジェクトに1本目の Hook を入れるときです。イベント名と JSON の構造を調べるところで止まりがちですが、やりたいことを日本語で書けば形にはなります。返ってきた設定が意図どおりかどうかは自分で読んでください。matcher が広すぎて関係のない操作まで止まる形になっていることがあります。

02 公式 Skill を用いたハーネス導入 [4min]

Skill は自分で書く前に、既にあるものを入れて挙動を見るのが早い手です。Claude Code には最初から使える Skill が同梱されていますので、/help で一覧を出し、そのうち1本を実際に呼びます。

/code-review

画面には、変更点を読んで指摘を返す動きが出ます。ここで見ていただきたいのは指摘の中身ではなく、Skill が呼ばれた瞬間に、それまで会話になかった手順が差し込まれる点です。SKILL.md の本文は、呼ばれるまでコンテキストに載りません。載るのは description だけです。

実務での使いどころは、チーム内で手順を配るときです。長い手順書を CLAUDE.md に書くと毎回全文が読まれますが、Skill に切り出すと、関係する場面まで中身が読まれません。CLAUDE.md が肥大してきたら、手順の性質を持つ節から Skill へ移してください。

03 成功体験の Skill 化 [4min]

うまくいったやりとりを、その場で Skill に固めます。作業が終わった直後のセッションで次を送ります。

いま私とやったこの手順を、次回そのまま再現できる SKILL.md にしてください。
私が判断した箇所は、判断のしかたも含めて残してください。
うまくいかなかった試行は書かないでください。

できあがる SKILL.md は次の形です。フロントマターの description が、この Skill をいつ読むかの判断材料になります。ここが曖昧だと、必要な場面で呼ばれません。

---
name: incident-first-reply
description: 社内ヘルプデスクの問い合わせに一次回答を作るときに使う。
  用語集と判断ルールを参照し、承認が必要な操作を判定してから回答を書く。
---

## 手順
1. context/glossary.md と context/systems.md から、該当システムの事実を集める
2. context/templates/reply.md の様式で回答本文を書く
3. context/rules.md に照らし、承認が必要かを判定する
4. 承認が必要な場合は、書き込まずに利用者へ確認する

実務での使いどころは、月に何度も繰り返している作業です。3回同じことを説明したら Skill にする、という基準にしておくと溜まっていきます。

04 Plan モードでの Subagents 作成 [4min]

Shift と Tab で Plan モードに切り替え、サブエージェントの定義を作らせます。このモードでは、コードベースの調査が読み取り専用のサブエージェントへ委譲され、調査の過程は別のコンテキストに隔離されたまま、計画だけが提示されます。

context/ を読んで、一次回答を作る流れを3体のサブエージェントに分ける案を出してください。
それぞれの役割、渡すツール、返す形式を決めて、計画として見せてください。まだ書き込まないでください。

提示された計画に合意してから書き込ませると、次のような定義ファイルができます。フロントマターで名前・説明・使えるツール・モデルを宣言し、本文がそのサブエージェントのシステムプロンプトになります。

---
name: context-researcher
description: context/ を検索して、回答に必要な事実だけを根拠付きで返す。
tools: Read, Grep, Glob
model: inherit
---

context/ 配下だけを調べます。見つけた事実は、出典としてファイル名と該当箇所を添えて返します。
context/ に書かれていないことは推測せず、「記載なし」と返します。回答本文は書きません。

tools を絞っている点を見てください。調べる役に書き込みのツールを渡していません。役割を分けるだけでなく、渡す道具も分けると、想定外の操作が起きにくくなります。

実務での使いどころは、いきなり作らせて後から直すのが高くつく場面です。サブエージェントは一度作ると呼ばれ続けますので、役割と権限は計画の段階で決めてしまうほうが、後の手戻りが少なくなります。

05 AI によるセルフレビューループの設計 [4min]

生成物を、別の観点でAI自身に検査させます。検査の観点は人が決めて、実行だけを任せる形です。

out/ に書いた回答を、次の3点で検査してください。
1. context/systems.md に書かれていない事実を書いていないか
2. rules.md の「人間の承認が必要な操作」に該当しないか
3. templates/reply.md の3欄がすべて埋まっているか
1つでも落ちたら、落ちた理由を挙げて、回答を書き直してから再検査してください。

画面には、検査で落ちて書き直し、もう一度検査して通るまでの往復が出ます。セルフレビューループで効くのは、検査の観点を人が固定している点です。「よくレビューして」と頼むと、その時々で見る場所が変わります。

往復の上限は決めてください。落ちるたびに書き直させると、通らない要件のときに止まらなくなります。実務では2回落ちたら人を呼ぶ、という形にしておくと、コストが読めます。

01 概念と実装の対応

この表が今夜の総整理です。左の列が座学で扱った概念、右の列がハンズオンで実際にさわった場所です。持ち帰る配布ファイルの中に、右の列がそのまま入っています。

今夜の40分で受講者の方が実際に書いたのは、このうち上の2行だけです。書いた分量は10行前後で、それで出力が別物になりました。残りの行は完成品として配っていますので、明日からは中身を読み替えて使ってください。

02 第3回への接続点

第3回は2026年11月、テーマは「ハーネスエンジニアリング 2026」です。今夜は1本の直列パイプラインを、人が見ている前で動かしました。第3回では、それを複数同時に、人が見ていない時間帯にも動かしたときに何が壊れるかへ進みます。

03 質疑応答

ZOOM のチャットへお書きください。読み上げてお答えします。時間内に答えきれなかった質問は、補足ページの追加資料に回答を追記します。追記の予定は開催の翌週です。

本サイトは開催後も同じURLで公開を続けます。座学の内容、ハンズオンの手順、実行ログはそのまま残りますので、当日その場で動かせなかった場合も、後からご自身の環境で再現できます。