AIエージェントツール

ChatGPT のようなチャットとは別物の「AIエージェント」（Claude Code・Codex など）。自分のPCやプロジェクトの中で、ファイルを読み・コマンドを実行し・変更まで行う。何が違い、どう使いこなすか。

1-1AIエージェントと Web版チャットの違い

Web版チャット（ChatGPT・Claude.ai など）とは、そもそも別の道具。

2つの違い

1. 手を動かす：自分で書いてAIに見せるのではなく、「やりたいこと」を伝えると、AIが探索 → 計画 → 実装まで行う。
2. 道具を使う：Web版は使える道具が固定・限られる。エージェントはあなたの環境の道具（ファイル操作・コマンド・git・検索・外部システム…）まで使える。

1-2道具を「知って・使わせる」のが肝

エージェントの強さは、あなたの環境の道具を使えること。「何が使えるか」を知り、使うよう明示するのが上達の近道。

やりたいことには、たいてい“公開された道具”がある

• 何かやりたいとき、それ専用の便利なツール／ライブラリが世の中に公開されていることがほとんど。エージェントはそれを呼び出して使う。
  • 例：PDFを編集するツール、Word・Excel・PowerPointを扱うツール、画像加工、データ集計 など。
  • MCP（外部システム接続の共通規格）でも、対応ツールが次々に公開されている（後述）。
• ＝ゼロから作らず、既製の道具を借りて使う（スキル〔2-4〕やライブラリと同じ発想）。

外とつながれるのが大きな強み

• APIを叩ける → データを持ってこれる：社内外のサービスから最新データを取得して使う。
• CLIを操作できる：gh・aws・gcloud などのコマンドで外部サービスを直接動かす（最も手数が少なく効率的）。
• 加えて、ファイルの読み書き・コマンド実行・git（履歴/差分）・Web検索 も道具。

既製の道具がなければ、その場でスクリプトを書く

• 専用の道具がない処理は、AIが小さなプログラム（スクリプト）を書いて実行して片付けられる（強力だが、まず探すのは“既製の道具”）。
• しかも出力が安定する：決まった処理をコードにやらせると、同じ入力なら同じ結果＝再現する。検証もでき、残せば次も同じ品質。
  • 例：「1000件を目で数える」より「数えるコードを書いて実行」。

AIの苦手は道具で補う

• 正確な計算・文字数・学習後の最新情報は苦手。「コードを実行して数えて」「Web検索で最新を確認して」のように道具を指定する。指定しないと“頭の中”で済ませ、自信満々に間違える。

1-3できること／苦手なこと

• 得意：手順を事前に決めきれない開放的な仕事。特にコーディングはテストで正否を検証できるので、結果をフィードバックに自分で直せる（実際にGitHubのIssueを自律解決する）。
• 得意：コードや資料の調べ物・説明（「このコードは何をしている？」と、先輩に聞くように尋ねる）。
• 苦手・注意：自律ゆえ誤りが連鎖し、コストも増える。要所で人間の監督が要る（丸投げしない）。
• 原則：検証できる形（テスト・スクリプト・スクショ）を渡すほど、安心して任せられる。

2-1最大の制約＝コンテキスト（作業机）

エージェントは、限られた「作業机（コンテキスト）」の上で考える。会話・読んだファイル・コマンド出力のすべてが机を占有する。チャット履歴は資産にならない。

• 机が埋まると性能が落ちる（前の指示を忘れる・ミスが増える）。1回の作業で数万トークン消費することもある。
• だから 長いチャット履歴は資産にならない。むしろノイズになる。
  • 無関係な話に移るときは履歴をリセットして机を片付ける。
  • 残したい価値はファイルに書く（ルールファイル・スキル・仕様書・gitのコミット）。＝資産はファイルに貯める。

2-2ルールファイル ― 毎回読ませる「前提」

エージェントは毎回、決められたファイルを最初に読む。そこにプロジェクトの前提を書いておけば、毎回同じ説明を省ける。

