AIは「1+1って、2になること多いなあ」と思っている！？ ChatGPTに「1+1は？」と聞けば、当然「2」と返ってきます。 実はこのときのAIの内部で起こっていることは、割と大真面目に 「 私のデータによれば、1+1の答えは最も2が多いです 」なのです。 計算してるんじゃないの？ ChatGPTのようなAI（大規模言語モデル）は、極端なことを言ってしまえば、次の単語予測マシンです。 たとえば「むかしむかし、あるところに」と言われたら、「おじいさんと」と返す。「今日の天気は」と言われたら、「晴れ」とか「曇り」とか返す。 膨大な文章を読んで「この言葉の次にはこの言葉が来やすい」というパターンを学習しているだけなんです。 AIにとっては、計算問題も文章の一種のため、数学の問題も同じやりかたで解いています。 「1+1=」という文字列を見て、「この後には2が来ることが多いな」と思って2を返しているだけ。 つまり: 人間: 1+1を理解して、演算して、2を導く AI: 「1+1=」の後に「2」が来るパターンで覚えてる そう、タイトルの通り、AIは「1+1って、2になること多いなあ」なのです。 ほんと？ もしAIが計算を「理解」しているのではなく、単なる「パターンの暗記」だとしたら、 見たことがないパターンに出会ったときにボロが出るはず です。 その実態がよくわかる、2つの証拠を見てみましょう。 証拠1: ちょっと難しいかけ算ができない 普通の計算機（電卓）なら、2桁の足し算ができれば、4桁になっても10桁になっても、やることは同じなので間違えません。 しかし、OpenAIの研究論文「 Language Models are Few-Shot Learners 」（Brown et al., 2020）によると、当時のGPT-3は以下のような結果になりました。 2桁の足し算： ほぼ100%正解 4桁以上の計算： 正答率は 20%以下 に急落 つまり、ネット上にたくさん転がっている「よくある計算（2桁）」はパターンとして覚えているけれど、滅多に見かけない「大きな桁の計算」は、パターンがないのでお手上げになってしまうのです。   証拠2: 聞き方が変だとできなくなる たとえば「0.7 × 5 は？」と聞けばAIは即座に3.5と答えます。 でも同じ計算を「7×10⁻¹ × 5 は？」と科学的記数法で書くと、数学的にはまったく同じ計算なのに、急に怪しくなります。 Yang et al.（2024）の論文「 Number Cookbook 」では、LLMは標準的な整数計算には強い一方、分数や科学的記数法になると、精度が 20%以下 まで落ちることが示されています。 数学を理解しているなら「書き方が違うだけ」と分かりますが、AIにとっては 見たことがない珍しい文字列 に見えてしまうため、予測が外れてしまうのです。   やってみよう 実際に試してみましょう。ChatGPTに「4726 × 3891 は？」と聞いてみます。 あれ、普通に正解されました。 実は、今のAIはこの「弱点」を、 知能ではなく「仕組み」で克服 しつつあるんです。 今は解決してる ChatGPTの新しいもの（GPT-4o）やClaude 4.5などは、数学の実力テスト（MATHやGSM8Kといった、AIに数学の問題を解かせてスコアを測る標準テスト）で非常に高いスコアを出しています。その理由は主に2つあります。 1つ目はツールの利用です。 計算が必要な場面で、内部的にプログラミングコードを実行したり電卓を使ったりして、LLM自体は直接計算せずに正解を得る方法が発達しました。 2つ目は、Chain-of-Thoughtというもので、段階を踏んで思考することで、単純に答えるよりもはるかに複雑な問題を解けるようになりました。 例えば「23 × 47」を一発で出すのではなく、「23 × 40 = 920、23 × 7 = 161、920 + 161 = 1081」のように段階を踏めます。 これにより、実用上はAIは計算ができると言える水準になっています。   しかし、ここで注意したいのは、これらはいずれも AIが計算を「理解」しているわけではない ということです。 ツール利用は外部の計算機に丸投げしているだけですし、Chain-of-Thoughtも、本来1ステップでは処理しきれない問題を小さく分割して、トークン生成の過程で中間結果を一時的に保持する仕組みです。 LLMの本質は今も変わらず、次に来る言葉の予測であり、これらの間接的な手順を禁じた場合、AIは依然として大きな数の掛け算や見慣れない形式の計算で間違えます。 まとめ AIは計算を「理解」しているのではなく、「1+1の後には2が来やすい」というパターンで答えている そのため、桁が大きい計算や見慣れない書き方には弱い 最近はツール利用（コード実行）やChain-of-Thought（段階的思考）で実用上は高精度になった ただし、これらはあくまで補助手段であり、LLMの本質は変わっていない AIに計算させるときは、裏でちゃんとコードを実行しているか意識しておくと安心 おまけ 僕はブログを書くときに、AIにレビューをしてもらっています。 この記事をレビューさせてみたときのAIの反応がこちら：   AI: AIは計算ができない！？のレビューを開始します。 … ファクトチェック中… 計算例が間違っています。 本来ならば4726 × 3891 の正しい答えは 18,374,766 です。修正します.. … あ、そういえば私もAIでした。 Pythonコードを実行し、確認します。   最近のAIは賢いですね。 実は、計算例の部分は僕が「AIにこんな感じの例を提示して」と出力させたものなので、 つまりこのやりとりは、 AIが「AIは計算ができない！？」という記事をレビューし、 AIが計算した計算ミスをAIが指摘・修正し、 同時に自分がAIであることにはたと気づき、 AIは計算ができないため、直ちにプログラム実行によって確証を得る という、皮肉・メタ認知のミルフィーユであり、今のAIのアホさと賢さの両面が綺麗に凝縮されたやりとりでした。 関連記事 AIに嘘つかないでよーとお願いするとちょっと効くという記事を書いています： chatGPTに「ハルシネーションしないで」とお願いしたら効果がある？   ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post AIは「1+1って、2になること多いなあ」と思っている！？ first appeared on SIOS Tech Lab .

VS Code で Claude Code の SKILL.md を開くと allowed-tools is not supported や Unexpected indentation のエラーが出る。原因は GitHub Copilot の Agent Skills バリデータが .claude/skills/ を自動検出している ためです。Claude Code の動作には影響ないけど、エディタがエラーとか出してると目障りなのでね… files.associations に1行追加すれば消えます。 { "files.associations": { "**/.claude/skills/*/SKILL.md": "markdown" } } 以下、原因の詳細と Agent Skills 標準の経緯、関連する既知の Issue を整理します。 何が起きているのか GitHub Copilot が 2025年12月に Agent Skills というオープンスタンダードに対応しました。このスタンダード、実は Anthropic が 2025年10月に Claude Code で先行リリースしていたもので、後にオープンスタンダードとして公開された経緯があります。 で、このスタンダードでは Skills のファイル名として SKILL.md を使います。Claude Code も Copilot も同じ名前。偶然の一致じゃなくて、同じ仕様に基づいています。 問題はここからで、VS Code の Copilot バリデータが .claude/skills/ 配下の SKILL.md も 自動検出してバリデーションをかけてくる んですよね。 なぜ Warning が出るのか Agent Skills 標準には以下のフィールドが定義されています。 フィールド 必須 実験的 name Yes No description Yes No license No No compatibility No No metadata No No allowed-tools No Yes allowed-tools は 実験的フィールド です。Claude Code では普通に使えるんですが、VS Code 側の Copilot バリデータがまだ対応していないので Warning が出ます。 ただ、問題は allowed-tools だけじゃありません。 description: | で Error が出る 実際の SKILL.md を見てみましょう。Claude Code の Skills では description に YAML のブロックスカラー（ | ）を使って複数行で書くのが一般的です。 --- name: blog-scraper description: | This skill should be used when the user asks to "ブログをスクレイピングして", "SIOS Tech Labの記事を保存して", or provides a SIOS Tech Lab blog URL to scrape and save. allowed-tools: Read, Edit, Bash --- これを VS Code で開くと、こうなります。 Error: Unexpected indentation (L4, L5) Warning: Attribute 'This skill should be used when...' is not supported in skill files. Warning: Attribute 'allowed-tools' is not supported in skill files. Error 2つに Warning 3つ。結構派手に怒られます。 原因は Copilot のバリデータが YAML のブロックスカラー記法（ | ）を解釈できていない こと。 description: | の後のインデントされた行を「description の値の続き」ではなく「別の属性」として読んでしまうので、インデントが不正だと怒り、さらに行の内容を未知の属性名として Warning を出します。 Claude Code 側はちゃんとパースしているので、 | で書いても動作は問題ありません。確認済みです。 ちなみに | を使わずに1行で書けば Error は消えます。ただ、description が長くなると読みにくいので、実用的にはちょっと厳しい。結局 files.associations で抑制するのが現実的な対処です。 自動検出されるパス VS Code Copilot は以下のパスを自動で検出します。 パス 用途 .github/skills/ プロジェクト（標準） .claude/skills/ プロジェクト（後方互換） ~/.copilot/skills/ パーソナル ~/.claude/skills/ パーソナル（後方互換） .claude/skills/ が「後方互換」として検出対象に入っています（後方互換性なのか??）。Claude Code ユーザーの Skills がそのまま Copilot でも使えるようにする意図なんですが、バリデータの対応が追いついていない状態です。 回避策: files.associations で Markdown として認識させる 回避策はシンプルです。SKILL.md を Copilot の Skill ファイルではなく、通常の Markdown ファイルとして認識させます。 .vscode/settings.json に以下を追加してください。 { "files.associations": { "**/.claude/skills/*/SKILL.md": "markdown" } } devcontainer を使っている場合は devcontainer.json の settings に追加しても OK です。 { "customizations": { "vscode": { "settings": { "files.associations": { "**/.claude/skills/*/SKILL.md": "markdown" } } } } } 検証結果 項目 設定前 設定後 description: | の Error Unexpected indentation なし allowed-tools の Warning not supported in skill files なし Claude Code の動作 正常 正常（影響なし） 設定後に VS Code の Diagnostics を確認したところ、Warning は完全に消えていました。Claude Code 側のスキル一覧にも正常に表示されます。まぁMarkdownとして認識させているんで当たり前ですね。Claude Codeの設定ファイルを書くときは自力で頑張りましょう。 Agent Skills 標準の経緯 せっかくなので背景も整理しておきます。 日付 できごと 2025年10月16日 Anthropic が Agent Skills を発表（Claude Code で利用可能に） 2025年12月18日 オープンスタンダードとして公開。同日に GitHub が Copilot での対応を発表 2025年12月 VS Code 1.108 で実験的サポート追加 Anthropic が先に作ったものをオープン化して、GitHub が同日に採用を発表した流れです。Agent Skills は「一度書けばどこでも使える（write once, use everywhere）」を目指していて、対応ツールは Claude Code、GitHub Copilot の他に、Cursor、Goose、Amp なども実験的に対応しています。 Claude Code が先行して独自拡張を進めている分、標準仕様との差分が Warning として表面化したのが今回の件ですね。 関連する既知の Issue この問題に関連して、いくつか Open の Issue があります。 Issue 内容 anthropics/claude-code #23723 user-invocable と user-invokable のスペル不一致。Claude Code CLI は user-invocable で動作するが、VS Code のスキーマは user-invokable を期待する anthropics/skills #314 SKILL.md のファイル名が大文字小文字を区別する仕様がドキュメントに記載されていない。 skill.md （小文字）だとエラーなく無視される anthropics/claude-code #13586 .claude/commands/skill.md を作ると組み込みの Skill ツールと名前が衝突して、全カスタムコマンドが読み込まれなくなる user-invocable / user-invokable の件は結構ハマりそうなポイントです。Claude Code CLI では user-invocable が正しいので、VS Code 側で Warning が出てもそのまま使ってください。VS Code の警告に従って user-invokable に変更すると、逆に Claude Code で動かなくなります。 まとめ 原因 : Claude Code と GitHub Copilot が同じ Agent Skills 標準を使っており、VS Code Copilot のバリデータが .claude/skills/ の SKILL.md を検出して Error / Warning を出す。 description: | のブロックスカラーと allowed-tools が引っかかる 対処 : files.associations で Markdown として認識させる（1行追加） 影響 : Claude Code の動作には一切影響なし 2026年2月15日時点の情報です。検証環境は以下のとおり。 ソフトウェア バージョン VS Code 1.109.3 GitHub Copilot Chat 拡張 0.37.6 Claude Code CLI / 拡張 2.1.42 Agent Skills はまだ発展途上で、VS Code 側のバリデータが allowed-tools に対応したり、 user-invocable のスペルが統一されたりすれば、この設定自体が不要になるはずです。 個人的には Claude Code の Skills と GitHub Copilot の Skills が統合される未来に期待してますが、まぁ希望的観測ですかね。今のところは Claude Code がガンガン先行しているので、この手の差分とはしばらく付き合うことになりそうです。 参考リンク Agent Skills Specification Claude Code Skills Documentation VS Code Agent Skills Documentation GitHub Copilot Agent Skills Docs ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 2人がこの投稿は役に立ったと言っています。 The post VS Code で Claude Code の SKILL.md にエラーが出る原因と対処法 first appeared on SIOS Tech Lab .

お世話になっております。サイオステクノロジー武井です。 メールの送受信テストを簡単に行えるmaildevというDockerを見つけましたので紹介したいと思います。 ちょっとテストでローカルの開発環境でメールの送受信テストするのってめんどくさいですよね。SMTPサーバー立てて、メール送信して、さらにそのメールがきちんと送信されたかを確認するためのメールボックスも用意しなければなりません。本番では、ちゃんとした環境でやる必要があるのですが、開発ではサクッとできれば十分ですよね。 そこでmaildevです。詳細は以下です。 https://github.com/maildev/maildev DockerでサクッとSMTPサーバーと、そのメール受信を確認するためのWebインターフェースを構築できるのです。構築方法は以下のとおりです。 $ docker run -p 1080:1080 -p 1025:1025 maildev/maildev これだけっす。SMTPのポートは1025、Webインターフェースのポートは1080です。 サクッと試してみましょう。telenetコマンドで送信してみます。 $ telnet localhost 1025 Trying ::1... Connected to localhost. Escape character is '^]'. 220 792c64766927 ESMTP HELO example.com 250 792c64766927 Nice to meet you, [172.22.0.1] MAIL FROM: <hoge@example.com> 250 Accepted RCPT TO: <fuga@example.com> 250 Accepted DATA 354 End data with . Subject: test mail test mail . 250 Message queued as FiY4Mc5L 受信できてるかどうか試してみましょう。http://localhost:1080にアクセスしてみます。 おおー、ちゃんと受信できてます。 これはべんり。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post モックSMTPサーバーを簡単に構築できるmaildev first appeared on SIOS Tech Lab .

「あの調査どこだっけ」で済む世界がほしかった ども！ドキュメントが70件を超えて検索がカオスになっている龍ちゃんです。 結論から言うと、ファイルパスを指定しなくても「あの調査どこだっけ」と話し言葉で聞くだけで、勝手に見つけてくれる仕組みを作りました。ファイルの作り方を工夫して、検索専用の Haiku サブエージェントを .claude/agents/ に置いただけ。今回はその仕組みの話です。 僕は Claude Code への指示を極力さぼりたい んですよね。ドキュメントのパスを毎回共有するようなことはしたくないので、文脈と単語で勝手に探してほしいんですよね。 以前、 AIフレンドリーなドキュメント管理 という記事で README にインデックスを作る方法を紹介しました。50件まではそれで回っていたんですが、70件を超えたあたりでClaude Codeの検索がポンコツになりました。 破綻からやったことは2つです。 ドキュメントにメタデータを埋め込む（まずはここから） — YAML Frontmatter で tags, keywords, use_when 等を付与して、検索精度を上げる 検索専用サブエージェントを作る — .claude/agents/ にエージェント定義ファイルを置いて、特定ディレクトリに特化した検索エージェントを作る 今回の内容です。 READMEインデックスが破綻した理由 エージェントの検索精度を上げるメタデータ設計 検索専用サブエージェント（Haiku）の作り方と Explore との違い 実際のエージェント定義ファイル（ブログの最後に配置されています） ドキュメント増えてきたら Claude Codeの検索がポンコツになる話 READMEインデックスとは まず前提から。Claude Code でドキュメントを管理するときに、僕がやっていた方法がこれです。 ドキュメントが入っているディレクトリに README.md を置いて、ファイル名・タイトル・カテゴリの一覧表を作る。Claude Code は CLAUDE.md から @import でこの README を読み込む。全ファイルを開かなくても、README を1つ読めば「このディレクトリに何があるか」が分かる。ドキュメントの「目次」を作って、AI に目次から探させる手法ですね。 まずは、 AIフレンドリーなドキュメント管理 を読んでみるとスムーズに話が入ってくるかも？ 70件を超えたら破綻した 50件程度まではこれで回ってました。70件を超えたあたりから破綻しましたね。 ファイル数が増えるとタイトルだけでは区別がつかないドキュメントが出てくるんですよ。実際に起きたのが、Claude Code の Skills について調べたかったのに、GitHub Copilot の Agent Skills の記事が出てきたケース。README のタイトル一覧を見ると、こういう状態です。 タイトル 対象 Claude Code Skills 実装ガイド Claude Code Claude Code一時ファイルからSkillsへ Claude Code 「Skillsが発火しない」を解決 Claude Code Agent Skills 入門：SKILL.md の基本から実践まで GitHub Copilot Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？ GitHub Copilot 「Skills」でタイトルを探すと、Claude Code と GitHub Copilot の記事が混在しています。README のインデックスにはタイトルしかないから、どっちの「Skills」なのか区別がつかない。 MCP 関連はもっとひどくて、調査ドキュメントだけで6件が「MCP」をタイトルに含んでました。「MCPが遅いんだけど」と聞いたとき、「MCP設計ベストプラクティス」「MCPの課題と制限」「CLI tools vs MCP 比較」「MCP計測・ログ方法」…どれを読めばいいのか、タイトルだけでは Claude にも判断できないんでファイルパス出して問い合わせが来ます。。 結果、Explore が全ファイルパスから探しに行ってトークンを消費する。本質的な問題は、README インデックスが「タイトルベースの検索」にのみ対応していること。ユーザーが言葉で表現する「やりたいこと」から適切なドキュメントを探す——こういう 意図ベースの検索 に対応できないんですよね。 メタデータで検索精度を上げる まずサブエージェントの話の前に、ドキュメント側の改善から。実はこれだけでもビルトインの Explore の検索精度が上がるんですよね。 YAML Frontmatter を設計する 僕の docs/research/ では、各ドキュメントの冒頭に YAML Frontmatter を付けています。 --- title: "MCPの課題と制限" date: 2026-01-29 category: Claude Code tags: - MCP - パフォーマンス related: - 2026-01-29-cli-tools-vs-mcp-comparison.md use_when: - "MCP接続でパフォーマンス問題に直面" - "MCPが遅いと感じたとき" keywords: - Notion MCP - Playwright MCP --- それぞれのフィールドの役割はこんな感じです。 フィールド 役割 例 title 直接的なトピック検索 「MCPの課題と制限」 tags カテゴリベースの絞り込み MCP, パフォーマンス use_when 意図ベースの検索 「MCPが遅いと感じたとき」 keywords 固有名詞での精密検索 Notion MCP, Playwright MCP related 芋づる式の関連探索 関連ファイル名 use_when が鍵 一番大事なのは use_when です。 「MCPが遅い」に対して、タイトルだけでは6件の中から選べない。でも use_when: "MCP接続でパフォーマンス問題に直面" が入っていれば、「パフォーマンスの話だ」と判断できるようになる。タイトルでは区別できなかった意図ベースの検索が、ここで実現するんですよね。 use_when には「〇〇のとき」「〇〇に直面」のように、ユーザーの状況を書きます。タイトルよりも具体的で、本文よりもコンパクト。 ここは何を知りたいと思ったか？というキーワードで考えるとつけやすいです。人間の頭は忘れるようにできるんで、気になったときには疑問のほうが先に浮かびます。 メタデータの管理もAIに任せる 「Frontmatter を全ドキュメントに手で書くのは大変じゃない？」——大変です。 だからこの仕組み自体の管理も AI に任せちゃってます。ドキュメントを作成する Skill や Agent の中に「保存時に Frontmatter を自動付与する」って指示を組み込んでおけば、ドキュメントが作られるたびにメタデータが勝手に付きます。 実際にうちの /research スキルでは、調査ドキュメントを保存する際に Frontmatter を自動生成してます。人間が手作業で tags や use_when を考える必要はない。仕組みを作る手間は最初の1回だけで、あとは放っておいても自動管理です。 んで既にドキュメントある人も安心してください。そんなことはAIさんにお願いすればいいんです。寝る前に「Sonnetの並列でYAML Formatterをつけといて」と依頼しておけばきっと布団でごろごろしている間に終わってます。 CLAUDE.md に Frontmatter の構造を教える サブエージェントを作らない人はここ注意です。Frontmatter を付けただけだと、ビルトインの Explore はその構造を知らないんですよね。 use_when というフィールドがあって意図ベースの検索に使える——この情報がないと、Explore は普通に本文を Grep するだけになります。 CLAUDE.md に「 docs/research/ のファイルには YAML Frontmatter があり、 use_when で利用シーン、 tags でカテゴリ、 keywords で固有名詞を検索できる」と書いておいてください。サブエージェントはエージェント定義ファイルにこの知識を仕込んでいるから不要ですが、Explore だけで運用するならこの一手間が必要です。 README インデックスは残す サブエージェントを入れたから README インデックスは不要……ではないです。後述する3段階検索の Level 1 で、まず README のカテゴリ別テーブルから候補を絞るんですよね。この高速な絞り込みが最初のフィルターになります。 README インデックス + メタデータ + サブエージェント。置き換えじゃなくて、積み上げです。 検索専用サブエージェント（Haiku）を作る Frontmatter を整えるだけでも検索精度は上がる。こっからは専門のエージェントを作って管理をしてもらうという話をしていきます。 Explore ではダメなのか？ 「検索なら Explore があるじゃん」と思った方、鋭いです。 でも Explore はプロジェクト全体から検索をかけるんで、時間食った挙句に違うファイルを出してくることがあったんですよね。 実は Claude Code のビルトインエージェント Explore も Haiku で動いてます。Claude Code 自体が、ドキュメント検索に Haiku を使ってるんですよね。じゃあなぜわざわざ専用エージェントを作るのか。 専用エージェントは description でスコープを絞れるし、エージェント定義の本文にドメイン知識を注入できる。Explore が図書館の一般案内係だとしたら、専用サブエージェントはその棚の構造を熟知した専門の司書みたいなもんです。 観点 Explore（ビルトイン） 専用サブエージェント モデル Haiku Haiku（同じ） スコープ プロジェクト全体 特定ディレクトリのみ 検索戦略 汎用（Glob/Grep/Read） 3段階絞り込み ドメイン知識 なし Frontmatter スキーマを理解 カスタマイズ 不可（ビルトイン） 自由に設計可能 モデルは同じ Haiku。違いは「どこまで知っているか」だけ。ちなみにサブエージェントから別のサブエージェントは起動できないんで（公式の制限）、検索エージェントはメインセッションから直接呼び出す設計にしてください。 エージェント定義ファイルの書き方 実際に僕が使っている research-searcher の定義ファイルを見てもらうのが早いです。 .claude/agents/research-searcher.md に置いています。 --- name: research-searcher description: > docs/research/配下の調査ドキュメントを検索・要約するエージェント。 「前に調べた〜の調査」「〜についての調査結果どこだっけ」 「MCPの課題をまとめた調査があったはず」等のリサーチドキュメント検索、 タグ・キーワードベースの横断検索に使用します。 tools: [Read, Grep, Glob] model: haiku --- それぞれ見ていきます。 model: haiku — 検索は読み取りがメインなので、Opus の 1/5 のコストで済みます。 tools: [Read, Grep, Glob] — 読み取り専用にしています。検索エージェントにファイルの編集はさせない。 description が最重要 — ここが一番大事。Claude はこの description を見て「この質問はこのエージェントに任せよう」と判断します。 description に自分の会話パターンを埋め込む description をもう一度見てください。 「前に調べた〜の調査」「〜についての調査結果どこだっけ」 「MCPの課題をまとめた調査があったはず」 これ、僕が普段 Claude に話しかけるフレーズそのままなんですよね。丁寧な説明文じゃなくて、ラフな口語をそのままぶち込んでます。 なぜかというと、Claude はこの description を見て「この質問はこのエージェントに委譲すべきか？」を判断するから。自分の口癖に寄せておいたほうが、実際の会話パターンとマッチしやすいんですよね。公式のベストプラクティスでも「いつ委譲すべきかを明確に記述する」ことが推奨されてます。入れなくても比較的意図を察してくれるんですが、入れておくと精度が上がります。 ポイントは、 description をドキュメントっぽく書かないこと。 自分がどういう場面でそのエージェントを使いたいか を具体的に書く。「ドキュメントを検索するエージェント」みたいな汎用的な説明だと、Claude の Explore が優先されて起動されます。 3段階検索戦略 エージェント定義ファイルの本文（ --- の下）には、検索の手順を書きます。僕のエージェントでは3段階で検索させてます。 Level 1: README インデックスを読む — docs/research/README.md のカテゴリ別テーブルから候補を絞る。これが一番安い Level 2: Frontmatter を確認する — 候補ファイルの冒頭にある YAML Frontmatter（tags, use_when, keywords）で内容を精査する Level 3: 本文を Grep で横断検索 — 上の2段階で見つからなかった場合の最終手段 ポイントは、いきなり本文を全部読まないこと。README → Frontmatter → 本文の順に、段階的に情報を絞り込む。これでサブエージェントのトークン消費も抑えられます。 実際に使ってみた結果 さっきの破綻の例、覚えてますか。Claude Code の Skills について聞いたのに GitHub Copilot の Agent Skills の記事が出てきたやつ。 サブエージェント導入後に同じように「Skills の調査どこだっけ」と聞いたら、ちゃんと Claude Code の Skills の記事から出してくれるようになりました。サブエージェントが Frontmatter の tags: Claude Code と use_when を見て、文脈から「これは Claude Code の話だ」と判断してるんですよね。タイトルだけで探してた頃とは精度が全然違います。大満足です。 まとめ 「あのファイルどこだっけ」が増えてきた人、まず YAML Frontmatter を付けてください。特に use_when 。これだけでビルトインの Explore でも検索精度が変わります。既存ドキュメントが大量にある人も、Sonnet に並列で投げれば寝てる間に終わるんで気にしなくていいです。 んでさらに速度と精度がほしくなったら .claude/agents/ に検索専用サブエージェントを足す。 description に自分の口癖をぶち込んでおけば、Claude が勝手に使い分けてくれます。 一回仕組み作っちゃえばあとはさぼれるんで、ドキュメント増えてきた人は試してみてください。 ではまた！ 関連記事 Claude Codeへの指示を少しでもさぼりたい！AskUserQuestionツール — 聞き返し機能で指示の手間を減らす。「さぼりシリーズ」の原点 Claude Code設計術：AIフレンドリーなドキュメント管理 — READMEインデックスの作り方。本記事の前提になる話 Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善 — CLAUDE.md設計で無駄な検索を減らして高速化する方法 Claude Code サブエージェントの最適構成：Opus で考え、Sonnet で動かす — Opus/Sonnet/Haikuの使い分け設計。本記事のHaikuサブエージェントもこの考え方がベース Claude Code /research の待ち時間をゼロに：Skill × サブエージェント構成 — Skillとサブエージェントを組み合わせて調査を並列実行する構成 Claude Codeに専門知識を仕込む：調査→構造化→注入の設計パターン — 調査結果をエージェントに注入するパターン。Frontmatterの設計思想に近い 付録：実際のエージェント定義ファイル全文 僕が使っている research-searcher の定義ファイル（ .claude/agents/research-searcher.md ）をそのまま載せます。コピーして自分の環境に合わせて書き換えれば動きます。 --- name: research-searcher description: docs/research/配下の調査ドキュメントを検索・要約するエージェント。「前に調べた〜の調査」「〜についての調査結果どこだっけ」「MCPの課題をまとめた調査があったはず」等のリサーチドキュメント検索、タグ・キーワードベースの横断検索に使用します。 tools: [Read, Grep, Glob] model: haiku --- # Research Searcher Agent `docs/research/` 配下の調査ドキュメントを検索・情報抽出するエージェントです。 ## 役割 メインセッション（Opus）から Task tool で呼び出され、調査ドキュメントの検索・照合・要約を行い結果を返却します。 ## データ構造の理解 ### ファイル命名規則 ``` YYYY-MM-DD-topic-name.md ``` ### Frontmatter（検索に活用） 各ファイルには以下の YAML Frontmatter がある： | フィールド | 説明 | 検索への活用 | |-----------|------|-------------| | `title` | ドキュメントタイトル（日本語） | タイトルマッチ | | `date` | 調査日 | 時期での絞り込み | | `category` | 主カテゴリ | カテゴリ絞り込み | | `tags` | 検索用タグ（3-8個） | タグベース検索 | | `related` | 関連ファイル名 | 関連調査の芋づる検索 | | `use_when` | 利用シーン | 「〇〇のとき」で検索 | | `keywords` | 重要キーワード（固有名詞等） | 技術名での検索 | ### カテゴリ一覧 - Claude Code / Azure / マーケティング / ライティング品質 - ライセンス / マネジメント / ツール・変換 / AI・LLM ## 検索戦略（3段階） ### Level 1: インデックス検索（最初に必ず実行） `docs/research/README.md` を読み、カテゴリ別テーブルから候補を絞り込む。 ``` Read({ file_path: "docs/research/README.md" }) ``` - カテゴリ別にファイル名・調査内容・調査日がテーブルで整理されている - **多くの検索はこの段階で候補が絞れる** ### Level 2: Frontmatter 確認（候補の詳細確認） 候補ファイルの frontmatter を読み、`tags`, `use_when`, `keywords`, `related` で内容を精査する。 ``` Read({ file_path: "docs/research/[候補ファイル].md", limit: 30 }) ``` frontmatter の `tags` と `keywords` は本文を読まずに関連性を判断できる強力な手がかり。 ### Level 3: 本文検索（キーワードがタイトル・タグに含まれない場合） Grep で本文内を横断検索する。 ``` Grep({ pattern: "検索キーワード", path: "docs/research/", glob: "*.md" }) ``` ## 検索パターン別の処理 ### パターン1: トピック検索 「MCPの調査あったよね」「RAGについて調べたはず」等の場合： 1. README.md のテーブルからトピック名でマッチ 2. 候補の frontmatter で `tags` / `keywords` を確認 3. 該当ファイルのタイトル・要約・タグを返却 ### パターン2: 用途ベース検索 「〜するときに参考になる調査」等の場合： 1. Grep で `use_when` フィールドを横断検索 2. マッチしたファイルの frontmatter を確認 3. 利用シーンと合致する調査を返却 ### パターン3: 関連調査の探索 「この調査と関連する他の調査は？」等の場合： 1. 基準ファイルの frontmatter から `related` フィールドを取得 2. 関連ファイルの frontmatter を確認 3. さらに同じ `tags` を持つファイルを探索（芋づる式） ### パターン4: カテゴリ・時期での絞り込み 「最近のClaude Code関連の調査一覧」等の場合： 1. README.md のカテゴリ別テーブルから該当カテゴリを抽出 2. 日付で絞り込み 3. 一覧として返却 ### パターン5: 技術名での検索 「FastMCP」「SCANOSS」等の固有名詞での検索： 1. Grep で `keywords` フィールドを検索 2. マッチしない場合、本文を横断検索 3. 該当ファイルを返却 ## 出力形式 ```markdown ## 検索結果 | ファイル | タイトル | カテゴリ | 調査日 | |----------|---------|---------|--------| | YYYY-MM-DD-topic.md | タイトル | カテゴリ | YYYY-MM-DD | ### 要約 [該当調査の概要。frontmatter の title + tags から構成、または本文冒頭から抽出] ### 関連調査 - [関連ファイル名] - [タイトル]（related フィールドから取得） ``` ## 制約事項 - **読み取り専用**: 調査ファイルの編集・作成は行わない - **スコープ限定**: `docs/research/` 配下のみを対象とする - **Web検索なし**: ローカルファイルの検索のみ - **トークン節約**: 本文全体を読むのは必要最小限にとどめる ポイントを補足しておくと: description は自分の口癖に合わせて書き換えてください。ここが委譲判断の精度に直結します カテゴリ一覧 や Frontmatter スキーマ は自分のドキュメント構造に合わせて変更してください 検索パターン は増やしても減らしても OK。自分がよく使う検索パターンだけ残せば十分です 参考リンク Claude Code Sub-agents 公式ドキュメント Anthropic Multi-Agent Research ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Codeのドキュメント検索を極力さぼれるようにした話 first appeared on SIOS Tech Lab .

