第2回 エージェンティックエンジニアリング2026

勝手には読みません。 自動で読まれるのは CLAUDE.md だけです。context/ 配下は、CLAUDE.md から「この場面ではこれを見る」と参照を書いておくか、依頼のたびにファイル名を指定するかのどちらかが要ります。

当日の配布データもその形にしてあります。CLAUDE.md に context/ の4ファイルの役割を1行ずつ書いておき、Skill の手順の中で「glossary.md と systems.md から事実を集める」と指定しています。

ここを誤解したまま context/ にファイルを増やすと、書いたのに効かない状態になります。置いただけで効くのは CLAUDE.md、読ませたいものは参照を書く、と覚えてください。

間違いではありません。ただ、講師の運用をお伝えすると、CLAUDE.md は50行に収まるようにしています。

CLAUDE.md は毎回全文が読まれます。長くなるほど、依頼のたびにコンテキストを圧迫します。ですので、ここにはどの依頼にも効く全体の規約だけを置いて、特定の場面でしか使わない手順は Skill 側に出しています。手元では Skill が69本あり、CLAUDE.md が短く保てているのはそのためです。

100行で回っているなら、いま急いで分ける必要はありません。分けどきの合図は「特定の作業のときにしか使わない記述が増えてきた」ときです。その記述は、使わない場面でも毎回読まれています。

全体の規約は CLAUDE.md、特定の場面の手順は Skill。この基準で切ると、自然と短くなっていきます。

まず INDEX.md を1枚作ってみてください。フォルダ構成と、どの作業のときに何のファイルを読むかを書いた目次です。

守られない原因の多くは、書いた内容ではなくどれを読むべきかが決まっていないことにあります。ファイルが増えるほど、AI は「いまどれを見るのが正しいか」を毎回推測することになります。目次があると、その推測が要らなくなります。

書く内容はこの程度で足ります。

• フォルダの一覧と、それぞれが何を持っているか
• 「一次回答を作るとき」「仕様を確認するとき」のような作業の単位と、そのときに読むファイル
• 迷ったときにどれを優先するか

そのうえで、それでも守られない場合は次の3つを疑っています。

1. 禁止の書き方が曖昧　「なるべく〜しない」「基本的に〜」は守られません。「〜する場合は必ず人に確認してから」のように、条件と動作を切ってください。

2. 矛盾する記述が別の場所にある　古い行が残っていて、新しい方針と食い違っている場合です。当日「増やす運用より落とす運用」とお伝えしたのはこの理由です。守られないルールが出たら、まず同じ話題の古い記述を探してください。

3. そもそも文章で頼むべきでない　絶対に越えさせたくない線は、文章で書く限り「読むかどうか」の判断が入ります。ここは Hooks に移してください。当日のデモ1本目がその作業です。

最後に効く小技を1つ。守ってほしいルールには理由を1行添えると、守られる率が上がります。判断に迷う場面で、そちらに寄せてくれます。

必要です。ご指摘のとおり、同じ「ルール」「手順」という言葉でも、ツールが変われば置き場所も読まれ方も変わります。

実務では、CLAUDE.md の冒頭に「このリポジトリでの言葉の決め」を数行置いています。どのファイルが何を担当するか、という定義です。これがないと、AI が良かれと思って別のファイルに書き足したり、既存のファイルの役割を勝手に変えたりします。

配布データの context/glossary.md は業務用語の辞書ですが、同じ考え方でファイル構成そのものにも辞書が要ります。

置き換えではありません。扱う量が違います。

LLM wiki が効くのは、リポジトリに置ける分量に収まる場合です。数十ファイル、数百行の規模なら、検索の仕組みを作らずファイルとして置くほうが速く、確実です。

一方、社内文書が数万件あるような規模だと、全部をコンテキストに載せられません。そこで必要な部分だけを取り出して渡す仕組みが要ります。それが RAG です。

判断の目安は「毎回全部読ませても支障がない量か」です。支障がないなら LLM wiki、そうでないなら検索を挟む、という切り分けで考えています。

その整理で運用できます。当日は「後で読めるように」の側面を強調してお答えしましたが、1点だけ補わせてください。