• Claude Code は CLAUDE.md／Codex など多数は AGENTS.md。名前は違うが役割は同じ＝「エージェントに毎回渡す前提メモ」。
• AGENTS.md は多ツール共通のオープン規格（“エージェント版のREADME”）。Codex・Copilot・Cursor・Gemini CLI など多数が対応し、1つ書けば複数ツールで効く。
• 何を書くか：コードから推測できない前提だけ。
  • 入れる：ビルド／テストのコマンド、独自のコード規約、ブランチ・PRの作法、環境の癖、非自明な落とし穴。
  • 入れない：コードを読めば分かること、言語の常識、頻繁に変わる情報、長い説明。
• 短く保つ：長いと肝心の指示が埋もれて無視される。各行に「これを消すとAIが間違えるか？」を問い、要らなければ削る。

2-32種類のメモリー ― 人が書く指示／AIが書く学び

置き場所（スコープ）で分ける

• 本体側（自分用・全プロジェクト共通）：どのプロジェクトでも効く自分の好み・作法。
• プロジェクトごと（リポジトリの中）：そのプロジェクトの決まり。gitに入れればチーム全員で共有。
• 個人メモは共有する場所に混ぜない（分けて置く）。

2-4同じ作業を再現させる ― スキル／コマンド

同じ手順を何度も貼っているなら、それはスキル化のサイン。

• スキル＝手順書ファイル。ルールファイルと違い、使うときだけ読み込まれるので、長い手順を置いてもコストが増えない。
  • 例：「Issueを直す」スキル＝〈読む → 調べる → 直す → テスト → コミット → PR〉を定型化し、一言で起動。
• 削除・送信など副作用のある手順は手動起動にして事故を防ぐ。
• 説明文は「何をする・いつ使う」を、他人に説明する三人称で書く。ここが曖昧だと呼び出されない。
• ゼロから書かなくてよい：多くのスキルは公開・インストールできる。スキルを作るためのスキル（skill-creator／writing-skills）まである。ただし玉石混交なので、公式・定評あるものを選ぶ。

良いスキルの作り方（段階的開示）：必要なときだけ深く読み込ませ、机（コンテキスト）を節約する。

3-1伝え方 ― 良い言い回し／悪い言い回し＋認識合わせ

具体的なほど、直しが減る。曖昧な指示は“探索したいとき”だけ有効。

認識合わせ＝文章化

• 作業させる前に、理解を確認する：いきなり着手させず、まず自分の意図を正しく理解しているかを確かめる（「どう理解した？」と一言聞く程度でよい）。ズレていれば作り始める前に直す。
• 大きな仕事は、いきなり作らせずAIに質問させて仕様（SPEC）を先に文章化 → 合意 → 実装。
• 仕様をファイルに残せば、実装はきれいな状態から始められる（計画で机が散らかったら、新しいセッションや /clear でリセット。短ければ同じセッションのままでよい）。
• 良い仕様は自己完結：関係ファイルを名指し、やらないことを明記、最後に動作確認の手順を置く。
• 原則：「どのファイル・どんな条件・完了の定義」を渡す。

3-3権限・安全性 ― 勝手に実行させない

エージェントは実際にコマンドを実行できる＝便利だが危険もある。既定では、変更を伴う操作の前に確認が入る。

確認疲れを減らす3段階（下ほど自由・上ほど安全）

• Codex は既定で「提案のみ」（承認するまで実行しない）＝安全な出発点。
• 鉄則：検証できないものは出さない。人間のレビューを前提に運用する。

3-4外に広げる ― 外部接続・チーム共有・失敗パターン

• 道具を増やす（MCP・CLI）：gh などのCLIや MCP で、Issue管理・DB・デザイン・監視・社内システムにつなぐ。＝エージェントの手が届く範囲を広げる。
• チーム共有：ルールファイルをgitにコミットすれば、全員が同じAI挙動を得る（属人化を防ぐ）。共通規格 AGENTS.md なら多ツールで共有できる。

よくある失敗（と対策）