お世話になっております。サイオステクノロジー武井です。 今回はマイクラサーバーをGUIで管理するCrafty Controllerについて書きます。 Crafty Controllerとは？ マイクラことMinecraftは、マイクラサーバーを構築し、ネットワークを通じてそのワールドを共有することができます。同じワールドを共有すると、友達と協力して建築物を作ったり、友達を◯したりすることができます。 しかしながらマイクラサーバーの管理は容易ではありません。マイクラサーバーは基本クラサバ構成で、クライアントであるMinecraftが、サーバーであるマイクラサーバーと通信し合いながら動きます。マイクラサーバーは設定ファイルの変更やMOD(拡張機能みたいなもの)の追加は特別なGUIは設けられておらず、直接設定ファイルを編集したり、サーバーにMODをアップロードしたり、プロセスの再起動が必要になります。でもこれは、Linuxに関する相応の知識がないとむずいです。 そこで、Crafty Controllerです。これはマイクラサーバーのプロセスをGUIで管理するOSSです。設定ファイルの編集、ファイルのアップロード、プロセスの再起動など全てGUIでできます。他にもCPUやメモリリソースなどの管理、ユーザーの管理(BANなど)もできます。 アーキテクチャとしては以下のとおりです。Crafty Controllerを起動するとプロセスが起動します。これはHTTPで待ち受けるプロセスです。いわゆるWebアプリです。サーバー管理者はブラウザを通して、このCrafty Controllerにアクセスをして、Minecraftサーバーを起動・停止・再起動、設定ファイルの変更などを行います。ポート番号を変えれば複数のMinecraftサーバーを起動することが可能です。プレイヤーは起動したMinecraftサーバーにアクセスして遊びます。 Crafty Controllerを構築できる技術あればGUIなくても、マイクラサーバー管理できるよねと言う感じなのですが、モチベーションとしては私の息子がマイクラサーバーを使いたいと言い出して、でもLibuxのコマンドを使って管理するのはいきなり敷居が高すぎるのでこういうものを用意した次第です。 ちなみにこのサーバーはAzure上で動いています。Ubuntu動く仮想マシンであればAWSとかGCPとかの他のクラウドでもOKのはずです。 Crafty Controllerのインストール では早速Crafty Controllerのインストール手順を見てみましょう。基本的には以下のインストール手順に従っています。 https://docs.craftycontrol.com/pages/getting-started/installation/linux/ またJavaがインストールされていることが前提となります。 Crafty Controller本体のインストール gitでリポジトリをcloneしてインストールスクリプトを起動して、以下の通りウィザードに従います。 # git clone https://gitlab.com/crafty-controller/crafty-installer-4.0.git # cd crafty-installer-4.0 # ./install_crafty.sh [+] Info:- Linux Check Success [+] Info:- Python Version Check - 3.12 We detected your os is: ubuntu - Version: 24.04 Install ubuntu_24_04.sh requirements? - ['y', 'n']: y ← yを入力してエンター [+] Info:- Crafty's Default install directory is set to: /var/opt/minecraft/crafty Install Crafty to this directory? /var/opt/minecraft/crafty - ['y', 'n']: y ← yを入力してエンター [+] Info:- Choose your destiny: [+] Info:- Crafty comes in different branches: [+] Info:- Master - Kinda Stable, a few bugs present [+] Info:- Dev - Highly Unstable, full of bugs and new features Which branch of Crafty would you like to run? - ['master', 'dev']: master ← masterを入力してエンター [+] Info:- Making start and update scripts for you Would you like to make a service file for Crafty? - ['y', 'n']: y ← yを入力してエンター [+] Info:- Cleaning up temp dir [+] Info:- Congrats! Crafty is now installed! [+] Info:- We created a user called 'crafty' for you to run crafty as. (DO NOT RUN CRAFTY WITH ROOT OR SUDO) Switch to crafty user with 'sudo su crafty -' [+] Info:- Your install is located here: /var/opt/minecraft/crafty [+] Info:- You can run crafty by running /var/opt/minecraft/crafty/run_crafty.sh [+] Info:- You can update crafty by running /var/opt/minecraft/crafty/update_crafty.sh [+] Info:- A service unit file has been saved in /etc/systemd/system/crafty.service [+] Info:- run this command to enable crafty as a service- 'sudo systemctl enable crafty.service' [+] Info:- run this command to start the crafty service- 'sudo systemctl start crafty.service' Crafty Controllerのサービス登録 自動起動するようサービス登録します。 # systemctl enable crafty.service # systemctl start crafty.service 初回ログイン 以下のURLにアクセスする(httpsであることに注意)。 https://[サーバーのIPアドレス]:8443/ 初回のログイン情報は 以下のパスに記載しています。ログイン後パスワードを変更してください。 /var/opt/minecraft/crafty/crafty-4/app/config/default-creds.txt 言語の変更 画面上の表示言語を日本語にします。画面右上のユーザーのアイコンをクリックして(①)、「Account Settings」をクリックします(②)。「User Language」を選択して、「ja_JP」を選択します(③)。最後に画面下部にある「Save」をクリックします。   サーバーの追加 では、マイクラサーバーを追加してみましょう。 まず、画面左部のメニューから「サーバー」→「新しいサーバーを作成」の順にクリックします。 以下のように設定して、最後に「サーバを作成」をクリックする。 サーバーの種類: Minecraft Servers サーバーを選択: 任意(vanillaやforge等お好きなものを) サーバーバージョン: 任意 サーバー名: 任意 最小メモリ使用量: 1GB 最大メモリ使用量: サーバーリソースが許すだけ サーバーポート: 基本は25565(複数立てる場合は他のサーバーと重複がないようにする)   「サーバー一覧」から先程作成したサーバーをクリックします。   ログにエラーがなければ、「起動」をクリックします。   EULAの同意画面が出るので、「Yes」をクリックします。これでサーバーの作成は完了です。 SSL化 一応デフォルトの状態でもSSLは有効になっているのですが、オレオレ証明書です。ApacheやNginx等でSSLの終端を行う方法もありますが、SSLの終端だけであればCaddyというのを使うとサクッと設定できます。しかもLet’s Encryptにネイティブに対応しています。 Caddyを導入すると以下のような感じになります。Caddyがリバースプロキシの働きをして、SSLの終端を行い、Crafty Controllerにアクセスします。 ここで図中ではCaddyからCrafty ControllerへのアクセスがHTTPSになっています。通常であればリバースプロキシなどでSSLの終端を行った後はそのバックエンドサーバーとのやり取りはHTTPになりましが、Crafty ControllerはデフォルトでHTTPSであり、HTTP化する方法があるのかもしれませんが、まぁ、今回はあまり設定変更などの手間はかけずサクッとやりたかったので、SSL終端後のバックエンドサーバーへのアクセスもそのままHTTPSとしています。この場合バックエンドサーバー側でもSSLの終端を行うため負荷がかかりますが、今回は個人用途なので、OKとしています。 ACMEのプロトコルを通じてLet’s Encryptにアクセスして証明書を自動取得・更新をします。 導入手順は以下のとおりです。Ubuntuを想定しています。 まず以下のコマンドを実行してCaddyをインストールします。 # apt install -y debian-keyring debian-archive-keyring apt-transport-https curl # curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg # curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list # chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg # chmod o+r /etc/apt/sources.list.d/caddy-stable.list # apt update # apt install caddy   次に 設定ファイル/etc/caddy/Caddyfileを以下のように定義します。FQDNは、minecraft.example.comを想定しています。 minecraft.example.com { reverse_proxy https://localhost:8443 { transport http { tls_insecure_skip_verify } } }   Caddyを再起動します。これで完了です。 # systemctl restart caddy まとめ みなさん、これで簡単にマイクラサーバーの管理をして、みんなでマイクラしましょう。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post マイクラサーバーをGUIで管理するCrafty Controller first appeared on SIOS Tech Lab .

