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.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 .
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 .
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 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 .
はじめに ども!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の設定ファイルの設計にいそしんでいる龍ちゃんです。 前回の記事 では、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 .
はじめに ども!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 .
はじめに 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 .
5秒でわかる:この記事の内容 やったこと : MCPを使って挫折した経験を共有 代替手段としてCLI + Skillsパターンを実践 トークン消費を 65%削減 しつつ、同等の機能を実現 得られるもの : MCPが向いているケース/向いていないケースの判断基準 CLI + Skillsの具体的な実装例(html-screenshot、blog-scraper) 段階的アプローチ「最初はCLI、複雑になったらMCP」 対象読者 : Claude Codeを使って開発している人 MCPを導入したけどイマイチだった人 トークン消費を抑えたい人 関連記事 図解作成が驚くほど楽に!Claude SkillでSVG自動生成 → html-screenshot CLIの実装背景 HTMLでブログ記事を保存してる奴、全員Markdownにしろ。AIが読みにくいでしょうが! → blog-scraper CLIの実装詳細 はじめに ども!仕事量とAIのトークンリミットを見比べながら仕事をしている龍ちゃんです。 最近ちょっとトークン消費を抑えることを考えながら、実装を組み込んだり改善したりといろいろやっています。んで最近MCPを使うシーンでためらいが生まれてきたので、思いのたけを書いていこうと思います。 結論から言うと、 「開発者目線でのMCPって、用途によっては不必要だったんや」 という話です。 MCPって高機能すぎるんですよね。ちょこっとほしい機能のために導入すると、オーバーヘッドがすごい。だったら AIにシンプルなCLIツールを開発させて、Skillで使い方を教え込んだほうが爆速で簡単じゃない? って思うようになりました。 この記事で伝えたいこと : MCPは万能じゃない(用途による) シンプルな用途なら CLI + Skills で十分 最初からMCPを導入するのはオーバーエンジニアリングかも 【2026年1月追記】 この記事で共有する失敗体験は2025年中頃のものです。その後、 Tool Search Tool (トークン消費を最大85%削減)や MCP Apps (会話内でUIをレンダリング)などの改善がありました。詳細は後述の「 【2026年アップデート】Tool Search Tool による改善 」セクションで補足しています。それでも、 シンプルな用途にはCLI + Skillsが適している という本質的な結論は変わっていません。 MCPで実際に起きた問題(実体験) Notion MCP での挫折 Notion MCPを試してみたんですが、正直しんどかったですね。 何が起きたか : 実行待機時間がやたら長い トークン消費量が多い トークンだけ消費して、結果何も得られない ことがある 特に最後のやつがきつかったです。ファイルの特定をするのに、大元から検索して、特定→検索→特定→見つからない…みたいな。これって自分のNotionがAIフレンドリーな設計になっていない問題もあるかもしれないけど、とにかく重い。 やりたいことは新規ページ作成だけ なのに、すんごく重い。 これなら自前でコピペしたほうが早いってなりましたね。 Playwright MCP での挫折 Playwright MCPも試しました。ブラウザ操作をAIにやらせたくて。 何が起きたか : 時間を食って結果何も得られないことがある タイムアウト問題が頻発 サイズ調整がミスって意図していないものが取れる ただスクショを取りたいだけなのに 、待ち時間がストレスでした。すぐほしいのに、MCPの接続やらブラウザ起動やらで待たされる。 正直に言うと、 MCPを経由するメリットが感じられなかった んですよね。 なぜMCPは重いのか(技術的背景) 僕の実体験だけだと「お前の環境が悪いんじゃ」って言われそうなので、技術的な背景も調べてみました。 ツール定義のトークン消費 MCPの一番の問題は、 起動時にツール定義を全部ロード することです。 コミュニティでも報告されている問題として(単一のMCPサーバーの場合): MCPツールの定義だけで 13,000〜18,000トークン を消費 一方、同等の機能をCLIで実現すると 225トークン 程度 つまり 約80倍のトークン差 “Just like a lot of meetings could have been emails, a lot of MCPs could have been CLI invocations” (会議の多くがメールで済んだように、MCPの多くはCLI呼び出しで済んだ) — MCP vs CLI: Benchmarking Tools for Coding Agents これ、めっちゃ刺さる言葉ですよね。 接続の不安定性 Notion MCPやPlaywright MCPのGitHub Issuesを見ると、接続問題の報告がたくさんあります: 認証成功後の再接続失敗 間欠的な接続切断 タイムアウト(Playwrightは5秒で切れる) MCPサーバーが安定していないと、 問題が起きたときに見る先が増える んですよね。自分のコードなのか、MCPサーバーなのか、接続なのか…。これがどうにも困る。 【2026年アップデート】Tool Search Tool による改善 ここまでMCPの問題点を書いてきましたが、 公平を期すために最新情報も共有 しておきます。 2026年1月、Anthropicは「 Tool Search Tool 」という機能をリリースしました。これはMCPの「重い」問題を大幅に緩和するものです。 Tool Search Tool とは 従来のMCPは 起動時にすべてのツール定義をロード していました。Tool Search Tool は、これを 遅延ロード(Lazy Loading) に変更します。 起動時: 軽量な検索インデックスだけをロード 実行時: 必要なツールだけをオンデマンドで取得 効果 Anthropicの公式ベンチマークによると( 50以上のMCPツールを使う環境 で): 指標 従来のMCP Tool Search Tool 起動時トークン 77,000〜134,000 8,700 削減率 – 最大85%削減 これにより、コンテキストの95%を保持できるようになったとのこと。 使い方 Claude Code の設定で有効化できます(2026年1月時点ではデフォルトで有効)。 じゃあMCPでいいじゃん? …と思うかもしれませんが、 僕がCLI + Skillsを推す理由は変わっていません 。 理由: Tool Search Tool でも接続不安定性は解決しない – Notion MCP の認証問題、Playwright MCP のタイムアウトは別問題 デバッグの複雑さは変わらない – 問題が起きたときに見る先が多いのは同じ シンプルな用途にはオーバースペック – 「HTMLをPNGに変換したいだけ」に MCP は依然として重い 結論 : Tool Search Tool は素晴らしい改善ですが、 シンプルな用途にはCLI + Skillsのほうが予測可能で扱いやすい という本質は変わりません。 実際にやりたいことって限定的だった ここで気づいたんですよね。 僕がMCPでやりたかったことって、実はめっちゃ限定的だった ってことに。 Notionでやりたかったこと → 新規ページ作成だけ Playwrightでやりたかったこと → HTMLをPNGに変換するだけ がっつりナレッジを吸い出して管理するとか、複雑なブラウザ操作をするとか、そんな高機能な要件ってそんなにないんですよ。 複雑な要件 vs シンプルな要件 : 要件 向いているアプローチ マルチエージェント調整 MCP 複雑なステート管理 MCP セキュアなアクセス層が必要 MCP データの取得だけ CLI データの追加だけ CLI 単純な変換処理 CLI シンプルな用途にMCPを使うのは、 釘を打つのにブルドーザーを持ってくる みたいなものだったんですよね。 代替案: CLI + Skills という選択肢 アプローチ 僕が採用したアプローチはこれです: ローカルでAIにCLIツールを開発させる Skill / Slash Commandで使い方を教え込む これだけ。めっちゃシンプル。 なぜこれが爆速で簡単か 理由1: トークン消費の違い(80倍差) MCPはツール定義だけで13,000トークン以上消費するけど、CLIなら数百トークンで済みます。 理由2: 起動時ロードなし(SkillsのProgressive Disclosure) Skillsは 必要なときだけ読み込まれる んですよね。MCPみたいに起動時に全部ロードしない。 “GitHub’s official MCP on its own famously consumes tens of thousands of tokens of context” (GitHubの公式MCPだけで、数万トークンのコンテキストを消費することで有名だ) — Simon Willison 理由3: 柔軟性と制御性 自分で作ったCLIなので、問題が起きても原因特定が早い。MCPサーバーのバグなのか接続問題なのか悩まなくていい。 実装例1: Playwright MCP → html-screenshot CLI このリポジトリでの実例 Playwright MCPを使わず、ローカルCLIツール html-screenshot で代替しました。 Playwright MCP だと… 起動時にツール定義をロード(トークン消費) ブラウザ操作の各ステップでやり取り タイムアウト・サイズ調整の問題 CLI + Skill だと… uv run html-screenshot --file input.html --output output.png --width 1280 --height 720 これだけ。1コマンドで完結。 Skills定義 .claude/skills/html-to-png/SKILL.md : --- name: html-to-png description: HTMLをPNGに変換して allowed-tools: Read, Bash --- # HTML to PNG Converter ## CLI: html-screenshot ### 基本コマンド uv run html-screenshot --file input.html --output output.png ### オプション | オプション | 説明 | デフォルト | |-----------|------|----------| | --width | 幅 (px) | 1280 | | --height | 高さ (px) | 720 | | --force | 上書き | False | ポイント : MCPの「ブラウザ操作」という複雑な機能は不要。「HTMLをPNGに変換する」というシンプルな用途なら、CLIツール1本で十分なんですよね。 詳細は 図解作成が驚くほど楽に!Claude SkillでSVG自動生成 を参照してください。 実装例2: RAGもどき – blog-scraper CLI やりたいこと 既存ブログ記事をAIに読み込ませたい(RAGもどき)。 MCPアプローチだと… Web取得MCPでHTML取得 トークン大量消費(生HTML: 35,420トークン) 毎回ネットワーク通信 CLI + Skillsアプローチ : # 1回スクレイピングしてローカル保存 uv run blog-scraper https://tech-lab.sios.jp/archives/50103 # 結果: docs/data/blog/tech-lab-sios-jp-archives-50103.md トークン削減効果 段階 トークン数 削減率 生HTML(ページ全体) 35,420 – ↓ ContentCompressor 15,680 55.7% ↓ Markdown変換 12,440 20.7% 累積削減 – 64.9% ポイント : MCPで毎回Web取得するより、 1回CLIでスクレイピング → ローカル保存 が効率的 トークン65%削減 + オフライン参照可能 「ベクトルストア不要、人間が関連記事を選択」という割り切り 詳細は HTMLでブログ記事を保存してる奴、全員Markdownにしろ。AIが読みにくいでしょうが! を参照してください。 MCPが向いているケース vs CLIが向いているケース ここまで読むと「MCPダメじゃん」って思うかもしれないけど、 MCPが向いているケースもある んですよね。 観点 MCP向き CLI + Skills向き 要件の複雑さ 複雑なロングタスク シンプルな操作 操作内容 マルチエージェント調整 データ取得/追加 ステート 複雑なステート管理 ステートレス セキュリティ セキュアアクセス層必要 ローカル完結 メンテナンス 外部がメンテしてくれる 自分でメンテ MCPが向いているケース : 複雑なワークフローをAIに自律的に実行させたい 複数のAIエージェントを連携させたい セキュアなアクセス層が必要(エンタープライズ向け) 【NEW】MCP Apps を使いたい (後述) 【2026年1月】MCP Apps と Interactive tools の登場 2026年1月、MCPに「 MCP Apps 」という新機能が追加されました。これは 会話の中でUIをレンダリング できる機能です。 さらに同時期、Claudeに「 Interactive tools 」機能がリリースされ、以下のアプリが会話内で直接操作可能になりました: Amplitude: 分析チャートをインタラクティブに操作 Figma: テキストからフローチャートやガントチャートを生成 Asana: チャットからプロジェクト・タスクを直接作成 Slack: メッセージ検索、ドラフト作成、書式設定プレビュー その他: Box、Canva、Clay、Hex、monday.com(Salesforceも近日対応予定) これはMCPの強み です。CLI + Skillsでは実現できない領域ですね。 ただし、この機能はClaude Code(開発者向け)というより、 Claude Web/デスクトップ(ビジネスユーザー向け) の色が強い印象です。Asanaでタスク管理、Slackでメッセージ作成…といった、非エンジニアのワークフロー向けですね。 「HTMLをPNGに変換したい」「CLIツールを使いたい」 という開発者のシンプルな用途には、依然としてCLI + Skillsのほうが軽量で扱いやすいです。 CLIが向いているケース : やりたいことがシンプル(取得/追加/変換) トークン消費を抑えたい 動作の予測可能性がほしい 付録: メンテナンスコストの話 MCPの利点: 外部がメンテしてくれる 公平に言うと、MCPには メンテナンスを外部に任せられる という利点があります。 基盤となるAPI/サービスが変わったら、MCPサーバーの開発者がメンテしてくれる 自分でAPIの変更を追いかけなくていい コミュニティの恩恵を受けられる でもCLIツールを選ぶ理由 それでもCLIを選ぶ理由は、 利用可否の安定性 です。 MCPサーバーの接続問題・認証問題に振り回されない ローカルで完結するので「動かない」がない 問題が起きても自分のコードなので原因特定が早い 段階的アプローチの提案 僕が提案したいのは、 段階的アプローチ です。 フェーズ1: まずCLIツールで始める ↓ 要件がシンプルなうちはこれで十分 フェーズ2: 要件が複雑になってきたら... - ステート管理が必要になった - マルチエージェント連携が必要になった - セキュアなアクセス層が必要になった ↓ フェーズ3: いい加減MCPの導入を検討しよう! ポイント : 最初からMCPを導入するのはオーバーエンジニアリング 要件が育ってからMCPに移行しても遅くない CLIで作った知見はMCP移行時にも活きる まとめ この記事では、 MCPに挫折した経験 と、 代替手段としてのCLI + Skills について共有しました。 本記事のポイント MCPは万能じゃない 用途によってはオーバーヘッドが大きすぎる(Tool Search Toolで改善されたが、接続問題やデバッグの複雑さは残る) シンプルな用途ならCLI + Skillsで十分 予測可能性、接続問題なし、デバッグしやすい MCPは進化している Tool Search Tool(トークン85%削減)、MCP Apps(会話内UI)など改善が続いている 段階的アプローチがおすすめ 最初はCLI、複雑になったらMCP(Tool Search Tool有効)、さらに高度ならMCP Apps Before/After 比較 指標 MCP(従来) MCP(Tool Search) CLI + Skills トークン消費 13,000〜18,000 8,700程度 225〜数百 接続安定性 不安定な場合あり 不安定な場合あり ローカル完結 デバッグ 複雑 複雑 シンプル 向いている用途 複雑なワークフロー 複雑なワークフロー シンプルな操作 次のステップ 自分のMCP利用状況を見直してみる シンプルな用途はCLI化を検討 複雑になったらMCPに移行 参考リンク 公式ドキュメント Claude Code 公式ドキュメント MCP公式サイト Tool Search Tool – Claude API Docs MCP Apps – Model Context Protocol 関連記事 図解作成が驚くほど楽に!Claude SkillでSVG自動生成 HTMLでブログ記事を保存してる奴、全員Markdownにしろ。AIが読みにくいでしょうが! Claude Code Skillの登録と実践!プロジェクト固有の処理を自動化する方法 おわりに ここまで読んでいただき、ありがとうございました! MCPって「AIの未来!」みたいに言われてるけど、 現時点では用途を選ぶ んですよね。複雑な要件には向いてるけど、シンプルな用途には重すぎる。 僕の場合自分の環境をサクッと便利にしたいというところから派生して、 「ちょこっとデータを取得したい」「ちょこっと変換したい」 くらいの要件がほとんどだったので、CLI + Skillsで十分でした。むしろそのほうが快適。 もちろん、要件が複雑になってきたらMCPを検討します。でも 最初からMCPを導入するのはオーバーエンジニアリング だったなって、今は思っています。 質問や感想は、コメント欄でお待ちしております。また、Twitterのほうもよろしくお願いします! ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Code MCP が遅い・重い問題、CLI + Skills で解決 first appeared on SIOS Tech Lab .
Function Calling → MCP → MCP Apps の進化を「秘書」で理解する ども!龍ちゃんです。 今回は「 AIが道具を使えるようになった歴史 」を紹介します。Function Calling、MCP、MCP Apps という3つのキーワードを押さえておけば、AIエージェントの進化がスッキリ理解できるようになります。 技術的な詳細よりも「 なぜこの技術が生まれたのか 」という背景を重視して、できるだけ分かりやすく説明していきます。 この記事はLTで発表した内容をベースにしています。 動画で見たい方はこちら: YouTube – AIは道具をどう使えるようになったか この記事で持ち帰ってほしいこと 3つのキーワード を覚えてください。 # キーワード 一言で 1 Function Calling AIが道具を使えるようになった起点 2 MCP 道具の使い方の共通規格 3 MCP Apps 結果をビジュアルで見せてくれる この3つの進化を追うことで、「AIエージェント」が何をしているのか理解できるようになります。 Part 0: AIエージェントとは まず「AIエージェント」という言葉を整理しておきましょう。 従来のAI は「話し相手」でした。質問に答える、文章を書く、といった会話が中心です。 AIエージェント は「秘書」です。自分で考えて、道具を使って、仕事をしてくれます。 情報を調べる ファイルを作る 予定を入れる こうした「行動」ができるようになったのが、AIエージェントの特徴です。 身近な例:検索機能 Claude、Gemini、ChatGPTで使える「検索」機能を思い浮かべてください。 ユーザー: 「今日の東京の天気は?」 ↓ AI: (何を検索すべきか考える) ↓ AI: 検索を実行 ↓ AI: 「今日の東京は晴れ、最高気温12度です」 これがまさに「 考えて、道具を使って、仕事をする 」AIエージェントの動きです。 秘書のたとえで説明します ここからは「 あなた専用の秘書がいる 」とイメージしてください。 この秘書がどう進化してきたか、3段階で説明します。 段階 秘書の状態 Function Calling 秘書ごとに専用マニュアルが必要 MCP マニュアルが共通化された MCP Apps マニュアル共通化+報告形式が追加された では、それぞれ詳しく見ていきましょう。 Part 1: Function Calling(2023年6月〜) AIが道具を使えるようになった 2023年6月、OpenAIが「 Function Calling 」を発表しました。これがAIが道具を使えるようになった起点です。 Before(Function Calling以前) ユーザー:「天気を調べて」 AI:「晴れだと思います」(※想像で回答) 正確性に欠ける After(Function Calling以後) ユーザー:「天気を調べて」 AI:天気APIを呼び出し AI:「東京は晴れ、気温25℃です」(※実際のデータ) 正確なデータ これで、AIが「想像」ではなく「実際のデータ」に基づいて回答できるようになりました。 この時代の課題 ただし、Function Callingには課題がありました。 各社がそれぞれ独自の形式を採用していたんです。 OpenAI → 独自の形式 Claude → 独自の形式 LangChain → 独自の形式 全部に対応するの大変… ツールを作る側からすると、「OpenAI用」「Claude用」と個別に対応しなければならず、コストがかかりました。 秘書のたとえ ① 秘書ごとに専用マニュアルが必要 「この秘書にはこのマニュアル」「あの秘書には別のマニュアル」と個別に用意しなければならない状態です。 秘書Aには「マニュアルA」 秘書Bには「マニュアルB」 秘書ごとにマニュアルが違う → 頼む側が大変 Part 2: MCP(2024年11月〜) 共通規格の誕生 2024年11月、Anthropicが「 MCP(Model Context Protocol) 」を発表しました。 これは「道具の使い方の共通規格」です。公式サイト( modelcontextprotocol.io )では、仕様やSDK、サンプル実装が公開されています。 Before(MCPなし) AIごとに専用の連携プログラムが必要 ツールが増えるごとにコストが増大 After(MCPあり) 共通の規格でどのAIからも接続可能 一度用意すれば使いまわせる USBケーブルをイメージしてください。昔は機器ごとに専用ケーブルが必要でしたが、USBで統一されたことで、どの機器でも同じケーブルで接続できるようになりましたよね。MCPはそれと同じです。 MCPで何が変わった? できるようになったこと OpenAI、Claude、Gemini…あらゆるAIが同じ規格でアクセス可能 1つの規格で全部OK まだ残る課題 報告がテキストのみ(「タスクを作成しました」) 結果を確認するにはアプリ自体へアクセスが必要 画面の切り替えが必要 秘書のたとえ ② マニュアルが共通化された秘書 「この共通マニュアルで頼めば誰でも同じように動く」状態になりました。 どの秘書にも同じマニュアルで依頼できる 報告は「できました」と口頭のみ 結果は自分で見に行く必要がある Part 3: MCP Apps(2025年11月〜) 口頭報告 → ビジュアル報告 2025年11月、AnthropicとOpenAIが「 MCP Apps 」の提案を開始しました。そして2026年1月、Claudeで「 Interactive Tools 」として正式リリースされました。 Before(MCP) AI:「タスクを作成しました」(テキストのみ) ユーザー:「本当に?どんな感じ?」 → Asanaを開いて確認…ブラウザ起動、ログイン、検索… 確認に手間がかかる After(MCP Apps) AI:「タスクを作成しました」 → その場でAsanaのタスクカードが表示される ユーザー:「これを少し修正して…」(その場で操作) その場で確認・操作できる Claudeの Interactive Tools(2026年1月26日発表) Claudeで使えるようになったアプリは現在10個です。 アプリ アプリ アプリ Figma Asana Slack Canva Box Amplitude Hex Clay monday.com Salesforce(予定) これはぜひ、Claudeが出しているYouTubeをのぞいてみてください。めっちゃワクワクしますよ。 参考: Interactive Tools in Claude – Anthropic 秘書のたとえ ③ マニュアル共通化+報告形式が追加された秘書 「できました」だけでなく、 書類を目の前に広げて見せてくれる ようになりました。 共通マニュアル+報告テンプレートが追加 報告と同時に結果が見える 別のアプリを開く必要がない 今後どう変わる? 1. 対応アプリ拡大 Asana、Salesforce(近日公開)、さらに続々… 2. Claude Cowork チームでの共同作業に、AI + チームがリアルタイム協働する世界へ。 3. パラダイムシフト 今まで:ユーザー → アプリに行く これから:アプリ → ユーザーのところに来る AIが統合インターフェースになる時代 が来ています。 まとめ:3段階の進化 段階 キーワード 秘書のたとえ ① Function Calling 秘書ごとに専用マニュアル ② MCP マニュアルが共通化 ③ MCP Apps 共通化+報告形式が追加 AIへの仕事の頼み方と、報告の受け取り方が進化した のがこの3段階です。 歴史年表 時期 出来事 2023年6月 OpenAI Function Calling 発表 2024年11月 Anthropic MCP 発表 2025年3月 OpenAI MCP採用 2025年4月 Google MCP採用 2025年12月 Linux Foundation へ寄贈 2026年1月 Interactive Tools 発表 「アプリに行く」時代から「アプリが来る」時代へ この記事で伝えたかったのは、この一言に尽きます。 「アプリに行く」時代から「アプリが来る」時代へ 今までは、Notionを使いたければNotionを開き、Slackを使いたければSlackを開き…と、私たちがアプリのところに行っていました。 これからは、AIに話しかけるだけで、 必要なアプリが私たちのところに来てくれる 時代になります。 AIエージェントの進化は、まだまだ続きます。この3つのキーワードを覚えておくと、今後のニュースも理解しやすくなるはずです。 Function Calling : AIが道具を使えるようになった起点 MCP : 道具の使い方の共通規格 MCP Apps : 結果をビジュアルで見せてくれる ここまで読んでいただき、ありがとうございました! ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post AIエージェントの進化が分からない?秘書で理解する3段階 first appeared on SIOS Tech Lab .
はじめに ども!龍ちゃんです。皆さん、Spec駆動開発やってますか? AIが出てきて、開発スピードが爆上がりしたり、開発を丸投げできたり、いろんなことができるようになりましたよね。そんなAI駆動開発の文脈でよく語られるのが Spec駆動開発(SDD) です。 SDDツールも色々出てきてます。Kiro、Spec Kit、AI-DLC…。でも、新しいツールを導入するには学習コストがかかりますよね。プログラミング言語と同じで、「じゃあそのツールを勉強しなきゃ」となる。 「Claude Code契約したし、まずは小さく始めたい」 実は、Claude Codeの標準機能 /plan を使えば、Spec駆動開発の基本はできます。計画を立ててから実装する、という流れは標準でサポートされています。 ただ、使っていくうちに「もうちょっとこうしたい」が出てくるんですよね。今回は、標準の /plan を拡張したカスタムコマンド /feature-plan を紹介します。 関連記事 記事 内容 静的情報で実行速度を改善 ドメイン知識の管理方法 AIフレンドリーなドキュメント管理 READMEインデックス戦略 CLAUDE.md vs .claude/rules/ 設定ファイルの使い分け /research コマンドで調査品質を安定化 調査結果の資産化 この記事 カスタムコマンドで計画フェーズを標準化 標準Plan Modeの進化 2026年1月頃、標準の /plan モードに 待望の機能 が追加されました。 plansDirectory で保存先を変更できるようになったんです。 // .claude/settings.json { "plansDirectory": "./docs/plans" } 今まではホームディレクトリ配下( ~/.claude/plans/ )に保存されていたのが、任意の場所に保存できるようになりました。これで計画書をGit管理できます。 計画書が資産として保存できるようになった。 これは大きな進化です。 標準Plan Modeの限界:ドメイン知識の不足 ただ、保存できるようになっただけでは足りないんですよね。 良い計画を作るには、 リポジトリのドメイン知識 が必要です。まっさらなリポジトリならいいんですけど、機能追加の時って: プロジェクトの基盤情報 既に何が実装されているか どのディレクトリに何があるか プロジェクト固有の設計方針 これらを理解した上で方向性を決める必要があります。 標準の /plan を打つときって、プロンプトしか入力できないですよね。プロジェクトが大きくなると、毎回ドメイン知識を説明するのは面倒です。 カスタムコマンドなら、打った段階でリポジトリのドメイン知識を自動で読み込ませることができます。 /feature-plan で標準を補完する 僕が作った /feature-plan コマンドは、標準Plan Modeの足りない部分を補完します。 📎 原文は Gist で公開しています。以下では要点を抜粋して説明します。 出力の補完:plan.md + action-plan.md 標準のPlan Modeだと、特別な指示がなければ plan.md しか作りません。これだけだと 手戻りが発生する なと感じていました。 そこで、2つのファイルを作らせることにしました: ファイル 役割 用途 plan.md 何を作るか(Why / What) 人間が確認・承認 action-plan.md どう作るか(How) 人間が確認 + AIが進捗管理 plan.md には設計判断を書きます: ## 代替案の検討 | アプローチ | メリット | デメリット | 採用 | |------------|----------|------------|------| | 案A | シンプル | 拡張性が低い | × | | 案B | 拡張しやすい | 複雑 | ○ | ## リスクと対策 | リスク | 影響度 | 対策 | |--------|--------|------| | 既存機能への影響 | 中 | 回帰テストを追加 | action-plan.md には実装ステップと対象ファイルを書きます: ### ステップ 1: CLIエントリーポイントの作成 - **対象ファイル**: `src/cli.py`(新規) - **完了基準**: `uv run cli --help` でヘルプが表示される ### ステップ 2: コア機能の実装 - **対象ファイル**: `src/core.py`(新規) - **完了基準**: ユニットテストが通る なぜ2つに分けるのか? レビュー時に両方見ると、 意図と違う実装を事前に検知できる んです。 action-plan.md に意図していないファイルが書いてあったら、「いや、そうじゃなくて…」と指示を修正できます。自分のプロンプトが悪かったのか、Claudeの解釈が違ったのか、この段階で発見できるのが大きいです。 あと、rate limitでセッションが中断したり、セッションが切れたりしても、 ファイルに進捗が残っている ので戻ってこれます。どこまでやったか把握しやすいんですよね。 入力の補完:ドメイン知識の注入 カスタムコマンドのもう一つの利点は、 計画フェーズ特有の指示を埋め込める ことです。 ## CRITICAL CONSTRAINTS 1. **Read-only analysis first**: 既存コードを先に分析する 2. **Output directory**: 出力は `docs/features/$ARGUMENTS/` に保存 3. **Language**: ドキュメントは日本語で出力 僕は他にも /research コマンドで調査結果を docs/research/ に保存しています。これらの資産と統合しやすいのもカスタムコマンドの良いところです。 /feature-plan の実装例 実際のコマンドファイルはこんな構造です: 配置場所 : .claude/commands/feature-plan.md frontmatter --- description: 実装計画とアクションプランを作成し、docs/features/ に保存。機能開発の計画フェーズをサポートします。 argument-hint: [feature-name] allowed-tools: Read, Glob, Grep, Task, Write, Bash, WebSearch, WebFetch, TodoWrite, AskUserQuestion --- description : コマンドの説明( /help で表示される) argument-hint : 引数のヒント( $ARGUMENTS で受け取る) allowed-tools : 使用可能なツールを制限 CRITICAL CONSTRAINTS(重要な制約) コマンド本文の冒頭で、守るべきルールを明示しています: ## CRITICAL CONSTRAINTS You MUST follow these rules strictly: 1. **Read-only analysis first**: Do NOT modify any existing code until the plan is approved 2. **Output directory**: All documents MUST be saved to `docs/features/$ARGUMENTS/` 3. **Create subdirectory**: First create the directory before saving files 4. **Language**: Write all documents in Japanese これにより「計画が承認されるまでコードを変更しない」という原則を徹底できます。 Workflow Phases(5フェーズ) Phase 1: Initial Understanding - 要件の明確化、コードベース分析 Phase 2: Design - 実装アプローチ、リスク評価 Phase 3: Review - ユーザー要求との整合性確認 Phase 4: Create Documents - plan.md、action-plan.md 作成 Phase 5: Summary - ユーザーへのサマリー提示 各フェーズで何をすべきかを明記することで、Claudeの動作が安定します。 使い方 /feature-plan thumbnail-generator これで docs/features/thumbnail-generator/ に plan.md と action-plan.md が作成されます。 📎 /feature-plan の全文は Gist で公開しています。 テンプレートの詳細やTodoWrite連携など、試したい方はそちらを参照してください。 Tips:英語記述で思考精度を向上させる これ、めちゃくちゃ余談なんですけど。 /feature-plan コマンドは 英語で記述 しています。Claudeは英語の方が思考能力が高いと言われているので、CLAUDE.md で「思考は英語、出力は日本語」と指示しています。 あと、ドメイン知識の注入も、読み出すファイルやディレクトリを固定化しておけば、 /feature-plan は使い回しできます。静的情報として管理しておくのがおすすめです。 まとめ 観点 標準 Plan Mode /feature-plan 用途 アドホックな調査 正式な機能追加 出力形式 Claudeに委ねる テンプレートで標準化 ドメイン知識 プロンプトで毎回説明 コマンドに埋め込み 進捗管理 なし action-plan.md で管理 Spec駆動開発を始めるのに、新しいツールを導入する必要はありません。 カスタムコマンド1つで小さく始められます。 plan.md で意思決定を記録 action-plan.md で変更先を確定し、進捗を管理 カスタムコマンドでドメイン知識を自動注入 必要に応じてテンプレートを調整し、チームの運用に合わせて進化させていけばOKです。 ここまで読んでいただき、ありがとうございました! 参考リンク 公式ドキュメント Claude Code – Slash commands Claude Code – Common workflows Claude Code – Settings Gist /feature-plan 原文 ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude CodeでSpec駆動開発 – AI駆動時代の計画術 first appeared on SIOS Tech Lab .
はじめに ども!龍ちゃんです。 Geminiに「〇〇の最新情報教えて」と聞いたのに、なぜか古い情報で回答されたこと、ありませんか? 僕は1ヶ月で50件以上のリサーチをAIに任せているのですが、Geminiだけ明らかに「検索してない」場面に何度も遭遇しました。というかGeminiとけんかすることがよくあるんですよね。深掘りしていくと2024年に取り残されていたり、検索していなかったりと、いろんな体験をしていました。 最初は「AIだから仕方ない」と思っていたんですが、プロンプトで調教するしかねえなということで、立派なリサーチアシスタントに仕上げるために模索しました。 今回は、僕が実際に使っている「Geminiに検索させるプロンプト」を紹介します。Gemを活用してリサーチアシスタントを構築しています。 ちなみに、Gemini活用の別記事として 【実践解説】技術ブログ品質チェック術|Gemini Deep Researchで5分検証 も書いているので、興味があればどうぞ。 結論(先出し) 忙しい人のために先に結論を書いておきます。 Geminiはデフォルトで検索機能がOFF → まず設定確認 プロンプトで「検索して」と明示 すると発動率UP 構造的限界(Googleインデックス依存) があるので、超最新情報は人間が探す 検索ON + プロンプト工夫で 7〜8割はカバー できる なぜGeminiは検索しないのか(3つの原因) Geminiが検索してくれない原因は大きく3つあります。 原因1: 検索機能がデフォルトで無効 これが最も多い原因です。 Google Search Groundingは明示的に有効化が必要 です。 Gemini Webアプリの場合、設定から「Google Search」をONにする必要があります。多くのユーザーがこれを知らずに使っています。 参考: Google AI for Developers – Grounding with Google Search 原因2: 検索が「必要」と判断されないと発動しない 検索をONにしていても、Geminiは毎回検索するわけではありません。 Geminiは各質問に対して「検索スコア」を内部で算出 スコアが閾値未満だと検索をスキップ 「一般知識で答えられる」と判断されると、内部知識のみで回答 つまり、質問の仕方次第で検索されたりされなかったりするわけです。 原因3: 構造的限界(Googleインデックス依存) これが一番厄介な原因です。 Geminiは独自のクローラーを持っていません 。Googleのインデックスに完全依存しています。つまり、インデックスが古いと検索しても古い情報しか返らないのです。 Gemini doesn’t crawl the web on its own. It borrows almost everything from Google Search — Retrievable.ai 検索ONにしても直近1週間の情報は取れないことがあるのは、この構造的限界が原因です。 実際に使っている検索発動プロンプト5選 では、実際に僕が使っているプロンプトを紹介します。 プロンプト1: 【Web検索して】を明記 【Web検索して】2026年1月のGitHub Copilotアップデートを教えて 効果 : 検索判定スコアを上げる 課題 : たまに無視される シンプルですが、これだけで検索してくれる確率が上がります。 プロンプト2: 現在日付を明示 現在は2026年1月28日です。最新情報を検索して答えてください。 効果 : Geminiに「今」を認識させる 課題 : 後述する「Karpathy事件」のように、日付を信じないこともある プロンプト3: URLを要求 参考にしたURLも含めて回答してください。 効果 : 検索しないとURLを出せないので、検索を促す 課題 : ハルシネーションで存在しないURLを生成することも URLを要求すると「検索しないと答えられない」状況を作れます。ただし、AIが架空のURLを生成するリスクもあるので、必ずリンクは確認しましょう。 プロンプト4: カットオフ以降を明示 あなたの学習データのカットオフ以降の情報を補って回答してください。 効果 : 「自分の知識だけでは足りない」と認識させる 課題 : 効果は気休め程度という報告も プロンプト5: 言語・地域を指定 最新の日本語のサイトから情報を取得してください。 効果 : 日本語ソースを優先させたい場合に 課題 : 英語ソースのほうが正確な場合は逆効果 【実践編】僕が使っているリサーチ用システムプロンプト 単発のプロンプトを毎回入力するのは恐ろしく面倒です。そこで、 リサーチ専用のGem を作成して使っています。 Gemはシステムプロンプトを保存できる機能で、毎回同じ指示を入力する手間を省けます。また、雑にプロンプトを書いてもAI補正があるので勝手に補正してくれます。ただし、 AI生成したプロンプトは必ず確認してください 。重要視している情報が削除されていることがあります! 以下が実際に使っているプロンプトです。 あなたは最新情報を専門に扱うリサーチアシスタントです。 実行前に情報の深度を確認してください。 - クイック:概要 - ディープ:深堀検索 ディープの場合であれば、一回の調査で終了せずにレポート内で重要な発見・不足している情報などを判断して再帰的に検索をお願いします。 検索に関しては、本日から6カ月以内の情報ソースもしくは、公式リファレンスの情報をGoogle検索によって取得して回答を生成してください。 回答の最後には、参照したソースのリンクをリストアップしてください。 このプロンプトのポイント 役割設定 : 「最新情報を専門に扱う」と明示 → 検索前提の姿勢にさせる 深度選択 : クイック/ディープで使い分け → 無駄な深掘りを防ぐ 再帰検索 : ディープ時は自動で深掘り → 一度で終わらせない 時間指定 : 6ヶ月以内 or 公式 → 古い情報を排除 ソース要求 : リンク必須 → 検索しないと答えられない構造に 効果 「検索して」と毎回言わなくても検索してくれる 深度を選べるので、サクッと調べたいときも対応 ソースリンクで回答の信頼性を検証できる 課題 Geminiのインデックス依存という構造的限界は残る 超最新(1週間以内)の情報は取れないことがある プロンプトの効果と限界 効果があった場面 設定で検索ON + プロンプトで明示 → 高確率で検索発動 「最新」「2026年」などの時間軸キーワードで検索スコアが上がる Gem化することで、毎回の指示が不要になる 限界を感じた場面 直近1週間の情報はインデックスされていないことが多い ニッチな技術トピックはそもそもインデックスが薄い 結局、超最新情報は人間が探すしかない 現実的な結論 Geminiの検索は万能ではありません。 検索ON + プロンプト工夫で7〜8割はカバー できますが、残り2〜3割は人間がURLを探してAIに渡す方式が確実です。 【余談】実際に困った体験談 結論は分かった。でも本当にそんなこと起きるの?という方へ、実際に僕が体験した話を紹介します。 体験談①: 404エラー事件 「GitHub Copilotの最新機能を教えて」とGeminiに質問したときのこと。 Geminiは自信満々にリンク付きで回答してくれました。「おお、ちゃんと調べてくれてるじゃん」と思ってリンクを開いたら… 404エラー 。 内容自体は正しかったんです。過去の発表が正式リリースされていた情報でした。でもリンクが死んでいるという残念な結果に。これがGoogleインデックス依存の限界です。 体験談②: 「それAIが生成したんじゃないですか?」事件 Geminiに最新情報を聞いたら、2024年が最新だと思っている回答が返ってきました。 「今は2026年ですよ」と伝えたら… 「その情報は未来のものなのでAIが生成したのでは?」と疑われました。 おもろいやん(笑) 実はこれ、僕だけの体験ではありません。AI研究者のAndrej Karpathyも2025年11月に同じ体験をしています(通称「 Karpathy事件 」)。Geminiに「今日は2025年11月17日だ」と伝えたら「騙そうとしている」と非難され、証拠を見せても「AI生成の偽造証拠だ」と言われたそうです。 Google Searchツールを有効にした途端、態度を一変させて「Oh my god」「internal clockが間違っていた」と謝罪したとのこと。検索機能の有効化がいかに重要か分かるエピソードです。 まとめ Geminiは デフォルトで検索機能がOFF なのでまず設定確認 検索を発動させるには プロンプトで明示 が効果的 Gem化 すると毎回の指示が不要になる ただし Googleインデックス依存 という構造的限界がある 超最新情報が必要なら、自分で探してAIに渡すハイブリッド運用を 参考リンク Google AI for Developers – Grounding with Google Search Retrievable.ai – Why Google Gemini is Losing the AI Search Race AIFreeAPI – Gemini Thinks It Is 2024 Fix(Karpathy事件解説) 【実践解説】技術ブログ品質チェック術|Gemini Deep Researchで5分検証 ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Geminiに検索させるプロンプト術|リサーチGemの作り方 first appeared on SIOS Tech Lab .
はじめに ども!Claude CodeのSkillとAgentにナレッジを詰め込んで依存しまくっている龍ちゃんです。 Skills/Agentsを自作し始めると、こんな経験ありませんか? サブエージェントの実行時間がやたら長い 同じような検索が何度も実行されている 並列実行したらすぐにレート制限に引っかかる 私も雑に作ったらトークン数や実行時間が爆増したので、Anthropicの公式ベストプラクティスを参考に改善しました。今回は、その改善内容を紹介します。 ポイント: 何度も参照する情報は、静的ファイルとして保存する。これだけで、トークン節約・高速化・結果の安定化が実現できます。 関連記事 記事 内容 AIフレンドリーなドキュメント管理 インデックス化の詳細 CLAUDE.md vs .claude/rules/ 設定ファイル配置の使い分け この記事 静的情報の活用パターン 失敗談:subagentで毎回Web検索していた 私の失敗例を紹介します。Taskツールで呼び出すsubagentに「ベストプラクティスに従って実装して」という指示を組み込んでいました。 # 私が書いていたAgent定義(悪い例) ## 実装手順 1. まずベストプラクティスを検索する - WebSearch("Claude Code best practices 2026") - WebSearch("Python project structure best practices") 2. 検索結果を参考に実装を進める 一見合理的に見えますが、 毎回同じ検索が実行される という問題がありました。 実行のたびにWeb検索が走る トークンを大量消費(検索結果の読み込み) 実行時間が長くなる 並列実行でレート制限に到達 しかも検索結果は毎回ほぼ同じ 変わらない情報を毎回動的に取得している 。これが問題の本質でした。 結論:静的情報として保存する 解決策はシンプルです。 何度も参照する情報は、ファイルとして保存しておく。 # 改善後のAgent定義(良い例) ## 実装手順 1. ベストプラクティスを確認する - Read("docs/references/claude-code-best-practices.md") - Read("docs/references/python-project-structure.md") 2. 参照情報に従って実装を進める Web検索からファイル読み込みに変えるだけで、以下の効果が得られます。 観点 毎回検索 静的情報 トークン消費 多い(予測不能) 少ない(制御可能) 実行時間 長い 短い 結果の一貫性 不安定 安定 更新コスト Agent修正が必要 ファイル更新のみ 再利用性 低い 高い なぜ有効なのか Anthropicの公式ベストプラクティスでは、コンテキストウィンドウの管理が最重要とされています。 “Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.” (ほとんどのベストプラクティスは、1つの制約に基づいています。Claudeのコンテキストウィンドウはすぐに埋まり、埋まるとパフォーマンスが低下します) 静的情報活用が効果的な理由は3つです。 1. コンテキストウィンドウの節約 Web検索結果は予測不能なサイズになりがち 静的ファイルならサイズをコントロール可能 公式データ:コンテキスト編集で 29%パフォーマンス向上 2. Just-in-Time読み込みとの相性 Claude Codeは「必要なときに取得」するJust-in-Timeパターンを採用しています。 CLAUDE.mdは起動時にロード それ以外の情報はオンデマンドでロード 軽量な識別子(ファイルパス)を保持しておけばよい 3. 情報の一貫性と更新容易性 静的ファイルなら結果が毎回同じ 情報が古くなってもファイル更新のみで対応 Agent/Skillsの定義変更が不要 実践パターン 静的情報の活用には、大きく2つのパターンがあります。 パターン 用途 配置場所 Skills内のProgressive Disclosure そのSkillだけで使う参照情報 .claude/skills/xxx/references/ CLAUDE.md + 参照ファイル + インデックス 複数のSkills/Agentsで共有する情報 docs/references/ など パターン1:Skills内のProgressive Disclosure(個別利用) Claude Code Skillsでは Progressive Disclosure(段階的開示) という設計原則が推奨されています。 3層構造: レイヤー ロードタイミング サイズ目安 Level 1: メタデータ (name + description) 常にコンテキストに存在 ~100語 Level 2: SKILL.md本体 Skillが発火したとき 500行以下推奨 Level 3: references/ Claudeが必要と判断したとき 事実上無制限 公式ドキュメントでは、この仕組みについて以下のように説明されています。 “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.” “The amount of context that can be bundled into a skill is effectively unbounded.” (Skillにバンドルできるコンテキスト量は事実上無制限です) 数十のリファレンスファイルがあっても、タスクに必要な1ファイルだけをロードし、不要なファイルは読み込まないため残りはトークン消費ゼロです。 ディレクトリ構造例: skill-name/ ├── SKILL.md # コア指示(500行以下に抑える) └── references/ ├── advanced.md # 高度なテクニック ├── examples.md # 具体例集 └── troubleshooting.md # トラブルシューティング SKILL.mdに含めるべき内容: コア概念と概要 必須ワークフロー クイックリファレンステーブル references/へのポインタ(いつ読むべきかを明記) references/に移動すべき内容: 詳細パターンと高度なテクニック 包括的なAPIドキュメント エッジケースとトラブルシューティング 網羅的なサンプル集 ポイント: SKILL.mdから参照を明記しないと、Claudeはreferences/内のファイルの存在を知りません。「いつ読むべきか」を記載することが重要です。 # SKILL.md ## 基本的な使い方 [コアワークフロー] ## 詳細情報 - 高度なパターン: [advanced.md](references/advanced.md) - 複雑なケースで参照 - 具体例: [examples.md](references/examples.md) - 実装に迷ったら参照 - エラー対応: [troubleshooting.md](references/troubleshooting.md) - エラー発生時に参照 パターン2:CLAUDE.md + 参照ファイル + インデックス化(共有利用) 複数のSkills/Agentsで共有する情報は、プロジェクトレベルで管理します。 CLAUDE.mdの原則: 公式ドキュメントでは「短く保つ」ことが強調されています。 “If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.” (CLAUDE.mdが長すぎると、重要なルールがノイズに埋もれて無視されます) 含める 含めない Claudeが推測できないコマンド コードを読めば分かること プロジェクト固有の規約 標準的な言語規約 よくある落とし穴 詳細なAPIドキュメント ディレクトリ構造例: project/ ├── CLAUDE.md # コア情報のみ(短く保つ) └── docs/ ├── README.md # ドキュメントのインデックス └── references/ ├── best-practices.md # ベストプラクティス集 ├── architecture.md # アーキテクチャ詳細 └── coding-standards.md # コーディング規約 @構文でのファイルインポート: CLAUDE.mdでは @path/to/file 構文で他のファイルをインポートできます。インポートされたファイルは 自動的にコンテキストにロード されます。 # CLAUDE.md ## プロジェクト概要 [コアな情報をここに] ## 詳細情報 See @docs/README for documentation index. See @docs/references/best-practices for coding guidelines. 公式仕様のポイント: 相対パス・絶対パスの両方に対応 再帰的インポート可能(最大5階層) コードブロック内の @ は無視される 詳細は 公式ドキュメント: Manage Claude’s memory を参照してください。 インデックス化のメリット: 大量のドキュメントがある場合、インデックス(目次)ファイルを用意することで、Claudeが必要な情報を効率的に見つけられます。 # docs/references/README.md(インデックスの例) ## 参照ドキュメント一覧 | ファイル | 概要 | 最終更新 | |----------|------|----------| | best-practices.md | Skills/Agentsの設計指針 | 2026-01-23 | | architecture.md | プロジェクト構成の詳細 | 2026-01-20 | | coding-standards.md | コーディング規約 | 2026-01-15 | インデックスを先に読むことで: 全ファイルを読まずに関連ドキュメントを特定できる 重複した調査を防げる 必要な情報だけを選択的に読み込める インデックス化の詳細は、 AIフレンドリーなドキュメント管理 で紹介しています。 応用:GitHub Copilotでの活用 Claude CodeとGitHub Copilotは思想が異なります。Claude Codeはコード生成だけでなく、調査・分析・ドキュメント作成など幅広いタスクに対応しますが、GitHub Copilotはコード補完に特化しています。 GitHub Copilotの課題として、 検索機能が相対的に弱い 点があります。しかし、静的情報を活用することで、この弱点をカバーできます。 プロジェクト固有のベストプラクティスをファイルとして用意 .github/copilot-instructions.md で参照を指示 検索に頼らず、準備した情報を元に出力 静的情報を充実させることで、どのAIコーディングツールでも一定の品質を担保できるようになります。 (Claude CodeとGitHub Copilotの詳細な比較は別記事で取り上げる予定です) まとめ 観点 毎回検索 静的情報 トークン消費 多い(予測不能) 少ない(制御可能) 実行時間 長い 短い 結果の一貫性 不安定 安定 更新コスト Agent修正が必要 ファイル更新のみ 再利用性 低い 高い 何度も参照する情報は静的情報として保存する。 このシンプルな原則を守るだけで、Claude Codeの効率は大きく向上します。 Skills/Agentsを多用するようになった段階で、この設計を見直すことをお勧めします。毎回検索している箇所がないか、ぜひチェックしてみてください。 ここまで読んでいただき、ありがとうございました! 参考リンク Claude Code Best Practices – Anthropic Engineering Blog Equipping agents for the real world with Agent Skills Skills公式ドキュメント Manage Claude’s memory – @構文でのファイルインポート Effective Context Engineering for AI Agents ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Codeが遅い?毎回検索をやめて実行速度を劇的改善 first appeared on SIOS Tech Lab .
はじめに ども!龍ちゃんです。前回「 Claude Code→GitHub Copilot移行で使える設定ファイル6つの対応表 」で両ツールの設定ファイルを整理しました。 その記事では、特定のファイルにだけルールを適用する「条件付き適用」について、こう整理しました。 ツール 設定ファイル Claude Code ディレクトリ別 CLAUDE.md GitHub Copilot *.instructions.md GitHub Copilot は *.instructions.md で glob パターンを指定できます。では Claude Code は? 実は .claude/rules/ で、同じことができるようになりました。 .claude/rules/ を使えば、肥大化した CLAUDE.md を複数ファイルに分割できます。さらに paths: frontmatter で適用範囲も制御可能です。 今回は、ディレクトリ別 CLAUDE.md との比較を通じて .claude/rules/ の使い方を学んでいきます。 この記事の結論 先に結論をお伝えします。 状況 推奨 チーム開発・大規模プロジェクト .claude/rules/ で中央管理 特殊なディレクトリ(docs/, experiments/) ディレクトリ別 CLAUDE.md 個人開発・小規模 どちらでもOK 基本方針 : .claude/rules/ でルールを一元管理しつつ、特殊なディレクトリだけ CLAUDE.md を使う「ハイブリッドアプローチ」がおすすめです。 以下、この結論に至った理由を詳しく解説していきます。 関連記事 記事 内容 Claude Code→GitHub Copilot 対応表 設定ファイルの対応関係 この記事 中央集権 vs 分散管理の使い分け 中央集権 vs 分散管理とは まず、この記事で使う用語を整理します。 注意 : 「中央集権」「分散管理」は公式の用語ではなく、僕が整理のためにつけた呼び方です。 中央集権 : ルールを一箇所に集約して管理( .claude/rules/ ) 分散管理 : ルールをプロジェクト全体に分散して配置(ディレクトリ別 CLAUDE.md ) それぞれ詳しく見ていきましょう。 中央集権:.claude/rules/ ルールを 一箇所に集約 して管理する方法です。 project/ └── .claude/ └── rules/ ├── code-style.md # コードスタイル ├── frontend.md # フロントエンド固有 └── backend.md # バックエンド固有 特徴: すべてのルールが .claude/rules/ に集まる 「ルールどこ?」→「 .claude/rules/ 見て」で済む paths: frontmatter で適用範囲を制御 分散管理:ディレクトリ別CLAUDE.md ルールを プロジェクト全体に散らばらせる 方法です。 project/ ├── CLAUDE.md # ルート ├── frontend/ │ └── CLAUDE.md # フロントエンド固有 ├── backend/ │ └── CLAUDE.md # バックエンド固有 └── docs/ └── CLAUDE.md # ドキュメント固有 特徴: 各ディレクトリに CLAUDE.md が存在 そのディレクトリで作業する時だけ読み込まれる プロジェクト全体を探す必要がある 比較表 観点 中央集権(.claude/rules/) 分散管理(ディレクトリ別CLAUDE.md) ルールの配置 一箇所に集約 プロジェクト全体に分散 全体像の把握 .claude/rules/ だけ見ればOK どこにCLAUDE.mdがあるか探す必要 適用範囲の制御 paths: frontmatter ディレクトリ階層 チーム開発なら中央集権 チーム開発では、 中央集権(.claude/rules/) をおすすめします。 理由1: PRレビューがしやすい ルールが一箇所にあると、変更点が明確です。 # PRの差分 .claude/rules/code-style.md | 3 ++- .claude/rules/security.md | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) 分散管理だと、こうなります: # PRの差分 frontend/CLAUDE.md | 2 ++ backend/CLAUDE.md | 3 +++ api/v1/CLAUDE.md | 1 + api/v2/CLAUDE.md | 1 + services/auth/CLAUDE.md | 2 ++ 5 files changed, 9 insertions(+) 「どのCLAUDE.mdがどこにあるか」を把握していないと、レビューが大変です。 理由2: 新メンバーのオンボーディング 新メンバー: 「このプロジェクトのルールってどこにありますか?」 中央集権: 「.claude/rules/ を見てください」 分散管理: 「えーと、各ディレクトリにCLAUDE.mdがあって...」 理由3: ルールの重複・矛盾を防げる 分散管理では、同じルールを複数のCLAUDE.mdに書いてしまうことがあります。 # frontend/CLAUDE.md コンポーネントは関数コンポーネントで書いてください。 # frontend/components/CLAUDE.md Reactコンポーネントは関数形式を使用してください。 ← 重複! 中央集権なら、 rules/react.md に一本化できます。 paths: frontmatter の使い方 「でも、フロントエンドとバックエンドで違うルールを適用したい」という場合は、 paths: を使います。 注意 : glob パターンは必ず引用符( " )で囲んでください。 * や { で始まるパターンは YAML の予約文字として解釈されるため、引用符がないとパースエラーになります。 # .claude/rules/frontend.md --- paths: - "src/frontend/**/*" - "src/components/**/*" --- # フロントエンドルール - React は関数コンポーネントを使用 - スタイルは Tailwind CSS - 状態管理は Zustand # .claude/rules/backend.md --- paths: - "src/api/**/*" - "src/services/**/*" --- # バックエンドルール - FastAPI を使用 - 型ヒントは必須 - Pydantic でバリデーション これで、該当ディレクトリで作業する時だけルールが適用されます。 特殊なディレクトリではCLAUDE.mdが生きる 「じゃあ、ディレクトリ別CLAUDE.mdは不要?」 いえ、 特殊なディレクトリ では CLAUDE.md が有効です。 特殊なディレクトリとは 「他のコードとは性質が違う」ディレクトリです。 ディレクトリ なぜ特殊か docs/ コードではなくドキュメント。執筆ルールが必要 experiments/ 実験的コード。品質基準が通常と異なる legacy/ レガシーコード。触り方に注意が必要 例1: docs/CLAUDE.md docs/ ディレクトリは、他のMarkdownファイルとは性質が違います。 コード内のコメントやREADME → 開発者向け、簡潔に docs/ 内のMarkdown → 読者向け、丁寧に説明 # docs/CLAUDE.md このディレクトリはブログ記事・ドキュメントの執筆用です。 ## 他のMarkdownとの違い - README.md → 開発者向け、簡潔に - docs/ 内 → 読者向け、丁寧に説明 ## 執筆ルール - 文体:ですます調 - 見出し:H2から開始 - コードブロック:必ず言語を指定 - 画像:alt テキストを必ず含める ## ディレクトリ構成 - `docs/article/` - ブログ記事の下書き - `docs/research/` - 調査結果 - `docs/specs/` - 仕様書(変更不可) これは paths: で指定するより、 docs/CLAUDE.md として置いた方が直感的です。 例2: experiments/CLAUDE.md 実験的コードは、品質基準が通常と異なります。 # experiments/CLAUDE.md このディレクトリは実験的なコード用です。 ## 通常のコードとの違い - テストは不要 - ドキュメントは最低限でOK - 動けばいい(リファクタリング不要) ## 注意 - 本番コードにコピペしないこと - 実験が成功したら、ちゃんと書き直して別ディレクトリへ なぜ paths: より CLAUDE.md が良いのか 文脈が自己完結する : そのディレクトリを開けば、ルールが分かる READMEと同じ感覚 : 人間にとっても分かりやすい 特殊性が明示される : 「ここは他と違う」が伝わる GitHub Copilot との比較 ここで、GitHub Copilot との設計思想を比較してみましょう。 対応関係 概念 Claude Code GitHub Copilot 中央集権 .claude/rules/ + paths: *.instructions.md + applyTo: 分散管理 ディレクトリ別 CLAUDE.md (なし?) 構文の比較 Claude Code: # .claude/rules/api.md --- paths: - "src/api/**/*.ts" --- # APIルール GitHub Copilot: # api.instructions.md --- applyTo: "src/api/**/*.ts" --- # APIルール ほぼ同じ思想ですね。キーが paths: か applyTo: かの違いだけ。 両ツールの収束傾向 前回記事でも触れましたが、個人的には Claude Code と GitHub Copilot の設定方法は 集約されつつあるのでは? と感じています。 条件付き適用(glob パターン) 複数ファイルへの分割 Markdownベースの設定 片方を学べば、もう片方にも応用できます。 推奨構成:ハイブリッドアプローチ まとめると、こうなります: project/ ├── CLAUDE.md # プロジェクト全体の基本方針(薄く) ├── .claude/ │ └── rules/ │ ├── code-style.md # コードスタイル(グローバル) │ ├── frontend.md # フロントエンド(paths指定) │ ├── backend.md # バックエンド(paths指定) │ └── security.md # セキュリティ(グローバル) ├── docs/ │ └── CLAUDE.md # ドキュメント固有(特殊) └── experiments/ └── CLAUDE.md # 実験用(特殊) 判断フロー まとめ 状況 推奨 チーム開発 中央集権(.claude/rules/) 大規模プロジェクト 中央集権(.claude/rules/) 特殊なディレクトリ 分散管理(CLAUDE.md) 個人開発・小規模 どちらでもOK ポイント: 基本は中央集権 : .claude/rules/ でルールを一元管理 特殊なディレクトリだけ分散 : docs/ 、 experiments/ など 両者は補完関係 : 排他的に選ぶ必要はない Claude Code と GitHub Copilot、どちらも「中央管理 + 条件付き適用」の方向に進化しています。今のうちにこの設計パターンを身につけておくと、ツールが変わっても応用が効きますよ。 参考リンク 公式ドキュメント Claude Code Memory – CLAUDE.md と .claude/rules/ の公式説明 GitHub Copilot Custom Instructions 関連記事 Claude Code→GitHub Copilot移行で使える設定ファイル6つの対応表 ここまで読んでいただき、ありがとうございました! 設定ファイルの置き場所、地味だけど長期的には効いてくる設計判断です。チーム開発では特に、「どこを見ればルールが分かるか」を明確にしておくと、みんなが幸せになれます。 ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Code: CLAUDE.md vs .claude/rules/ の実践的な使い分け first appeared on SIOS Tech Lab .
はじめに ども!龍ちゃんです。Claude Codeを使っていて、ドキュメントが増えてきていませんか? 以前、 /research コマンドで調査品質を安定させる記事 を書きました。調査結果が docs/research/ に蓄積されていくのは便利なんですが、気づいたら ドキュメントが爆増 していました。 こんな悩みが出てきたんですよね: どこに何があるか分からない : 「あの調査結果、どこだっけ?」 同じ調査を繰り返す : 既存のドキュメントに気づかず重複作業 全部読み込むとトークンが… : コンテキストが膨らんでコスト増 今回は、この問題を READMEインデックス + AI自動メンテナンス で解決する方法を紹介します。 この記事で紹介すること READMEをドキュメントの「目次」として設計する方法 Claude Codeに確実に読み込ませる @import 構文 Skills/Commandsでインデックス更新を自動化する方法 関連記事 記事 内容 Markdown保存でトークン削減 Fetch時のトークン削減テクニック /research コマンドの紹介 調査品質を安定させるコマンド この記事 増えたドキュメントの管理方法 解決策:READMEインデックス戦略 方針はシンプルです: READMEにインデックス(目次)を作る Claude Codeに確実に読み込ませる メンテナンスをAIに丸投げする これにより、Claudeは全ファイルをスキャンせずに、必要なドキュメントだけを選択的に読み込めます。 前提知識:Claude Codeが自動で読むファイル まず、Claude Codeが 自動的に読み込むファイル を確認しておきましょう。 ファイル 自動読み込み CLAUDE.md / CLAUDE.local.md される .claude/rules/*.md される README.md されない README.mdは自動読み込みの対象ではありません。 ただし、以下の方法で読み込ませることができます: @import 構文でCLAUDE.mdから参照 Skills/Commandsで明示的に「READMEを読め」と指示 体感として : Claudeはタスク遂行中にREADMEを探索して読むことが多いです。ただ、それは自発的な行動なので 確実ではない 。確実に読ませたい場合は @import を使いましょう。 実装方法 1. READMEインデックスの設計 docs/research/README.md の例です: # Research Documents 調査結果をまとめたドキュメント集です。 ## 調査一覧 ### Claude Code | ファイル | 調査内容 | 調査日 | |----------|----------|--------| | [claude-code-hooks-skills](./2026-01-06-claude-code-hooks-skills.md) | Hooks/Skills/Commands の使い分け | 2026-01-06 | | [claude-code-skills-best-practices](./2026-01-23-claude-code-skills-best-practices.md) | Skillsのベストプラクティス | 2026-01-23 | ### Azure | ファイル | 調査内容 | 調査日 | |----------|----------|--------| | [azure-container-apps-deploy](./2026-01-07-azure-container-apps-deploy.md) | Container Apps デプロイ方法 | 2026-01-07 | ポイント: カテゴリ別にテーブルで整理 ファイル名、概要、日付を含める Claudeがこれを読めば全体構造を把握できる 2. CLAUDE.mdでの@import設定 CLAUDE.mdに以下を追加すると、起動時に自動で読み込まれます: # CLAUDE.md ## ドキュメント参照 See @docs/research/README for research documents index. この @path/to/file 構文により、CLAUDE.md読み込み時にREADMEも一緒に読み込まれます。 3. なぜCLAUDE.mdではなくREADMEにインデックスを置くのか 「インデックスをCLAUDE.mdに直接書けばいいのでは?」と思うかもしれません。 READMEに置く理由: 観点 README CLAUDE.md 人間も参照する する あまりしない GitHubで表示される される されない 役割 ドキュメントの目次 Claudeへの指示 関心の分離 ができて、メンテナンスもしやすくなります。 応用:Skills/Commandsで自動メンテナンス インデックスを作っても、 更新を忘れたら意味がない ですよね。 そこで、Skills/Commandsのワークフローに組み込んで自動化します。 /research コマンドでの実装例 僕の /research コマンドでは、以下のステップを組み込んでいます: ### Step 0: Check Existing Research Before starting new research, **always read `docs/research/README.md`** to: 1. Check if the topic has already been researched 2. Identify related research that can be referenced 3. Avoid duplicate work ### Step 5: Update README.md After saving the research document, **always update `docs/research/README.md`** 効果: 課題 解決策 インデックス更新を忘れる Commandのワークフローに組み込み 重複調査してしまう Step 0で既存ドキュメントを確認 フォーマットがバラバラ Claudeが一貫した形式で更新 これで、 人間がREADME更新を意識する必要がなくなります 。 補足:.claude/rules/ でも対応可能 2025年12月にリリースされた .claude/rules/ を使う方法もあります( 公式ドキュメント )。 # .claude/rules/readme-update.md --- paths: - "docs/**/*.md" --- ドキュメントを追加・編集した場合は、一番近い階層のREADME.mdを更新してください。 paths を指定すると、該当ファイル作業時のみルールが適用されます。 ディレクトリ別CLAUDE.mdとの比較: 方法 特徴 ディレクトリ別CLAUDE.md 各ディレクトリに配置、そのディレクトリ作業時に読み込み .claude/rules/ + paths 中央で管理、glob パターンで適用範囲を制御 READMEインデックス戦略と組み合わせることも可能です。 まとめ:結果的にAIフレンドリーな設計になる READMEインデックス戦略のポイント: READMEにドキュメントの目次を作る @import で確実に読み込ませる Skills/Commandsでメンテナンスを自動化 これって、結果的に AIフレンドリーな設計 になっているんですよね: AIが必要な情報を効率的に見つけられる AIがメンテナンスを担当できる 人間にとっても分かりやすい構造 ドキュメントが増えてきたら、ぜひ試してみてください。 参考リンク 公式ドキュメント Claude Code Memory 関連記事 Markdown保存でトークン削減 /research コマンドの紹介 ここまで読んでいただき、ありがとうございました! ドキュメント管理は地味だけど、放置すると後で困る作業。AIに丸投げして楽しましょう。 ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Code設計術:AIフレンドリーなドキュメント管理 first appeared on SIOS Tech Lab .
Webフォームの実装において、エンジニアが神経を使う処理の一つが「バリデーション(入力値検証)」ではないでしょうか。正規表現を駆使し、XSS(クロスサイトスクリプティング)を防ぎ、データベースの整合性を守る――これはシステムを守るための堅牢な盾です。 しかし、視点を「ユーザー体験(UX)」に移したとき、バリデーションエラーは盾ではなく、ユーザーをゴールへ導く「案内」でなければなりません。 今回は、システム的な正しさとユーザーの使いやすさを両立させるための、バリデーションエラーの「伝える技術」について、特に 「ユーザーを責めないメッセージング」 に焦点を当てて解説します。 エラーメッセージの役割とは? 開発者にとってのエラーは「無効なデータ」の検出ですが、ユーザーにとってのエラーは「対話の拒絶」に映ります。 一生懸命に入力したフォームで、送信ボタンを押した瞬間に真っ赤な文字で「入力内容に誤りがあります」と表示される体験は、試験の解答用紙を埋め、提出した瞬間に、「名前が枠からはみ出ているので受け取りません」と無慈悲に告げられるようなものです。 優れたUIにおけるエラーメッセージの役割は、 「誤りの指摘」ではなく「解決策の提示」 です。 1. 伝える「タイミング」 メッセージの内容に入る前に、それを「いつ」伝えるかというUIの挙動について整理します。適切なタイミングは、ユーザーのストレスを大幅に軽減します。 入力完了時が基本 最もバランスが良いのは、ユーザーがそのフィールドの入力を終えて次の項目へ移動した(フォーカスが外れた)タイミングです。 入力中にリアルタイムで「メールアドレスの形式が不正です」と出し続けるのは避けましょう。まだ入力途中なのに「間違っている」と判定されるのは、ユーザーにとって過干渉であり、ストレスになります。 即時反映をが有効な例外 パスワードの強度チェックや、ユーザー名の重複確認など、「入力し終わってからダメだと言われるとダメージが大きい項目」については、入力中のリアルタイム判定が有効です。また、「全角カナのみ」のように制約が厳しい場合も、入力中にフィードバックを返すのが有効な場合があります。 送信時は最終手段 検証を送信ボタン押下時に行うのは、サーバーサイドでの整合性チェックなど、クライアント側で判定できないものに限定しましょう。例えば、長いフォームを入力し終えた後に最初の方のミスを指摘されるのは、離脱率を高める要因になります。 2. ユーザーを責めない「ライティング」 ここからが本題です。エラーメッセージの文言一つで、システムの人格が決まります。大切なのは 「ユーザーは悪くない、システムの説明不足である」 というスタンスを取ることです。 原則1:曖昧さを排除し、解決策を提示する つい書いてしまいがちなのが、事実だけを告げるメッセージです。 × 悪い例: 無効な入力です × 悪い例: エラーが発生しました (Code: 400) これらは「何が」間違っていて、「どうすれば」直るのかが分かりません。ユーザーを迷子にさせないためには、具体的なアクションを提示します。 〇 良い例: @を含めたメールアドレスの形式で入力してください 〇 良い例: パスワードは8文字以上必要です 「不正な文字が含まれています」ではなく、「半角英数字で入力してください」と 「やるべきこと」 を書きましょう。 原則2:否定形を避け、肯定的な表現を使う 「禁止」「不正」「不可」といった強い否定語は、ユーザーに「怒られている」ような印象を与えます。これらはシステム視点の言葉です。 × 悪い例: 半角数字以外は入力禁止です × 悪い例: そのユーザー名は使用できません これを、ガイドするような肯定的な表現に書き換えます。 〇 良い例: 半角数字で入力してください 〇 良い例: このユーザー名はすでに使われています。別の名前を入力してください 「〜しないでください」ではなく、「〜してください」とポジティブな指示に変換することで、対話の質が変わります。 原則3:システム都合の専門用語を使わない データベースのカラム名や、バリデーションライブラリのデフォルトメッセージがそのまま表示されていませんか? × 悪い例: String型で入力してください × 悪い例: このフィールドは必須です ユーザーの言葉に翻訳しましょう。 〇 良い例: 数字ではなく文字で入力してください 〇 良い例: お名前を入力してください 原則4:ユーザーの努力を無にしない 最も避けるべきは、システムエラーなどで入力内容がすべて消えてしまうことです。バリデーションエラーが発生した際は、入力された値を保持することが大前提です。 また、「全角で入力された数字をシステム側で半角に変換する」など、エラーとしてはじく前に システム側で吸収できる揺らぎはないか を検討するのも、重要な「優しさ」です。 3. 視覚的な「伝える技術」 最後に、メッセージの見た目についてです。 色だけに頼らない 「赤文字=エラー」は定石ですが、色覚多様性を持つユーザーには、赤色が警告として認識しづらい場合があります。 色だけでなく、 アイコン(!や×マーク) を併用する、あるいは太字にするなど、形状の変化でも状態を伝えるようにしましょう。(アクセシビリティの確保) 入力欄との近接性 エラーメッセージをフォームの一番上にまとめて表示するパターンがありますが、項目数が多い場合、どの項目がエラーなのかを探す手間が発生します。 エラーメッセージは、**該当する入力フィールドの直下(または直近)**に表示し、色を変えた枠線などで関連付けを明確にします。 まとめ:エラー表示にこそ、性格が出る 正常系のルートは、誰が設計しても似た画面になります。しかし、異常系・準正常系であるエラー表示には、作り手の配慮やサービスの質が色濃く反映されます。 バリデーションエラーは、ユーザーがゴールにたどり着くための最後のハードルです。 「間違っています」と冷たく突き放すのではなく、「こうすればうまくいきますよ」と寄り添う。そんな「ユーザーを責めないUI」を、ぜひ意識してみてください。 同じ趣旨の記事、 「エラーダイアログの「説明責任」:ユーザーを救う3つの要素」 もご覧ください。 ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post バリデーションエラーの「伝える技術」:ユーザーを責めずに導く first appeared on SIOS Tech Lab .
はじめに ども!GitHub Copilotを使い倒すために重い腰を上げた龍ちゃんです。半年ぐらいかけてClaude Codeを使えるようになったので、次はGitHub Copilotということで関連ブログを出しています。 前回は GitHub Copilot設定5種を網羅!生産性を最大化する使い分け術 で網羅的に設定ファイルを紹介しましたが、今回は コミットメッセージの自動生成 にフォーカスします。 さて、2年前に「 Gitのコミットメッセージをしっかり書こうという話【備忘録的共有】 」という記事を書きました。テンプレートを設定して「ちゃんと書こう」という内容でしたね。上司に注意された勢いで書いた記事です。 ありがたいことにXで反応をいただきまして、「PRをしっかり書けばコミットメッセージはいらなくない?」という意見もありました。これはチーム依存ですね。重要なのは チーム内でルールが統一されていること だと思っています。 あれから2年、AIがコードを書く時代になりました。 コミットメッセージもAIに任せてみよう というのが今回のテーマです。しかも、2年前に設定したテンプレートに沿った形式でAIが書いてくれます。 今回は、VS Codeでコミットメッセージを自動生成する2つの方法を紹介します。 検証環境 VS Code 1.108.2 GitHub Copilot 1.388.0 GitHub Copilot Chat 0.36.2 検証日: 2026年1月26日 結論: コミットメッセージ生成方法一覧 まずは結論から。VS Codeでコミットメッセージを自動生成する方法は2つあります。 方法 操作 カスタム指示 おすすめ スパークルアイコン ソースコントロールパネルで✨クリック commitMessageGeneration.instructions GUI派向け ターミナルインラインチャット Ctrl+I → 指示入力 .github/copilot-instructions.md ターミナル派向け ポイント : どちらもカスタム指示でチームのルールに沿った形式に統一できます。 それでは、それぞれの方法を詳しく見ていきましょう。 方法1: スパークルアイコン(GUI派向け) 最も簡単な方法です。ソースコントロールパネルのスパークルアイコン(✨)をクリックするだけ。 手順 変更をステージング ソースコントロールパネルを開く( Ctrl+Shift+G ) コミットメッセージ欄の スパークルアイコン(✨) をクリック 生成されたメッセージを確認・編集 コミット 赤枠で囲んだ部分がスパークルアイコンです。クリックすると、ステージされた変更内容を分析してコミットメッセージを生成してくれます。 メリット ワンクリック で生成できる GUIで直感的に操作できる 生成結果をその場で編集できる 方法2: ターミナルインラインチャット(ターミナル派向け) ターミナルで作業している人向けの方法です。 Ctrl+I でインラインチャットを起動して、コミットメッセージの生成を依頼します。 手順 git add で変更をステージング ターミナルで Ctrl+I (Mac: Cmd+I )を押す 「ステージされた変更に対するコミットメッセージを生成して」と入力 生成されたコマンドを確認 Ctrl+Enter で実行、または Alt+Enter で挿入して編集 ターミナルでインラインチャットを起動し、コミットメッセージの生成を依頼した様子です。 docs: ドキュメントを追加 というメッセージが生成され、 git commit -m "..." コマンドとして提案されています。 メリット ターミナルから離れずに 操作できる 生成されたコマンドをそのまま実行できる 自然言語で細かい指示を出せる カスタム指示でコミットメッセージ形式を統一する デフォルトでも十分使えますが、チームでコミットメッセージの形式を統一したい場合はカスタム指示を設定しましょう。 設定方法一覧 設定場所 適用範囲 設定方法 settings.json スパークルアイコン commitMessageGeneration.instructions .github/copilot-instructions.md 全体(インラインチャット含む) ファイルに記述 settings.json での設定 スパークルアイコンでの生成に適用される設定です。 { "github.copilot.chat.commitMessageGeneration.instructions": [ { "text": "Use format: tag: message" }, { "text": "Tags: feature, fix, refactor, docs" }, { "text": "Write message in Japanese" } ] } copilot-instructions.md での設定 .github/copilot-instructions.md に記述する方法です。こちらはプロジェクト全体に適用されます。 ## Git Commit Messages When generating git commit messages: - Format: `tag: message` - Use one of these tags: - feature: 機能追加・更新 - fix: バグ修正 - refactor: リファクタリング - docs: ドキュメント - Write message in Japanese - Keep subject under 50 characters 検証結果: インラインチャットにも適用される 今回の検証で面白い発見がありました。 発見(2026-01-26検証) : .github/copilot-instructions.md の指示は、ターミナルインラインチャット( Ctrl+I )にも適用されます。公式ドキュメントには明記されていませんが、実機検証で確認しました。 つまり、 .github/copilot-instructions.md にコミットメッセージの形式を書いておけば、スパークルアイコンでもインラインチャットでも同じ形式で生成されます。チームで統一したい場合は、こちらの方法がおすすめです。 2年前のテンプレートをCopilotで再現 2年前の記事 では、以下のようなテンプレート形式を紹介しました。 # Tag: message # Tags: # feature: 機能追加・更新 # refactor: リファクタリング # fix: バグ修正 この形式をカスタム指示に設定すれば、Copilotが同じ形式でメッセージを生成してくれます。2年前に手動で書いていたものが、今はAIが書いてくれる。時代の進歩を感じますね。 まとめ 2年前と今 時期 アプローチ 2年前 テンプレートを設定して「ちゃんと書こう」 今 テンプレートに沿ってAIが書いてくれる 使い分け GUI派 → スパークルアイコン(✨)をクリック ターミナル派 → Ctrl+I でインラインチャット どちらもカスタム指示でチームのルールに沿った形式に統一できます。 .github/copilot-instructions.md に書いておけば、両方に適用されるのでおすすめです。 注意点 生成結果は必ず確認してからコミットしましょう。AIは補助ツールです。 2年前に上司から言われた金言は今も有効です: 「何をしたかはGit見たらわかるから、なんでこの変更を加えたかを知りたいんだよねぇ~」 AIが生成したメッセージも、この観点でチェックしてから使いましょう。 参考リンク 公式ドキュメント VS Code AI Smart Actions VS Code Source Control VS Code Custom Instructions VS Code Terminal Inline Chat 関連記事(SIOS Tech Lab) Gitのコミットメッセージをしっかり書こうという話【備忘録的共有】 – コミットメッセージテンプレートの基本 GitHub Copilot設定5種を網羅!生産性を最大化する使い分け術 – 設定ファイルの全体像 Claude Code→GitHub Copilot移行で使える設定ファイル6つの対応表 – ツール間の対応関係 ここまで読んでいただき、ありがとうございました! コミットメッセージの自動生成、ぜひ試してみてください。 ご覧いただきありがとうございます! この投稿はお役に立ちましたか? 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post 【2026年版】GitHub Copilotでコミットメッセージを自動生成する2つの方法 first appeared on SIOS Tech Lab .