• 何でも詰め込みセッション → 無関係な話でリセット
• 同じ修正の繰り返し → 2回ダメなら履歴を捨て、良い指示で再開
• ルールファイルが肥大 → 剪定する
• もっともらしいが未検証 → 必ず検証を渡す
• スコープなしの「調べて」で暴走 → 範囲を絞る（別枠で調べさせる）

3-5各テーマは、もう「スキル」として公開されている

この資料で挙げたベストプラクティスの多くは、すでに公開スキルとして存在する。自分で書く前に、探して使う／手本にするのが早い。

• 公式（Anthropic）：pdf／docx／pptx／xlsx（Word・Excel・PowerPoint・PDFを作る）、web-artifacts-builder、webapp-testing、mcp-builder（外部接続）、skill-creator。
• Claude Code 同梱：/code-review（差分をレビュー）、/debug。
• コミュニティ：superpowers、addyosmani/agent-skills など、開発の一連（要件→計画→実装→検証→レビュー→出荷）を網羅する集まり。

この資料のテーマ → 近い公開スキルの例

• 注意：公開スキルは数十万規模だが品質はまちまち（調査では平均品質は中程度、良質なものだけが成績を大きく上げる）。公式・定評あるものを選ぶ。共通規格（Agent Skills）なので、Codex・Cursor・Gemini CLI など多ツールで使い回せる。

第1〜3部の考え方（道具・コンテキスト・ルールファイル・フォルダ設計）を、1つの具体像にまとめる。プロジェクトを会社（1つのオフィス）に見立てる。フォルダ＝部屋、その部屋に置く指示書＝ルールファイル（CLAUDE.md／AGENTS.md）。

4-1会社の見取り図 ― 働くのは1人、部屋ごとに指示書

• プロジェクト＝会社（建物）。中のフォルダ＝部屋。
• 働くのはAI1人（新人）。部屋が勝手に動くのではない。新人が部屋を巡回し、入った部屋のドアに貼ってある指示書を読んで、その通りに手を動かす。
• つまり ―― 場所＝フォルダ／指示書＝そこに置くルール／動く人＝AI1人。この3つを分けて考える。

部屋は役割で分ける（回る順番は仕事によって変わる。必要な部屋だけ置く）。中身は 4-4 で扱う。ここに挙げるのは例。大事なのは「役割ごとに分ける」考え方で、自分の仕事に必要な役割を見つけて、部屋を自分で足す（例：翻訳室、集計室、レビュー室 など）。

• もの・データが流れる部屋：データ倉庫（生データの保管）／加工室（データを変換。道具棚つき）／デザイン室（出力の体裁）／出荷室（完成物の置き場）
• それを支える部屋：資料室（記録）／見本室（手本）／検品室（検証）／金庫（鍵・認証情報）／下書き室（一時ファイル）／ルール室（共通の規程。4-5）

4-2指示書があるか、ないか ― ここが安定の分かれ目

新人が部屋に立ったとき、何をするかは従うべき指示書があるかで変わる ―― その部屋に貼ってあるか、または共通の手順書を持ち込んでいるか（4-5）。

• 指示書がある（貼り紙、または持ち込み）：その通りに動く。だから毎回同じ結果＝安定する。
• 指示書がない（貼り紙も持ち込みもない）：新人はその場を放置しない。その時の全体の指示（入口の一般的な決まりや、口頭で頼んだ一過性の指示）を頼りに、自分の判断で「いい感じ」に仕上げてしまう。頼めば動くが、拠り所がその場限りなので毎回変わる。

指示書がないと、こうブレる（例）

• デザイン室に体裁の指示書がない → 出力のたびにフォント・色・見出し・形式が変わる。前回と揃わない。
• データ倉庫に仕分けの規則がない → 置き場所や名前がバラバラになり、次に探せない。
• 加工室に手順・使う道具の指示がない → 自己流で処理する。うまくいく回もあるが、方法が毎回変わって安定しない（苦手な処理を道具なしで済ませ、外すことも）。