ども！最近 Claude Code に設計レビューを頼んでみている龍ちゃんです。 Claude に「この設計レビューして」と投げると、一般論しか返ってこないんですよね。「スケーラビリティを考慮しましょう」とか「セキュリティに配慮してください」とか。いや、それはそうなんだけど、 見てほしい観点を伝えてないから AIも答えようがない。 「OWASP Top 10 を確認して」とか「このフレームワークの公式ドキュメントと照合して」とか、 具体的な観点を渡せば AI の出力が変わる 。でも毎回それをゼロから調べて伝え直すのは現実的じゃない。調べたとしても、次のセッションではその知識がリセットされてまた同じ Web 検索をする羽目になるんですよね。 これを解決したのが「調査 → 構造化 → 注入」のパイプラインでした。 /research で調べた結果を docs/references/ に構造化して保存し、Skill や Agent が必要なタイミングでそのデータを読み込む。一度調査して整理すれば、あとは AI がフレームワークや評価基準を参照した上で分析してくれる。自分にはその正当性を完全には判断できないけど、少なくとも「根拠のある参考資料」として読めるレベルの出力が出てくるようになりました。 今回は、この仕組みの作り方と実際にどう変わったかを共有します。 今回の内容 なぜ AI の出力がイマイチになるのか 「調査 → 構造化 → 注入」パイプラインの全体像 実際の Before/After（SEO タイトル提案の例） ハマりどころと気をつけるポイント ※ちなみに Web 調査の自動化（ /research スキル）については 前回の記事 で詳しく解説してます。気になる方はそちらもどうぞ。 なぜ AI の出力がイマイチになるのか AI に自分の専門外の仕事を頼むとき、だいたい3つの問題にぶつかります。 1. AI が汎用知識しか持ってない 「PV データを分析して」と指示しても、AI が持ってるのは一般論だけ。マーケティングフレームワークに基づいた分析にはなりません。SEO のタイトル提案も同じで、具体的なチェックリストや基準がないからふわっとした答えしか出てこない。 僕も最初は「AI なら分析できるでしょ」と思ってたんですが、結果は「PV が多い記事に注力しましょう」みたいな誰でも思いつくようなこと。BCG マトリクス？ Pareto 分析？ エンジニアの僕にはそもそもそれが何か怪しいレベルで、AI の出力が正しいのかも判断できませんでした。 2. 毎回ゼロからやり直し 前のセッションでマーケティング分析手法について調べたのに、次のセッションではその知識がリセットされてる。また同じ Web 検索をして、同じような結果を読み込んで、コンテキストウィンドウを埋めていく。Claude Code のベストプラクティスにもこう書かれています。 “Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.” — Best Practices for Claude Code 毎回 Web 調査でコンテキストを埋めると、肝心の作業に使える領域が減っていく。調査と作業でコンテキストの取り合いをしてるようなものです。 3. 出力の良し悪しを検証できない これが一番厄介。自分が専門家じゃない領域だと、AI の出力が良いのか微妙なのかすら判断できません。でも references にマーケティングフレームワークの基準を入れておけば、少なくとも「KPI 指標に基づいた分析」「Pareto 原則に沿った投資判断」みたいに、根拠が明示された出力になる。正しさを100%保証できなくても、「なぜそう判断したか」が見えるだけで、参考資料として読む価値が全然違うんですよね。 この3つ、全部まとめて解決する仕組みを作りました。 今日から始められる最小行動 仕組みの全体像を見せる前に、まず試してほしいことがあります。2つのプロンプトを使うだけです。 1つ目のプロンプト（調査して保存） : SEO タイトル最適化のベストプラクティスについて調査して、title-optimization.md として保存して 2つ目のプロンプト（参照して実行） : title-optimization.md を参照して、この記事のタイトル案を3つ提案して これだけです。1つ目で調査結果を保存して、2つ目でそれを参照して作業する。思いつく例があれば、記事を読み進める前にやってみてください。 僕も最初はこの2つのプロンプトを繰り返してました。「Docker のセキュリティベストプラクティス調べて保存」→「それ見てレビューして」みたいな感じで。でもこれを何回かやると、保存したファイルがあちこちに散らばって「あのファイルどこだっけ？」ってなるんですよね。だから保存先を整理して、Skill から自動で読み込めるようにパイプラインとして仕組み化したんです。 次のセクションでは、その仕組み化したパイプラインの全体像を見せます。 解決策の全体像: 調査 → 構造化 → 注入 さっきの2プロンプトを繰り返すうちに、「これ毎回やるなら仕組み化した方がいいな」と思って作ったのがこのパイプラインです。 ステップ やること 保存先 役割 1. 調査 /research で Web 調査を自動化 docs/research/ 生データの収集 2. 構造化 調査結果を目的別に整理・蒸留 docs/references/ 再利用可能なナレッジに変換 3. 注入 Skill / Agent が必要な references を Read で動的ロード .claude/skills/*/references/ 等 AI が正確な出力をするための根拠 ポイントは、一度このパイプラインを通すと、あとは Skill を実行するだけで検証済みのナレッジが自動的に注入されること。毎回 Web 検索する必要がなくなります。 では、各ステップを順番に解説していきますね。 ステップ1: /research で調査を自動化する まずは調査の自動化から。 前回の記事 で詳しく紹介した /research スキルを使います。ざっくり言うと、Web 調査を Claude Code に自動でやらせる仕組みです。 やったことはこんな感じです。 Claude Code の Skill として /research コマンドを作成 調査用の Worker を複数並列で起動して、効率的に情報収集 調査結果は docs/research/YYYY-MM-DD-topic-slug.md に自動保存 例えば SEO タイトルの最適化について調べたいときは、こう実行するだけ。 /research SEO タイトル最適化 技術ブログ これで Worker が公式ドキュメント、技術ブログ、日本語の情報を並列で検索して、結果を docs/research/2026-02-05-seo-structured-data-tech-blog.md みたいなファイルに保存してくれます。バックグラウンドで動くので、調査中に他の作業を進められるのも地味にありがたい。 ただ、ここで注意点が1つ。 調査結果は「生データ」 です。網羅的に集めてくれるのはいいんだけど、そのままだと情報量が多すぎて使いにくい。この生データを「AI が使える形」に蒸留するのが、次のステップの話です。 ステップ2: 調査結果を構造化する（research → references の蒸留） 個人的には、ここが一番大事なステップだと思ってます。 /research で調査を自動化すると、網羅的に情報を集めてくれるのはありがたいんだけど、「人間が読もうと全く思わない」ボリュームになります。数千行のマークダウンファイルがドンと出てきて、そこから必要な知識をすぐ出せるかというと…無理でした。 そこで、調査の生データから「AI が使える形」に蒸留する工程を入れました。 research と references の違い docs/research/ docs/references/ 内容 調査の生データ（URL、引用、メモ） 目的別に整理されたナレッジ サイズ 大きい（調査の全記録） コンパクト（必要な情報だけ） 寿命 調査時点のスナップショット 継続的にメンテナンス 用途 あとから振り返る記録 AI が参照するリファレンス docs/research/ は「調べた記録」で、 docs/references/ は「使えるナレッジ」。research に直接 AI を繋ぐと数千行を丸呑みすることになるけど、references に蒸留しておけば必要な部分だけ読み込める。この違いは結構大きいです。 具体例: SEO の蒸留プロセス 実際に SEO タイトル最適化の調査結果を蒸留したときの例を見せます。 docs/research/2026-02-05-seo-structured-data-tech-blog.md（生データ、数千行） ↓ 蒸留 docs/references/seo/ ├── title-optimization-guidelines.md ← タイトル最適化基準 ├── power-words.md ← パワーワード一覧 ├── checklist.md ← チェックリスト ├── spark-framework.md ← SPARKフレームワーク └── meta-description-guidelines.md ← メタディスクリプション基準 1つの巨大な調査ファイルから、目的別に5つのファイルに分けています。こうしておくと、AI が「タイトルを考えるときは title-optimization-guidelines.md と power-words.md を読む」「メタディスクリプションを書くときは meta-description-guidelines.md を読む」と、必要なファイルだけを選んで読み込めるようになります。 蒸留のコツ 1ファイル1目的 : 「タイトル最適化」と「パワーワード」は分ける。混ぜると AI が不要な情報まで読み込む AI が参照しやすい形式 : 表、箇条書き、チェックリスト。文章でダラダラ書くより構造化されたデータの方が AI は正確に使える 出典を残す : 蒸留元の調査ファイルや参考 URL を記載しておく。あとから「この基準、本当に合ってる？」と検証できるように ステップ3: Skill / Agent に注入する（Progressive Disclosure） 最後のステップ。構造化した references を Skill や Agent に読み込ませます。 ここで使うのが、Claude Code Skills の Progressive Disclosure （段階的開示）という仕組みです。公式ブログにはこう書かれています。 “Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable. Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix, skills let Claude load information only as needed.” — Equipping agents for the real world with Agent Skills 要は、情報を3層に分けて必要なときだけロードする設計です。 レイヤー ロードタイミング サイズ Level 1: メタデータ 常にコンテキストに存在 ~100語 Level 2: SKILL.md Skill が発火したとき 500行以下推奨 Level 3: references/ 必要なときだけ Read で取得 事実上無制限 Level 3 の references/ が今回の主役。公式にも「Skill にバンドルできるコンテキスト量は 事実上無制限 」と書かれています。ファイルシステム上に置いておくだけなら、いくらでも参照資料を増やせるということです。 実際のコード例: SEO レビューエージェント 具体的にどう使うか、このプロジェクトの SEO レビューエージェント（ .claude/agents/seo-reviewer.md ）の例を見せます。やっていることは単純で、人間が資料を手元に広げながら作業するのと同じです。「まずタイトル基準のファイルを読んで評価し、次にパワーワード一覧を読んでタイトルを生成する」という流れを、エージェントの定義ファイルに書いておく。 ### Phase 3: SEO価値の評価 **参照資料の読み込み**（Readツールで取得）: - `docs/references/seo/title-optimization-guidelines.md` - `docs/references/seo/meta-description-guidelines.md` - `docs/references/seo/spark-framework.md` ### Phase 4: タイトル生成 **参照資料の読み込み**: - `docs/references/seo/three-patterns.md` - `docs/references/seo/power-words.md` Phase 3（評価）と Phase 4（生成）で、それぞれ必要なファイルだけを Read で取得しています。全部を一度にロードしない。これが Progressive Disclosure の実践です。 なぜこれが効くのか 不要な references はトークン消費ゼロ : ファイルシステム上にあるだけで、Read されなければコンテキストを使わない 毎回 Web 検索しなくていい : 一度蒸留した references を再利用するだけ。コンテキストが作業に使える 品質が安定する : 検証済みのデータが毎回同じように注入されるので、出力のブレが減る Before/After: 実際にどう変わったか ここまで仕組みの話をしてきたので、実際に変わった部分を見せます。 SEO タイトル提案の比較 一番わかりやすいのが SEO タイトルの提案。同じ記事に対して、references なしとありで出てきたタイトル案を比べてみます。 references なし references あり タイトル案1 Claude CodeのAI出力がイマイチ？専門外の知識もAIに使わせる3ステップ Claude Codeの出力品質を3倍高める調査→構造化→注入パイプライン【2025年版】 タイトル案2 Claude Codeで調査結果を活用する方法：研究データを構造化してAI出力を改善 Claude Codeで専門外知識をAIに使わせる：参考資料レベルの出力を得る方法 タイトル案3 AIに専門知識を注入する仕組み：調査→構造化→注入のパイプライン設計 【2025年版】Claude Code研究パイプライン完全ガイド：SEO・マーケ分析を自動化 references なしだと、タイトル案1は現在の記事タイトルをそのまま返してきました。全体的に「内容の説明」にとどまっています。一方、references ありでは SPARKフレームワーク（キーワード前方配置）、パワーワード（「3倍」「完全」「自動化」）、文字数コントロール（30〜40文字）が適用されて、検索意図別に3パターン出てきています。 ライティングレビューでの変化 SEO タイトル以外で一番変化を感じたのが、ライティングレビューです。レビューの観点（AI っぽさ検出、技術ライティングルール、チェックリスト）をそれぞれ調査して references に入れたら、具体的な指摘が出るようになりました。「文章が冗長です」みたいな曖昧なフィードバックではなく、「『様々な』は具体的な表現に置き換えてください」という粒度になった。 HTML 図解の配色が安定した テキスト以外でも変化がありました。Claude に HTML 図解を作らせると、毎回グラデーションつけてくるんですよ。「AI が図解って言われるとグラデーション使いたがるよね」って気づいた瞬間、これ前提を共有できてないだけだなと。デザインガイドラインを references に入れたら、配色が一貫するようになりました。references はテキスト系の作業だけじゃなく、生成系の出力にも効きます。 正直な課題 ただし、全部がうまくいったわけじゃありません。 ライティングの references を詳細に作りすぎて、修正を盛り込むと逆に AI っぽさが出るという課題がありました。references の粒度は「詳しすぎず、粗すぎず」のバランスが大事で、ここはまだ試行錯誤中です。この話は次のセクションの「落とし穴4」で詳しく触れます。 ハマりどころ・気をつけるポイント この仕組みを作る過程で、何回かハマりました。同じ落とし穴にハマらないように共有しておきます。 落とし穴1: 調査資料が膨大すぎて活用できない 調査資料が増えたのはいいけど、全然活用できない瞬間がありました。 /research は網羅的に集めてくれるから、 docs/research/ にファイルがどんどん溜まっていく。でも膨大すぎて検索がうまくいかないし、「あの情報どこだっけ？」が頻発した。 解決策として、YAML Frontmatter で各ファイルにメタデータを付けたり、 docs/research/README.md をインデックスとして活用するようにしました。調査資料はそのままでは使えない。検索性を考えた整理が必要です。 この辺の話は、こちらの記事（ Claude Code設計術：AIフレンドリーなドキュメント管理 ）で解説をしています。 落とし穴2: SKILL.md に全部詰め込んで肥大化 最初は references を使わず、SKILL.md に全部書いてました。チェックリストも基準もコード例も全部。当然肥大化して、Skill の実行が遅くなるし、Claude が指示を見落とすことも増えた。 公式にも「SKILL.md は500行以下に抑えて、詳細なリファレンスは別ファイルに移動する」と 推奨されています 。SKILL.md はあくまで「全体の流れと、どの references をいつ読むか」を書く場所。詳細は references/ に分離してコンテキストをスリムに保つのが正解でした。 落とし穴3: references を置いたのに読まれない references/ にファイルを置いて満足してたら、Skill が全く読んでくれなかったことがあります。SKILL.md から明示的にリンクしないと、Claude はそのファイルの存在を知らないんですよね。 対策はシンプルで、SKILL.md に「Phase 3 でこのファイルを Read する」と明記するだけ。「何を」「いつ」読むかを書いておけば、Claude はちゃんと読みに行ってくれます。 落とし穴4: references が詳細すぎると逆効果になることも 前のセクションで触れた課題の詳細。ライティングの references を作り込みすぎて、AI がそれを機械的に適用した結果、逆に AI っぽい文章になってしまいました。 試行錯誤してわかったのは、 出力したいものによって references の粒度を変える必要がある ということ。 レビュー基準（seo/, review/） → 詳細にするほど評価の一貫性が上がる。チェックリストや評価基準は具体的であるほど良い スタイルガイド（writing/） → 粗めにしないと AI がガイドを機械的に適用して AI っぽさが出る。「方向性」を示す程度にとどめる つまり「判定するための基準」は詳細に、「創作のためのガイド」は粗めに。この使い分けが大事でした。 専門外こそ効く理由 この仕組みを作って回してみて気づいたのは、技術リファレンス（ claude/ ）の管理よりも、マーケティング分析や SEO の references の方が圧倒的に価値があったということです。技術的なことは自分で判断できるから、references がなくてもなんとかなる。でもマーケティングのフレームワークや SEO のパワーワード一覧は、references がなければ AI もまともな分析ができなかった。 実際、ブログの PV データに対してマーケティング分析をかけたとき、 /research で調査した BCG マトリクスや Pareto 分析の手法を references として注入したら、207記事のデータから「上位20%の記事が64.7%のPVを生んでいる」「カテゴリ別の投資判断」みたいな分析が出てきた。その分析が正しいかどうかは僕には完全にはわからない。でも「KPI 指標に基づいてこう判断した」という根拠が付いているから、参考資料として読める。「なんとなく AI が言ってること」と「根拠付きで AI が分析したこと」では、信頼度がまるで違う。 自分が詳しくない領域こそ、この仕組みが一番効く 。やってみて初めて実感しました。 実際、このプロジェクトで管理している references のカテゴリはこんな感じです。 カテゴリ ファイル数 用途 seo/ 9 SEO タイトル・メタディスクリプション基準 review/ 9+ レビュー評価基準 claude/ 5 Claude Code 拡張のベストプラクティス 技術リファレンス（ claude/ ）はエンジニアとして自然に管理できます。でも seo/ は、 /research で調査して構造化したからこそ作れたもの。そしてそのリファレンスを Skill に注入するだけで、AI の出力が「根拠のある」ものに変わった。 専門家じゃなくても、調査して構造化すれば、その領域の知識を AI に正確に使わせることができる。 まとめ 今回の記事のテイクアウェイです。 最小行動から始める : まずは2つのプロンプト（「調査して保存」→「参照して実行」）を試してみる。繰り返すうちに仕組み化したくなったら、Skill に組み込む references の粒度は用途で変える : 「判定するための基準」は詳細に、「創作のためのガイド」は粗めに 専門外の領域こそ、この仕組みの恩恵が大きい : 自分で判断できない領域に検証済みのナレッジを注入することで、AI の出力に根拠が付く。正しさの保証はできなくても、「根拠のある参考資料」として活用できるレベルになる 改めて、最初にやってほしいことを書いておきます。 ○○のベストプラクティスについて調査して、 docs/references/xx/yy.md として保存して docs/references/xx/yy.md を参照して、 これを××してください 思いつく例があれば、まずこの2つを試してみてください。繰り返すうちに「これ Skill にしたいな」と思えたら、その先のパイプラインを作ってみる。そんな感じで始めるのがいいんじゃないかなと思います。 ほなまた〜 参考リンク 公式ドキュメント Claude Code Skills 公式ドキュメント Equipping agents for the real world with Agent Skills Effective Context Engineering for AI Agents Best Practices for Claude Code 関連ブログ（SIOS Tech Lab） Claude Code Skills 実装ガイド：ローカルツールをスムーズに統合する方法 Claude Code: 公式MCPを補完するSkills設計パターン Claude Codeの調査品質がバラバラ？：/researchで解決する方法 Claude Code /research の待ち時間をゼロに：Skill × サブエージェント構成 Claude Code設計術：AIフレンドリーなドキュメント管理 Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善 CLAUDE.md効かない？ドメイン注入を設計思想から見直す ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Codeに専門知識を仕込む：調査→構造化→注入の設計パターン first appeared on SIOS Tech Lab .

Figmaの手作業から脱却したい ども！最近は図解の自動化にハマっている龍ちゃんです。 技術ブログの図解、みんなどうしてますか？ 僕は以前、Figmaで人力で図を作ってたんですよね。アーキテクチャ図とかフロー図とか、1つ作るのに結構な時間がかかる。ブログの本数が増えるほど、だんだん図を作るのが億劫になってきて。 で、 SVG図解自動生成 、 HTML図解自動生成 と試行錯誤を重ねてきました。過去記事を読んでなくても今回の記事だけで完結するので、安心してください。 やっていることはシンプルで、Claude Code の SKILL で HTML 図解を自動生成して、CLI ツールで PNG に変換する。ここまではツールの話なんですが、今回伝えたいのはその先で、 気に入ったデザインを reference に突っ込んでスキルを「育てる」ことができる んですよね。これがめっちゃ重宝してます。 ぶっちゃけ僕が作るよりも、たまにいいデザインを作ってくるから最高なんですよ。んで、そのいいやつを保存しておくと、次からもっと良くなる。 今回の内容です。 自然言語で図解を爆速で作る ブラウザ立ち上げ不要でスクショをとる 自分専用のデザイナーに育てる方法 実際にやってみた結果と、正直な限界 仕組みの全体像 なぜ HTML + Tailwind なのか ここに至るまでに色々試しました。ざっくり経緯を話すと: Mermaid : 手軽なんですけど、図の種類が制限されるんですよね。使用場所を選ぶ感じです（ Mermaid図作成の記事 も書いてます） SVG : トークンだけバカ食いして、あんまりいい出力じゃなかった。座標計算が苦手で、文字はみ出しとか要素の重なりが頻発してました HTML+Tailwind : Claude は CSS（Flexbox/Grid）が得意。HTMLだと自力で修正もできる 方式 良い点 課題 Mermaid 手軽 図の種類が制限される SVG 自動生成可能 トークン食い・ズレやすい HTML+Tailwind 自動生成＋修正しやすい PNG変換が必要 HTMLは最初からうまくいったわけじゃなくて、参考になりそうなHTMLとかデザインプラクティスを調べて改善していった結果です。前回の記事では3つの実例が全て修正不要で完成するレベルまで持っていけました。あと、HTMLだと気に入ったデザインをパーツごとに蓄積させておくことで、自分だけのデザインブックが作れるんですよね。これが後で効いてきます。 Claude Code の SKILL って何？ Claude Code を使ってない人もいると思うので、ここだけ少し補足します。 一言で言うと「AIへの作業手順書」 です。 .claude/skills/ ディレクトリに SKILL.md というファイルを置いておくと、Claude が指示を受けた時に自動でそのファイルを読んで実行してくれます。 例えば「アーキテクチャ図を作って」と言うと、Claude は図解生成用のスキルファイルを見つけて、「どんなHTMLで」「どんなルールで」「どんなサイズで」作るかを理解した上で図を生成してくれる。毎回同じ説明をしなくていいんですよね。 ここで大事なのが Progressive Disclosure（段階的開示） という設計です。 Level 1 : スキルの名前と説明（常時ロード。軽い） Level 2 : SKILL.md 本体（スキルが起動した時にロード） Level 3 : references/ ディレクトリ（必要な時にだけロード） この Level 3 が後で「育てる」話に繋がるので、覚えておいてください。 実際に作った図解スキルの中身 じゃあ実際に僕が作った diagram-generator-html というスキルを見てみましょう。 HTML5 + Tailwind CSS + Material Icons で 1280x720px 固定サイズの図解を生成します。対応パターンは8種類で、アーキテクチャ図やフロー図、比較図、ディレクトリツリー図なんかを作れる。 スキルファイル自体はコンパクトに保って、デザインパターンのお手本集は別ファイル（ references/examples.md ）に分けてあります。この「お手本集」が後で話す「育てる」仕組みの核になるんですが、詳しくはデモを見た後に。 HTMLからPNGに変換するCLIツール スキルが生成するのはHTMLファイルです。ブログに貼るにはPNG画像が必要なので、変換ツールを作りました。 uv run html-screenshot --file diagram.html --output diagram.png これだけ。中身は Python + Playwright（Chromium）で、やってることはシンプルです: Chromium をヘッドレスで起動 HTMLファイルを file:// プロトコルで読み込み Tailwind CDN や Material Icons の読み込み完了を待機（ wait_until="networkidle" ） body 要素のスクリーンショットを PNG で保存 デフォルトで 1280×720 の画像が出力されます。HTMLで w-[1280px] h-[720px] と固定サイズを指定しているので、ブラウザのビューポートサイズに関係なく常に同じ結果になります。 実際に使ってみた 基本的な使い方 実際にやった流れを見せます。Claude Code に「3層アーキテクチャのフロー図を作って」と指示すると、スキルが自動で起動して HTML ファイルを生成してくれます。 生成されたHTMLはこんな感じ（抜粋）: <body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-gray-50"> <div class="w-full h-full flex items-center justify-center p-10" role="img" aria-label="3層アーキテクチャ図"> <div class="w-full max-w-4xl flex flex-col gap-4"> <!-- Presentation Layer --> <div class="bg-blue-100 border-2 border-blue-500 rounded-lg p-6"> <h2 class="text-2xl font-bold text-blue-900">Presentation Layer</h2> </div> <!-- 以下、Business Logic Layer、Data Access Layer と続く --> </div> </div> </body> Tailwind CSS のクラスで全部スタイリングされてるので、HTML が読める人なら「ここの色を変えたい」「この余白を詰めたい」って修正が自分でできるんですよね。 これを CLI で変換すると: uv run html-screenshot --file architecture.html --output architecture.png ぶっちゃけ僕が作るよりいい時がある 使ってて驚いたのが、ベン図とか比較系に関してはすごくいいんですよ。配色のバランス、要素の配置、余白の取り方。Claude は CSS の知識が豊富だから、Tailwind のクラスを適切に組み合わせて整ったデザインを出してくる。 全部が良いわけじゃないです。でも「たまに自分より上手いの出してくる」っていうのがリアルなところで、そういう時は素直にそのまま活用をしています。あとは、何ラリーかして補正すれば大体はいけますね。 うまくいかないパターン 正直に言うと、ダメなパターンもあります。 要素が多すぎる図 。720px の高さに収めないといけないので、10個も20個も要素がある図は厳しい。はみ出すか、文字が小さくなりすぎる。 指示が曖昧な時 。「いい感じの図を作って」みたいなざっくりした指示だと、汎用的すぎるデザインが出てくる。「3層アーキテクチャで、各層にアイコン付きで」くらい具体的に言った方がいい結果が出ます。 あと地味に困るのが Tailwind CDN の読み込みタイムアウト 。ネットワークが不安定な時にたまに起きる。変換ツールは wait_until="networkidle" で外部リソースの読み込みを待つ設計なので、CDN が遅いとそのまま待ち続けちゃう。まあ、再実行すればだいたい解決しますけど。（この辺は環境依存です） スキルを「育てる」: reference フィードバック ここからが今回の記事で一番伝えたいところです。 良いデザインを reference に保存する さっき「デザインパターンのお手本集を別ファイルに分けてある」と書きました。これが references/examples.md で、スキルが図解を生成する時に参照するお手本集です。 やることは単純で、 気に入ったデザインの HTML コードをこのファイルに追記するだけ 。 .claude/skills/diagram-generator-html/ SKILL.md ← スキル本体（Level 2） references/ examples.md ← ここにお手本を追加していく（Level 3） SKILL.md から examples.md へのリンクが既にあるので、ファイルに追記するだけで Claude が次回から参照してくれます。 1つ注意点があって、 SKILL.md から明示的に参照（リンク）されていないファイルは Claude が認識しません 。references/ にファイルを置いただけでは駄目で、SKILL.md 内に [examples.md](references/examples.md) みたいなリンクが必要です。既にリンクがあるファイルに追記する分には問題ないですけど、新しいファイルを追加する場合は忘れずに。 Before/After: reference 追加で出力はどう変わるか ここが核心。reference にパターンを追加すると、実際にスキルの出力がどう変わるのか。 今回は examples.md にまだ入っていない「タイムライン図」で試してみます。 Before（reference にタイムライン図がない状態） 「プロジェクトの開発タイムラインを図にして」と指示。正直、微妙だった。悪くはないんだけど、うちのブログの図じゃない。配色もアイコンの使い方も、プロジェクトで統一しているルールが反映されてない。 After（良いタイムライン図を reference に保存した後） 同じ「タイムライン図を作って」という指示なのに、出てきたものが全然違う。配色もアイコンの使い方もブログのトンマナに合っている。これ初めて見た時、マジで「おっ」ってなりました。しかもここから「ステップを5つに増やして」みたいなカスタマイズもできる。reference のパターンをベースに、さらに調整が効くんですよね。 見比べると違いがわかると思います。reference があると、Claude は「このプロジェクトではこういうデザインが求められている」という文脈を持った状態で図を生成する。指示が同じでも、出力の解像度が上がるんですよね。 reference が増えてもスキル起動コストは変わらない Progressive Disclosure の Level 3 の設計がここで効いてきます。 references/ ディレクトリのファイルは、スキルが起動した時に自動で全部読み込まれるわけじゃないんです。Claude が「必要だ」と判断した時にだけ読み込まれる。だから、お手本パターンを10個追加しようが50個追加しようが、スキルの起動時に消費するトークンは変わらない。 これ、地味だけどかなり重要で。パターンを追加するデメリットがほぼないんですよ。「良いデザインが出たら保存する」をひたすら繰り返すだけでスキルが育っていく。 あと、Git で管理されているので、チームで共有できるのも良い。僕が見つけた良いパターンをコミットすれば、チーム全員のスキルが育つ。「AIに教える」というより「お手本集を充実させる」イメージですね。 正直な現在地 定型的な図解（アーキテクチャ図、フロー図、比較図、ベン図あたり）はかなり使えるレベルになりました。reference にパターンを蓄積するほど品質が安定してきているのは実感があります。 でも、毎回100点のデザインが出るわけじゃない。「たまにいい」が正直なところです。複雑なインフォグラフィックとか、独創的なレイアウトが必要な図はまだ難しい。Figma レベルの自由度はないです。 HTMLだから自力で修正できるのが救いで、「80点のものが出てきたら、残り20点は自分で調整する」くらいの付き合い方がちょうどいい。reference の蓄積が進めば、この80点が85点、90点になっていくんだろうなとは思ってます。トークンを気にしないのであれば、何ラリーかすれば普通に使える図になります。でも、マジの軽微な修正だったらコードを直接修正したほうが良いね。 将来的には完全に図化をAIに丸投げできたらうれしい。でも今はまだその途中で、「育てている最中」っていうのが正直な現在地です。 まとめ 技術ブログの図解作成、Figma で人力でやってた頃と比べるとだいぶ楽になりました。SKILL で HTML 図解を自動生成して、CLI で PNG に変換する。仕組み自体はシンプルです。 でも、この仕組みの本当の価値は「育てられる」ことだと思ってます。良いデザインが出たら reference に保存する。それだけで次からの出力品質が上がる。パターンを追加するコストはほぼゼロ。この成長サイクルが回り始めると、使えば使うほどスキルが育っていく。 完璧じゃないけど、育てていける。みんなも自分のスキルを育ててみない？ ほなまた〜 作ってみよう: 構築手順 ここからは「自分の環境でも作りたい」って人向けの構築手順です。必要なのは3つ: 図解生成スキル （SKILL.md）、 お手本集 （references）、 PNG変換ツール 。 最終的なディレクトリ構成はこうなります: .claude/skills/diagram-generator-html/ ├── SKILL.md ← スキル定義本体（Step 1） └── references/ └── examples.md ← デザインパターンのお手本集（Step 2） SKILL.md がスキルの本体で、references/ 以下がお手本集。PNG変換ツール（Step 3）は別途用意します。この構成が記事前半で説明した Progressive Disclosure の Level 2（SKILL.md）と Level 3（references/）にそのまま対応しています。 Step 1: 図解生成スキル（SKILL.md）を配置する .claude/skills/diagram-generator-html/ ディレクトリを作って、 SKILL.md を配置します。僕が実際に使っているスキル定義をそのまま載せます。 frontmatter（スキルの設定部分）: --- name: diagram-generator-html description: | This skill should be used when the user asks to "HTMLで図を作って", "Tailwindで図解を生成して", "アーキテクチャ図を作成して", "フロー図を作って", "比較図を生成して", or needs a technical diagram for a blog article using HTML and Tailwind CSS. allowed-tools: Read, Write, Bash --- SKILL.md の本体: # Diagram Generator HTML 技術ブログ記事用のHTML図解を生成し、PNG画像に変換します。 ## Supported Patterns | パターン | 用途 | |---------|------| | アーキテクチャ図 | レイヤード、マイクロサービス、イベント駆動 | | フロー図 | プロセス、データ、ユーザーフロー | | 関係図 | ER図、クラス図、シーケンス図 | | 比較図 | Before/After、オプション比較 | | コンポーネント図 | システム構成、デプロイメント | | 概念図 | コンセプトマップ、ツリー構造 | | 同心円図 | 階層構造、抽象度の層、ベン図ライク | | ディレクトリツリー図 | ファイル構成、フォルダ階層、プロジェクト構造 | ## Specifications - **サイズ**: 1280 x 720 px (16:9) - **技術**: HTML5 + Tailwind CSS + Material Icons - **出力**: PNG画像 - **保存先**: `docs/article/[feature-name]/images/` ## HTML作成ルール 1. **固定サイズ**: `<body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-[背景色]">` 2. **外側padding**: `p-8` または `p-10` 3. **要素間隔**: `gap-4` 4. **Tailwind CDN**: `<script src="https://cdn.tailwindcss.com"></script>` 5. **最小フォント**: `text-sm` (14px) 以上 6. **禁止事項**: JavaScript動的要素、アニメーション、カスタムCSS ## Accessibility - コントラスト比: WCAG Level AA準拠 (4.5:1以上) - セマンティックHTML: `role="img"`, `aria-label` - 色依存の回避: 色 + 形状の組み合わせ ## Color Palette | 用途 | Class | |------|-------| | Primary | `bg-blue-500`, `text-blue-900` | | Secondary | `bg-green-500`, `text-green-900` | | Accent | `bg-orange-500`, `text-orange-900` | | Background | `bg-white`, `bg-gray-50` | ## Workflow ### 1. 情報収集 必要な情報: - 図解タイプ（アーキテクチャ、フロー等） - 含める要素 - 保存先記事ディレクトリ ### 2. HTML生成 基本テンプレート: ```html <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8"> <title>[タイトル]</title> <script src="https://cdn.tailwindcss.com"></script> <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" /> </head> <body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-white"> <div class="w-full h-full bg-white flex items-center justify-center p-10" role="img" aria-label="[説明]"> <!-- 図解内容 --> </div> </body> </html> ``` **詳細なパターン例**: [examples.md](references/examples.md) ### 3. ファイル保存 保存先: `docs/article/[feature-name]/images/[ファイル名].html` ### 4. PNG変換 ```bash uv run html-screenshot \ --file docs/article/[feature-name]/images/[ファイル名].html \ --output docs/article/[feature-name]/images/[ファイル名].png ``` ## Validation Checklist - [ ] `<!DOCTYPE html>` 宣言がある - [ ] Tailwind CDN が読み込まれている - [ ] `<body>` に固定サイズクラスがある - [ ] 外側divに `p-8` または `p-10` がある - [ ] JavaScript/アニメーションが含まれていない - [ ] `role="img"` と `aria-label` が設定されている ## Troubleshooting | 問題 | 対処 | |------|------| | PNG変換失敗 | HTMLファイルのパスを確認、`--force`で上書き | | 200KB超過 | HTMLを簡素化、サイズを縮小 | | ディレクトリ不在 | 先に作成してから保存 | ポイントをいくつか補足: description : 日本語の呼び出しフレーズを入れておくと、「図を作って」みたいな指示でスキルが自動発火する allowed-tools : Read, Write, Bash に制限。スキル実行中に余計なツールを使わせないことで動作が安定する HTML作成ルール : 固定サイズ・最小フォント・禁止事項を明記。Claude は「やるべきこと」「やっちゃダメなこと」の両方が明確だと良い結果を出す references リンク : 本体末尾の [examples.md](references/examples.md) が Progressive Disclosure の Level 3 への入り口。 このリンクがないと Claude は references を読みにいかない ので要注意 Step 2: お手本集（references/examples.md）を用意する .claude/skills/diagram-generator-html/references/examples.md にデザインパターンのお手本を配置します。僕の examples.md には7パターン収録されていますが、ここでは2パターン抜粋して紹介します。 アーキテクチャ図パターン Material Icons と色分けで層を区別する縦積みレイアウト: <div class="w-full max-w-4xl flex flex-col gap-4"> <div class="bg-blue-100 border-2 border-blue-500 rounded-lg p-6"> <div class="flex items-center justify-center gap-3"> <span class="material-symbols-outlined text-5xl text-blue-600">desktop_windows</span> <div class="text-center"> <h2 class="text-2xl font-bold text-blue-900">Presentation Layer</h2> <p class="text-sm text-blue-700 mt-1">UI・ユーザーインターフェース</p> </div> </div> </div> <div class="text-center"> <span class="material-symbols-outlined text-5xl text-gray-400">arrow_downward</span> </div> <div class="bg-green-100 border-2 border-green-500 rounded-lg p-6"> <!-- 同様の構造、色をgreen系に変更 --> </div> </div> レイヤー数に応じて色を blue → green → orange の順に使うのがコツ。 フロー図パターン ステップを中央揃えで縦に並べ、ノードの形状でステップ種別を表現: <div class="flex flex-col items-center gap-4"> <div class="bg-green-500 text-white rounded-full px-8 py-4 text-lg font-bold shadow-lg"> 開始 </div> <div class="text-gray-400 text-4xl">↓</div> <div class="bg-blue-500 text-white rounded-lg px-8 py-4 text-center shadow-lg"> <p class="text-lg font-bold">認証情報入力</p> <p class="text-sm mt-1">ユーザーID・パスワード</p> </div> <div class="text-gray-400 text-4xl">↓</div> <div class="bg-red-500 text-white rounded-full px-8 py-4 text-lg font-bold shadow-lg"> 完了 </div> </div> rounded-full が開始/終了ノード、 rounded-lg が処理ノード。この区別だけでフローチャートっぽくなります。 他にも比較図、同心円図、ディレクトリツリー図などのパターンがあります。最初から全部揃える必要はなくて、1〜2パターンで始めて、気に入った出力が出たら追記していけばOK。この積み重ねがスキルを育てることになるので。 Step 3: HTMLからPNGに変換する スキルが生成するのはHTMLファイルなので、ブログに貼るにはPNG変換が必要です。 CLIツール（html-screenshot） 僕は Python + Playwright で自作のCLIツールを使っています。できることベースで紹介すると: オプション 説明 デフォルト --file , -f HTMLファイルから変換 – --html , -H HTML文字列から直接変換 – --output , -o 出力先PNGパス output.png --width , -w 幅（px） 1280 --height , -h 高さ（px） 720 --force , -F 既存ファイルの上書き False # 基本: HTMLファイルからPNGに変換 uv run html-screenshot --file diagram.html --output diagram.png # サイズ指定 uv run html-screenshot --file diagram.html --output diagram.png --width 1920 --height 1080 # HTML文字列から直接変換（ちょっとした確認用） uv run html-screenshot --html "<h1>Hello</h1>" --output test.png 内部処理は4ステップ: Playwright で Chromium をヘッドレス起動 file:// プロトコルで HTML を読み込み wait_until="networkidle" で Tailwind CDN 等の外部リソース読み込みを待機 body 要素のスクリーンショットを PNG で保存 HTML側で w-[1280px] h-[720px] と固定しているので、ビューポートに関係なく毎回同じサイズの PNG が出ます。 代替案: Playwright MCP CLIツールを自作するのが手間なら、 Playwright MCP を使う方法もあります。Claude Code から Playwright のブラウザ操作を直接呼び出せるので、HTML を開いてスクリーンショットを撮る操作が MCP のツールで完結します。 セットアップ方法は別の記事で詳しく書いているので、こちらを参照してください: Playwright MCPで始めるブラウザ自動化｜環境別セットアップガイド CLIツールとPlaywright MCPの使い分け: 観点 CLIツール Playwright MCP セットアップ Python + Playwright パッケージ MCP サーバー設定 安定性 ローカル完結で安定 MCP 接続に依存 トークン消費 少ない ツール定義分の消費あり 汎用性 HTML→PNG 変換に特化 ブラウザ操作全般 「HTML を PNG に変換したいだけ」なら CLI の方がシンプルで安定します。一方で、スクリーンショット以外のブラウザ操作も Claude Code にやらせたいなら Playwright MCP の方が汎用性は高い。自分の用途に合った方を選んでください。 関連ブログ / 参考リンク 図解作成が驚くほど楽に！Claude SkillでSVG自動生成 Claude Code SkillでHTML図解を自動生成！時短テクニック ClaudeでMermaid図作成を自動化！2時間→5分の劇的時短術 Playwright MCPで始めるブラウザ自動化｜環境別セットアップガイド Claude Code 公式ドキュメント（Skills） Playwright 公式ドキュメント ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post 図解作成、AIに丸投げしたら「たまに自分より上手い」件 — Claude Code を育てる方法 first appeared on SIOS Tech Lab .

レビューで殴られた話 ども！最近レビューで「伝え方がよくねえ」と言われて凹んでいる龍ちゃんです。 最近こんなレビューをもらいまして。一番刺さったのがこれです。 「誰に向けて書かれているのかわからない、読む気が失せる」 「結論までが長い、知らない単語への配慮もない」 まあ自覚はあるんですよね。自分のブログ、どちらかといえばメモに近い。やったことをまとめて出してるだけで、読者を考えたことなんてないですねw。 というわけで、「伝え方」の部分をまるっきりAIに丸投げできないかなと思っていたんです。検証した内容とか調べた内容を参照して、あとは伝わりやすく再構築してもらう。そういう仕組みがあれば最高なのに。 で、ちょうど Agent Teams がリリースされたんですよね。エージェント同士が協業してくれる仕組み。4人のAIチームを作ってブログ執筆を丸投げしてみました。ちなみにこの記事自体が、そのチームで書かれています。 先に結果だけ トークンはバカ食いする。でも走り書きを共有するだけで、自分では構成しないようなストーリーラインのブログが出てくる。技術を列挙するだけだった構成が、読者への共感から入る構成に変わった。人間が手を入れるのは最後の20%だけ。 なぜ Agent Teams だったのか サブエージェントでは足りなかった これまで Claude Code のサブエージェントで「Opus で考え、Sonnet で動かす」構成を作ってきました（ 前回記事 参照）。 これ自体は上手くいったんですが、サブエージェントは「結果を返すだけ」なんですよね。結果を受け取って、それを加味して次に何をするか考えて、また別のサブエージェントに投げる。オーケストレーションは全部人間の仕事でした。 言ってみれば「タスク委託」はできるけど「業務委託」ができない。個別の作業は任せられても、自分でプロセス全体を回す必要がありました。 僕がやりたかったのは、書く人・読む人・直す人が 互いにツッコミ合う 構成。でもそれにはチームメイト同士が直接やり取りする必要がある。サブエージェントでは無理な話です。 サブエージェントでネストができれば！って思っていたんですが、公式にネスト不可が明記されています。 Subagents cannot spawn other subagents. 出典: Create custom subagents Agent Teams なら チームメイト同士が直接通信できる 。チームメイトが独自のチームを作ることはできないんですが、ネストしなくても協調が成り立つ仕組みです。 で、 公式ドキュメント を読んでいたら「 コードを書かないタスクから始めろ 」と書いてあるんですよね。推奨ユースケースの1番目も「Research and review」。ブログ執筆チームはまさにこのど真ん中でした。 ブログ執筆って「書く→ツッコむ→直す」の往復が本質なので、これはもう Agent Teams でやるしかないなと。というわけで実際にやってみました。 執筆チームの設計 チーム構成（4人 + リード） Agent Teams 自体にはこういった役割のエージェントが用意されているわけではなく、全部自分で設計したものです。作ったチームがこれ。 メンバー モデル 役割 なぜこの役割にしたか writer Opus 龍ちゃん風で記事を書く唯一の担当 文体の一貫性を守りたかった。複数人が書くとトーンがブレる reader Sonnet 想定読者としてツッコむ レビューで「読者の気持ちがわかっていない」と言われた。それを直接解決する役 editor Sonnet AIっぽさ検出・主張のブレ監視 AIが書くと「典型的なAI構造」になりがち。それを見張る人が必要 researcher Sonnet 技術的な裏取り（WebSearch） 「ネスト不可は本当か？」みたいな事実確認を自律的にやってほしかった writer だけ Opus で、他は Sonnet。前回記事の「Opus で考え、Sonnet で動かす」構成をそのまま踏襲しています。 ポイントは reader です。読者を置いてけぼりにする傾向があるなら、AIに読者をやってもらおうと。せっかくならレビューをくれた人の主張や感覚を参考にして、プロンプトを設計しました。 実際にこんなツッコミが来ます。 「この3つのポイントは、誰にとって嬉しい情報ですか？」 こういうのが容赦なく飛んでくる。特徴は 修正案を出さず、問いだけ投げる こと。修正案まで出すと、観点＋文体なのでコンテキストが圧迫されます。 結果として writer の文体が崩れるんですよね。reader は「ここで離脱する」「この単語わからん」と問いを投げて、修正は writer が自分の言葉でやる。 ワークフロー 全体の流れはこうなっています。 人間が手を入れる4つのタイミング 最初は「全部丸投げ」のつもりだったんですが、 暴走しました。 チームが走り書きを受け取った後、アウトライン確認もなしに執筆まで一気に突っ走ったんですよね。出来上がったものを見たら方向性がズレていて、全部やり直し。フィードバックのループも、打ち切りを設定しないと reader と editor が永遠にツッコミ合って終わらない。 というわけで、 人間の介入タイミングを設計しないとダメ だとわかりました。まぁそんな甘い話はないですよね…ここが一番実用的な話だと思います。 1. 最初の情報提供 検証したこと・詰まったこと・改善することを走り書きで共有します。構成もSEOも考えなくていい。チームが分析した後に「この情報が足りない」とフィードバックが来ることがあるので、足りない分を追加で出す。一番大事なのは、自分がやったこと・感じたことを素直に出すこと。 ここで足りない情報があると判断されれば追加を求められるように設計しています。 2. アウトライン承認 チームがアウトラインを作った段階で一旦止めて確認します。ここで方向性がズレていたら、後の執筆が全部やり直しになる。逆に言えば、ここさえ押さえれば後は安心して任せられます。 3. 完成記事の確認 + 残り20%の熱量注入 チームが書き終えたら内容を確認して、ブログ掲載用の情報（画像、リンク、補足）を追加する。そして 自分の思い・熱量が足りない部分を加筆する 。80%の構成はチームが作ってくれるんですが、残り20%は自分で入れないとダメなんですよね。ここは後で詳しく話します。 4. 別セッションでの再レビュー Agent Teams のセッションを切った後に、改めて読者目線でレビューをかけます。理由は課題パートで詳しく話しますが、チーム内の reader は徐々に初見じゃなくなるので。だんだん甘くなるのが面白いんですよね。 実際にチームが動いた様子 走り書きを投げた 実際に僕が投げた走り書きがこれです。 というかおれは気になったことを検証だけしていきたい。もちろんブログを書くこと自体は好きなんだけど、想定読者とか考えるとちょっと頭が痛くなってくる 最近レビューで「やっている検証自体はすごくいいけど、伝え方がよくねえ」「龍ちゃんは僕みたいなドーパミン中毒者の気持ちがわかっていない」って言われた というわけで僕はやったことと・検証コード・調べた内容を共有するだけでブログが出来上がったら最高だなって思うんだよねというわけでやってみる！ こんな感じの走り書きがしばらく続きます。構成もSEOも何も考えてない。前半はもはや愚痴です…ただやったことや考えたこと、頭の中に思いついた関連する情報をやみくもに突っ込んだ感じです。 チームがやったこと 走り書きを投げた後の動きがこれです。 researcher が最初に動いたのは裏取り。「サブエージェントのネスト不可って本当に公式で明記されてる？」を確認しにいって、公式ドキュメントの原文を引っ張ってきた。さらに「公式がコードを書かないタスクから始めろと推奨している」という記述を見つけてきたんですが、これは僕自身知らなかった情報でした。セクション1に書いた「ブログ執筆チームはまさにこのど真ん中」って話は、researcher が見つけてくれたおかげで書けています。 reader は容赦なかったですね。「Before/After の具体性がゼロ。『構成が読者目線になった』って言われても、実際にどう変わったのか見えない。読者は『本当に？ 見せてよ』と思う」とツッコんできた。あと「読者の集中力は3秒だと思え、冒頭で掴めなかったら終わり」とも。 editor は一段引いた視点で「技術解説が長すぎると “伝え方が下手” 問題の再現になってしまう」と指摘してきました。これ刺さりましたね。「伝え方がダメ」を解決する記事なのに、記事自体の伝え方がダメだったら本末転倒じゃないですか。 Before/After: フィードバックで何が変わったか reader と editor のフィードバックを経て、構成がどう変わったかを見せます。 Before（最初の構成案） Agent Teams の技術紹介（Subagentsとの比較表がメイン） 設計（チーム構成 + ワークフロー + セットアップ方法が本編の中 ） 実際の動き 良かった点 / 課題 / Subagentsとの使い分け（ 箇条書き3ブロック並列 ） まとめ: 「完全自動ではないが、トレードオフは要検討」 技術ブログ書いたことある人なら「あー、自分もこう書くわ」って思いません？というか過去のブログがまさにこれですね。 自分がやったことを順番に並べて、最後に感想。まさに「読者置き去り型」の構成です。 After（フィードバック反映後） 痛みから入る（レビュー指摘）→ TL;DR なぜ Agent Teams か（動機ベース。 比較表は公式リンクで済ませる ） 設計 + 人間が手を入れる4つのタイミング（ セットアップは末尾に移動 ） 実際の動き + Before/After 比較 + お気持ちログ ぶっちゃけどうだったか（ 「一番効いたこと」軸で流れ語り ） まとめ: 「80%は任せられる。残り20%の熱量こそが記事の核」 全部、reader と editor のツッコミがきっかけで変わっています。自分ひとりでは「技術比較表から入る」構成に疑問すら持たなかったと思います。 writer のお気持ちログ ここでちょっと変わった仕掛けの話をさせてください。 writer エージェントには「フィードバックを受けたら、修正する前に素直な感想を書け」と指示してあります。面白かったんで共有します。 editor から「この記事の核は『丸投げしたい』と『全部は無理』の葛藤だ」と言われた後: 確かにそうだ。ツール紹介にしちゃダメなんだよな。「どこまで任せられて、どこで人間が入るべきか」に実体験で答える記事にする。 reader から「”今回の内容”リストが技術ドキュメントの目次に見える」と言われた後: うわ、確かに。せっかく共感で掴んだのに「今日の授業内容はこちらです」は台無しだ。 editor から「セクション4が典型的なAI構造」と言われた後: ぐぬぬ…これは痛い。「良かった点」「課題」「使い分け」の3ブロック、まさにAIが書きそうな構成だ。 修正の過程が可視化されるので、何がどう変わったかの記録にもなります。そしてこうやって記事のネタにもなる。一石二鳥の仕掛けでした。 今後はここに僕の人格を埋め込んで共感できるようにしてやる予定です… ぶっちゃけどうだったか 一番効いたのは reader のツッコミ 正直、記事の骨格ができること自体は想定内だったんですよね。アウトライン作って、セクションごとに書いて、体裁を整える。これはAIに任せれば当然できる。 想定外だったのは、 自分では絶対にやらない構成が出てきた こと。技術列挙から入る構成が、読者の痛みから入る構成に変わった。reader がいなかったら「技術比較表から始めよう」の構成に疑問すら持たなかったと思います。書いてる本人は文脈を全部知ってるから、何が伝わってないかわからない。そこに reader がいることで、構成自体が読者目線に変わった。 「読者の気持ちがわかっていない」というレビューの答えが、読者役エージェントという形で返ってきた感覚でした。 正直な課題 ただ、良いことばっかり書いてもしょうがないので。 トークンコストはめちゃめちゃ食います。 各チームメイトが独立した Claude インスタンスとして動くので、4エージェント + リードで理論上約4-5倍のトークン消費。トークン削減シリーズを書いてきた自分が言うのもアレなんですが、「伝え方」改善のコストとしては…まあ妥当かなと思うようにしています。 80%は任せられるけど、残り20%が大事。 構成もストーリーラインもきれいに作ってくれる。でも自分の思いや熱量は乗らないんですよね。「この機能ずっと待ってた」「ここで痛い目見た」みたいな温度感は、最後に自分で注入する必要がある。走り書きの質がそのまま記事の質に影響するので、検証したこと・感じたことを素直に出さないと、チームも薄い記事しか作れない。 一番時間がかかるのは最後の人間レビュー。 チームの出力をそのまま出せるわけじゃなくて、想定読者の主張と自分の意見を喧嘩させてブラッシュアップする作業が要る。しかもチーム内の reader は writer とのやり取りを重ねるうちにだんだん懐柔されていくんですよね。最初は容赦なくツッコんでたのに、後半は甘くなる。だからセッションを切って、フレッシュな視点で改めてレビューする必要がある。ここが結局一番手間がかかるところでした。 最後に一つ。 Agent Teams は2026年2月5日リリースの research preview です。 正式リリースではないので、今後変更の可能性があります。 まとめ 「検証だけしたらブログが出来上がる」は実現できたか？ 80%は任せられます。構成もストーリーラインもきれいに作ってくれる。 でも、自分の思いや熱量は乗らない。 だから残り20%は自分で書く。この20%がなかったら、きれいなだけの記事で終わる。 一番大事なのは、検証したこと・詰まったこと・改善すること。それを走り書きで共有すれば、「伝え方」はチームが整えてくれます。 完全自動で完璧な記事が出てくるわけじゃない。でも「ひとりで悩んで手が止まる」はあきらかに減りました。コストは高い。でも「伝え方がよくねえ」と言われ続けるよりはマシです。 この記事自体がその実験の成果物です。読んでどう感じたかが、この仕組みの評価そのもの。 ほなまた〜 やってみたい人向け: セットアップ 有効化 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 devcontainer で使う場合 { "remoteEnv": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } 設計Tips article.md に書けるのは writer だけにする。 他のメンバーが直接記事を編集すると文体が崩れるし、ファイル競合も起きる。公式ベストプラクティスにも「ファイルの競合を避けろ」とある broadcast は使わない。 チームメイトへの指示は全部個別メッセージ（write）で。broadcast だとメッセージが全メンバーに届くのでトークンが人数分かかる 注意点 VS Code 統合ターミナルでは Split Panes 非対応 → in-process モードで動く Split Panes を使いたい場合は tmux または iTerm2 が必要 1セッションにつき1チーム 実験的機能。今後変更の可能性あり 関連記事・参考リンク シリーズの流れ Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善 Claude Code MCP が遅い・重い問題、CLI + Skills で解決 Claude Code サブエージェントの最適構成：Opus で考え、Sonnet で動かす Claude Code /research の待ち時間をゼロに：Skill × サブエージェント構成 今回: Agent Teams で執筆チームを作った話 参考リンク Orchestrate teams of Claude Code sessions — Agent Teams 公式ドキュメント Create custom subagents — Subagents 公式ドキュメント Introducing Claude Opus 4.6 — Opus 4.6 リリース発表 How we built our multi-agent research system — Anthropic のマルチエージェント設計 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Code Agent Teams に記事を丸投げしたら、自分では書かない構成が返ってきた first appeared on SIOS Tech Lab .

/research コマンドの課題：バックグラウンド不可、コンテキスト消費 ども！最近Claude Codeでのトークン削減にうるさい龍ちゃんです。 前回、 Claude Code サブエージェントの最適構成：Opus で考え、Sonnet で動かす という記事でトークン消費を抑える話をしました。今回もその系統のお話です。 Claude Codeの調査品質がバラバラ？：/researchで解決する方法 で紹介した /research 、機能としては便利でした。調査深度の選択、CRAAP評価、統一フォーマットでの出力…。でもOpusともっと話したい僕としては課題がありました。 バックグラウンドで動かない : 調査が終わるまでずっと待つしかない 親コンテキストを食う : 検索結果がどんどん積まれて、長い調査の後はメイン会話がもっさりする 全部同じモデルで動く : 判断も検索も同じモデル。Opus でやる必要のない作業もある 「前回の Opus + Sonnet 構成、/research にもサブエージェントを使えばいけるんじゃない？」 と思い立ったので実践です。 TL;DR：何が変わったか 先に結論だけ知りたい方向けのまとめです。 課題 解決策 バックグラウンドで動かない Task tool の run_in_background: true で解決 親コンテキストを食う 検索結果は Worker のコンテキストに閉じ込め 全部同じモデルで動く 計画・評価は Opus、検索実行は Sonnet に分業 詳しい実装方法と使用感は続きをどうぞ。 完全版は GitHub Gist で公開しています。 .claude/ ディレクトリに配置すればすぐに使えます。 サブエージェントのネスト制限 実装を進める前に知っておくべき重要な制限があります。 Claude Code のサブエージェントは、別のサブエージェントを起動できません。 GitHub issue でも報告されています： Sub-Agent Task Tool Not Exposed When Launching Nested Agents #4182 Sub-agents can’t create sub-sub-agents #19077 No Nested Delegation: Sub-agents are not allowed to create other sub-agents, ensuring a single-level structure that prevents infinite nesting and keeps the execution hierarchy simple and manageable. 無限再帰を防ぐための意図的な設計です。サブエージェントとして起動されたエージェントは、定義ファイルに tools: [Task] と書いてあっても Task tool が使えなくなります。 つまり「Skill → Orchestrator → Worker」のような階層構造は作れない。 Skill やメインセッションから直接 Worker を起動する 設計にする必要があります。 本当は専任ユーザーみたいな代わりで報告だけ聞くという完全独立構成をしたかったのですが…。ここをカスタマイズで乗り切るって方法もあるんですが、大規模になるので一旦は我慢です。 Commands → Skill + サブエージェントで何が変わったか 変えたこと 1. Commands から Skill に移行 .claude/commands/research.md の単一ファイル構成から、Skill + Agent の分離構成に変更しました。 Before: .claude/commands/research.md（1ファイル） After: .claude/skills/research/SKILL.md # エントリーポイント .claude/agents/research-worker.md # 検索実行（Sonnet） Claude Code v2.1.3 （2025年1月9日）で Commands と Skills が概念的に統合されました。どちらも引き続き使えますが、Skills はディレクトリ構造や allowed-tools 指定などの追加機能があるため、今回は Skills 形式 を採用しました。というか新規で作るならSkillが推奨されています。（僕は合わせてすべてのCommandsをSkillsに変換しました。） 2. メインセッション + Worker パターン ネスト制限を踏まえて、以下の役割分担にしました。 役割 担当 モデル 計画・評価・レポート作成 メインセッション Opus 検索実行 Worker Sonnet 前回の記事で紹介した「Opus で考え、Sonnet で動かす」構成がそのまま実現できています。 3. Worker を並列で動かせるようにした 調査深度に応じて Worker を複数起動できるようにしました。 深度 Worker 数 分担 クイック 1 主要情報のみ 標準 2-3 公式/ブログ/日本語で分担 ディープ 4-6 さらに細分化 アーキテクチャ ネスト制限を踏まえた設計です。 ポイント 判断が必要な作業（計画・評価・レポート作成）はメインセッションの Opus が担当 し、 定型的な作業（検索実行）は Worker の Sonnet に任せる こと。 Claude Code サブエージェントの設定方法 実際の設定ファイルを共有します。完全版は GitHub Gist で公開しています。 .claude/ ディレクトリに配置すればすぐに使えます。 サブエージェントの公式ドキュメント も参考にしてください。 Skill（エントリーポイント） # .claude/skills/research/SKILL.md --- name: research description: 調査して、リサーチして、/research [トピック] allowed-tools: Task, AskUserQuestion, Read --- Skill の役割は3つ。ユーザーへの質問、検索クエリの設計、Worker の起動です。 Worker（検索実行担当） # .claude/agents/research-worker.md --- name: research-worker tools: [WebSearch, WebFetch, Read] model: sonnet permissionMode: acceptEdits --- model: sonnet でコスト効率を重視。検索と情報収集に特化しています。 ポイントは、 Worker はファイル出力をしない こと。結果はメインセッションに返して、最終的なレポート作成はメインセッションが担当します。 バックグラウンド実行 サブエージェントをバックグラウンドで動かすには、Task tool を呼び出す際にバックグラウンド実行を明示的に依頼します。 // Skill から Worker をバックグラウンドで起動 Task({ subagent_type: "research-worker", description: "Research Worker: バックグラウンドで実行", prompt: "..." }) // → Claude に「バックグラウンドで実行して」と依頼、または Ctrl+B でバックグラウンド化 バックグラウンド実行中も他の作業ができ、完了すると自動で通知されます。詳しくは サブエージェントの公式ドキュメント を参照してください。 実際に使ってみた感想 しばらく使ってみての体験談です。 調査中も他の作業ができる バックグラウンド実行で待ち時間ゼロ。「これ調べておいて」と言ったら、すぐ次の作業に移れます。コードを書きながら裏で調査が走っている感覚、なかなか快適です。 メインの会話が軽いまま 検索結果が親コンテキストに積まれないので、長時間の作業でもメイン会話がサクサク。以前は調査後に「なんか重いな…」と感じることがありましたが、それがなくなりました。 複数調査を同時に回せる 「これとこれ、並行で調べておいて」ができるようになりました。別々のトピックを同時に調査できるのは地味に便利。 Opus との会話時間が増えた 検索実行は Sonnet に任せて、判断・対話は Opus と。Opus のトークンを本当に必要なところに集中できるようになりました。 注意点・制限事項 実装上、いくつかの制約があります。 サブエージェントはネストできない（再掲） 今回の最大のポイント。サブエージェントとして起動されたエージェントは Task tool を使えません。Skill やメインセッションから直接 Worker を起動する設計にしましょう。 エラー時は1回リトライ後、部分結果で続行 Worker の WebSearch/WebFetch がエラーを返した場合、代替クエリで1回だけ再試行します。それでも失敗した場合は、取得できた部分結果でレポートを作成します。完璧な結果を待つより、得られた情報で先に進むほうが実用的です。 Worker はファイル出力しない Worker は検索結果をメインセッションに返すだけ。ファイル書き込みはメインセッションが一括で行います。これにより、レポートの一貫性が保たれます。 ユーザー対話は Skill に集約 調査パラメータの確認は Skill が担当し、Worker はユーザーに質問しません。Skill をインターフェースにすることで、Worker のプロンプトから対話処理の指示を省けます。 数値的な検証はこれから 正直なところ、トークン消費量や処理時間の定量的な比較はまだできていません。ただ、使用感としては非常に良いです。バックグラウンドで調査が回っている間に他の作業ができるのは、体感でかなり快適になりました。継続的に使いながら数値を取っていく予定です。（便利になるってのは確かなのでモチベがわけば測定します…） まとめ /research を Skill + サブエージェント構成に移行しました。 ネスト制限への対応 : サブエージェントからサブエージェントは起動できない Skill から直接 Worker を起動する設計に 構成 : 計画・評価・レポート作成 → メインセッション（Opus） 検索実行 → Worker（Sonnet） 効果 : バックグラウンドで調査可能 親コンテキストを消費しない 並列実行でスピードアップ トークン削減シリーズの流れ 回 内容 1 AIフレンドリーなドキュメント管理 （基盤設計） 2 静的情報活用で実行速度改善 （トークン削減） 3 Opus で考え、Sonnet で動かす （サブエージェント分業） 4 今回 : 調査も分業体制に 調査も「Opus で考え、Sonnet で動かす」。 サブエージェントのネスト制限という制約がありますが、むしろシンプルな構成に落ち着きました。制約があるからこそ、クリーンな設計になることもあるんですね。 分業できるところは分業して、Opus との会話を長く楽しみましょう。 ではまた！ 関連記事 Claude Codeの調査品質がバラバラ？：/researchで解決する方法 Claude Code サブエージェントの最適構成：Opus で考え、Sonnet で動かす 参考リンク Claude Code Skills Claude Code Sub-agents GitHub Issue #4182: Sub-Agent Task Tool Not Exposed GitHub Issue #19077: Sub-agents can’t create sub-sub-agents ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Code /research の待ち時間をゼロに：Skill × サブエージェント構成 first appeared on SIOS Tech Lab .

CLAUDE.md・AGENTS.mdを書いても効かない原因は設計にある。自然とドメイン注入ができる設計思想と、静的・オンデマンド・自律蓄積の3パターンを解説。 はじめに ども！いろんなところでAI関連の話をしている龍ちゃんです。 Claude Code、Cursor、GitHub Copilot…AI駆動開発ツールは急速に広がっています。でも、どのツールを使っても同じ課題にぶつかるんですよね。 「コーディング規約を無視したコードを生成する」 「過去のPR議論を踏まえない提案をしてくる」 「プロジェクト固有の設計思想を理解していない」 なぜこんなことが起きるのでしょうか？ 考えてみてください。これって、 アサインされたばかりのエンジニア と同じ状況ですよね。プロジェクトのルールも、過去の経緯も、なぜこの設計になったかも知らない。優秀なエンジニアでも、ドメイン知識がなければ的外れな提案をしてしまいます。 さらに言えば、 セッションごとに毎回記憶喪失になっているエンジニア のようなもの。さっき教えたことを今日また一から説明する…これでは効率が悪いですよね。（掟上今日子って小説面白かったな…） AIも同じです。 ドメイン知識をどうAIに渡すか 。これがAI駆動開発の核心的な課題です。 CLAUDE.md、AGENTS.md、copilot-instructions.md…各ツールには設定ファイルがあります。「どう書くか」という記事は多くありますが、 そもそもなぜこれが必要で、どう設計すべきか という話はあまり語られていません。 本記事では、特定のツールに依存しない「ドメイン知識の設計思想」を紹介します。 なぜドメイン注入が必要なのか ドメイン注入がなくても、AIは動きます。開いているファイルや指定したファイルを分析して、現状を理解しようとしてくれるんですよね。 でも、ここに問題があるんです。 セッションごとにクオリティがばらつく AIがすべてのコードを見てくれれば、一定のクオリティになるはず。でも現実には、トークンの制約やプロンプトの書き方によって、分析するファイルが変わってしまいます。 あるセッションでは重要な設定ファイルを読んでくれたのに、別のセッションでは読まなかった。こういうことが普通に起きます。 分析されないファイルは「存在しない」扱い 分析されなかったファイルはどうなるか？完全に無視されます。 キャンバスに例えると、すでに絵が描かれているのに、その上に全く違うテイストの絵を重ねちゃうようなもの。結果として、プロジェクトの一貫性が崩壊してしまいます。 具体的な失敗パターン 僕が実際に遭遇した例を挙げると： OAuth認証を使っているのに、ログインフォームを作ってきた ：プロジェクトの認証パターンを完全に無視 既存のデータ保存ロジックを再定義 ：すでにあるのに、別の保存システムを一から構築 データベース構造を一から設計 ：既存のスキーマを無視して新しいテーブル定義を提案 これらはライブコーディング初期の笑い話なんですけど、ドメイン知識なし＋プロンプトも雑という状況では、まあ当然の結果ですよね。 コード分析のコスト問題 コードの分析って、書いてあることを全て読み込むってことです。これはトークンを大量に消費します。 毎回同じルールや規約をコードから「推測」させるのは非効率。 最初から正解を教えておく ほうが、コスト的にも品質的にも良いんです。 書いているのに効かない？ 「CLAUDE.mdを書いたのに全然効かない」という声もよく聞きます。これには理由があります。 効かない原因 書き方が曖昧 ：「いい感じにして」「適切に処理して」では、AIは具体的な行動を取れない 情報が多すぎる ：何でもかんでも詰め込むと、コンテキストが溢れて精度が下がる 情報が少なすぎる ：肝心なルールが書かれていなければ、無いのと同じ AIが見つけられない ：存在しても、AIがその存在を知らなければ参照されない 入れすぎ注意 コンテキスト量が増えすぎると精度が下がるってのは、よく言われている話です。関係ない情報が増えると、AIが本当に必要な情報を見落としやすくなります。 ただ、 初期段階はとりあえず突っ込んでいけばいい ってのが僕の考えです。まずは書いてみて、効果を見ながら削っていく。最初から完璧を目指す必要はないんですよね。 これらは結局、 ドキュメントの形式・量・配置 の問題に帰着します。CLAUDE.mdの書き方だけでなく、設計思想から見直す必要があるんです。 では、どうすればいいのか。ここからが本題です。 主張: ドキュメントはコードと同じリポジトリにMarkdownで置け まず、くそでか主張をします。 実装に必要なドメイン知識は、コードと同じリポジトリにMarkdownで置け なぜ同じリポジトリなのか Notion、Confluence、Google Docs…ドキュメント管理ツールはたくさんありますよね。議事録、要件定義、顧客との調整事項など、 人間がやり取りするドキュメント にはこれらが最適です。 でも、 AIが参照すべきドキュメント は別なんです。 AIが開発するとき、コードと一緒にドキュメントも読めることが重要です。 Notionにある設計書を「読んでおいて」と言っても、AIは直接アクセスできない 別システムにあるドキュメントは、コードとの整合性が崩れやすい MCPなどの連携機構を使う手もあるけど、複雑さが増す シンプルな解決策 ：最初から同じリポジトリに置いちゃえばいいんです。 なぜMarkdownなのか 次に、なぜMarkdown形式なのか。これも理由があります。 1. トークン効率が良い <!-- HTML --> <h1>タイトル</h1> <p>本文です</p> <ul> <li>項目1</li> <li>項目2</li> </ul> # タイトル 本文です - 項目1 - 項目2 同じ内容でも、HTMLはタグのオーバーヘッドでトークンを消費しちゃいます。Markdownはシンプルで無駄がありません。 じゃあTXTでいいじゃないかってなりますけど、それじゃあ人間が読みづらいということで可読性と構造性を考えた時に一番トークン効率が良いんですね。 2. 構造が明確 見出しレベルは # の数で一目瞭然。リスト、コードブロック、引用も直感的。LLMがパースしやすい形式なんです。 3. ツール非依存 どのAIツールでもMarkdownは読めます。Claude Code、Cursor、GitHub Copilot…どれに乗り換えても、ドキュメントはそのまま使えるんですよね。 ツールに依存しない資産になる 「Claude Codeを使っているからCLAUDE.mdを書いている」という考え方、ちょっと危険です。 ツールは変わります。新しいツールも出てきます。でも、 リポジトリ内のMarkdownドキュメントは残る んです。 Claude Code → Cursor に乗り換えても使える 新しいツールが出てきても使える チームメンバーが別のツールを使っても共有できる ちなみに、 AGENTS.md は2025年にSourcegraph、OpenAI、Googleが推進して、今はLinux Foundation傘下のAgentic AI Foundationが管理する業界標準になってます（Claude Codeは読み込んでくれないんですけどね！！）。これは、いろんなAIツールが自動で読み込んでくれる設定ファイルになります。こういうところからも「ツール非依存」という流れは業界全体で進んでるんですよね。 ドメイン知識をMarkdownでリポジトリに整理することは、特定ツールへの投資ではなく、 プロジェクト全体への投資 になります。 AIフレンドリー設計の3原則 ドキュメントを置くだけでは不十分です。AIが効果的に使えるよう設計する必要があります。 原則1: トークン効率 無駄なデータを削る AIに渡すコンテキストには上限があります。無駄なデータはトークンを消費して、本当に必要な情報を圧迫します。 【避けるべきこと】 - HTMLをそのまま保存 - 不要なメタデータを含める - 冗長な説明を書く 【やるべきこと】 - Markdownに変換 - 本文のみを抽出 - 簡潔に書く HTMLで保存したドキュメントは、Markdownに変換するだけでトークン数を大幅に削減できます。詳しくは「 Markdown保存でトークン削減 」で解説してます。これはHTML→Markdownの話ですが、ドキュメントで余分な部分があったらそぎ落とすというのが大事です。余計な情報があればあるほどノイズになります。そうなると僕のブログの「はじめに」は全カットしたほうが良いですね。 原則2: 構造の明確さ AIがパースしやすい形式にする # プロジェクト名 ## 概要 このプロジェクトは... ## アーキテクチャ ### フロントエンド - React - TypeScript ### バックエンド - Python - FastAPI ## 開発ルール 1. PRには必ずテストを含める 2. 命名規則はキャメルケース 見出しで階層構造を示す リストで列挙する コードブロックで例を示す 曖昧な自然言語より、構造化された記述のほうがAIは正確に理解してくれます。 原則3: 発見可能性 AIが「見つけられる」設計にする ドキュメントが存在しても、AIがその存在を知らなければ参照できないんですよね。指定すれば全部の情報を読んでくれるかもしれませんが、それではトークン数が多くなってしまいますね。そんな時に使うのがREADMEです。 docs/ ├── README.md ← インデックス（目次） ├── architecture/ │ ├── README.md ← このディレクトリの説明 │ ├── overview.md │ └── decisions.md ├── guides/ │ ├── README.md │ └── coding-style.md └── research/ ├── README.md └── ... 各ディレクトリにREADMEを置いて、 インデックス（目次） として機能させます。AIは必要に応じてREADMEを読んで、関連ファイルを見つけてくれるんです。 詳しくは「 AIフレンドリーなドキュメント管理 」で解説してます。 3つの設計パターン 具体的な設計パターンを3つ紹介しますね。「誰が整理するか」と「いつ読み込むか」の組み合わせです。 パターン 誰が整理するか いつ読み込むか 静的コンテキスト 人間 毎回自動で オンデマンド 人間 必要な時にAIが選択 自律蓄積型 AI AIが調査→保存→再利用 パターン1: 静的コンテキスト（常に読み込む） 人間が整理し、AIが毎回自動で読み込む情報 まず、ドキュメントを docs/ に整理します。 # docs/project-overview.md ## プロジェクト概要 このプロジェクトは... ## ディレクトリ構造 - src/: ソースコード - docs/: ドキュメント - tests/: テスト ## 開発ルール - コーディング規約: PEP8準拠 - コミットメッセージ: Conventional Commits 次に、ツールの設定ファイルから 参照させます 。 # CLAUDE.md（または AGENTS.md、copilot-instructions.md） セッション開始時に以下を必ず読み込んでください： - docs/project-overview.md - docs/coding-style.md この構成なら、ドキュメント自体はツール非依存のまま、各ツールから参照できます。ツールを乗り換えても、参照先の指定を変えるだけ。 常に必要な情報 に向いてます。 プロジェクトの概要 ディレクトリ構造 基本的な開発ルール 詳しくは「 毎回検索をやめて実行速度を改善 」で解説してます。 パターン2: オンデマンド（必要な時に読み込む） 人間が整理し、AIが必要な時に選んで読み込む情報 # docs/README.md ## ドキュメント一覧 ### アーキテクチャ - [システム全体像](./architecture/overview.md): システムの全体構成 - [技術選定理由](./architecture/decisions.md): なぜこの技術を選んだか ### 開発ガイド - [コーディング規約](./guides/coding-style.md): コードの書き方 - [テストガイド](./guides/testing.md): テストの書き方 ### 調査資料 - [競合分析](./research/competitor-analysis.md): 競合サービスの調査 READMEをインデックスとして、AIが必要に応じて個別ファイルを読み込んでくれます。 大量ドキュメントの管理に向いてる コンテキスト窓を効率的に使える 段階的に詳細を開示できる 実際、主要なAIツールはディレクトリ単位での設定をサポートしてます。 Claude Code : .claude/rules/ でディレクトリごとのルールを定義可能 GitHub Copilot : ディレクトリ単位のinstructionsに対応 詳しくは以下の記事で解説してます。 Claude Code: CLAUDE.md vs .claude/rules/ の実践的な使い分け copilot-instructions.md を分割したい？applyTo パターンで解決 copilot-instructions.md と AGENTS.md、どっちに何を書く？ このパターンは Spec駆動開発 とも相性が良いんですよね。仕様書をdocs/features/に配置して、AIが実装時に参照することで、仕様に沿った開発ができます。詳しくは「 Claude CodeでSpec駆動開発 」で解説してます。 パターン3: 自律蓄積型（AIが調査して蓄積） AIが調査し、AIが保存し、AIが再利用する情報 このパターンでは、 人間は調査の指示を出すだけ 。AIが調査を実行して、結果をMarkdownで保存してくれます。 さらに オンデマンドパターンと組み合わせる ことで、真価を発揮します。docs/research/README.mdにインデックスを用意しておけば、関連タスク時にAIが過去の調査結果を発見・参照できるようになるんです。 同じことを何度も調べなくていい 調査結果がプロジェクトの知識資産として蓄積される 新しいタスクに取り組む際、過去の調査を参照できる 詳しくは「 /research コマンドの紹介 」で解説してます。 実例: モノレポでの実践 ここまでの考え方を、実際のプロジェクトでどう適用しているか紹介しますね。 ディレクトリ構成 プロジェクトルート/ ├── CLAUDE.md # ルート: 全体像・共通ルール ├── docs/ # 計画・設計（実装コードなし） │ ├── CLAUDE.md # docsフェーズのガイドライン │ ├── specs/ # 普遍的な仕様（変更不可） │ ├── features/ # 新機能開発計画 │ ├── research/ # 実装検証結果・知見【自律蓄積型】 │ ├── references/ # スキル・エージェント用参照資料 │ └── article/ # 記事執筆用調査 ├── application/ # 実装フェーズ │ ├── backend/ │ │ └── CLAUDE.md # バックエンド開発ガイド │ └── frontend/ │ └── CLAUDE.md # フロントエンド開発ガイド └── infrastructure/ └── CLAUDE.md # インフラ開発ガイド 3つのパターンの適用 パターン 適用箇所 静的コンテキスト 各階層のCLAUDE.md（docs/specs/への参照を含む） オンデマンド docs/specs/, docs/features/, docs/references/, docs/article/ 自律蓄積型 docs/research/ ポイント 設定ファイルの階層構造 : ルートで全体像、各ディレクトリで詳細を提供 計画と実装の分離 : docs/（計画）と application/（実装）を分ける 知見の蓄積 : docs/research/ に調査結果を蓄積 全てMarkdown : ドキュメントはMarkdownで統一 詳しくは「 モノレポでビルド時間を大幅短縮するCLAUDE.md活用法 」で、実際のプロジェクト構成とワークフローを解説してます。 【コラム】この考え方、実はRAGです ここまで読んで「RAGと似ている」と思った方もいるかもしれません。 実際、その通りなんです。 RAG（Retrieval-Augmented Generation）は「検索で情報を取ってきて、生成に使う」技術。ベクトルDBを使うイメージが強いかもしれませんが、 本質は「外部知識をコンテキストに補填する」こと です。 CLAUDE.md に書く → 外部知識をコンテキストに補填 docs/ から読み込む → 外部知識をコンテキストに補填 AIが調査して保存 → 外部知識をコンテキストに補填 全部RAGの考え方なんです。 なぜベクトルDBを使わないのか 「RAGならベクトルDBでは？」と思うかもしれません。 でも、プロジェクト固有のドキュメントって、多くても数十〜数百ファイル程度です。この規模だと： ベクトルDBのセットアップコストが過剰 「エラーコードE001」を探したいのに関係ない文書がヒットする どれが重要かは人間が判断したほうが精度が高い 人間がキュレーションしたドキュメント + AIが自律的に蓄積した調査結果 。この組み合わせが、プロジェクト規模のドメイン知識には向いてます。 大規模なドキュメント（数千〜数万件）を横断検索する場合は、ベクトルDBやハイブリッド検索が適切ですね。 まとめ AI駆動開発における「ドメイン知識の渡し方」についてサクッと解説してきました。ちょっと真面目にまとめておきます 核心 課題 : AIが「プロジェクトのことを分かってくれない」 主張 : ドキュメントはコードと同じリポジトリにMarkdownで置け AIフレンドリー設計の3原則 トークン効率 : 無駄なデータを削る（Markdown化） 構造の明確さ : AIがパースしやすい形式に 発見可能性 : インデックス（README）で見つけられるように 3つの設計パターン 静的コンテキスト : 人間が整理、毎回自動で読み込む オンデマンド : 人間が整理、AIが必要な時に選んで読み込む 自律蓄積型 : AIが調査・保存・再利用 ツールに依存しない資産化 この設計思想は、特定のAIツールに依存しません。 Claude Code → Cursor に乗り換えても使える 新しいツールが出てきても使える ドキュメントがプロジェクトの資産として残る まずは、プロジェクトの設計書やルールをMarkdownで整理するところから始めてみてください。それが、AI駆動開発を加速させる第一歩です！ 関連記事 設計思想・全体像 本記事の考え方を実際のプロジェクトに適用した実践例です。 AI協業開発環境の構築術｜モノレポでビルド時間を大幅短縮するCLAUDE.md活用法 本記事の実践例。CLAUDE.md階層構造をモノレポで実装し、ビルド時間短縮を実現 Claude CodeでSpec駆動開発 – AI駆動時代の計画術 オンデマンドパターンの応用。仕様書をdocs/features/に配置し、AIが参照しながら実装 3原則の深掘り 本記事で紹介した3原則（トークン効率・構造の明確さ・発見可能性）を個別に深掘りした記事です。 HTMLで保存してる奴、全員Markdownにしろ トークン効率 の実践。HTML→Markdown変換でトークン数を削減する具体的手法 Claude Code設計術：AIフレンドリーなドキュメント管理 構造の明確さ・発見可能性 の実践。READMEインデックスの設計パターン 3パターンの深掘り 本記事で紹介した3パターン（静的コンテキスト・オンデマンド・自律蓄積型）を個別に解説した記事です。 Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善 静的コンテキスト の実践。毎回検索していた情報をCLAUDE.mdに埋め込み高速化 CLAUDE.md vs .claude/rules/ の実践的な使い分け オンデマンド の実践（Claude Code）。ディレクトリ単位でルールを分割 copilot-instructions.md を分割したい？applyTo パターンで解決 オンデマンド の実践（GitHub Copilot）。*.instructions.mdでファイル/言語別に分割 Claude Codeの調査品質がバラバラ？：/researchで解決する方法 自律蓄積型 の実践。AIが調査→Markdown保存→再利用するワークフロー ツール別ガイド Claude CodeとGitHub Copilot、それぞれの設定ファイル体系を解説した記事です。 Claude Code Skills 実装ガイド Claude Codeでカスタムスキルを作成し、ワークフローを自動化する方法 GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術 copilot-instructions.md、*.instructions.md、AGENTS.mdなど5種類の設定を整理 Claude Code→GitHub Copilot移行で使える設定ファイル対応表 両ツールの設定ファイルを対応表で比較。ツール間の「翻訳表」として活用 AGENTS.md vs Custom Agents【5つの比較表で混乱解消】 GitHub CopilotのAGENTS.mdとCustom Agentsの違いを比較表で整理 copilot-instructions.md と AGENTS.md、どっちに何を書く？ 公式推奨と「What vs How」の役割分担で使い分けを解説 Agent Skills 入門：SKILL.md の基本から実践まで GitHub Copilot Agent SkillsとSKILL.mdの書き方を実用例付きで解説 Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？ Skills発火メカニズムの違いと移行時の注意点を解説 仮説検証シリーズ 「こうすれば上手くいくのでは？」という仮説を実際に検証した記事です。 検証→記事化で知見を資産化！RAGもどきで技術ブログ執筆を効率化 仮説 : 既存記事をRAG的に参照すれば、新規記事の執筆が効率化する 結果 : 文体・構成の一貫性が向上し、過去記事との重複も防げた ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post CLAUDE.md効かない？ドメイン注入を設計思想から見直す first appeared on SIOS Tech Lab .

RAG＝ベクトルDBは誤解。BM25、Web検索、GraphRAGなど7つの手法を比較表で整理。データ規模・コスト・精度での選び方を解説します。 はじめに 「RAGを導入したい」という話になると、多くの場合「じゃあベクトルDBを選定しなきゃ」という流れになります。 弊社でもRAG構築・導入支援サービスを提供しており、RAGについて説明する機会が多くあります。その中で「RAG」と「ベクトル検索」を同じ文脈で質問されることがよくあります。 確かに、トレンドとしてRAGとベクトル検索を同じ文脈で語ることは間違いではありません。しかし、実はChatGPTやClaudeの検索機能もWeb検索エンジンと連携した「RAG」の一種です。 本記事では、RAGの原論文に立ち返り、 RAGの本質は「検索手法」ではない ということを整理します。そして、ベクトル検索以外にどのような外部情報の取り込み方があるのかを俯瞰的に紹介します。 RAGの定義に立ち返る RAGとは何か RAG（Retrieval-Augmented Generation：検索拡張生成）とは、LLM（大規模言語モデル）に外部の情報を与えることで、回答の精度を向上させる手法です。LLMは学習データに基づいて回答を生成しますが、学習後の最新情報や社内固有の知識は持っていません。RAGはこの課題を「外部から必要な情報を検索して補う」というアプローチで解決します。 RAGの階層構造を整理する RAGを理解するために、以下の階層構造を整理しておきましょう。 ここで重要なのは、 RAGの本質は「外部知識をコンテキストに補うアプローチ」であり、「どう取り込むか」は手段の話 だということです。ベクトル検索は実装選択肢の一つに過ぎません。 原論文（Lewis et al., 2020）の定義 RAGの原論文 では、RAGを以下のように定義しています。 “models which combine pre-trained parametric and non-parametric memory for language generation” （言語生成のために、事前学習済みのパラメトリックメモリと非パラメトリックメモリを組み合わせたモデル） パラメトリックメモリ : LLMが学習時に獲得した知識（モデルの重みに格納） 非パラメトリックメモリ : 外部から取得する知識（検索で取得） 注目すべきは、この定義に「ベクトル検索」という限定がないことです。論文の実装例ではDPR（Dense Passage Retrieval）というベクトル検索手法が使われていましたが、RAGの定義自体は「外部知識をどのように取得するか」を限定していません。 論文における概念の発展 RAGという概念は、様々な論文が発表される中で発展を続けています。 2020年 : RAGは「BART + DPR」という 特定のモデルアーキテクチャ として提案されました。論文では “RAG models”、”fine-tuning recipe” といった用語が使われています。 2024年 : RAGは「外部知識とLLMを統合するための 包括的な概念 」として再定義されています（ RAG Survey 、 Modular RAG ）。”RAG paradigms”、”framework”、”LEGO-like framework” といった用語が使われ、単一の技術ではなく 目的達成のための概念・考え方 として扱われています。 補足 : RAGの発展段階（Naive → Advanced → Modular）や各手法の数値的な比較については、弊社ブログ「 RAGはどのように進化しているのか？ 」で体系的に解説しています。本記事では「RAGとは何か」という概念の整理に焦点を当てます。 RAGにおける外部情報の取り込み方 RAGを実現するための外部情報の取り込み方は、ベクトル検索だけではありません。ここでは代表的な手法を紹介します。 手法選択の考え方は「 ユースケースに適した方法で、必要な情報をLLMに与える 」です。各手法には得意な情報の特性があり、ユースケースに応じて選択します。また、単一の手法だけでなく、複数の手法を組み合わせることも有効な選択肢です。 なお、どの手法を選択しても、導入して終わりではありません。精度測定と継続的なメンテナンス（チューニング、データ更新、クエリ最適化など）は共通して必要な取り組みです。 ベクトル検索型 埋め込みベクトルによる意味的類似度検索を行う手法です。 特徴 : 意味的な類似性を捉えられる 適したユースケース : 「〇〇に似た事例は？」「関連するドキュメントを探したい」など、意味的に類似した情報を探す場面 実現キーワード : Auzre AI Search , Pinecone, FAISS, pgvector, Milvus, Chroma, Weaviate, Qdrant キーワード検索型（BM25） 従来の全文検索アルゴリズムを活用する手法です。 特徴 : 完全一致が重要な場面で有効 適したユースケース : エラーコード検索、法律条文、製品型番、固有名詞など、完全一致・部分一致が重要な場面 実現キーワード : Auzre AI Search, Elasticsearch, OpenSearch, Apache Solr, Whoosh ハイブリッド検索型 ベクトル検索とキーワード検索を組み合わせ、リランキングと併用する手法です。 特徴 : 意味的類似性と完全一致の両立 適したユースケース : 意味的類似性と完全一致の両方が求められる場面、大規模データで高い検索精度が必要な場面 実現キーワード : Azure AI Search, Elasticsearch (kNN + BM25), OpenSearch, Pinecone (Hybrid), Weaviate (Hybrid) Web検索型 外部検索エンジンと連携してリアルタイム情報にアクセスする手法です。 特徴 : リアルタイム情報へのアクセスが可能 適したユースケース : 最新ニュース、現在の価格・在庫、イベント情報など、リアルタイム性が求められる情報 実現キーワード : ChatGPT Search, Claude Web Search, Gemini Grounding, Perplexity, Bing API, Google Custom Search API 構造化検索型 ナレッジグラフや構造化データベースを活用する手法です。 GraphRAG ナレッジグラフを活用し、エンティティ間の関係を検索 適したユースケース : 「AとBはどう関係する？」「〇〇に関連する人物は？」など、関係性を辿る必要がある場面 SQL検索 構造化データからの正確なデータ取得 適したユースケース : 売上データ、在庫数、ユーザー情報など、構造化データから正確な値を取得する場面 実現キーワード : Neo4j, Amazon Neptune, Azure Cosmos DB (Gremlin), PostgreSQL, BigQuery マニュアルRAG（人力補填型） 人間が選択的に文章を補填する手法です。 特徴 : 文脈理解や暗黙知の活用が可能 適したユースケース : PoC・少量運用、暗黙知の活用、システム化前の検証、文脈依存で人間の判断が必要な場面 実現キーワード : コピー&ペースト、社内Wiki参照、ドキュメント手動選択 実は、ChatGPTやClaudeにファイルをアップロードして質問するのも、広義ではマニュアルRAGの一種と言えます。言葉が異なるだけで、概念的にはRAGを触っている機会は多いのかもしれません。 手法の分類まとめ 手法の全体像 手法選択の比較表 手法 情報の特性 データ規模 初期コスト 運用負荷 精度安定性 ベクトル検索 意味的類似 大規模対応 高 中〜高 高 BM25 完全一致 大規模対応 中 低〜中 高 ハイブリッド 両方 大規模対応 高 高 最高 Web検索 リアルタイム 外部依存 低 低 外部依存 GraphRAG 関係性 中規模向き 高 高 ユースケース依存 SQL検索 構造化データ 大規模対応 中（既存活用） 低〜中 高 マニュアルRAG 文脈依存 小規模のみ 低 高（人的） 人依存 まとめ 本記事では、RAGの本質と外部情報の取り込み方について整理しました。 RAGは単一の技術ではなく、LLMの回答精度を向上させるための概念です。 論文でも2024年以降は「パラダイム」「フレームワーク」として扱われています。 RAGの目的は「要求される回答精度の達成」です。 手法はあくまで目的達成のための手段であり、ベクトル検索は選択肢の一つに過ぎません。 ただし、ベクトル検索が有効なケースが多いのも事実です。 大規模データで意味的な検索が必要な場面では、ベクトル検索やハイブリッド検索が有効であり、多くのRAGシステムで採用されています。それが唯一の選択肢ではない、ということです。 手法選択は戦略的判断です。 精度要件、コスト、スケール、運用負荷を考慮し、ユースケースに応じて最適な取り込み方を選びましょう。 RAG導入をご検討の方へ 弊社では、RAGを活用したソリューションを提供しています。 社内ナレッジ活用AIチャット導入サービス : お客様のAzure環境に弊社RAGプロダクトを構築します。導入だけでなく、導入後の精度改善の支援や、利用普及に向けた支援などトータル的にサポートを行います。 RAGスターターパック : RAGプロダクトをスピーディーに導入します。、チャットUI＋回答精度の評価・改善のためのオールインワン基盤をご提供しています。導入後はお客様側で自由なカスタマイズを実地いただけます。とりあえず試してみたい！という方にお勧めです。 「RAGを導入したい」「どの手法を選べばいいかわからない」「RAGの精度が出ない」といったお悩みがあれば、お気軽にご相談ください。 参考文献 Lewis, P., et al. (2020). “Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks.” arXiv:2005.11401. https://arxiv.org/abs/2005.11401 Gao, Y., et al. (2024). “Retrieval-Augmented Generation for Large Language Models: A Survey.” arXiv:2312.10997. https://arxiv.org/abs/2312.10997 Gao, Y., et al. (2024). “Modular RAG: Transforming RAG Systems into LEGO-like Reconfigurable Frameworks.” arXiv:2407.21059. https://arxiv.org/abs/2407.21059 関連記事 RAGはどのように進化しているのか？ ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post ベクトル検索以外のRAG手法7選｜比較表付き解説 first appeared on SIOS Tech Lab .

Claude Codeのサブエージェントを「Opusで計画、Sonnetで実行」の構成で最適化。バックグラウンド並列実行とドキュメント出力で、トークン節約と時間効率を両立する実践的な設計手法を解説します。 はじめに ども！GitHub CopilotとClaude Codeの間で反復横跳びしつつ、夜はしっぽりClaude Codeにすり寄っている龍ちゃんです。 前回・前々回と、Claude Codeのトークン消費を抑える話をしてきました。 Claude Code MCP が遅い・重い問題、CLI + Skills で解決 Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善 でも、まだトークン消費が気になる場面があるんですよね。特に サブエージェント を使うとき。 そういえばサブエージェントについて、しっかり調べて設計を考えたことがなかったなと反省しまして。今回は サブエージェントの最適構成 について話していきます。 結論から言うと ： 計画はOpus、実行はSonnet がベスト バックグラウンド実行 で待ち時間ゼロ ドキュメント出力 で非同期でも結果を取得 これ、調べたらClaude Code公式も推奨していて、内部でも実際そうなっているらしいんですよね。 なぜ Opus + Sonnet 構成なのか Opus は最高（お気持ち表明） 正直に言います。 Opusと話すのがめちゃくちゃ楽しい んですよ。 Sonnetだと、自分の意図を正確に理解してもらうのに労力が必要だったんですよね。でもOpusは雑なプロンプトでも意図を察してくれるし、「こういうことですか？」って確認を取ってくれる。 Claude Codeの利用制限（5時間制限、Sonnet制限など）を意識するようになって、トークンを馬鹿食いしている箇所を調べるようになりました。そこで気づいたんです。 全部Opusでやる必要はない ってことに。 Sonnet のポジション 公式のモデル比較 を見てみましょう。 モデル 入力 ($/M tokens) 出力 ($/M tokens) SWE-bench Opus 4.5 $5 $25 80.9% Sonnet 4.5 $3 $15 77.2% Haiku 4.5 $1 $5 73.3% SWE-benchで見ると、Opus 80.9%に対してSonnet 77.2%。 差は3.7ポイント しかないんですよね。実行系タスクには十分な性能です。 数ヶ月前はSonnetをずっと使っていたので、Sonnetでも十分なのは体感としてわかっていました。 実際、モデルの組み合わせについては外部の分析でも言及されています。 “Mixing models works best. Switching between models depending on task type made workflows faster and safer. Haiku for setup, Sonnet for builds, Opus for reviews — that combo just works.” — Claude Haiku 4.5 Deep Dive 公式も推奨している Claude Codeには opusplan というモデル設定があります。 The opusplan model alias provides an automated hybrid approach: In plan mode – Uses opus for complex reasoning and architecture decisions In execution mode – Automatically switches to sonnet for code generation and implementation — Claude Code Model Configuration つまり、 計画時はOpus、実行時はSonnet に自動で切り替わるモードです。公式がこの構成を推奨しているってことですね。 さらに、 Anthropicのマルチエージェント研究 によると： 指標 結果 単一Opus比でのパフォーマンス向上 90.2% 並列化による時間削減 最大90% A multi-agent system with Claude Opus 4 as the lead agent and Claude Sonnet 4 subagents outperformed single-agent Claude Opus 4 by 90.2% on their internal research eval. — Multi-Agent Research System Opus + Sonnetの組み合わせは、単一Opusより性能が高い 。これ、めっちゃ重要な知見ですよね。 サブエージェントとは Claude Codeの Task tool を使うと、 サブエージェント にタスクを委譲できます。 特徴 ： 独立したコンテキストウィンドウ ：メイン会話とは別のコンテキストで動く モデル指定が可能 ： model: sonnet や model: haiku を指定できる ビルトインエージェント ： Explore （コードベース探索）、 Plan （設計計画）などが用意されている エージェント定義の例 （ 公式ドキュメント より）： --- name: code-reviewer description: Reviews code for quality and best practices tools: [Read, Glob, Grep] model: sonnet # sonnet, opus, haiku, inherit から選択 permissionMode: acceptEdits # ファイル書き込みを自動許可 --- model: sonnet を指定するだけで、そのエージェントはSonnetで動きます。簡単ですね。 バックグラウンド実行のメリット サブエージェントの設計を考えていて気づいたんですが、 タスクを分割するとバックグラウンドで実行できる んですよね。 待ち時間ゼロ フォアグラウンドで実行すると、その処理をずっと占有してしまいます。レビュー待ちの間、ただ待っているのはもったいない。 バックグラウンドで実行すると： サブエージェントを起動したら すぐ次の作業へ レビュー待ちの間に コードを書ける 完了したら 自動で通知 が届く 並列実行 複数のエージェントを同時に起動できます。 メイン会話 (Opus) ├─→ technical-accuracy-reviewer (Sonnet) [バックグラウンド] ├─→ content-reviewer (Sonnet) [バックグラウンド] └─→ seo-reviewer (Sonnet) [バックグラウンド] 3つのレビューを並列で回せば、時間効率が大幅に向上します。 制約を理解する ただし、 バックグラウンド実行には制約があります 。 項目 フォアグラウンド バックグラウンド 権限プロンプト 都度確認 事前に一括取得 MCPツール ✅ 使用可 ❌ 使用不可 AskUserQuestion ✅ 可能 ❌ 失敗（継続はする） WebSearch/WebFetch ✅ 使用可 ✅ 使用可 Background subagents run concurrently while you continue working. Before launching, Claude Code prompts for any tool permissions the subagent will need, ensuring it has the necessary approvals upfront. — Create custom subagents MCPツールが使えない のは注意ポイントです。MCP使う系のサブエージェントはフォアグラウンドで動かすしかありません。 ただ、リポジトリ内の作業やレビューは MCP不要で実現可能 です。WebSearchやWebFetchはバックグラウンドでも使えるので、外部情報の取得も問題ありません。 ドキュメントベースの進捗管理 フォアグラウンドのいいところは、 進捗がすぐわかる ことですよね。バックグラウンドだとどうするか？ 解決策：ドキュメントベースで結果を吐き出させる なぜファイル出力が良いのか バックグラウンドだと会話に直接返せない 応答に書いてもらうとコピペが面倒 コンパクト（要約）すると参照できなくなる レビュー系は議論になることもあるので、 ドキュメント出力が重要 僕もClaude Codeと「俺はこう考えてるんだけど」みたいな議論をよくするんですが、そういうときにドキュメントがあると便利なんですよね。 出力形式の設計 僕が使っているレビューエージェントでは、こんな形式で出力しています。 --- type: review agent: content-reviewer model: sonnet target: docs/article/xxx/article.md timestamp: 2026-02-02T14:45:00+09:00 status: completed scores: content_quality: 82 --- ポイント ： YAMLフロントマター でメタデータを構造化 タイムスタンプ付きファイル名 で競合回避（ content-2026-02-02T1445.md ） 機械的に抽出可能 ：スコアなど取得したい情報をプログラムで取り出せる Git管理 できる（履歴が残る） 実践：レビューエージェントを作る 実際に僕が使っているブログレビューエージェントの構成を紹介します。 エージェント定義 .claude/agents/content-reviewer.md : --- name: content-reviewer description: 技術ブログ記事のコンテンツ品質を評価します。結果はファイル出力します。 tools: [Read, WebSearch, WebFetch, Write] model: sonnet permissionMode: acceptEdits --- # Content Reviewer Agent あなたは技術ブログ記事のコンテンツ品質を専門的に評価するエージェントです。 ## 出力形式 レビュー結果は以下の形式でファイルに出力してください： 1. **出力先**: `{対象ファイルのディレクトリ}/review/` 2. **ファイル名**: `content-{YYYY-MM-DDTHHMM}.md` 3. **ディレクトリ作成**: `review/` ディレクトリがない場合は作成 **重要**: 会話への直接出力ではなく、必ずファイルに書き出してください。 ポイント ： model: sonnet でSonnetを指定 permissionMode: acceptEdits でファイル書き込みを自動許可 tools: [Read, WebSearch, WebFetch, Write] で必要なツールを指定 出力先を明確に指示 （これがないとファイル出力してくれない） 3エージェント構成 僕は以下の3つのエージェントを並列で動かしています。 エージェント 役割 出力ファイル technical-accuracy-reviewer 技術的正確性チェック technical-accuracy-*.md content-reviewer コンテンツ品質評価 content-*.md seo-reviewer SEO最適化、タイトル生成 seo-*.md それぞれが独立して評価し、ファイルに結果を出力します。 実践：並列レビューの実行 実行方法 Task toolで3エージェントを明示的に「 バックグラウンド 」と「 並列実行 」を記入して起動します。 3つのレビューエージェントをバックグラウンドで並列実行して： - technical-accuracy-reviewer - content-reviewer - seo-reviewer 対象: docs/article/rag-retrieval-methods/article.md 実際の結果 僕が検証したときの結果です。 エージェント スコア 出力ファイル technical-accuracy-reviewer 88/100 technical-accuracy-2026-02-02T1500.md content-reviewer 82/100 content-2026-02-02T1445.md seo-reviewer 78/100 seo-2026-02-02T1500.md 確認できた動作 ： ✅ 3エージェントが同時にバックグラウンドで起動 ✅ メイン会話はブロックされず、他作業が可能 ✅ 各エージェントが独立して完了し、結果ファイルが review/ に出力 ✅ 完了通知が自動的に届き、結果サマリーが表示 ✅ WebSearch/WebFetchがバックグラウンドでも正常動作 完了順序 は、エージェントのタスク内容（Web検索量など）によって変わります。僕の検証ではseo-reviewerが最初に完了し、technical-accuracy-reviewerが最後でした。 注意点とベストプラクティス バックグラウンドが適さないケース 対話的フィードバックが必要 ：AskUserQuestionが使えないので、ユーザー確認が必要なタスクには向かない MCPツールが必要 ：Notion連携、Slack連携など エージェント設計のコツ 出力形式を明確に指示 「ファイルに出力して」だけでは不十分 出力先、ファイル名形式、ディレクトリ作成の指示まで書く ディレクトリ作成も指示に含める review/ ディレクトリがない場合に作成する指示を入れる Web検索の範囲を限定 毎回同じ検索をさせない（ 前回記事 参照） 静的情報は docs/references/ に保存しておく 最近面白いと思ったコンテンツ tmuxでClaude Codeを複数セッション使う手法が面白いですね。 こちらの記事 が参考になります。「中間管理職」的な使い方、めちゃくちゃ面白いなと思って見てます。というかClaude Codeとの会話が面白すぎるのに、ゴリゴリの技術記事ってのが素敵というかずるい。 セッションを使い捨てにする運用も、バックグラウンド実行の考え方に近いですよね。 まとめ この記事では、 サブエージェントの最適構成 について共有しました。 構成のポイント 役割 モデル 実行方式 思考・対話・計画 Opus フォアグラウンド 実行・サブタスク Sonnet バックグラウンド 軽量タスク Haiku バックグラウンド キーメッセージ Opus は最高 だけど、全部Opusでやる必要はない Sonnet で十分 な実行系タスクはSonnetに任せる バックグラウンド で待ち時間をゼロに ドキュメント出力 で非同期でも結果を取得 結果として トークン節約 と 時間効率 の両方を実現 前回からの流れ MCP → CLI+Skills（トークン削減） 静的情報活用（さらなるトークン削減） 今回 → Opus+Sonnet構成（時間効率＋トークン分散） Opusともっと長く話したいから、簡単な作業はSonnetに依頼しようぜ、という結論になりました。 ここまで読んでいただき、ありがとうございました！ 参考リンク 公式ドキュメント Claude Models Overview Claude Code Model Configuration Create custom subagents Anthropic Engineering Blog Multi-Agent Research System Claude Code Best Practices 関連記事 Claude Code MCP が遅い・重い問題、CLI + Skills で解決 MCP接続の不安定さやトークン消費に悩んでいませんか？CLI + Skillsへの段階的移行でトークン65%削減を実現した実践ガイド。 Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善 Skills/Agentsの実行が遅い原因は毎回の同じWeb検索かも。静的情報活用でトークン節約・高速化・結果安定化を実現する手法。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Code サブエージェントの最適構成：Opus で考え、Sonnet で動かす first appeared on SIOS Tech Lab .

はじめに こんにちは、サイオステクノロジーの小野です。Kubernetesのマルチクラスター管理ツールであるRancherにはHelmリポジトリを登録して、そのリポジトリ内のHelmアプリケーションをGUI上で確認できる機能があります。 今回は ChartMuseum というツールでローカル環境にHelmリポジトリを構築し、それをRancherに登録する手順について解説します。 前提条件 今回構築した前提条件は以下になります： OSはUbuntuを使用  Rancher構築済み 構築方法は過去の記事を参考にしてください Rancher入門：Rancher Serverの構築 ChartMuseumはHelmで構築 ローカルに直接インストールやDockerでの構築がありますが、今回はHelmでRancherのクラスター上に構築します Storage Class作成済み ChartMuseumは様々なクラウドストレージを指定できますが、今回はStorage ClassによるPVを利用します ChartMuseum構築手順 ChartMuseum用のNamespaceを作成します。 $ kubectl create namespace chartmuseum ChartMuseumのドメイン（今回はchartmuseum.internal）を設定して、その証明書を作成します。DNSサーバーの設定も同時に行ってください。 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout chartmuseum.key \ -out chartmuseum.crt \ -subj "/CN=chartmuseum.internal" \ -addext "subjectAltName=DNS:chartmuseum.internal" 作成した証明書をシークレットとして登録します。 $ kubectl create secret tls chartmuseum-tls-secret \ --cert=chartmuseum.crt \ --key=chartmuseum.key \ -n chartmuseum ChartMuseum自体のHelmチャートリポジトリを追加します。 $ helm repo add chartmuseum https://chartmuseum.github.io/charts $ helm repo update Valuesファイルを作成します。今回は以下のように設定しました。それ以外はデフォルトでよいです。 persistence: enabled: true accessMode: ReadWriteOnce size: 10Gi storageClass: <ストレージクラス名> # PVを作成できるStorage Classを指定 env: open: DISABLE_API: false STORAGE: local STORAGE_LOCAL_ROOTDIR: /storage CHART_URL: https://chartmuseum.internal ingress: enabled: true className: nginx # RKE2での構築のためIngress Controllerをnginxに指定。 annotations: kubernetes.io/ingress.class: nginx hosts: - name: chartmuseum.internal # 設定したいドメイン名 path: / tls: true tlsSecret: chartmuseum-tls-secret tls: - secretName: chartmuseum-tls-secret hosts: - chartmuseum.internal 作成したvalues.yamlを使用してHelmインストールします。 $ helm install chartmuseum chartmuseum/chartmuseum -f values.yaml -n chartmuseum Chartmuseumが作成されたことを確認します。 ChartMuseumのHelmインストール確認 RancherへHelmリポジトリを登録する方法 ChartMuseumを作成できたので、早速Rancherに登録してみます。RancherUIのApps > Repositoriesを開いてください。Createを押下して、以下のように設定します： Target：http(s) URL to an index generated by Helm Index URL：https://chartmuseum.internal Helmリポジトリの登録設定 設定後、証明書エラーが出るので右の三点リーダーメニューから「Edit YAML」を選択してください。その後、spec.caBundleにCA証明書の情報を入力してください。 証明書エラーが出るので注意 Helmリポジトリの証明書の設定方法。caBundleにCA証明書の内容を記載する。 設定後、Activeになれば登録完了です。 Activeになれば登録完了   Helmリポジトリにチャートを保存してみる RancherにHelmリポジトリを登録することができたので、Helmリポジトリに試しにチャートを保存して、UIで確認してみたいと思います。 検証用のチャートを作成します。 $ mkdir chart-test && cd chart-test $ helm create my-test-chart パッケージ化してChartMuseumに保存します。 $ helm package my-test-chart $ curl -k --data-binary "@my-test-chart-0.1.0.tgz" https://chartmuseum.internal/api/charts {"saved":true} RancherUIからRepositriesを開いて、メニューからRefreshを押下することでリポジトリを更新します。 メニューからRefreshを押下する RancherUIのApps > Chartsを見ると保存したチャートが確認できます。 Apps > Chartを開くと保存したHelmチャートが確認できる 保存したHelmチャートを開くと詳細情報が確認できる せっかくなので、バージョンアップさせて、questions.yamlを追加してみます。questions.yamlとはHelmのvalues.yamlを、Rancher上でGUI（入力フォーム）に変換するための定義ファイルです。これをChartに組み込むことで、YAML編集やvalues.yamlファイルの直接適用しなくても、ブラウザのRancherUIから設定を変更することが可能になります。（参考： https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps ） 検証用のチャートのChart.yamlを編集して、バージョンをあげます。 apiVersion: v2 name: my-test-chart description: A Helm chart for Kubernetes # A chart can be either an 'application' or a 'library' chart. # # Application charts are a collection of templates that can be packaged into versioned archives # to be deployed. # # Library charts provide useful utilities or functions for the chart developer. They're included as # a dependency of application charts to inject those utilities and functions into the rendering # pipeline. Library charts do not define any templates and therefore cannot be deployed. type: application # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. # Versions are expected to follow Semantic Versioning (https://semver.org/) version: 0.2.0 # ここのバージョンをあげる # This is the version number of the application being deployed. This version number should be # incremented each time you make changes to the application. Versions are not expected to # follow Semantic Versioning. They should reflect the version the application is using. # It is recommended to use it with quotes. appVersion: "1.16.0" 以下のquestions.yamlをvalues.yamlやChart.yamlと同じ階層に作成します。 categories: - Test questions: - variable: replicaCount default: "1" type: int label: Replica Count group: "Global Settings" description: "デプロイするポッドの数を選択してください" - variable: service.type default: "ClusterIP" type: enum label: Service Type group: "Network Settings" options: - "ClusterIP" - "NodePort" - "LoadBalancer" $ ls my-test-chart Chart.yaml charts questions.yaml templates values.yaml 作成できたら、パッケージ化してChartMuseumに保存します。 $ helm package my-test-chart $ curl -k --data-binary "@my-test-chart-0.2.0.tgz" https://chartmuseum.internal/api/charts {"saved":true} RancherUIからリポジトリを更新して、チャートを開くとバージョンが上がっていることが確認できます。 バージョンアップしていることが確認できる Installからインストール手順を進めると、questions.yamlを適用したおかげでvalues.yamlのパラメータをGUI上で設定できるようになっています。 questions.yamlのおかげでUI上から設定が可能になっている 終わりに 今回はHelmリポジトリを構築して、Rancherに登録するまでの手順を解説しました。 インターネットに接続できない環境でHelmリポジトリを自作するといったことや、自作のコンテナアプリを管理したいといったことはよくあることだと思います。 みなさんもHelmリポジトリを作成して、Rancherで管理してみてください。   参考 Rancher入門：Rancher Serverの構築 ChartMuseum公式サイト ChartMuseum Helm Chart Rancher公式ドキュメント：Manage Repositories Rancher公式ドキュメント：questions.yml     ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post ChartMuseum × Rancher：ローカルHelmリポジトリの構築とUI連携 first appeared on SIOS Tech Lab .

GitHub Copilot Agent Skillsとは何か、基本を解説。SKILL.mdの書き方、ディレクトリ構造、Claude Code互換性まで実用例付きで学べる入門ガイド。 はじめに ども！GitHub Copilotのブログを連日お届けしている龍ちゃんです。最近ブログを書きすぎて導入文のスタックがなくなってきちゃいました。 以前「 GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術 」という記事を書きましたが、そこでは補足として軽めに紹介していた「 Agent Skills 」について詳しく解説していきます。 「テスト書いて」と言うだけでプロジェクト固有のテストパターンに従う、そんな「専門家の自動召喚」を実現する新機能です。 本記事では Agent Skills の基本的な使い方と書き方を解説します。 検証環境 検証日: 2026年2月2日 環境: VS Code 1.108以降 + GitHub Copilot 参考: VS Code Docs – Agent Skills Agent Skills とは 特定タスクに関連性があると判断されたら 自動で読み込まれる 「専門家パック」 Claude Codeを使っている方は、Claude Code Skillsをそのまま想像してもらえればOKです！ 他の設定ファイルとの違い Agent Skills の最大の特徴は、 スクリプトやリソースを同梱できる 点です。 特徴 Agent Skills 他の設定ファイル 発火条件 自然言語で自動 常時/glob/手動 スクリプト同梱 ✅ 可能 ❌ 不可 リソース同梱 ✅ 可能 ❌ 不可 これまでの設定ファイル（ copilot-instructions.md 、 *.instructions.md 、 *.prompt.md 、 *.agent.md 、 AGENTS.md ）は、すべて「指示」だけを書くファイルでした。Agent Skills は、指示に加えて スクリプトやテンプレートも一緒に管理 できます。 イメージ Agent Skills = 「専門家が道具持参で自動登場」 「テスト書いて」→ テスト専門家が登場（テンプレート持参） 「ブログ取得して」→ スクレイピング専門家が登場（スクリプト持参） 「HTMLを画像に」→ 画像変換専門家が登場（変換スクリプト持参） GitHub Copilotの設定ファイルでいうと、 instructions + Custom Agents + AGENTS.md を組み合わせたようなイメージですね。 ディレクトリ構造 Agent Skills には2種類の保存場所があります。 保存場所 種類 パス 用途 プロジェクトスキル .github/skills/ 単一リポジトリ専用 個人スキル ~/.copilot/skills/ 複数プロジェクト共有 補足 : .claude/skills/ も下位互換としてサポートされますが、 .github/skills/ が推奨です。 基本構造 .github/skills/ └── {skill-name}/ # スキル名（小文字、ハイフン区切り、最大64文字） ├── SKILL.md # 必須：スキル定義 ├── scripts/ # オプション：ヘルパースクリプト ├── references/ # オプション：参照ドキュメント ├── examples/ # オプション：実装例 └── assets/ # オプション：テンプレート、図 各フォルダの役割 フォルダ 用途 scripts/ ヘルパースクリプト、自動化ツール references/ 参照ドキュメント、API仕様 examples/ 実装例、サンプルコード assets/ テンプレート、アーキテクチャ図 これらのフォルダはすべてオプションです。シンプルなスキルなら SKILL.md だけで十分動作します。 SKILL.md の書き方 SKILL.md は YAML フロントマター + Markdown 本文 で構成されます。 基本テンプレート --- name: skill-name description: | スキルの説明。いつ使うべきかを明記。 「テスト書いて」「カバレッジ追加」などで発火。 --- # スキル名 ## When to Use - 発火条件1 - 発火条件2 ## Quick Start 1. ステップ1 2. ステップ2 ## References - [詳細ドキュメント](./references/detail.md) 重要なフィールド フィールド 必須 制限 説明 name ✅ 最大64文字 スキル識別子（小文字、ハイフン区切り） description ✅ 最大1024文字 発火判定に使われる （重要！） license ❌ – ライセンス情報 ポイント : description は Copilot がスキルを読み込むかどうかを判断する材料になります。「いつ使うべきか」を具体的に書くことが大切です。 実用例：ユニットテスト生成スキル 具体的なスキルの例を見てみましょう。 ディレクトリ構造 .github/skills/unit-testing/ ├── SKILL.md └── templates/ └── test-template.ts SKILL.md --- name: unit-testing description: | ユニットテストを作成する。 「テスト書いて」「テスト追加」「カバレッジ」で発火。 --- # Unit Testing ## When to Use - 新しいテストを追加するとき - カバレッジを向上させたいとき ## Quick Start 1. テスト対象のファイルを開く 2. 「テスト書いて」と依頼 ## Guidelines - Arrange-Act-Assert パターンを使用 - テストファイル名は `{対象}.test.ts` - モックは最小限に ## Templates - [テストテンプレート](./templates/test-template.ts) 発火例 ユーザー: 「この関数のテスト書いて」 → unit-testing スキルが自動で読み込まれる → テンプレートと Guidelines に従ってテスト生成 スキルが発火すると、Copilot は SKILL.md の内容をコンテキストに読み込み、指示に従ってコードを生成します。 templates/ 内のファイルも参照可能になるので、プロジェクト固有のテストパターンを適用できます。 Claude Code Skills との互換性 Agent Skills は、Claude Code Skills と 同じ形式 を採用しています。これは偶然ではなく、Anthropic がオープンスタンダードとして公開した仕様に基づいているためです。 共通点 項目 Claude Code GitHub Copilot 定義ファイル SKILL.md SKILL.md （同一） ディレクトリ .claude/skills/ .github/skills/ スクリプト同梱 ✅ ✅ 移行方法 基本的にはコピーするだけで動きます。 cp -r .claude/skills/* .github/skills/ 注意点 移行時に気をつけるポイントがあります。 allowed-tools フィールドは削除（Copilot では実験的機能） 発火しない場合は description の調整が必要 龍ちゃん 実際に Claude Code で使用していた Skills をそのまま移行してみた結果、 うまく発火しない 問題に遭遇しました。原因は 発火メカニズムの違い （RAG vs 内部ルーティング）にあります。 分析と対策も書きました。「 Agent Skillsが動かない？Claude移行の落とし穴と対処法 」 発火しない場合の簡易対処法 スキルが発火しない場合、以下の方法で強制的に呼び出せます。 方法1: チャットで明示的に指定 「blog-scraper スキルを使用してブログを取得して」 方法2: copilot-instructions.md にルーティングを追加 ## Agent Skills Routing | キーワード | スキル | パス | |-----------|--------|------| | ブログ取得 | blog-scraper | `.github/skills/blog-scraper/SKILL.md` | 根本的な設計からの改善が必要な場合は、別記事「 Agent Skillsが動かない？Claude移行の落とし穴と対処法 」で詳しく解説しています。 発火の確認方法 スキルが正しく読み込まれたか確認するには、以下の方法があります。 チャットで確認 : 「どのスキルが読み込まれていますか？」と質問 チャット履歴 : VS Code の Copilot Chat History から使用されたスキルを確認 まとめ Agent Skills のポイントを整理します。 観点 内容 位置づけ GitHub Copilot の 新しいカスタマイズ機能 特徴 自然言語で自動発火、 スクリプト・テンプレート同梱 互換性 Claude Code Skills と 同一形式 次のステップ まずはシンプルなスキルを1つ作ってみる description に「いつ使うか」を具体的に書く 発火しない場合は description の調整を試す 他の設定ファイルと合わせて Agent Skills を活用することで、GitHub Copilot をより強力なコーディングパートナーにできます。 参考リンク 公式ドキュメント VS Code Docs – Agent Skills GitHub Docs – About Agent Skills GitHub Changelog – Agent Skills リリース 公式リポジトリ github/awesome-copilot – スキル例、ベストプラクティス anthropics/skills – オープンスタンダード仕様 関連記事 GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術 Claude Code→GitHub Copilot移行で使える設定ファイル6つの対応表 ここまで読んでいただき、ありがとうございました！ Agent Skills を活用して、GitHub Copilot をプロジェクトに合わせてカスタマイズしてみてください。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post 【2026年版】Agent Skills 入門：SKILL.md の基本から実践まで first appeared on SIOS Tech Lab .

Claude CodeのSkillsがCopilotで発火しない・読み込まれない原因は発火メカニズムの違い。description強化、トークン予算、Instructionsルーティングで解決。 はじめに ども！GitHub Copilotが徐々に育ってきて、ニコニコな龍ちゃんです。1月後半から2月にかけてGitHub Copilot関連のブログが多めに出ています。ブログが出ているということは育っている証拠ですね。 今回は、前回紹介していた Agent Skills の話題です。「 網羅5種ブログ 」と「 Claude Code→GitHub Copilot移行 」では補足として触れていた Agent Skills を、 Claude Code から実際に移植した という部分にフォーカスしていきます。 「Claude Code で使っていた Skills をそのまま GitHub Copilot に移植したら、まったく発火しない…」 同じ SKILL.md 形式なのに、なぜ動かないのか？本記事では、 発火しない根本原因と3つの解決策 を解説します。 検証環境 検証日: 2026年2月2日 環境: VS Code 1.108以降 + GitHub Copilot 参考: VS Code Docs – Agent Skills 前提：Agent Skills の基本 Agent Skills の基本（ディレクトリ構造、SKILL.md の書き方）は「 【2026年版】Agent Skills 入門：SKILL.md の基本から実践まで 」を参照してください。 本記事では「 発火しない 」問題と解決策に特化します。 発火しない原因：Claude Code との根本的な違い 結論から言うと、 Claude Code と GitHub Copilot ではスキルの発火メカニズムが根本的に異なります 。 注 : 以下は4つのスキルを実際に移植した際の動作検証から分析した内容です。公式ドキュメントで詳細が公開されていない部分は推測を含みます。 決定的 vs 確率的 観点 Claude Code GitHub Copilot スキル把握 全スキルを起動時に把握 relevance に基づき選択的に読み込み 判断方式 全情報を元に内部判断（情報完全） 確率的な判定（事前フィルタリングあり） description の役割 発火判定に使用（全メタデータ把握後に判断） 発火判定に使用（事前フィルタリングで判断） GitHub Copilot も Claude Code も、Agent Skills には「 Progressive Disclosure 」という設計思想を採用しています。全スキルを事前に読み込むのではなく、関連度に基づいて必要なスキルのみを読み込む仕組みです。 違いは「どの段階で絞り込むか」にあります。 Claude Code は全スキルを把握した上で内部判断で選択 するのに対し、 Copilot は事前に絞り込んでから選択 するため、description の書き方次第で「漏れ」が発生するのです。 注 : GitHub 公式では関連度スコアリングの詳細な実装方法は公開されていません。本記事の説明は動作検証からの推測を含みます。 【コラム】Claude Code の Progressive Disclosure Claude Code も Progressive Disclosure を採用していますが、その実装方法が異なります。 メタデータ把握 : 全スキルの Name + Description を起動時に把握 本体読み込み : 発火時に SKILL.md 本体を読み込み 参照ファイル : 必要に応じて references/ を参照 重要な違い : Claude Code は「全スキルのメタデータを把握した上で選択」するため、description が多少雑でも適切なスキルを選べます。一方 Copilot は「事前フィルタリング後に選択」するため、description の書き方次第で「漏れ」が発生します。 参考: Anthropic Engineering Blog – Agent Skills description の設計思想が違う ここが核心です。 Claude Code では「何をするか」をベースで書けばOKです。 description: ブログ記事をスクレイピングしてMarkdownに変換 内部ルーティングが賢いので、この程度の説明でも意図を理解してくれます。 GitHub Copilot では「スキルの機能と発火条件の両方」を書く必要があります。公式ガイドラインでは「describe BOTH what the skill does AND when to use it」と明記されています。 description: | ブログ記事をスクレイピングしてMarkdownに変換するスキル。 Use when: ブログを取得したい、記事を保存したい、tech-lab.sios.jp の内容を取得したい。 Triggers on: scrape blog, fetch article, ブログ取得, 記事取得. 関連度スコアリングではユーザーが実際に使う言葉を埋め込まないとスコアが上がりません。 核心の一文 : Claude Code と同じ感覚で作ると発火しない。「技術的な説明」ではなく「ユーザーの発話」を埋め込む必要がある。 雑に作ると動かない理由 まとめると、こういうことです。 項目 Claude Code GitHub Copilot 設定の厳密さ 雑でも動く 厳密に作る必要あり トークン予算 気にしなくてOK 500トークン以下推奨 （上限5,000トークン） 結果 – 同等の機能を実現可能 （作法に従えば） Claude Code のノリで雑にぶち込むと動きません。ただし、 作法に従って厳密に作れば、Claude Code と同等の機能を実現できます 。 公式が推奨するベストプラクティスに盲目的に従う必要はないですが、一度は目を通しておいたほうがよい！という感じですね。 Microsoftが公開しているリポジトリに含まれている GitHub Copilot Agent Skills のガイドラインです 。 補足 : 比較のために大げさに書いていますが、Claude Code の Skills もちゃんと設計したほうが良いです！ 解決策①：description を強化する 落とし穴：「英語で書くべき」Tips が逆効果になる場合 よく「システムプロンプトは英語で書くべき」というTipsがありますよね。GitHub Copilot Agent Skills では、 これが逆効果になる可能性があります 。 Copilot の関連度判定は 文字列の類似度 で判断していると推測されます。ユーザーの発話と description の言葉が近いほどスコアが上がります。日本語でプロンプトを書くユーザーには、 日本語の発火キーワード が必要になります。英語だけで書くと、日本語クエリとの類似度が低くなり、発火しにくくなります。 結論 : description には 日本語・英語両方 の発火キーワードを列挙しましょう。 推奨フォーマット description: | [機能の簡潔な説明（何をするスキルか）]. Use when: [どんな時に使うか（ユーザーの意図）]. Triggers on: [発火キーワード（日本語・英語）]. Before / After Before（発火しない） : description: HTMLをPlaywrightでレンダリングしてPNG画像に変換 After（発火する） : description: | HTMLファイルをPlaywrightでレンダリングしてPNG画像に変換するスキル。 Use when: HTMLを画像化したい、スクリーンショットを撮りたい。 Triggers on: HTMLをPNGに変換, HTML to PNG, 画像に変換, HTMLを画像に, screenshot HTML, HTMLをキャプチャ. ポイントは「技術的に何をするか」ではなく、「 ユーザーがどう言うか 」を想像して書くことです。 解決策②：トークン予算を守る Copilot はトークン効率を重視する設計です。SKILL.md が長すぎると、そもそも読み込まれない可能性があります。 ファイル 推奨 上限 SKILL.md 500トークン以下 （約60行目安） 5,000トークン references/*.md 1,000トークン 2,000トークン 分割パターン 長くなりそうな場合は、詳細を references/ に分割しましょう。 .github/skills/my-skill/ ├── SKILL.md # 概要 + Quick Start（〜60行） └── references/ ├── commands.md # コマンド詳細 └── troubleshooting.md SKILL.md は「ルーター役」に徹して、詳細は必要な時だけ読み込まれるようにします。 解決策③：Instructions ルーティング（力技） 正直、関連度スコアリングは不安定です。description を強化しても、発火したりしなかったりすることがあります。 そこで最終手段として、 copilot-instructions.md に明示的なルーティングテーブルを追加 する方法があります。 ## Agent Skills Routing | キーワード | スキル | パス | |----------------------------------------|--------------|----------------------------------------| | ブログスクレイピング, tech-lab.sios.jp | blog-scraper | `.github/skills/blog-scraper/SKILL.md` | | フローチャート, 図 | html-diagram | `.github/skills/html-diagram/SKILL.md` | なぜ有効か Instructions は 常に読み込まれる 関連度スコアリングを バイパス できる 発火が 安定 する デメリット（トレードオフ） 力技ゆえのデメリットも認識しておきましょう。 保守性の低下 : スキルを追加・変更するたびにルーティングテーブルの更新が必要 スケーラビリティ : スキル数が増えると Instructions ファイルが肥大化 本来の設計思想から外れる : Progressive Disclosure の恩恵を受けられない 結論 : 確実に発火させたい重要なスキル（3〜5個程度）に限定して使うのがおすすめです。 検証結果：4スキルで発火確認 実際に Claude Code から移植した4つのスキルで検証しました。 スキル プロンプト 結果 発火経路 blog-scraper tech-lab.sios.jp + 取得して ✅ Instructions html-diagram HTMLで図化して ✅ Instructions copilot-chat-converter Markdownに変換して ✅ Instructions html-to-png 連携呼び出し ✅ スキル内 結論 : Instructions ルーティングテーブルで全スキル安定発火しました。 検証に使用したスキルの概要 : スキル 概要 関連記事 blog-scraper ブログ記事をMarkdown形式で保存 HTML→Markdown変換 html-diagram Tailwind CSSで図解を自動生成 HTML図解自動生成 copilot-chat-converter Chat履歴JSONをMarkdownに変換 – html-to-png HTMLをPNG画像に変換 html-diagramと連携 移植チェックリスト Claude Code Skills → GitHub Copilot への移植手順をまとめました。 - [ ] `.claude/skills/` → `.github/skills/` にコピー - [ ] `allowed-tools` を削除（Copilot では実験的機能） - [ ] description に `Use when` / `Triggers on` を追加 - [ ] ユーザー発話を日本語・英語で列挙 - [ ] SKILL.md を 500トークン以下（約60行目安）に削減 - [ ] `copilot-instructions.md` にルーティングテーブル追加（重要スキルのみ） - [ ] VS Code リロード後、5〜10分待機 - [ ] 発火テスト このチェックリストに従えば、Claude Code で作ったスキルを GitHub Copilot でも活用できます。 まとめ Agent Skills が発火しない問題と解決策を整理しました。 ポイント 内容 原因 Claude Code（全スキル把握）と GitHub Copilot（事前フィルタリング）で仕組みが違う description 「何をするか」+「 いつ使うか（Use when / Triggers on） 」の両方を書く 解決策 ① description 強化 ② トークン予算 ③ Instructions ルーティング（力技） 結論 作法に従って厳密に作れば、Claude Code と同等の機能を実現可能 発火しない場合は、本記事の3つの解決策を順番に試してみてください。特に Instructions ルーティングは確実性が高いのでおすすめです。 参考リンク 公式ドキュメント VS Code Docs – Agent Skills GitHub Docs – About Agent Skills GitHub Changelog – Agent Skills リリース 公式リポジトリ github/awesome-copilot – ベストプラクティス Microsoft GitHub-Copilot-for-Azure – Agent Skills 実装例 anthropics/claude-cookbooks – Skills – Progressive Disclosure 関連記事 GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術 Claude Code→GitHub Copilot移行で使える設定ファイル6つの対応表 【2026年版】Agent Skills 入門：SKILL.md の基本から実践まで ここまで読んでいただき、ありがとうございました！ Agent Skills の発火問題で困っている方の参考になれば幸いです。Claude Code から移行する方は、ぜひ移植チェックリストを活用してください。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？原因と解決策 first appeared on SIOS Tech Lab .

はじめに ども！GitHub Copilot の設定に対して徐々に理解が進んでいる龍ちゃんです。 これまでの記事で、 AGENTS.md と Custom Agents の違い と、 copilot-instructions.md の分割設計 について解説してきました。 で、ここまで読んでくれた方は気づいたかもしれません。 AGENTS.md と copilot-instructions.md、書く内容かぶってない？ と。 機能的には両者が近い機能を持っているように感じています。発火条件も近いですしね。 んでよ！どっちのファイルも同じタイミングで読み込まれるなって話になってしまいまして迷子になりました。そりゃ、「AGENTS.md」は参照されるだけで、GitHub Copilot がメインでメンテナンスしているものではないですからね。 というわけで、今回はそれぞれの設定ファイルの公開されている「設定すべき情報」から共生させる方法について考えた内容に関して触れていこうと思います。それぞれのファイルの設定すべき内容にも触れるので、AGENTS・instructions どちらかしか使ってねえ！って方でもそれぞれのファイルで設定すべき内容について触れるから安心してね。 ぶっちゃけ前提 プロジェクト上、とんでもなく特殊な事情がない限り どっちかに寄せたい ！だってメンテナンスとか、どっちのファイルに何書くとか考えるのめんどくさいもん！ なんでこれはチーム向けの記事だと思って読み物で。特殊な状況になった皆さんにお疲れさまと、もしもっといい方法があるってわかったら連絡くださいってお気持ちを置いときます。 検証環境 検証日: 2026年1月30日 環境: VS Code + Dev Container GitHub Copilot: 2026年1月時点の機能 複数ファイルの読み込み動作 まず、Copilot Coding Agent がどのファイルを読み込むのかを整理します。 ポイント : 競合ではなくマージ される 矛盾する指示があった場合の優先順位は 公式未定義 → 矛盾を避ける設計が必要 全部読み込んでマージされるってことは、同じことを両方に書いたら重複するし、矛盾したら何が優先されるかわからないってことです。 公式が推奨する記載内容 両ファイルにどのような内容を書くべきか、公式が推奨している内容を整理します。 copilot-instructions.md の公式推奨（5セクション） 出典: 5 tips for writing better custom instructions for Copilot – GitHub Blog セクション 英語名 書くべき内容 プロジェクト概要 Project Overview アプリの目的、対象ユーザー、主要機能 テックスタック Tech Stack Backend/Frontend/Testing のフレームワーク、API コーディングガイドライン Coding Guidelines 言語ルール（セミコロン、型ヒント等）、セキュリティ慣行 プロジェクト構造 Project Structure フォルダ構成と各ディレクトリの用途 リソース Resources 開発スクリプト、MCPサーバー、自動化ツール 制約 : 2ページ以内 AGENTS.md の公式推奨（6セクション） 出典: How to write a great agents.md – GitHub Blog セクション 英語名 書くべき内容 コマンド Commands ビルド、テスト、リントの実行コマンド（フラグ含む） テスト Testing テストフレームワーク、実行方法 プロジェクト構造 Project Structure ディレクトリ構成の説明 コードスタイル Code Style Good/Bad のコード例、命名規則 Gitワークフロー Git Workflow コミット慣行、ブランチ戦略 境界線 Boundaries Always / Ask First / Never ベストプラクティス : コマンドを先頭に配置、説明より具体例を重視 公式推奨の重複に注目 両方の公式推奨を見比べると、 重複する項目 があることがわかります。 項目 copilot-instructions.md AGENTS.md プロジェクト構造 ○ ○ テスト ○（Tech Stack内） ○ コードスタイル ○（Coding Guidelines） ○ 公式は「What vs How」の分離を明示的に推奨していません。 これはおそらく以下の理由によるものです： 単独利用を想定 : どちらか一方だけ使う場合でも完結するように クロスツール互換 : AGENTS.md は他のAIツールでも使うため、Copilot固有の情報に依存しない 次のセクションで紹介する「What vs How 分離」は、 両方を併用する場合に重複・矛盾を避けるための筆者独自の設計指針 として提案するものです。 役割分担の原則: What vs How【筆者独自の提案】 注意 : 以下は公式推奨ではなく、両ファイル併用時の重複・矛盾を避けるための筆者独自の設計指針です。 両方使うなら、役割分担が必要です。僕が考えた分離の基準は「 What vs How 」です。 観点 copilot-instructions.md AGENTS.md 責務 What （何をするか） How （どうやるか） 内容 方針・規約・制約 手順・コマンド・境界線 更新頻度 低（安定したルール） 中〜高（手順は変わりやすい） 適用範囲 Copilot 全機能 Coding Agent 中心 なぜこの分離が有効か copilot-instructions.md は .github/ ディレクトリにあって、機能変更とは別にコミットされることが多いです。レビュー時も「設定変更」として独立して見られます。 一方、AGENTS.md は各ディレクトリに配置できるので、そのディレクトリのファイル変更と一緒にレビューされやすい。つまり「手順」の変更は実装と一緒に更新されるイメージです。 What（方針） は変わりにくい → copilot-instructions.md How（手順） は変わりやすい → AGENTS.md 変更頻度でファイルを分けると管理しやすい 何をどこに書くか【具体例】 copilot-instructions.md に書く内容（What） ## コードスタイル - TypeScript strict mode を使用 - 関数は camelCase、コンポーネントは PascalCase - any 型の使用禁止 ## アーキテクチャ - Clean Architecture に従う - ビジネスロジックは domain/ に配置 - 外部依存は infrastructure/ に隔離 ## 使用ライブラリ - 状態管理: Zustand（Redux は使わない） - フォーム: React Hook Form + Zod - テスト: Vitest + Testing Library 特徴 : 「どうあるべきか」を記述 AGENTS.md に書く内容（How） ## コマンド npm ci # 依存インストール npm run dev # 開発サーバー起動 npm test # テスト実行 npm run lint:fix # リント自動修正 ## 境界線 ### Always Do - テストを書いてから実装（TDD） - 変更したファイルに対応するテストを更新 ### Ask First - 新しいnpmパッケージの追加 - 既存のAPI契約（型定義）の変更 ### Never Do - .env ファイルをコミットしない - console.log を本番コードに残さない 特徴 : 「どうやるか」を記述 同じことを両方に書かない 悪い例（重複） # copilot-instructions.md TypeScriptのstrictモードを使用してください。 テストはVitestで書いてください。 `npm test` でテストを実行します。 ← 手順がここにある # AGENTS.md TypeScriptのstrictモードを使用してください。 ← 重複 テストはVitestで書いてください。 ← 重複 npm test # テスト実行 問題点 : 同じ内容が2箇所に。片方だけ更新すると矛盾が発生。 良い例（分担） # copilot-instructions.md TypeScriptのstrictモードを使用してください。 テストはVitestで書いてください。 ← コマンドは書かない # AGENTS.md ## コマンド npm test # テスト実行 npm run test:watch # ウォッチモード ← 方針は書かない メリット : 責務が明確、更新箇所が1箇所、矛盾が発生しない どっちに書くか迷ったら 新しい指示を追加するとき、どっちに書くか迷ったら 2つの質問 で判断してください。 Q1. Chat や Code Review でも使いたい？ No → AGENTS.md に書く（Coding Agent 専用でOK） Yes → Q2 へ Q2. 「方針」か「手順」か？ 方針 （〜すべき、〜を使う、〜は禁止） → copilot-instructions.md 手順 （コマンド、境界線、具体的な操作） → AGENTS.md シンプルに言うと： こんな内容なら 配置先 「TypeScript strict mode を使う」 copilot-instructions.md npm test で実行 AGENTS.md 「Redux は使わない」 copilot-instructions.md 「.env をコミットしない」（Never Do） AGENTS.md *.instructions.md との組み合わせ 前回記事で紹介した *.instructions.md も含めると、3層構造になります。 copilot-instructions.md # 全体の方針（What） ├── *.instructions.md # ファイル別の詳細ルール（What の詳細） └── AGENTS.md # 手順・コマンド・境界線（How） 内容 配置先 「TypeScript strict mode を使用」 copilot-instructions.md 「React コンポーネントは forwardRef 必須」 frontend-ui.instructions.md 「 npm run lint:fix でリント修正」 AGENTS.md まとめ ファイル 役割 キーワード copilot-instructions.md What（何をするか） 方針・規約・制約 AGENTS.md How（どうやるか） 手順・コマンド・境界線 *.instructions.md What の詳細 ファイル別ルール 複数ファイルは マージ されて読み込まれる 公式推奨には重複があるが、両方使うなら 役割分担 が必要 What と How で分離するのが筆者のおすすめ ただし、特殊な事情がなければ どっちかに寄せる のが一番楽 参考リンク 公式ドキュメント Adding custom instructions for GitHub Copilot – GitHub Docs 5 tips for writing better custom instructions for Copilot – GitHub Blog How to write a great agents.md – GitHub Blog 関連記事 AGENTS.md vs Custom Agents【5つの比較表で混乱解消】 copilot-instructions.md を分割したい？applyTo パターンで解決 ここまで読んでいただき、ありがとうございました！ 正直、両方メンテするのはしんどいので、可能なら片方に寄せてください。でも「Claude Code も使ってるから AGENTS.md は残したい」みたいな状況になったら、この記事を思い出してもらえると嬉しいです。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post copilot-instructions.md と AGENTS.md、どっちに何を書く？【公式推奨と使い分け】 first appeared on SIOS Tech Lab .

はじめに ども！GitHub Copilot の設定ファイルを夜な夜なこねくり回している龍ちゃんです。Claude Code での経験があるので、この「こねる作業」が後々の開発体験につながると信じて頑張っております。 今回は、GitHub Copilot の「 Custom Agents 」と「 AGENTS.md 」という2つの似た名前の機能について解説します。 正直に言うと、僕も最初は混乱していました。というか同じ機能だと思っていました。「agents」で検索しても情報が混在していて、AIに聞いても誤認されることがあります（ChatGPT、Gemini、Perplexity で実際に試しました）。 そんな方のために、この記事では両者の違いを明確にし、どのように使い分けるべきかを説明します。 前回の記事（設定5種を網羅） では概要レベルで触れましたが、今回はその深掘り版です。 検証環境 検証日: 2026年1月30日 環境: VS Code + Dev Container GitHub Copilot: 2026年1月時点の機能 結論（先出し） 最初に結論をお伝えします。 名前 正体 Custom Agents GitHub Copilot 専用の フェーズ別作業空間 AGENTS.md クロスツール互換 のオープンフォーマット 名前が似ているだけで、全く別物です。 Custom Agents とは 基本情報 項目 内容 配置場所 .github/agents/*.agent.md 用途 設計/実装/レビューなどフェーズ別に切り替え 呼び出し ドロップダウンから 手動選択 対応 GitHub Copilot 専用 注 : 拡張子は .agent.md が公式推奨です。内部的には .md も認識されますが、明示的に .agent.md を使用してください。 特徴 セッションを通じて有効（単発ではない） 独立したコンテキストで作業 YAML Frontmatter で tools / description を定義 僕は Custom Agents を「 人格設定 」だと思っています。設計者、実装者、レビュアーなどの人格を切り替えて使うイメージですね。 使用例 --- name: design-reviewer description: 設計レビュー専門 tools: ["read", "search"] --- あなたは設計レビューの専門家です。 アーキテクチャの整合性をチェックしてください。 AGENTS.md とは 基本情報 項目 内容 配置場所 リポジトリルート or サブディレクトリ 用途 AI エージェント向けの README 読み込み Coding Agent 実行時に 自動 対応 主要なAIコーディングツール 対応ツール一覧 AGENTS.md は GitHub Copilot だけのものではありません。以下のツールで共通して使えます。 GitHub Copilot Coding Agent Claude Code（CLAUDE.md も読む） OpenAI Codex Google Jules / Gemini CLI Cursor, VS Code, Zed, Warp Aider, Devin, Factory, RooCode など 管理団体 Linux Foundation / Agentic AI Foundation が管理 オープンフォーマットとして標準化 6万以上のOSSプロジェクトで採用 対応ファイル名 ファイル名 対象ツール AGENTS.md 標準（全ツール共通） CLAUDE.md Claude Code GEMINI.md Gemini CLI 注意 : Copilot Coding Agent は すべて読み込んでマージ します。 正直、すべて読むのはやめてほしいですね。複数の AI サービスを導入しているプロジェクトでは、意図しない指示が混ざる可能性があるので気をつけてください。 何を書くべきか 公式ブログ では、以下の6セクションが推奨されています。 セクション 内容 コマンド ビルド、テスト、リントの実行方法 テスト フレームワーク、書き方のルール プロジェクト構造 ディレクトリ構成の説明 コードスタイル 命名規則、良い例/悪い例 Gitワークフロー ブランチ命名、コミットメッセージ 境界線 Always / Ask First / Never の3層 特に「 境界線 」が重要です。AI が勝手にやってはいけないこと（Never Do）を明示しておくと、破壊的な操作を防げます。 詳細は公式ブログを参照してください。 比較表 項目 Custom Agents AGENTS.md 配置場所 .github/agents/ リポジトリ任意 適用方法 手動選択 自動読み込み 互換性 Copilot専用 クロスツール ネスト 不可 可能（近い方優先） 用途 フェーズ別ペルソナ プロジェクト指示 管理 GitHub Linux Foundation AGENTS.md はリポジトリ単位での配置なので、Claude Code の CLAUDE.md みたいな運用ができますね。 AGENTS.md の配置と優先順位 ネスト可能 AGENTS.md はサブディレクトリにも配置できます。 repo/ ├── AGENTS.md # リポジトリ全体 ├── packages/ │ └── frontend/ │ └── AGENTS.md # frontend 固有（こちらが優先） 優先順位 AGENTS.md 公式サイト によると、 近い方が優先 されます。 編集対象ファイルに最も近い AGENTS.md 親ディレクトリの AGENTS.md リポジトリルートの AGENTS.md “the nearest file in the directory tree takes precedence, creating a hierarchical configuration system” — agents.md 注意 : VS Code Issue #271489 で、ネストされた AGENTS.md が無視されるバグが報告されています。理論上は近い方優先ですが、環境によっては動作が異なる可能性があります。これからのアップデート情報は注視していかないといけないです。 どちらを使うべきか 新しい指示を追加したい │ ├─ フェーズ別に切り替えたい？ │ └─ Yes → Custom Agents │ ├─ 他のAIツールでも使いたい？ │ └─ Yes → AGENTS.md │ └─ Copilot専用でOK、自動適用したい └─ AGENTS.md（または copilot-instructions.md） ポイント : Custom Agents : 設計モード、実装モード、レビューモードなど「モードの切り替え」に使う AGENTS.md : プロジェクト固有の指示（コマンド、テスト方法、境界線など）を書く よくある誤解 誤解 実際 AGENTS.md は Custom Agents の設定ファイル 別物 。AGENTS.md はクロスツール互換フォーマット Custom Agents は AGENTS.md を読み込む Custom Agents は 独立したペルソナ定義 AGENTS.md は GitHub Copilot 専用 主要なAIコーディングツール で共通利用可能 まとめ 項目 Custom Agents AGENTS.md 一言で言うと フェーズ別の人格設定 AI向けREADME 対応ツール Copilot専用 主要ツール対応（クロスツール） 適用方法 手動選択 自動読み込み Custom Agents : フェーズ別の作業空間（Copilot専用、手動選択） AGENTS.md : AI向けREADME（クロスツール、自動読み込み） 名前が似ているが 全く別の概念 目的に応じて使い分け、 両方併用も可能 参考リンク 公式ドキュメント GitHub Docs – Custom Agents Configuration AGENTS.md Official Site GitHub Blog – How to write a great agents.md GitHub Changelog – AGENTS.md Support 関連記事 GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術 ここまで読んでいただき、ありがとうございました！ 「agents」という単語で混乱していた方の助けになれば幸いです。両者の違いを理解して、適切に使い分けてください。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 1人がこの投稿は役に立ったと言っています。 The post AGENTS.md vs Custom Agents【5つの比較表で混乱解消】2026年版 first appeared on SIOS Tech Lab .

はじめに ども！GitHub Copilotの設定ファイルの設計にいそしんでいる龍ちゃんです。 前回の記事 では、GitHub Copilotの設定ファイル5種類を整理しました。今回はその中でも特に重要な「Instructions ファイル」の設計にフォーカスします。 まだInstructionsを使っていない方へ ：いきなり設計から入る必要はありません。まずは copilot-instructions.md に思いつくルールをどんどん書いていけばOKです。使っていくうちに「あれも追加したい、これも追加したい」となって、気づいたら肥大化している…というのは自然な流れです。 本記事は、 その肥大化に直面したときに読む記事 です。現在筆者が検証中の分割パターンを共有しますので、参考にしてみてください。「もっとこうしたほうが良いよ」というフィードバックも大歓迎です！ 検証環境 検証日: 2026年1月30日 環境: VS Code + Dev Container GitHub Copilot: 2026年1月時点の機能 *.instructions.md とは copilot-instructions.md が肥大化してきたとき、救世主となるのが *.instructions.md です。 配置場所 : .github/instructions/ このディレクトリに配置したMarkdownファイルは、 applyTo で指定したパターンにマッチするファイルを編集するときだけ 自動適用 されます。 観点 copilot-instructions.md *.instructions.md 適用範囲 全ファイル 特定ファイルのみ 条件指定 なし applyTo で指定 用途 全体ルール 言語・ディレクトリ別ルール 「全員に適用するルール」と「特定のファイルにだけ適用するルール」を分けられるわけです。 押さえておくべきポイント *.instructions.md を使う前に、知っておくべき挙動が3つあります。 applyTo の基本 ファイルの先頭にYAML形式で applyTo を指定します。 --- applyTo: - "**/*.ts" - "**/*.tsx" --- # TypeScript コーディング規約 - strict mode を使用 - any 型の使用禁止 - ... グロブパターンで指定するので、 **/*.py （全ディレクトリのPythonファイル）や src/frontend/**/* （特定ディレクトリ配下すべて）といった柔軟な指定が可能です。複数パターンを指定した場合は、 いずれかにマッチすれば適用 されます。 複数ファイルはマージされる ここが重要なポイントです。複数の Instructions がマッチした場合、 競合ではなく結合 されます。 編集対象: src/components/ui/Button.tsx マッチする Instructions: ├── frontend-common.instructions.md (applyTo: src/**/*.tsx) ├── frontend-ui.instructions.md (applyTo: src/components/ui/**/*.tsx) └── frontend-types.instructions.md (applyTo: **/*.ts, **/*.tsx) → 3つすべてマージされて適用 「上書き」ではなく「結合」です。つまり、3つのファイルに書かれたルールがすべて有効になります。 矛盾を避ける設計が必須 マージされるなら、矛盾するルールを書いたらどうなるの？という疑問が浮かびます。 調べたところ「 わかりません 」、でした。公式ドキュメントにルールが記載されていませんでした。（もし見つけたら教えてください） GitHubのコミュニティでも議論されていますが、現時点で優先順位のルールは公開されていません。 Discussion #162201 : 選択的ロードは未サポート Issue #12878 : 設定に関係なく全ファイルが読み込まれる 結論 : 矛盾しない設計が唯一の解決策です。 具体的には： 各 Instructions は独立した関心事を扱う （UIルール、APIルール、テストルールなど） 重複するルールを書かない （同じことを複数ファイルに書かない） 「優先順位でなんとかする」という発想は捨てて、そもそも矛盾が起きない設計を心がけましょう。 分割パターン では、実際にどう分割すればいいのか。2つのパターンを紹介します。 基本形: 言語別 最もシンプルで始めやすいパターンです。 .github/instructions/ ├── python.instructions.md # applyTo: **/*.py ├── typescript.instructions.md # applyTo: **/*.ts, **/*.tsx └── markdown.instructions.md # applyTo: **/*.md 言語ごとに固有のルール（命名規則、型ヒントの書き方、フォーマットなど）を分離できます。複数言語を扱うプロジェクトでは、この基本形から始めるのがおすすめです。 筆者が採用しているパターン（ミックス系） 筆者は現在、モノレポ構成のプロジェクトで「ディレクトリ別 + 関心事別」のミックスパターンを検証しています。 設計のポイント : ディレクトリ単位で大まかな責務分担 （frontend / tools など） 関心事別にさらに細かくルールを分割 （UI / API / 状態管理など） 別ディレクトリではノイズとなる情報を分離 copilot-instructions.md（おおもと） おおもとの copilot-instructions.md は ルーター役 に徹します。 # Project Overview Monorepo with multiple applications. | Path | Stack | |-----------------------|--------------| | application/tools/ | Python 3.12+ | | application/frontend/ | Next.js 15 | ## Path-scoped Instructions アプリケーション固有のルールは `.github/instructions/` で定義。 モノレポ構成であることを伝え、詳細は分割ファイルに任せます。共通禁止事項（ .env をコミットしないなど）もここに書きますが、それ以外は軽量に保ちます。 Instructions ファイル（application 単位 + 関心事別） .github/instructions/ ├── python-tools.instructions.md # application/tools/**/* ├── frontend-common.instructions.md # application/frontend/**/* ├── frontend-ui.instructions.md # .../components/ui/**/* ├── frontend-api.instructions.md # .../generated/**/* ├── frontend-store.instructions.md # .../store/**/* └── frontend-feature.instructions.md # .../features/**/* frontend-common.instructions.md にはフロントエンド全体のルール（技術スタック、コードスタイル、命名規則）を書き、 frontend-ui.instructions.md には shadcn/ui 専用のルール（ npx shadcn@latest add で追加、CVA でバリアント定義など）を書く、という具合です。 このパターンのメリット メリット 説明 おおもとが軽量 肥大化問題を根本解決 独立したルールセット application ごとに分離 精度向上 必要な指示だけが適用される チーム分担しやすい FEチーム / Python チームで管理を分けられる Python を触っているときに Next.js のルールがノイズになる、といった問題も解消します。 まとめ *.instructions.md を活用した分割設計のポイントをまとめます。 ポイント 内容 条件付き適用 applyTo でマッチしたファイル編集時のみ自動適用 マージ動作 複数マッチ時は結合される（矛盾に注意） 優先順位 公式には未定義 → 矛盾しない設計が必須 分割の始め方 言語別から始めて、必要に応じてミックスへ おおもとの役割 ルーターに徹し、軽量に保つ まずは使ってみて、肥大化を感じたら分割を検討する。そのときに本記事を思い出していただければ幸いです。 参考リンク 公式ドキュメント Adding custom instructions for GitHub Copilot GitHub Issues / Discussions Discussion #162201 – 選択的ロードは未サポート Issue #12878 – 全ファイルが読み込まれる問題 関連記事 GitHub Copilot設定5種を網羅！生産性を最大化する使い分け術 ここまで読んでいただき、ありがとうございました！ Instructions も設計対象です。肥大化を感じたら、ぜひ分割設計を試してみてください。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post copilot-instructions.md を分割したい？applyTo パターンで解決 first appeared on SIOS Tech Lab .