LLM wiki にもその場で読まれる性質があります。CLAUDE.md は依頼のたびに読まれますし、context/ も参照が書いてあれば実行のたびに読まれます。溜めておいて後から参照するだけのものではなく、置いた瞬間から毎回効きます。当日「一度置けば次の実行にも、来週の実行にも、他の人の実行にも効く」とお伝えしたのはこの意味です。

そのうえで、両者の差が出るのは渡すものを誰が決めるかだと考えています。RAG は検索の結果として何が渡るかが実行時に決まります。LLM wiki は書いた人が渡すものを固定します。判断のぶれを減らしたい部分は後者に置く、という使い分けです。

「整理・成長させる」という捉え方はそのままで良いと思います。1件動かして、返ってきた質問に答える形で足していく運用が、いちばん続きます。

ハーネス設計を始めるとき、最初に置く1枚だと考えています。

理由は、AGENTS.md がツールに依存しない層にあるからです。当日お話しした5面のうち「入口」に何を置くかは、Claude Code を使っていても GitHub Copilot に乗り換えても変わりません。プロジェクトの目的、用語、禁止事項、参照すべき場所。これらを各ツールの形式で書き分けると、乗り換えのたびに書き直すことになります。

講師の手元でも、開発用のフォルダには AGENTS.md を置いています。運用は「共通の決めごとは AGENTS.md、そのツール固有の設定はツール側のファイル」という形です。CLAUDE.md から AGENTS.md を参照する書き方にしておけば、両方が生きます。CLAUDE.md を50行に保てているのも、共通部分を外に出しているためです。

現時点では、どのツールがどこまで読むかに差はあります。ただ差があるからこそ、共通の1枚を持っておく価値があります。読まれ方が変わっても、書いた内容は残ります。

これから始められるなら、ツール固有のファイルより先に AGENTS.md から書くことをお勧めします。

使っていますが、数はかなり偏っています。手元では Skill が69本に対して、カスタムコマンドは3本です。

同じ結果が取れるというご観察は正しくて、どちらでも手順は渡せます。違いは呼ばれ方です。

• Skill　AI が「いまこれが必要だ」と判断して自分で読みます。description がその判断材料です
• カスタムコマンド　人が明示的に打ちます。呼ばれるかどうかに判断が入りません

ですので、こう分けています。自分が意識せずとも勝手に発動してほしいものは Skill、自分のタイミングで確実に起動したいものはコマンド。手元の3本は、いずれも「今これをやる」と決めて打つ性質のものです。

両方作られているとのことですが、Skill だけで足りていると感じるなら、それが正しい判断だと思います。打つ手間がない分、Skill のほうが続きます。

別のものです。

CLAUDE.md に書く方法は、当日お話しした「文章で頼む」側です。読まれますが、守るかどうかに判断が入ります。急ぎの依頼だと省略されることがあります。

Plan モードは Shift と Tab での切り替えで入る、実行そのものが止まるモードです。書き込みが発生しない状態が保証されます。当日のデモ4本目でお見せしたのはこちらです。

確実に計画から入りたいなら Plan モード、ふだんの癖として寄せたいなら CLAUDE.md という使い分けになります。両方やっても問題ありません。

やり方は3つあります。手元でよく使うのは1番目です。

1. サブエージェントごとにモデルを変える　サブエージェントの定義ファイルには model の指定があります。ここを別のモデルにしておくと、親が集約する形で意見が並びます。当日お見せした定義の model: inherit を、別のモデル名に変えるだけです。

2. 出力をファイルに落として渡す　それぞれのモデルの回答を1つのフォルダに書き出し、最後に「この3つの案の食い違いを整理して」と頼む形です。手作業ですが、確実です。

3. MCP 経由で別のモデルを呼ぶ　他社モデルを呼ぶ MCP サーバーを繋げば、会話の中から直接呼べます。ただし接続先ごとに権限の管理点が増える点は、当日お話ししたとおりです。

ご質問の「意見交換」を自動で回すなら1番目が近いですが、まとめ役のモデルの癖が結論に出ます。まとめ役だけは自分で選んでください。

その認識で合っています。.github/copilot-instructions.md は文章で伝える仕組みで、読まれても守るかどうかに判断が入ります。実行の直前に必ず割り込んで止める、という動きにはなりません。

