【勉強】生成 AI 協働者編①手元の開発環境に AI を入れる

生成 AI は毎日使っているのに、知識そのものは数年前で止まっている自覚がありました。Gemini や Claude を私生活で触っているのですが、どちらも「だいたい分かっている」つもりになっていて、実際には用語の意味も課金の仕組みも説明できない、という状態です。そこで、キャッチアップすべき項目を洗い出したラーニングパスを自分用に作り、端から潰していくことにしました。

構成は 4 レイヤー・15 ステップで、項目数は 80 ほどです。利用者編から始めて、協働者編・開発者編・運用者編へ進みます。進め方は「まず自分で手を動かして調べる・検証する」「詰まったところや調べきれなかったところを AI に補ってもらう」「ワークログに残す」の 3 つを項目ごとに繰り返します。

前回までの利用者編①〜③では、チャット UI での使い方から、専用の環境を用意するところまでを扱いました。今回から協働者編に入ります。協働者レイヤーは、コーディングエージェントを自分の開発ワークフローに組み込む段階で、協働者編①ではその最初のステップとして、手元の開発環境にエージェントを入れ、エージェントに渡す設定を整えるところまでを扱います。題材は普段使っている Claude Code に絞っていて、プラグイン・hooks・サブエージェントのような Claude Code 固有の機能も多く含みます。この記事は、そのワークログを清書したものです。個人的に勉強して、個人的にまとめただけのものなので、網羅的な解説になっていない可能性が大いにあります。また、生成 AI まわりは動きが速いので、記載の内容はすべて 2026-09 時点のものになります。

協働者編では、次のことができる前提で進めます。どれも生成 AI とは関係のない知識なので、ラーニングパスの項目には含めていません。

• ターミナルでコマンドを実行し、ファイルやディレクトリを操作できる
• Git で branch・commit・merge を自分で実行できる（Pro Git の最初の 3 章程度）
• GitHub でリポジトリを作り、プルリクエストを作ってマージしたことがある（GitHub の Hello World 程度）
• Python などで書かれたコードを読み、テストを実行できる

下の表が今回のやることリストです。私と同じような状況にある人は、ぜひこの順番で自分でもタスクをこなしてみることをオススメします。

AI エディタ

コーディングエージェントを自分の開発ワークフローに組み込むにあたって、まずは手元の開発環境を見直していきます。コーディング向けの AI エディタや CLI エージェントを一通り調べ、そのうちの 1 つでコードを書かせてみることにしました。

調べたツール

公式ページで調べたものを表にしました。

印象的なのは、VS Code や Zed といった AI 特化ではないエディタが、エージェントを載せる場所になっていることです。なお、2026-06 前後に製品の移行や改名が相次いでいて、最新の情報を探すのに苦労しました。

VS Code ＋ Claude Code 拡張を試す

普段から、エディタは VS Code、AI エージェントは Claude Code を使っているので、これを組み合わせた環境で動作確認をしてみました（VS Code で Claude Code を使用する）。Claude Code 拡張を入れた状態で Obsidian の Vault を開くと、左のサイドバーにアカウント情報とセッション履歴、右のサイドバーにチャット欄が表示されました。過去のセッション履歴が見えるのは、Claude Code ではプロジェクト単位で履歴を管理しており、普段からこの Vault は CLI 版の Claude Code で使っているためです。

チャット欄では次の 3 つを頼みました。

• 「あなたにはどんな役割が与えられている？」→ CLAUDE.md に書いた「個人的なナレッジベースを管理する AI アシスタント」と返ってきた
• 「このプロジェクトにはどんなメモリやスキルが蓄えられている？」→ メモリ 21 ファイルと Skill 1 つ（ユーザー側にもう 1 つ）と返ってきた
• 「〈特定のフォルダ〉に素数判定の Python スクリプトを書いて」→ 書いてくれた

ターミナルで使っている Claude Code の設定がそのまま読まれていて、UI が違うだけという印象でした。公式ドキュメントによると、拡張でできることは CLI でできることのサブセットになっているようなので、普段から CLI を触っていれば特に違和感なく使い始めることができそうです（VS Code 拡張機能と Claude Code CLI の比較）。