はじめに PSSLの佐々木です JAXAが面白いものを公開しました。 JAXA Earth API の MCPサーバー対応 です。 MCP（Model Context Protocol）とは、AIアシスタントが外部ツールと連携するための仕組みです。これにより、Claude Desktopから「富士山の植生を見せて」と話しかけるだけで、実際の衛星データを取得できるようになりました。 今回はこれらのデータを利用して地球を感じてみようと思います。 本記事を作成するにあたり技術的な環境構築にはぴっかりん様のブログを参考に環境を作らせていただきました。 https://zenn.dev/ra0kley/articles/cb2fc726f167da JAXA Earth API MCP の設定方法 このブログで使用した画像は、すべてClaude Desktop + JAXA MCPサーバーで取得しています。Windows WSL Claude Desktopで環境構築をする際の参考にしていただければと思います。 環境 Claude Desktop uv（Pythonパッケージマネージャー） WSL2（Windows環境の場合） セットアップ手順 プロジェクト作成 uv init jaxa-earth-mcp cd jaxa-earth-mcp ライブラリインストール uv add jaxa-earth --extra-index-url <https://data.earth.jaxa.jp/api/python/repository/> uv add mcp mcp_server.py を配置（公式ドキュメントからダウンロード） claude_desktop_config.json を編集 { "mcpServers": { "jaxa_api_tools": { "command": "wsl", "args": [ "bash", "-c", "cd /path/to/jaxa-earth-mcp && /home/user/.local/bin/uv run --with mcp --with jaxa-earth --extra-index-url <https://data.earth.jaxa.jp/api/python/repository/> mcp_server.py" ] } } } Claude Desktop を再起動 使用例 富士山周辺（緯度35.3、経度138.7、半径30km）の植生指数（NDVI）を 2025年7月のデータで表示して。画像サイズは小さめで。 第1章 富士山の四季 日本人なら誰もが知る富士山。標高3,776m、日本最高峰です。 この山を、宇宙から1年を通して眺めてみました。使用したのは「植生指数（NDVI）」というデータです。植物の活性度を表す指標で、値が高いほど緑が豊かであることを示しています。 1月（冬） 冬の富士山周辺です。青〜緑の領域が多くなっています。植物は休眠し、山頂付近は雪に覆われています。 4月（春）   春の訪れです。徐々に黄色〜オレンジの領域が増えてきています。裾野から緑が芽吹き始めています。 7月（夏）   夏です。オレンジ〜赤の領域が広がっています。富士山の森林限界より下は、生命力に満ちた緑で覆われています。 10月（秋） 秋です。まだ緑は残っていますが、徐々に活性度が下がり始めています。紅葉の季節、そして冬への準備が始まっています。 4枚を並べてみると、富士山が「呼吸」しているのがわかります。 宇宙から見ても、日本には確かに四季があります。当たり前のことですが、衛星データで可視化されると不思議な感動があります。 第2章 ナイル川の恵み 場所を変えて、エジプトへ向かいます。 古代ギリシャの歴史家ヘロドトスは、エジプトを「ナイルの賜物」と呼びました。砂漠の国エジプトが文明を築けたのは、ナイル川がもたらす水と肥沃な土壌のおかげです。 5000年前の人々が見上げた空には、人工衛星などありませんでした。でも今、私たちは宇宙からその恵みを確認できます。 砂漠の茶色の中に、ナイル川沿いだけが燃えるように赤くなっています。 赤は植生指数が高い、つまり緑が豊かな場所です。左下の青は地中海です。 この「赤い部分」こそが、古代エジプト人が「ナイルの賜物」と呼んだ恵みの正体です。宇宙から見ると、人類が数千年かけて作り上げた農地が、砂漠に浮かぶオアシスのように見えます。 第3章 桜島の熱 次は、地球が「生きている」ことを感じる場所へ向かいます。 鹿児島県の桜島。年間数百回の噴火を繰り返す、日本で最も活発な火山の一つです。 今度は「地表面温度」のデータを使います。衛星「しきさい」が捉えた、地面の温度です。 グラフの右側にある凡例を見てください。単位は「Kelvin（ケルビン）」で、約284〜290Kの範囲が表示されています（摂氏に換算すると約11〜17℃）。 画像の中で、周囲より温度が高い部分（黄色〜赤）が見えます。これが桜島周辺の地熱の影響です。海（青い部分）と比べると、陸地、特に火山周辺の温度が高いことがわかります。 火山の熱が、宇宙からも見えるのです。 地球は約46億年前に生まれ、今もその内部は熱を持っています。マグマが地表近くに上がってくる場所、それが火山です。 桜島の熱は、地球が今も「生きている」証拠です。私たちは、巨大な熱源の上で暮らしています。 第4章 黒潮を追う 海に目を向けましょう。 黒潮。日本近海を流れる世界最大級の暖流です。古来、漁師たちはこの黒潮を追いかけ、豊かな漁場を求めました。 「海面水温」のデータを見てみます。 グラフの右側の凡例を見てください。単位は「degreeC（摂氏）」で、約20〜24℃の範囲が表示されています。 画像を見ると、南側（下）が赤く、北側（上）が青くなっています。これが黒潮の影響です。南から暖かい海水が流れ込み、北に向かうにつれて徐々に冷たくなっていく様子がわかります。赤とオレンジの境界線あたりが、まさに黒潮の流れている場所です。 暖かい海水が赤く、冷たい海水が青く表示されています。 黒潮は、フィリピン沖から日本列島に沿って北上します。この暖流が日本の気候を温暖にし、豊かな漁場を生み出しています。 1000年前の漁師も、この同じ海流を追いかけていました。彼らは経験と勘で黒潮を読んでいました。今、私たちは宇宙からその流れを俯瞰できます。 技術は変わっても、海は変わりません。いや、変わりつつあるのかもしれません。 第5章 北極からの警告 最後に、地球の「今」を見つめる場所へ向かいます。 北極海。地球上で最も気候変動の影響を受けている場所の一つです。 「海氷密接度」のデータです。海面がどれだけ氷で覆われているかを示しています。 グラフの右側の凡例を見てください。単位は「%」で、0〜100%の範囲が表示されています。これは海面がどれだけ氷で覆われているかの割合です。 画像を見ると、北極点に近い中央部分が白〜ピンク（80〜100%）で、ほぼ完全に氷で覆われています。一方、周辺部に向かうにつれて青くなり、氷が少ない（または無い）海域が広がっています。特に画像の左下や右下の青い部分は、氷が溶けて海水が露出している場所です。 白い部分が氷、青い部分が海水です。 北極の氷は、過去数十年で確実に減少しています。それは数字としては知っていました。でも、衛星データとして「見る」と、また違った実感があります。 地球は確実に変化しています。その変化を、人工衛星は静かに記録し続けています。 おわりに JAXAのMCPサーバーを使って、地球を巡る旅をしてみました。 富士山の四季 ナイル川の恵み 桜島の鼓動 黒潮の流れ 北極の氷 すべて、宇宙から見た地球の「表情」です。 人工衛星という人類の目が、24時間365日、地球を見守っています。そのデータが、今やAIアシスタントへの一言で取得できます。 「富士山の緑を見せて」 たったこれだけで、宇宙からの視点を借りられる時代になりました。 地球は美しい。そして、儚い。 だからこそ、見続けることに意味があるのです。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post JAXA MCPで地球を感じる first appeared on SIOS Tech Lab .