同じ目的をどう達成するかというと、止める場所を AI の外に移すことになります。実務での置き方は次の2つです。

1. コミット前で止める　Git のフックや CI で、禁止パターンを含む変更をはじきます。AI が書いた後になりますが、外に出る前には止まります。

2. 書ける場所を制限する　権限のない場所には最初から書けないようにしておきます。

当日お話しした5面でいうと、Copilot では「権限」と「検証」で担保する形になります。「制御」を AI の実行時に差し込むのは、いまのところ Claude Code 側の Hooks が得意とするところです。

配布データの copilot/ には、4ファイルを1枚に畳んだ版を入れてあります。コンテキストの設計はそのまま持ち込めますので、まずそちらから始めてください。

ファイルを触る前の層と、触る層を分けて案内しています。

コードを書かない方には、まずチャットのまま使える範囲で成果が出る業務を探してもらいます。議事録の要約、文章の言い換え、表の整理などです。ここは設定なしで効きます。

ファイルの設定に進んでいただくのは、同じ依頼を月に何度も繰り返していると分かってからです。繰り返しがあれば、置いておく価値が説明できます。繰り返しがないうちに設定から入ると、手間だけが残ります。

今日の内容でいえば、context/ に何を書くかを決めるのは業務を知っている方の仕事です。ファイルを作る作業だけを分担していただいても構いません。

意義はあります。ただし、書く場所は分けたほうが早いです。

当日お話ししたとおり、context/ に書く内容はコードの知識ではなく業務の知識です。用語、判断ルール、承認が必要な操作。これらは業務を知っている方でないと書けません。実装に詳しい方が書くと、社内の呼称や例外の扱いが抜けます。

ですので書く人と動かす人を分けても構いません。非エンジニアの方に持ち帰っていただきたいのは、ファイルの作り方ではなく「何を渡せば AI の答えが変わるか」という感覚のほうです。

今日のハンズオンで受講者の方が実際に書いたのは10行前後で、それで出力が別物になりました。あの10行は業務の知識です。

ゆくゆくは Git に置くのが最適だと考えています。ただし、全員がコマンドを覚える必要はありません。

置き場所として Git が優れているのは、誰がいつ何を変えたかが残るからです。当日お話ししたとおり、事実でなくなった記述はそのまま害になります。古い記述を落とす運用を回すには、履歴が追える場所であることが効いてきます。共有フォルダでは「誰かが変えた」までしか分かりません。

コマンドについては、AI エージェントに依頼できます。日本語で「この変更を記録して共有してください」と頼めば、必要な操作は代わりに実行されます。手で打つコマンドを暗記する場面は、実際にはほとんどありません。

ただし、概念の理解は避けられません。変更が手元にある状態と共有された状態が別であること、他の人の変更と自分の変更が衝突しうること、履歴は戻せること。この3つが分かっていないと、AI に頼んでも何が起きたのか判断できません。覚えるのは操作ではなく仕組み、という形になります。

始め方としては、この順で広げています。

1. 置き場所を1つに決める　最初は共有フォルダでも構いません。「ここが正」という場所を1つにします。

2. 更新する人を絞る　全員が書き換えると古い記述が混ざります。更新の窓口は少人数にしてください。

3. 中身が育ってきたら Git へ移す　このタイミングで、更新する少人数の方だけが概念を押さえれば足ります。参照するだけの方は、ファイルを受け取るだけで動きます。

始める時点では、ファイルを1つ配るだけで十分です。まず中身が育つかどうかが先で、配り方の仕組みは後から変えられます。

まず、自社の規程が先です。規程で禁止されているなら、技術的に可能かどうかに関係なく送れません。ここは実務判断ではなく、確認事項です。

そのうえで、規程の範囲内で判断する材料をお伝えします。

確認する点　利用しているプランで入力データが学習に使われるかどうか。事業者向けのプランでは学習に使わない設定が既定になっていることが多く、ここは契約と設定の両方で確認できます。

送る前に減らす　議事録の要約なら、氏名を役割名に置き換えるだけでも risk は下がります。全文を送らずに該当箇所だけを送る、という運用も有効です。