4-3AIの思考をどこに使うか ― 考えさせる所と、決めておく所

安定にはもう1つの軸がある。仕事を「AIに考えさせる所」と「決まった手順に固定する所」に切り分けること。

• 考えさせる所（ルール＋思考）：ルール（規約）を守りながら、判断・創造して出力する部分。例：コーディングのロジック設計、文章の構成、分析の切り口。ここはAIの思考が価値を生む。
• 決めておく所（固定スクリプト）：毎回同じでよい、決まった処理。例：整形・lint・ビルド・テスト実行・集計・形式そろえ。ここはスクリプトや道具に固定する。

なぜ切り分けるか

• AIの思考はゆらぐ・毎回少し変わる・コストがかかる。考える必要のない所まで毎回考えさせると、遅く・不安定になる。
• 決まった所をスクリプトに固定すると毎回同じ・速い・検証できる。そのぶんAIの思考を本当に判断が要る所に集中させられる（1-2「決まった処理はコードにやらせる」を設計判断に引き上げたもの）。
• コーディングが顕著：ロジック（考える）と、整形・テスト・ビルド（決まった手順）の線引きがはっきりしている。後者を毎回考えさせない。

どこまで任せられるかは、状況で動く

• モデルの能力（上位ほど複雑な判断に強い）／思考時間（じっくり考えさせるほど難所に強い）。
• タスクの難しさ・曖昧さ／渡した材料（指示書・手本・仕様・データ）の質／指示の具体性（3-1）／検証できる形か（1-3）。
• → 固定の正解はない。小さく試し、結果を見て「ここまで任せる／ここは決め打ちにする」の感覚をつかむしかない。

4-4各部屋に何を書くか（指示書の中身）

各部屋の指示書には、「その部屋で毎回ブレると困る決め事」を書く。コードや中身を見れば分かることは書かない（2-2 ルールファイルと同じ原則）。

もの・データが流れる部屋

それを支える部屋

• ルール室は、複数の部屋で共有する共通の規程を置く場所。読ませ方が他と違う（持ち込み式）ので、4-5で扱う。
• 「使うべき道具があればそれを使う」ことも、加工室の指示書に明示（指定しないと自己流で済ませる）。共通して使う道具は、別に道具庫としてまとめてもよい。
• 出来上がりをどこに置くかまで書く。置き場が曖昧だと、次に取りに来たとき迷う。

4-5指示書の置き場所と読まれ方 ― 入口は薄く、共通は持ち込む

すべてを入口（メインルートの CLAUDE.md）に書くと、コンテキスト圧迫（関係ない規則まで毎回読む）と指示のブレ（別の部屋の規則が混ざる）が起きる。だから入口は薄く保ち、置き場所を3つに分ける。

• 入口（ルート）：短い全体ルールと、建物の地図（「各部屋の指示書に従え」）。作業の最初に自動で読まれるので、全体に効く短い決まりだけ置き、薄く保つ。
• 各部屋の貼り紙（そのフォルダの指示書）：その部屋だけの固有ルール。その部屋のファイルに触れた時点で自動で読み込まれる。近い部屋の指示書ほど優先。
• 共通文書（ルール室にまとめて置く手順書）：複数の部屋で共有する、または長くて入口に置きたくない決まり（例：コーディング規約、命名規則、検品の手順）。各部屋に貼らず1か所にまとめ、その部屋に入るときに「これも読め」と参照させて持ち込む。

"持ち込み（参照）"の方が、むしろ多い

• 「全部屋で常に効くルール」は実は少ない。多いのは「この部屋（この種類の作業）に入るなら、この共通文書も読め」という部屋を限った参照。
  • 例：コーディングをする部屋に入るときだけ、ルール室のコーディング規約を持ち込む。データ倉庫やデザイン室には持ち込まない。
• こうすると、共通ルールを部屋ごとに複製せず1か所で直せて、要る部屋にだけ効く。スキル（2-4）も、この持ち込む手順書の一種。

4-6その場しのぎでなく整備する ― 指示書を育てる