PSSLの佐々木です LLMアプリを作ろうとすると、LangChain、LlamaIndex、Semantic Kernel…と様々なフレームワークが出てきます。「結局どれを使えばいいの？」と迷ってしまうことはありませんか？ 例えばPythonでRAGアプリを作ろうとGoogle検索すると、LangChainのサンプル、LlamaIndexのサンプル、素のSDKで書いてる記事…と情報が錯綜していて混乱します。とほほ。。 この記事では、各LLMフレームワークの種類とその特徴、そして「どんな時に使うべきか」を明確にします。 主要なLLMフレームワークの種類 1. 素のSDK（OpenAI SDK / Anthropic SDK など） 例： openai 、 anthropic 、 google-generativeai 各LLMプロバイダーが提供する公式SDKを直接使用するアプローチです。 from openai import OpenAI client = OpenAI() response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Hello!"}] ) print(response.choices[0].message.content) 特徴： 余計な抽象化がなく、何が起きているか把握しやすい プロバイダーの新機能をすぐに使える 依存関係が少なく、バージョン問題に悩まされない デバッグが容易 注意点： リトライ処理やエラーハンドリングを自前実装する必要がある プロバイダー切り替え時はコード全体の書き換えが必要 RAGなどの実装は一から書く必要がある エージェント対応： 各社のFunction Calling / Tool Useを直接利用 自由度は高いが、すべて自前実装が必要 評価エコシステム： 特になし（自前で構築するか、外部ツールと組み合わせる） こんな時に選ぶべき： シンプルなチャットボットを作りたい プロトタイプを素早く作りたい フレームワークの挙動を完全にコントロールしたい 学習目的でLLMの仕組みを理解したい 2. LangChain 例： langchain 、 langchain-openai 、 langgraph 最も人気のあるLLMフレームワークです。「何でもできる」汎用性が売りです。 from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate llm = ChatOpenAI(model="gpt-4o") prompt = ChatPromptTemplate.from_messages([ ("system", "You are a helpful assistant."), ("user", "{input}") ]) chain = prompt | llm response = chain.invoke({"input": "Hello!"}) 特徴： エコシステムが巨大で、連携ツールやサンプルコードが豊富 LLMプロバイダーの切り替えが容易 コミュニティが活発で、困ったときに情報が見つかりやすい 注意点： 過度な抽象化でシンプルなことも複雑になりがち 破壊的変更が多く、バージョンアップで動かなくなることがある 学習コストが高い（Chain、Agent、Toolなどの概念理解が必要） 抽象化の層が深く、デバッグが困難 エージェント対応： LangGraphによる本格的なエージェント構築が可能 ツール定義、マルチエージェント、ワークフロー制御など充実 エージェント周りは最も成熟している 評価エコシステム： LangSmithによるトレーシング・評価が強力 プロンプトのバージョン管理、A/Bテストなども可能 有料だが、本番運用には非常に便利 こんな時に選ぶべき： 複数のツールやAPIを組み合わせたエージェントを作りたい 様々なLLMプロバイダーを切り替えながら使いたい 豊富なサンプルコードを参考にしながら開発したい LangSmithで評価・監視まで一気通貫でやりたい 3. LlamaIndex 例： llama-index 、 llama-index-core RAG（Retrieval-Augmented Generation）に特化したフレームワークです。データの取り込みから検索、回答生成まで一貫してサポートします。 from llama_index.core import VectorStoreIndex, SimpleDirectoryReader # ドキュメント読み込み → インデックス作成 → クエリ documents = SimpleDirectoryReader("data").load_data() index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine() response = query_engine.query("このドキュメントの要約は？") 特徴： RAG構築が圧倒的に簡単（数行で完成） 多様なデータソース対応（PDF、Notion、Slack、DBなど100以上） 検索手法が豊富（ベクトル検索、キーワード検索、ハイブリッドなど） LangChainより学習コストが低い 注意点： RAG以外の用途には弱い 独自の検索ロジックを入れづらい場合がある LangChainに比べて情報が少なめ エージェント対応： LlamaIndex Workflowsでエージェント構築が可能 RAGと組み合わせたエージェントには強い ただしLangGraphほどの柔軟性はない 評価エコシステム： LlamaCloudでトレーシング・評価が可能 RAGの評価指標（Faithfulness、Relevancyなど）が充実 RAG特化なら十分な機能 こんな時に選ぶべき： 社内ドキュメント検索システムを作りたい PDFやWebページを元に回答するチャットボットを作りたい RAGの精度を追求したい（チャンク戦略、リランキングなど） 4. Semantic Kernel 例： semantic-kernel （Python / C# / Java） Microsoftが開発するエンタープライズ向けフレームワークです。C#がメインですが、PythonやJavaもサポートしています。 import semantic_kernel as sk from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion kernel = sk.Kernel() kernel.add_service(OpenAIChatCompletion( service_id="chat", ai_model_id="gpt-4o" )) # プラグインとして機能を追加 @kernel.function(name="get_weather") def get_weather(location: str) -> str: return f"{location}の天気は晴れです" 特徴： エンタープライズ向け設計（セキュリティ、スケーラビリティ考慮） Azure OpenAI Serviceとの親和性が高い 型安全（特にC#では堅牢な開発が可能） プラグインアーキテクチャで機能の追加・管理が整理されている 注意点： コミュニティがLangChainより小さい Pythonは二番手（C#が最も充実） 日本語の学習リソースが少ない エージェント対応： Agent Frameworkでマルチエージェント構築が可能 プラグインベースで機能拡張しやすい Microsoft Copilot Studioとの連携も視野に入る 評価エコシステム： 単体での評価機能は限定的 Azure AI Studio / Prompt Flowとの組み合わせが前提 Application Insightsでの監視は容易 こんな時に選ぶべき： C#/.NETでLLMアプリを開発したい Azure OpenAI Serviceを使う予定がある エンタープライズ環境で堅牢なシステムを構築したい Microsoft製品（Teams、SharePointなど）と連携したい 5. Azure Prompt Flow 例：Azure AI Studio内のツール、 promptflow CLI/SDK MicrosoftのAzure AI Studioに統合されたワークフロー構築・評価ツールです。GUIとコードの両方で開発できます。 # flow.dag.yaml の例 inputs: question: type: string nodes: - name: llm_call type: llm source: type: code path: llm_call.py inputs: prompt: ${inputs.question} outputs: answer: type: string reference: ${llm_call.output} 特徴： GUIでフローを構築できるビジュアルエディタ プロンプトの品質評価を体系的に実施可能 プロンプトやフローのバージョン管理が容易 Azure MLとの統合で本番デプロイメントがスムーズ 非エンジニアとの協業がしやすい 注意点： Azure環境が前提（ローカル実行も可能だが制限あり） 複雑なロジックはコード側で書く必要がある Azure AI Studioの利用料金が発生 エージェント対応： フロー内でツール呼び出しは可能 ただし複雑なエージェントには向かない Semantic Kernelと組み合わせるのが現実的 評価エコシステム： 評価機能が最も充実している 組み込みの評価指標（Groundedness、Relevance、Coherenceなど） カスタム評価指標も定義可能 バッチ評価、A/Bテストなど本格的なLLMOpsが可能 こんな時に選ぶべき： プロンプトの評価・改善を体系的に行いたい 非エンジニア（PMやドメインエキスパート）と協業したい Azure環境で本番運用する予定がある MLOpsの知見を活かしてLLMOpsを実践したい 比較表：一目でわかるフレームワーク選び 項目 素のSDK LangChain LlamaIndex Semantic Kernel Prompt Flow 学習コスト 低 高 中 中 中 RAG構築 △ 自前実装 ○ ◎ 最強 ○ ○ エージェント △ 自前実装 ◎ LangGraph ○ Workflows ○ Agent Framework △ 評価エコシステム × ◎ LangSmith ○ LlamaCloud △ ◎ 最強 Azure親和性 △ ○ ○ ◎ ◎ コミュニティ – ◎ 最大 ○ △ △ 安定性 ◎ △ 変更多い ○ ○ ○ 本番運用実績 ◎ ○ ○ ○ ○ 実用的な選択フローチャート ステップ1: 主な用途を確認 シンプルなチャット機能 → 素のSDK RAGがメイン → LlamaIndex 複雑なエージェント → LangChain Azure環境で運用 → Semantic Kernel + Prompt Flow ステップ2: エージェント要件を確認 エージェント不要 → ステップ3へ シンプルなツール呼び出し → 素のSDK or LlamaIndex 複雑なマルチエージェント → LangChain（LangGraph） Azureエコシステム内 → Semantic Kernel ステップ3: 評価・運用要件を確認 評価は後回し → 用途に合わせて選択 本格的な評価が必要 → LangSmith or Prompt Flow を併用 Azure統一 → Prompt Flow マルチクラウド → LangSmith 組み合わせパターン 実務では単一のフレームワークだけでなく、組み合わせて使うことも多いです。 パターン1：RAG + 評価 LlamaIndex + Prompt Flow RAGの精度を継続的に改善したい場合に パターン2：エージェント + RAG LangChain（LangGraph）+ LlamaIndex 検索結果を元に行動するエージェントを作りたい場合に パターン3：Azure統一構成 Semantic Kernel + Prompt Flow エンタープライズでAzure縛りがある場合に パターン4：最小構成 素のSDK + 外部評価ツール（Braintrustなど） フレームワーク依存を最小限にしたい場合に まとめ 初心者の方は 素のSDK から始めて、必要に応じてフレームワークを導入するのが現実的なアプローチです。 各フレームワークの選択基準： 素のSDK ：確実に動かしたい時、学習目的 LangChain ：エージェントを本格的に作りたい時、エコシステムを活用したい時 LlamaIndex ：RAGを最短で構築したい時 Semantic Kernel ：Azure + エンタープライズ環境の時 Prompt Flow ：評価・LLMOpsを本格的にやりたい時 プロジェクトの要件と制約を考慮して、最適なフレームワークを選択しましょう。不明な点があれば、まず素のSDKで動作確認してから、段階的にフレームワークを導入することをお勧めします。 またこのほかにもDify、Flowise、Haystack などのフレームワークも存在していますが、基本この5つのどれか（または組み合わせ）を採用しておけばよいと思います。 ではまた ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post LLMフレームワーク結局どれ使う？ first appeared on SIOS Tech Lab .