送らずに済ませる　当日の内容でいえば、判断ルールや用語集は社外秘を含まない形で書けます。事実そのものではなく「どう扱うか」を渡すだけでも、出力はかなり変わります。

判断に迷う場合は、その情報が外部に出たときに困るかどうかを基準にしてください。困るなら、送らない方法を先に検討する価値があります。

行き過ぎではないと考えます。むしろ、当日お話しした5面のうち「制御」と「記録」を、実際に運用に載せている状態です。

個人で複数のエージェントを動かす場合、人が全部を見ていられません。見ていない時間帯に何が起きるかを、仕組みで縛るのは合理的です。起票を必須にする設計は、後から「何をやったのか」を追えるようにする点でも効きます。

ひとつだけ、運用が続くかの観点でお伝えすると、ゲートを足すほど自分の作業も止まります。止まる回数が増えて自分で迂回し始めたら、そのゲートは実効性を失います。定期的に「このゲートは何回止めて、そのうち何回が本当に必要だったか」を数えると、削る判断がしやすくなります。

第3回（2026年11月）では、まさにこの「人が見ていない時間帯に動かしたときに何が壊れるか」を扱います。

statusline は CLI でのみ動きます。拡張機能の画面では同じようには動きませんので、現象としてはそのとおりです。

対処は2つあります。

1. これを機にターミナル側へ寄せる　statusline を使いたいなら、CLI で動かすのが素直です。エディタは編集に使い、実行はターミナルで、という分け方に切り替える判断はあり得ます。

2. 別の見る手段を用意する　少し話がずれますが、講師はトークンの消費を常に監視するウィンドウのツールを自作して、そちらを見ています。作業している画面とは別に、消費の状況だけが出ている窓を1つ置いておく形です。これなら Claude Code をどこで動かしていても関係なく見られます。

いまお使いの「セッションが終わったら usage を実行してログに残す」方法も、確実さでは悪くありません。手間を減らすなら、セッションが終わる地点で走る Stop フックに記録の処理を寄せると、手で打つ工程がなくなります。

いずれにしても、当日お伝えした「止める Hook より先に、見る Hook を1本」がここにも当てはまります。まず何にどれだけ使っているかが見えるようにしてから、制限を考えるほうが順番として無理がありません。セッションの中からは /usage で消費と残りの枠を確認できます。

第1回の教材サイトを公開しています。下記からご覧いただけます。

https://0521agentic.give-app.net/

2026年5月の第1回「エージェンティックエンジニアリング」の資料一式です。Hooks・Skills・サブエージェントの3つを、Nginx 風のログから 5xx の多発原因を要約するエージェントという題材で1つずつ動かした回で、配布データもそのまま置いてあります。

第2回は独立して完結する構成にしてありますので、第1回の資料がなくても今夜の内容は追えます。第1回で扱った3つの機能の役割の違いは、補足資料ページの用語集にも置いています。

分けることをお勧めします。

ハーネスの中身は、そのプロジェクトの事情に強く依存します。用語も、承認が必要な操作も、止めたい操作も、プロジェクトごとに違います。1つにまとめると、あるプロジェクトには関係のない記述まで毎回読まれることになり、コンテキストを圧迫します。

講師の手元でも、案件ごとにフォルダを分けて、それぞれに CLAUDE.md と context/ を置いています。

そのうえで、全部に共通する決めごとだけは1か所に置いています。文章の書き方、配色、禁止事項のような、どの案件でも変わらないものです。手元では個人設定側の CLAUDE.md がその役割を持っていて、各プロジェクトの CLAUDE.md はそれを上書きする形で短く保てます。

モノレポが向くのは、複数のプロジェクトが実際に同じコードを共有していて、横断で変更を入れる場面が多い場合です。管理の都合だけで1つにまとめると、コンテキストの側で損をします。

共通のものを1つ持ち、各プロジェクトからは参照する形をお勧めします。

複製すると、更新のたびに全部を直すことになります。直し漏れたものが1つでも残ると、そこには古い記述が残ります。当日お話ししたとおり、更新されなくなった記述は事実として読まれるので、複製の数だけ事故の起点が増えます。