CLAUDE.md とメモリの棚卸し

以前の記事「利用者編②」で「何がいつ読み込まれるか」は整理したものの、自分のメモリは Claude Code に書かせたまま整理しておらず、全プロジェクト共通のはずの情報までメインプロジェクトの中にしか置いていませんでした。この機会に Claude Code に渡している情報を棚卸しして、置き場を組み替えました。

コンテキストエンジニアリング

メモリの棚卸しは、「プロンプトエンジニアリング」の次の段階として語られることが多い「コンテキストエンジニアリング」の一環とみなすことができます。この 2 つについて自分なりに整理しておきます。

• プロンプトエンジニアリング：個々の依頼文（プロンプト）の最適化
• コンテキストエンジニアリング：広範な前提知識（コンテキスト）の最適化（プロンプト＋メモリ＋ツール）

加えて、関連要素として、ハーネスエンジニアリングとループエンジニアリングにも触れておきます。

• ハーネスエンジニアリング：あるタスクの達成のために指示を毎ターン自動で続ける仕組みの設計（コンテキスト・ツール・Skill・エージェント・権限・ループ処理など）
• ループエンジニアリング：ターンを重ねたときに収束させる仕組みの設計（終了条件・反復条件・失敗の扱いなど）

なお、ハーネスエンジニアリングを実践していこうというのが、協働者編のテーマとなっています。そして本記事（協働者編①）の中盤以降では、そのための部品（Skill・サブエージェントなど）を扱っていきます。

メモリはいつ読み込まれるか

Claude Code では、CLAUDE.md の仕組み全体を「メモリ」、Claude が会話から自分で書き溜める memory/ 配下を「自動メモリ」と呼んでいます（Claude があなたのプロジェクトを記憶する方法）。CLAUDE.md には、全プロジェクト共通のユーザーメモリ（~/.claude/CLAUDE.md）と、プロジェクトごとのプロジェクトメモリがあります。読み込みのタイミングは次のとおりです。

なお、CLAUDE.md に何を書くかは先人の記事（効果的なCLAUDE.mdの書き方・Claude Code入門 #2: CLAUDE.mdの書き方と育て方）が多く、とても参考になります。

棚卸しと仕分け

私の環境の 2026-09-20 時点の状態は次のとおりでした。

プロジェクトメモリは、Vault に関する内容ばかりだったので、移動する必要はなさそうでした。一方で自動メモリにはさまざまなことが記載されているので仕分けの必要がありそうです。仕分けの基準は「Vault 以外のディレクトリで Claude Code を開いても効いてほしいか」にしました。以下がその結果です。

私はこの Vault で日々の作業のメモを残していたり、それをもとに Claude Code に相談したりしていたので、私のパーソナルな内容について自動メモリに残されていることが多かったです。これらのうち、開発環境に関することや、これまでの職歴や経験についてはユーザーメモリに移すことにしました。これは、開発等で別プロジェクトを開いた際にも覚えておいてほしい内容だからです。

一方で、ライフイベントやブログ執筆に関することはそのまま自動メモリに残すことにしました。これらもユーザーメモリに載せておけば別のプロジェクトでも参照されて楽なのですが、逆に言えばユーザーメモリは毎回必ず読まれるので、なるべく小さく留めておくに越したことはありません。必要になったらそのときにユーザーメモリに移動を検討します。

なお、自動メモリの内容には、古いままの情報（職種など）が残されていました。自動メモリは Claude が自身のタイミングで更新するので、その後いちども話題に出なかったトピックなどは古いまま放置されることがあります。定期的な棚卸しの必要性を感じました。

動作確認として、Vault で「私について教えて」と聞くと、直したほうの職種に加えて、自動メモリに残した引っ越しの時系列も答えてくれました。別のフォルダで起動したときは、職種だけを答え、引っ越しの話は出てきませんでした。これは意図どおりの挙動でした。