指示書は、ゼロから自分一人で書かなくてよい。作り方は2つ。

• AIと一緒に作る：「こういう出力にしたい／この部屋ではこう決めたい」と目的をAIに伝え、指示書の案をAIに書かせる。案と実際の出力を見比べ、AIと直していけば狙い通りに近づく。
• 良い出力から逆算する：たまたま上手くいった成果物から、効いていた決め事を抜き出し、各部屋の指示書に落とす。

どちらの場合も ―― 毎回変わるもの（その回の入力・宛先など）だけその都度指示し、変わらないものは指示書に固定する。＝一過性の成功を、次から再現する仕組みに変える。

4-7使い方の例 ― 3つのケース（部屋をフォルダに落とす）

これまでの考え方と会社モデルを、具体的な仕事にあてはめる。各例で、部屋（役割）が実際のフォルダにどう並ぶかも示す。

①アナリティクスのレポートを毎月作るAPI → PDF → 繰り返し

• データはAPIで自動取得：手入力やCSVでも作れるが、APIを叩けば取得を自動化できる。特に定期的に作るもの（毎月のレポート等）は効果が大きい。
• 整形・PDF化は既製の道具：PDFを作るライブラリ/ツールで体裁に整える。
• 手順をスクリプト/スキルに固める：一度作った流れをスクリプト化すれば、翌月は「今月分を作って」で同じ品質のPDFが再現。人は数字の確認だけ。
• 形式はルールに書く：項目・並び・宛先・体裁をルールファイル/スキルに定義 → 毎回ブレない。

report-monthly/
├── CLAUDE.md      # 入口：地図＋短い全体ルール
├── data/          # データ倉庫（API取得の生データ・日付別）＋ CLAUDE.md（仕分け規則）
├── scripts/       # 加工室（集計スクリプト・道具）＋ CLAUDE.md（手順・使う道具）
├── templates/     # デザイン室（体裁・CSS）＋ CLAUDE.md（形式）
└── output/        # 出荷室（完成PDF）

②Webサイトを作る

• まず認識合わせ：目的・ページ構成・トーン・参考サイト（画像で見せる）を、AIに質問させて仕様に文章化。言葉より手本を見せるのが速い。
• 1ページずつ作って、見て直す：作る →ブラウザ表示／スクショ→ 差分を見て直す、の短いループ。一気に全部作らせると崩れる。
• 既製の部品を使う：UIのテンプレートやライブラリを活用。ゼロから書かせない。
• 一貫性はルールで：配色・フォント・命名・使うライブラリをルールファイルに。全ページで揃う。

site/
├── CLAUDE.md      # 入口：配色・フォント・使うライブラリ（短い全体ルール）
├── pages/         # 各ページ
├── styles/        # デザイン室（CSS・テンプレ）＋ CLAUDE.md
├── assets/        # 画像など
└── examples/      # 見本室（参考サイトのスクショ＝手本）

③アプリを作る

• 認識合わせ → 仕様書：AIにインタビューさせ、何を作る／作らない／完了条件を先に仕様（SPEC）として文章化。合意した仕様はファイルに残す。実装はきれいな状態から始める。
• 既製ライブラリを使う：ログイン・DB・決済などは公開ライブラリ／サービスを使う（車輪の再発明をしない）。
• ルールファイルで土台を固定：使う技術・規約・テスト方法・ブランチ運用を CLAUDE.md／AGENTS.md に書き、gitで共有。
• 検証しながら小さく進める：テストを書かせて通す → 次。権限は確認／サンドボックス。技術選定などの判断は記録（ADR）に残す。

app/
├── CLAUDE.md          # 入口：使う技術・短い全体ルール
├── docs/              # 資料室（仕様SPEC・決定ADR）
│   └── conventions.md # ルール室：コーディング規約（コード作業時に持ち込む）
├── src/               # 加工室（実装）＋ CLAUDE.md
├── tests/             # 検品室（テスト）
└── .env               # 金庫（gitに入れない）