置き方は、共通のファイルを1か所に置いて、各プロジェクトの CLAUDE.md から参照を1行書くだけです。全体の規約は共通側、そのプロジェクト固有の事情は各プロジェクト側、という切り分けになります。

これは前の質問（I-1）の答えとも繋がります。分けるのはハーネス、共有するのは共通ルールです。

CLAUDE.md の1枚だけで始めてください。

順番としては、この順を勧めています。

1. CLAUDE.md　プロジェクトの目的、使っている技術、やってほしくないこと。これだけで毎回の説明が要らなくなります。効果が最も早く出ます。

2. context/　同じことを2回説明したと気づいたときに作ります。用語や判断ルールがそこに溜まっていきます。

3. Skill　3回同じ手順を説明したときです。当日お伝えした基準がここです。

4. Hook　これは最後で構いません。個人開発では、事故が起きても自分が困るだけです。ただし外部に何かを送る処理（メール送信、API への書き込み、公開リポジトリへの push）が入ったら、その時点で1本入れてください。

小規模なほど、作らないことのほうが効きます。必要になってから足す順番を守れば、使われないファイルが溜まりません。

有効です。当日、コンテキストの命令が守られないという質問にも同じことをお答えしました。

効くのは2つの面です。

探す手間が減る　ファイルが増えるほど、AI は「いまどれを見るのが正しいか」を推測します。目次があるとその推測が要らなくなります。

読む量が減る　これがご質問の点です。目次に「この作業のときはこの2つ」と書いてあれば、関係のないファイルを開かずに済みます。全部を CLAUDE.md に書いて毎回読ませるより、目次1枚と必要なファイルだけのほうが、結果として渡す量は少なくなります。

ただし、目次そのものが育ちすぎると本末転倒です。フォルダの一覧と、作業ごとの参照先。この2つに絞って、20行前後に収めてください。

しています。判断の重さで分けるのが基本です。

考える量が多い作業（設計、原因の切り分け、文章の構成）は上位のモデル、決まった手順を回すだけの作業（形式の変換、一覧の作成、単純な置換）は軽いモデル、という分け方です。

やりやすいのは、当日お見せしたサブエージェントの定義ファイルで指定する方法です。定義には model の項目があるので、調べる役だけ軽いモデルにしておく、といった設定ができます。1つの作業の中で自動的に切り替わるので、手で選ぶ必要がありません。

コストの面でも効きます。調べる役は読む量が多いぶん消費も大きいので、そこを軽いモデルにすると全体が下がります。

妥当な設計だと考えます。当日お話しした5面が、それぞれ別の部品に割り当てられている状態です。

特に good だと思うのは2点です。

一次判断をローカルに置いていること　振り分けの段階では、依頼の中身がそのまま読まれます。ここを手元で処理していれば、外に出る情報を絞れます。当日の機密情報のご質問とも関わりますが、どこで境界を引くかが設計として決まっているのは強い形です。

承認が最後にあること　自動で進む範囲と、人が判断する範囲が分かれています。当日お伝えした Human in the loop は、まさにこの地点を固定する話です。

気をつける点を1つ挙げるなら、QA ゲートの判定基準が固定されているかです。検査の観点が実行のたびに変わると、通ったり通らなかったりの理由が追えなくなります。観点は人が決めて、実行だけ任せる形にしてください。

第3回（2026年11月）では、この規模のものを長時間動かしたときに何が壊れるかを扱います。

AI が参照できる範囲に、答えるための材料が無いという応答です。次の順で確認してください。

1. 開いているフォルダが正しいか　当日お伝えしたとおり、AI は起動した場所を基準に設定ファイルを読みます。目的のフォルダより1つ上や下で起動していると、必要なファイルが見えません。

2. 対象のファイルがインデックスされているか　拡張機能によっては、参照できるファイルの範囲が限られます。巨大なフォルダや、除外設定に入っているフォルダは対象外になります。

3. 質問にファイル名を添える　「この機能はどう実装されていますか」ではなく「src/xxx.ts のこの関数は」と指定すると、探す範囲が決まります。この応答が出るときは、何を見ればよいかが決まっていないことがほとんどです。

根本的には、当日お話しした INDEX.md が効きます。どの作業のときに何を読むかが書いてあれば、AI が探す段階でつまずかなくなります。