Agent Skills

普段 Claude Code で Skill を使っているのですが、Agent Skills がオープン標準として公開されたと知ったので、その仕様について調査してみることにしました。

フォルダの中身を標準化

標準化された Skill の実体は、SKILL.md を含むフォルダです。起動時には名前と説明（description）だけが読み込まれ、本文は Claude が必要と判断したときに初めて読まれます（Claude をスキルで拡張する）。Agent Skills は、2025-12 に Anthropic がオープン標準として公開したもので（Agent Skills）、対応するクライアントの一覧には、Gemini CLI・Codex・Cursor・GitHub Copilot などが並んでいます。ただし、そのフォルダをどこに置くかは標準化されていないので、この仕様どおりにSkill の定義ファイルをフォルダに同梱しても、それが自動で読み取られるかはクライアントの実装次第になります。

気になったので、ほかに標準化されたものはないか調べてみると、外部ツールの呼び方として MCP、エージェントへの指示ファイルとして AGENTS.md があるようでした。AGENTS.md はリポジトリのルートに置く想定のファイルで（AGENTS.md）、Claude Code はこれまで CLAUDE.md だけを読んでいましたが、v2.1.277 から AGENTS.md も読むようになりました。ただし、デフォルトでは同じ場所に CLAUDE.md があると AGENTS.md は読まれません（AGENTS.md）。なお、Skill を MCP サーバー経由で配る仕組み（Skills over MCP）も標準化が進んでいるようです。

合言葉を返す Skill で動作確認

呪文「ゾルタクスゼイアン」を唱えたときだけ、特定の合言葉を返す Skill spell-check を作りました。合言葉が返れば Skill が呼ばれたと判定できます。

Claude Code では、/spell-check と明示して呼び出しても、「ゾルタクスゼイアン！」とだけ入力しても、あらかじめ決めておいた合言葉が返りました。以下がその時の入出力です。

❯ ゾルタクスゼイアン！

● Skill(spell-check)
Successfully loaded skill

SKILL-OK-xxxxxxxx

「ン」を抜いた「ゾルタクスゼイア！」では Skill は呼ばれず、トリガー語と一致しないという説明が返りました。このような応答を返せたのは、この Skill の description が起動時から読み込まれているためです。

次に、同じフォルダで Antigravity CLI を起動して同じ呪文を唱えると、全く関係のない応答が返りました。これは、Antigravity CLI が読みに行くのは .agents/skills/ で、Claude Code の .claude/skills/ は読まないためです。そこで、フォルダをそのまま .agents/skills/ にコピーしたところ、無事に Skill を認識することができ、合言葉が返りました。

> ゾルタクスゼイアン！

● Read(…/.agents/skills/spell-check/SKILL.md)

  SKILL-OK-xxxxxxxx

フォルダの形式が標準になっている効果で、フォルダの置き場所さえ気をつければ、Skill を自由に使い回すことができそうです。調べてみると、Codex・Gemini CLI・Cursor・GitHub Copilot も .agents/skills/ を読むようになっていて、ここがデファクトスタンダードになっていました。読まないのは Claude Code だけなので、複数のエージェントで使い回すなら、.agents/skills/ に実体を置いて .claude/skills/ からシンボリックリンクを張る形にすれば済みそうです。

プラグイン

/plugin を開いたら、自分で作った Skill とは別の欄に skill-creator が並んでいて、Skill とプラグインが何が違うのか分かりませんでした。プラグインに束ねられるものを調べ、公式のプラグインを 1 つ入れてみました。

束ねて配るための形式

プラグインは、Skill・サブエージェント・hooks・MCP サーバー・LSP サーバーの設定などを 1 つにまとめて配るための形式で、2025-11 にパブリックベータとして公開されました（プラグインを作成する）。公式ドキュメントでは、.claude/ に直接置く構成を「スタンドアロン」と呼び、次のように使い分けを説明しています（プラグインとスタンドアロン設定をいつ使うか）。

• スタンドアロン（Skill は /hello で呼ぶ）：個人のワークフロー、プロジェクト固有のカスタマイズ、ちょっとした検証
• プラグイン（Skill は /プラグイン名:hello で呼ぶ）：チームでの共有、コミュニティへの配布、バージョン管理されたリリース

配布はマーケットプレイス経由で可能であり、Anthropic 公式のもの、審査を通ったコミュニティのもの、GitHub などに自分で立てるもの、の 3 種類があります。インストールのスコープはユーザー・プロジェクト・ローカルの 3 つです。Skill 単体を配るだけなら前の項目の Skills over MCP でもよく、hooks や MCP サーバーまで束ねて配りたいときがプラグインの出番です。プラグインは Claude Code 固有の形式で、Agent Skills のような標準はありません。

LSP プラグインを入れてみた

公式マーケットプレイスには、LSP（Language Server Protocol）で型情報や定義の場所を Claude に渡す、コードインテリジェンス系のプラグインがあります（コードインテリジェンス）。Python 向けの pyright-lsp プラグインを、Python で書かれた適当な GitHub リポジトリのプロジェクトプラグインとしてインストールし、「この部分のコードを実行したときに、実際に処理をするメソッドはどれ？」のようなコードを読む質問を、プラグインを導入する前後で 3 つずつしてみました。

導入の前後とも Claude は Bash（grep）で調べて 12〜30 秒で答え、差は出ませんでした。LSP を使うよう明示すると 30〜57 秒に延びています。直感に反する結果だったのですが、どうやら質問が簡単すぎて、LSP プラグインを使うまでもなく答えられてしまうような設問になってしまっていたようでした。明示しないと Bash を使う理由を尋ねてみたところ、auto mode（権限の確認を AI が肩代わりするモード）では「Bash で済むことは Bash で」という指示が入っているためとのことでした。

LSP プラグインの効果を測定する実験にはならなかったものの、プラグインをインストールし、同梱しているツールを実行させること自体はできたので、これで良しということにしました。

hooks による品質ゲート

CLAUDE.md や Skill の指示は「お願い」なので、守られないことがあります。そこで、エージェントに任せる範囲を広げる前に、必ず走る検査を置いておきたいと思い、lint を自動で掛ける hook を 1 つ置いてみました。

指示と強制の違い

hooks は、Claude Code の動作の特定のタイミングで、シェルコマンドなどを自動で実行する仕組みです（Hooks リファレンス）。発火するイベントは約 30 ありますが、よく使うのはツール実行前の PreToolUse（危険なコマンドのブロック）、ツール実行後の PostToolUse（品質ゲート）、応答完了時の Stop です。

CLAUDE.md や Skill の指示が「お願い」なのに対して、hooks は「強制」です。公式ドキュメントを読むと、強制の側にはさらに permissions があり、整理すると次のようになります。

hooks の注意点は、イベントごとに毎回処理が走ることと、任意のコマンドを実行できることです。前者についてはなるべく軽量化を心がけることで対応し、後者については信頼できないリポジトリを clone したときは、Claude Code を起動する前に .claude/settings.json を確認しておく必要があります。

lint を自動で掛ける hook を置いてみた

プラグインの項目で使った Python の GitHub リポジトリに、編集のたびに ruff（Python のリンター兼フォーマッタ）を掛ける hook を置くよう Claude に依頼しました。そのあと、.claude/settings.local.json を覗いてみると、Write ツールと Edit ツールの使用後に PostToolUse で発火し、.py のファイルだけに ruff check --fix と ruff format を掛ける設定が出来上がっていました。

なお、コマンド実行後に返す終了コードにより、その後の Claude の振る舞いが変わります（終了コード出力）。exit 0 なら成功として処理が続き、exit 2 ならブロッキングエラーとして stderr の内容が Claude に渡され、Claude はそれを受けて次の行動を決めます。

動作確認では exit 2 が返ったあとの挙動も見てみたかったので、以下のようなわざと汚いコードを Write ツールを使って書かせてみました。

import os
import sys
def  f( ):
    l = 1
    return sys

すると、hook が発火し、自動実行の ruff により未使用の import os とかっこの中の空白は修正されましたが、l = 1 の 2 つの違反（紛らわしい変数名の E741、使われていない変数の F841）は残りました。その後、hook がこれを Claude に exit 2 で返すと、Claude はエラー内容を確認したうえで同じターンのうちにコードを直し、2 回目の hook の発火で無事にチェックを通過しました。

import sys


def f():
    return sys

なお、Claude が Edit ではなく Bash でファイルを書き換えた場合は、この hook は発火しません。そのため、ファイル更新後に確実に hook を走らせたい場合は、ターンごとに作業ツリーを調べる Stop hook や、書き込み元を問わず発火する FileChanged hook を組み合わせるよう、公式が注意喚起しています（matcher で hooks をフィルタリングする）。

サブエージェント

調べものを頼むと検索結果で会話がどんどん長くなるので、調査だけ別のエージェントに切り出したらどれだけ節約できるのかを確かめたいと思いました。サブエージェントの仕組みを調べ、調査担当のサブエージェントを 1 つ作りました。なお、Claude Code で複数のタスクを並行させる方法はサブエージェント以外にも 4 つあります（エージェントを並列実行する）。

仕組みと利点・欠点

サブエージェントは、独自のシステムプロンプト・使えるツール・権限を持ち、親とは別のコンテキストで動く専門役です（カスタムサブエージェントの作成）。実体は YAML フロントマター付きの Markdown ファイルで、ユーザー用は ~/.claude/agents/、プロジェクト用は .claude/agents/ に置きます。その他に、組み込みとして、読み取り専用で検索する Explore、計画の前に調査をする Plan、汎用の General-purpose が用意されています。利点は次の 4 つです。

• 結果だけを親に返すので、親のコンテキストを節約できる
• 使えるツールや権限を絞れる
• 専用のシステムプロンプトで、特定の仕事に特化させられる
• 安いモデルに切り替えて、コストを抑えられる

一方で欠点もあります。サブエージェントは会話の文脈を持たずにゼロから情報を集め直すので時間がかかり、途中で口を挟みにくく、子が使ったトークンのぶん総消費も増えます。こうした利点が要らない仕事なら、メイン会話で Skill を使えば十分です。

作り方は、以前は /agents コマンドの対話式ウィザードでしたが、v2.1.198 でウィザードがなくなり、今は Claude に作成を頼むか Markdown を直接書きます。作る前に Claude Code に相談すると、権限の絞り方、モデルを変えたときの比較、返す結果の形式を決めておくこと、の 3 点を勧められました。これを踏まえて、あるトピックに関する国内企業の実践事例を調べ、URL と要約のペアで返す jp-case-researcher を作成しました。これまでは同じことを手動で行っていましたが、検索上位にはただの解説記事や個人の「やってみた」系のブログがヒットしがちなので、効率化のためにサブエージェントを用意したかたちです。

親のコンテキスト消費を比べてみた

「Claude のサブエージェントを文章の執筆に活用しているような事例を調べて」という依頼を、サブエージェントを使わない場合と、jp-case-researcher のモデルを Haiku もしくは Opus にした場合の 3 条件で投げ、親（Opus 5.5）のコンテキストがどれだけ増えたかを見ました。

サブエージェントに任せると、親の増分は 30.0k から約 19k へ、4 割弱減りました。検索結果や読んだページの本文が、子の側に閉じたぶんです。ゼロにならない残りの約 19k は、子の報告と、それを受けて親が書いた最終回答のぶんで、子のモデルを変えてもほぼ同じでした。一方で、所要時間は 2〜3 倍に延びています。そのため、今回の状況設定ではサブエージェントを使わない方がメリットが大きそうでした。

サブエージェントに依頼するメリットが大きくなるのは、複数のトピックの事例を同時に調査させる時（恐らく 3 つのトピックを調べさせたらサブエージェントありの方が所要時間が短くなるでしょう）や、その後の親の会話がずっと続くような時（4 割減の効果がずっと効き続ける）、もしくは親は Fable のような高性能モデルを使っているもののサブエージェントに任せるタスクは Haiku のようなモデルで十分な時（請求額が少なく済む）、あたりでしょうか。

なお、定義にはあとから、子に CLAUDE.md を読ませない設定（omitClaudeMd: true）と、当たりだったドメインなどを覚えさせるエージェント専用の自動メモリ（memory: user）を足しました。これにより、次回以降はもう少し効率的に事例を調査してくれるようになるはずです。サブエージェントもメモリや Skill と同様に、使いながら育てていく意識が重要だと感じました。

まとめると、サブエージェントはコンテキストを節約できる代わりに、時間と総トークンは伸びがちです。目的ごとに分けると、次のようになります。

• 速くしたいだけなら、ツールの並列呼び出しで足りることが多い
• 親のコンテキストを守りたいなら、サブエージェント
• ファイルを編集する作業を並列にしたいなら、worktree で作業ディレクトリを分ける（次節のテーマ）

git worktree

サブエージェントでコーディングをさせるときに git worktree を使うことがあると聞いたので、仕組みから調べ、サブエージェントに worktree を 2 つ作らせてみました。

git worktree とは

git worktree は生成 AI の機能ではなく、Git にもともと備わっている機能です（git-worktree）。1 つのリポジトリから複数の作業ディレクトリを作れるので、ブランチごとに別のフォルダを開いたまま並行して作業でき、git switch や git stash で切り替える必要がありません。git clone を複数回するのと違って履歴は共有されるので、リモートを経由しなくても別の worktree のコミットをすぐにマージできます。同じブランチを 2 つの worktree で開こうとするとエラーになるので、混乱も防げます。

生成 AI の文脈では、複数のサブエージェントに同じリポジトリを別々のディレクトリで並行して触らせるために使います。Claude Code には次の仕組みがあります（worktree を使用して並列セッションを実行する）。

• claude -w <名前>：worktree を作り、その中で Claude Code を起動する（.claude/worktrees/ の下に作られる）
• .worktreeinclude：.env など Git で管理していないファイルを、新しい worktree にコピーする
• isolation: worktree：サブエージェントの定義に書くと、起動時に専用の worktree が自動で作られる

サブエージェントで試してみた

hello.py を 1 つだけコミットした小さなリポジトリで、2 つのサブエージェントにそれぞれ print の文言を変えてコミットするよう依頼しました。作業完了後の git log --graph --all の形は以下のようになり、ブランチ名は自動で付いていました（ハッシュや日時は省いています）。また、サブエージェント用の worktree が .claude/worktrees/ の下に作られていることも合わせて確認できました。

* (worktree-agent-a1bd695d82c7875b1) Change greeting in subagent worktree 2
| * (worktree-agent-aed90cfb510863c75) Change greeting in subagent worktree 1
|/
* (HEAD -> master) Add hello.py

注意点として、worktree が分けるのはファイルで、変更ではありません。今回の 2 本はどちらも同じ print の行を書き換えているので、master に順にマージすると、2 本目で必ずコンフリクトになります。作業中の衝突は防げても、同じ行を別々に変えた衝突は、マージのときまで先送りされるだけということです。これだとマージをする部分で詰まって作業の効率化につながらないので、並列にするなら、触るファイルや範囲が重ならないようにタスクを分けておくことが重要になります。

おわりに

エディタ、CLAUDE.md とメモリ、Skill、プラグイン、hooks、サブエージェント、worktree と、Claude Code に渡す設定を 1 つずつ整えてきました。どれもエージェントを無人で回すための、ハーネスエンジニアリングの下準備にあたる内容で、テーマが通っていたので進めやすいステップでした。一方で、エディタは従来の VS Code のままで、Cursor のような AI ネイティブなエディタは試せていません。使用感の違いは、いずれ比べてみたいと思っています。

ここまでは手元の土台づくりです。次は協働者編②として、GitHub の Issue を入口、プルリクエストを出口にして、エージェントに実装やレビューを任せるところへ進む予定です。