AIと一緒に仕様書を書く ども！最近AIを使った仕様書作りの検証とかに取り組みだした龍ちゃんです。 「AIと人間の両方で仕様書を効率的に管理するため」にはという課題に取り組んでいた時の内容です。 今回はAIツールを開発に使ってるチームで、仕様書をGitで管理してる人向けの話です。 この記事で話すこと: なぜ仕様書の図はAIに伝わりにくいのか 図解にソースコードを添える設計パターン（3パターン） 実際に試して分かった制約と注意点 まず完成形のイメージを見せます。 <!-- この図のソースコード（AI向け）: sequenceDiagram Client->>+Server: ログインリクエスト Server->>+DB: ユーザー照合 DB-->>-Server: 結果 Server-->>-Client: トークン発行 設計意図: DB直接参照を避け、サービス層を経由する設計。 理由: テスタビリティとマイクロサービス移行への備え。 -->  これはMarkdownファイル（ .md ）に書きます。リポジトリの docs/ 配下に仕様書として置いておくだけ。今はなんとなく雰囲気だけ掴んでもらえればOKです。具体的な書き方は後で3パターン紹介します。 このコメントには3つ詰め込んでます。 図のソースコード （Mermaid記法）→ AIが構造を正確に読める 設計意図 （なぜこの構造にしたか）→ AIが「なぜ」を理解できる 注釈 （制約や前提条件）→ AIがスコープを把握できる 人間はPNG画像を見るだけで、AIはHTMLコメントの中身を読む。両方が同じファイルに収まることでAIの理解と人間の視認性を確保することができます。 今の仕様書、AIに読める形になってますか？ 「仕様書にきれいな図を描いた。シーケンス図、アーキテクチャ図、状態遷移図。人間のレビューは問題なく通る。」 でもこの仕様書、AIに渡したらどうなるか考えたことありますか？ AIは仕様書の図を「推測」で読んでいる 試しに仕様書の図をAIに見せて「この設計について説明して」と聞いてみてください。それっぽい回答が返ってきます。実際には、2つの「推測」が存在しています。 推測その1: 構造の推測 PNG画像からAIが読み取る構造は、厳密ではないです。矢印の方向、条件分岐の条件、サービス間の依存関係。人間なら「見ればわかる」ものも、AIは画像のピクセルから推測しています。シンプルな図なら当たることが多いけど、複雑になるほど精度が落ちます。 推測その2: 意図の推測 仮に構造を正確に読めたとしても、「なぜこの構造にしたのか」は画像のどこにも書いてない。「なぜこの構成にしたのか」「なぜこのサービスを分けたのか」。AIは設計意図を推測するしかない。推測が当たることもあるけど、外れることもある。 つまりAIは、構造も意図が含まれていなければ推測が入ります。これからAI駆動開発を始めたい人も、既にやってる人も、ここがボトルネックになります。 じゃあ全部テキストで書けばいい？ テキストだけの仕様書だと人間が読むのがしんどいんですよね。構造が一目でわからない。フローの分岐とか、サービス間の依存関係とか、図解があるから仕様書として機能してる部分があります。 推測をなくすには ここにジレンマがあって。 人間のためにはPNG画像がほしい AIのためにはテキスト（Mermaid/PlantUMLコード + 設計意図）がほしい ソースコードを添えれば構造の推測がなくなる。設計意図を書いておけば意図の推測がなくなる。この2つをセットで、同じファイル内に持たせる方法があります。次のセクションで具体的に見せます。 図解にソースコードを添える — 人間の視認性とAIの理解を両立する ここからが本題です。 やることはシンプルで、Markdownの仕様書内で図のPNG画像の直前に、HTMLコメントとして以下を書く。 Mermaid/PlantUMLのソースコード — 図の構造そのもの 設計意図 — なぜこの構造にしたか 注釈 （必要なら）— 異常系の考慮、将来の拡張方針など 人間の視認性とAIの理解、両方を1つのファイルで実現する方法です。 なぜHTMLコメントなのか Markdownの中にHTMLコメント（ <!-- --> ）を書くと、GitHubやドキュメントビューアで表示されない。人間がドキュメントを読むときには見えないんですよね。 でもAI（Claude CodeやCopilot等）がファイルを読むときは、HTMLコメントの中身もテキストとして見える。 つまり「人間には見えないけどAIには見える」メモ欄として機能する。人間は画像を見る。AIはコメントの中身を読む。お互い干渉しない。 リポジトリに置くだけでいい 自分がこのパターンを気に入ってる理由は、「食わせる（AIへのコンテキスト注入）」作業が簡単になるという点です。 GitリポジトリのMarkdownにHTMLコメント付きで置いておくだけで、Claude Codeが勝手に読んでくれる。Claude Codeはプロジェクトのリポジトリ内のファイルを直接参照できるので、わざわざプロンプトに貼り付ける必要がない。RAGの仕組みを作る必要もない。リポジトリにあるドキュメントをAIが自然に参照できる状態にしておくだけ。 これは自分が以前書いた「 AIフレンドリーなドキュメント管理 」や「 調査→構造化→注入の設計パターン 」の記事と同じ考え方です。テキストドキュメントをリポジトリに集約するアプローチの「図解版」ですね。 「それ、二重管理じゃない？」 この後のパターン集では  のようにPNG画像を参照する形で書いてます。「ソースコードとPNG画像の両方を管理するのは二重管理では？」という疑問が出ると思います。 結論から言うと、 PNG画像が必要になるタイミングとソースコードが必要になるタイミングは別 なので、問題にならないかなと考えています。 エンジニア同士で設計を進めるフェーズでは、Mermaid/PlantUMLのソースコード + テキスト注釈だけで十分。AIも読める。ここでは図の記法で爆速で構造を整理していくことに集中すればいい PNG画像が必要になるのは、非エンジニア（お客さん、品質管理チームなど）に資料を出すタイミング。その瞬間にソースコードから生成すればいい 生成はMermaid CLIやPlantUML Web Service・HTML＋Claude Codeを使用して自動化できる 管理するのはソースコードだけ。PNG画像は必要なときに生成する出力物 。二重管理ではなく「ソースが1つ、出力が必要なときに作る」という発想です。Claude Codeを使えばMermaidもPlantUMLも爆速で書けるので、ソースコードの作成・修正も苦になりません。具体的な方法は以下の記事で解説しています。 Mermaid/PlantUMLを知らなくても始められる 記法を知らないから無理、と思った人もいるかもしれません。でもAIに「この図のMermaidコードを書いて」と頼めば書いてくれます。既存のPNG画像を渡して「このPNG画像をMermaid記法に変換して」という方法もあります。 入門（ソースコード作成） ClaudeでMermaid図作成を自動化！2時間→5分の劇的時短術 Claude Codeで仕様書のPlantUML図を自動生成 — VS Codeプレビューで完結 発展（見た目カスタマイズ + PNG変換） Mermaid × Tailwind CSS — ハイブリッド図解の作り方 PlantUMLの表現力をTailwind CSSで設計書品質に仕上げる 記法の習得はあとからで大丈夫です。最初の一歩としては、設計意図のコメントを書くところから始めてみてください。 実装パターン集 ここからは具体的なコードサンプルを3つ見せます。全部コピペして使えます。自分の仕様書に近いパターンを選んでください。 パターン1 : シーケンス図（API設計書の認証フローなど） パターン2 : アーキテクチャ図（マイクロサービス構成など） パターン3 : 状態遷移図（注文ステータス管理など） まず: Mermaid と PlantUML どっちを使う？ ソースコードの記法は2種類あります。迷ったらこの表で判断してください。 こういう図なら こっちを使う フローチャート、簡易シーケンス図、状態遷移、ER図 Mermaid アクティビティ図、ユースケース図、コンポーネント図 PlantUML UML準拠が求められる設計書 PlantUML 10ノード以上の大規模な図 PlantUML 迷ったらMermaidで始めて、限界を感じたらPlantUMLに切り替えればいい。AIとの相性はMermaidが最高、PlantUMLも高い。どちらを選んでもAIは読み取れます。 パターン1・3はMermaid、パターン2はPlantUMLで書いてます。使い分け表の通り、コンポーネント構成はPlantUMLのほうが得意です。 設計意図の書き方 パターンに入る前に1つだけ。前のセクションではHTMLコメントに「何を入れるか」（ソースコード・設計意図・注釈）を説明しました。ここでは設計意図の「書き方」の話です。ソースコードだけ貼っても、AIは構造は読めるけど「なぜ」がわからない。コメント内に最低限書くべきはこの3つ。 設計意図 : なぜこの構造にしたか（1-2行） 制約・前提 : この設計が成り立つ条件（あれば） スコープ外 : この図が扱わない範囲（あれば） 全部書く必要はないです。「なぜ」だけでも十分価値がある。以下の3パターンで書き分けの実例を見せます。 パターン1: シーケンス図 + 設計意図コメント ユースケース : API設計書の認証フロー <!-- AI向けソースコード: sequenceDiagram Client->>+API Gateway: POST /auth/login API Gateway->>+Auth Service: validateCredentials() Auth Service->>+User DB: findByEmail() User DB-->>-Auth Service: User Auth Service-->>-API Gateway: JWT Token API Gateway-->>-Client: 200 OK + Token 設計意図: Gateway がトークン発行の責務を持たず、Auth Service に委譲。 理由: 認証ロジックの変更（OAuth追加等）時に Gateway を触らなくて済む。 注意: Rate Limiting は Gateway 側で実装。Auth Service には到達しない前提。 -->  上記のソースコードから生成した図がこちら。右側の注釈パネルは、HTMLコメント内の設計意図をビジュアル化したもの。 人間が見るもの : きれいなシーケンス図の画像 AIが読むもの : Mermaidコード + 「なぜGatewayがトークンを発行しないか」の設計意図 制約 : Mermaidシーケンス図は4参加者・8メッセージ以下が読みやすい（検証済み） パターン2: アーキテクチャ図 + 責務定義コメント ユースケース : システム構成書のマイクロサービス構成 <!-- AI向けソースコード: @startuml package "Frontend" { [SPA - React] as SPA [BFF - Next.js] as BFF } package "Backend" { [Auth Service] as Auth [User Service] as User [Order Service] as Order } package "Data" { database "User DB" as UserDB database "Order DB" as OrderDB database "Redis Cache" as Cache } SPA --> BFF BFF --> Auth BFF --> User BFF --> Order Auth --> UserDB User --> UserDB User --> Cache Order --> OrderDB Order --> Cache @enduml 責務定義: - BFF: フロントエンド専用のAPI集約層。バックエンドサービスへの直接アクセスを防ぐ - Auth Service: 認証・認可のみ。ユーザー情報の参照はUser Serviceに委譲 - Cache: Read-through パターン。書き込みはDB直接 技術的制約: サービス間通信は gRPC。BFF→Backend のみ REST -->  上記のソースコードから生成した図がこちら。責務定義が右側の注釈パネルに対応している。 人間が見るもの : マイクロサービスの全体像が一目でわかる構成図 AIが読むもの : PlantUMLコード + 各サービスの責務定義 + サービス間の通信方式 + キャッシュ戦略 PlantUMLの利点 : database や queue の専用記号が使える。パッケージでレイヤーを明示できる パターン3: 状態遷移図 + 異常系注釈コメント ユースケース : 業務フロー仕様書の注文ステータス管理 <!-- AI向けソースコード: stateDiagram-v2 [*] --> 注文受付 注文受付 --> 在庫確認中 在庫確認中 --> 決済処理中: 在庫あり 在庫確認中 --> キャンセル: 在庫なし 決済処理中 --> 出荷準備中: 決済成功 決済処理中 --> 決済エラー: 決済失敗 決済エラー --> 決済処理中: リトライ(最大3回) 決済エラー --> キャンセル: リトライ上限超過 出荷準備中 --> 出荷済み 出荷済み --> 配達完了 配達完了 --> [*] キャンセル --> [*] 異常系の設計: - 決済エラー → リトライは最大3回。exponential backoff（1秒→2秒→4秒） - 在庫なし → 即キャンセル。仮押さえはしない設計（在庫ロック競合を避ける） - 出荷後のキャンセル → この図の範囲外。返品フローは別仕様書を参照 -->  上記のソースコードから生成した図がこちら。正常系（青）と異常系（赤）を色で区別している。 人間が見るもの : 注文の正常系・異常系が一目でわかる状態遷移図 AIが読むもの : 状態遷移のルール + 異常系のリトライ戦略 + スコープ外の明示 制約 : 状態遷移図は8-10状態が上限（検証済み。それ以上は縦に伸びて見切れる） 3つのパターンに共通しているのは、 ソースコードだけでなく「なぜ」を書いている こと。パターン1は設計意図、パターン2は責務定義、パターン3は異常系の設計判断。AIが読んで「この設計の理由」まで理解できる状態にしてます。 実際に試して分かったこと ここまでのパターンを実際に検証して分かった注意点を2つ共有します。 ノード数の上限は思ったより低い Mermaidで図を描くとき、ノード（箱や状態）を増やしすぎると自動縮小されて文字が読めなくなります。1280x720pxの描画領域で検証した推奨上限はこれです。 図の種類 推奨上限 フローチャート 8-10ノード シーケンス図 4参加者・8メッセージ 状態遷移図 8-10状態 上限を超えたら図を分割してください。1つの図に全部詰め込みたくなる気持ちはわかるけど、分割したほうが人間にもAIにも読みやすい。 PlantUMLはサーバー側で描画するので、Mermaidほど厳しくないです。10ノード以上の大規模な図が必要なら、PlantUMLのほうが安全。 本当にAIが読み取れるのか？ — 試してみてほしい 「HTMLコメントをAIが読めるって言うけど、本当に？」と思った人へ。自分で試すのが一番早いです。 パターン1のMarkdownをそのままファイルに保存する Claude Code（またはお好みのAIツール）にそのファイルを読ませる 「この仕様書の認証フローについて説明して。設計意図も含めて」と聞く HTMLコメント内の設計意図まで含めて回答してくれるはずです。「GatewayはRate Limitingだけを担当し、トークン発行はAuth Serviceに委譲しています」みたいな回答が返ってきたら、AIがコメントの中身を正確に読み取れている証拠。 やってみてください。 まとめ 仕様書の図を「人間だけが読むもの」から「人間とAIが読むもの」にする。やることはシンプルです。 図のPNG画像の横に、HTMLコメントでソースコードと設計意図を添える。 Mermaid/PlantUMLを使えば、AIが推測ではなく正確に設計構造を理解できる。設計意図を書いておけば「なぜこの構造にしたか」まで伝わる。 「AIに仕様書を食わせる」んじゃなくて、 AIが自然に読める仕様書をリポジトリに置いておく 。これだけ。 これは仕様書を書いてる人にしかできないことです。設計意図を知っているのは仕様書の著者だけだから。このパターンをチーム内で共有しておくと、AIを使ったレビューやコード生成で「設計の意図を汲んだ」出力が得られるようになります。 まずは1つの図から試してみてください。 ほなまた。 関連ブログ・参考リンク 関連ブログ Claude Code設計術：AIフレンドリーなドキュメント管理 今回の記事の前提となる考え方です。テキストドキュメントをリポジトリに集約してAIが自然に参照できる状態を作る設計パターンを解説しています。 Claude Codeに専門知識を仕込む：調査→構造化→注入の設計パターン AIへのコンテキスト注入を「調査→構造化→注入」の3ステップで設計するパターンを紹介。今回のHTMLコメント手法も同じ思想の延長線上にあります。 図解作成、AIに丸投げしたら「たまに自分より上手い」件 Claude CodeのSKILL機能でHTML図解を自動生成し、CLIでPNG変換する方法を紹介しています。図の生成手段を増やしたい人はこちらもどうぞ。 ClaudeでMermaid図作成を自動化！2時間→5分の劇的時短術 Mermaidでフローチャート・シーケンス図・パイチャートを自動生成する方法を解説。今回の記事でソースコードとして使うMermaid記法の書き方はこちらを参照してください。 Claude Codeで仕様書のPlantUML図を自動生成 — VS Codeプレビューで完結 PlantUMLのアクティビティ図・ユースケース図・コンポーネント図をClaude Codeで生成し、VS Code上でプレビューする方法を解説。Mermaidでは作れない図が必要なときはこちら。 Mermaid × Tailwind CSS — ハイブリッド図解の作り方 Mermaid図にTailwind CSSの装飾を組み合わせて設計書品質のPNGに変換する実践方法。見た目をカスタマイズしたいときはこちら。 PlantUMLの表現力をTailwind CSSで設計書品質に仕上げる PlantUML図をTailwind CSSで装飾してPNGに変換するテンプレート付き。コンポーネント図・アクティビティ図・ユースケース図に対応。 参考リンク Mermaid.js公式 Anthropic: Effective Context Engineering for AI Agents ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post 仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン first appeared on SIOS Tech Lab .

テキストベースの図、もっと表現力が欲しい ども！ PlantUML × VS Codeの記事 を書いた龍ちゃんです。 Claude Codeを使って爆速でPlantUMLを書けるようになりました。でも！実際に設計書やブログに貼るとなると「もうちょっと見た目をなんとかしたい」ってなるんですよね。図の横に設計ポイントを添えたり、色を揃えて見やすくしたり。 そこで今回は、PlantUMLの図にTailwind CSSの装飾を組み合わせます。1つのHTMLファイルにPlantUML図 + 注釈パネルをまとめて、PNGに変換する仕組みです。 「なんでPlantUML?」理由はシンプルで、Mermaidではカバーできない図があるからです。 コンポーネント図 — database "PostgreSQL" と書くだけであのドラム型DBアイコンが出る アクティビティ図 — ワークフローの分岐・マージを if/else/endif で描ける ユースケース図 — actor "ユーザー" で棒人間アイコンが出る Mermaidはフロー図やシーケンス図が得意ですけど、この3つは守備範囲外なんですよね。PlantUMLならテキストベースのまま作れます。 Mermaid × Tailwind CSSの組み合わせも同時に記事にしてます。フロー図やシーケンス図を作りたい人は「 Mermaid × Tailwind CSS — ハイブリッド図解の作り方 」をどうぞ。 今回の内容です。 コピペ用テンプレート2種（右サイド注釈型 / 左右均等型） PNG変換の手段3つ 関連記事 : 仕様書の図にソースコードと設計意図を添える方法については「 仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン 」で詳しく書いてます。AIに図の構造を正確に伝えたい人はこちらもどうぞ。 テンプレートA: 右サイド注釈型 コピペして使えるHTMLテンプレートを2種類用意しました。 仕組みはシンプルで、plantuml-encoderというライブラリでPlantUML構文をエンコードしてplantuml.comに投げるだけです。Tailwind CDNとの共存も問題なし。テンプレートをコピペすればそのまま動きます。plantuml.comへの通信が発生するのでネット接続は必要ですが、大抵の開発環境では問題にならないです。 まずはテンプレートA。左にPlantUMLで描画したコンポーネント図、右にTailwind CSSで装飾した注釈パネルを並べるレイアウトです。ドラム型のDB記号やキュー記号が見えるのがPlantUMLならではのポイントですね。 向いてる場面 : 横に広がる図（コンポーネント図、シーケンス図）に設計ポイントを3-4個添えたいとき キャンバスサイズ : 1280x720px <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>コンポーネント図: 3層アーキテクチャ</title> <script src="https://cdn.tailwindcss.com"></script> <script src="https://cdn.jsdelivr.net/npm/plantuml-encoder@1.4.0/dist/plantuml-encoder.min.js"></script> <style> body { width: 1280px; height: 720px; margin: 0; padding: 0; background: white; overflow: hidden; } </style> </head> <body class="p-8"> <div class="h-full flex flex-col"> <!-- タイトル --> <h1 class="text-2xl font-bold mb-6 text-gray-800">コンポーネント図: 3層アーキテクチャ</h1> <!-- メインコンテンツ: 2カラム --> <div class="flex gap-6 flex-1"> <!-- 左: PlantUML図 --> <div class="flex-1 flex flex-col"> <div class="bg-blue-50 border-2 border-blue-300 rounded-lg p-4 flex-1 flex items-center justify-center"> <div id="diagram-container" class="flex items-center justify-center"> <p class="text-gray-500">Loading diagram...</p> </div> </div> </div> <!-- 右: 注釈パネル --> <div class="w-72 flex flex-col gap-4"> <div class="bg-yellow-50 border border-yellow-300 rounded-lg p-4"> <h3 class="font-bold text-yellow-800 mb-2">フロントエンド層</h3> <p class="text-sm text-yellow-900">Web・モバイルの2系統。APIゲートウェイを経由して統一的にアクセス</p> </div> <div class="bg-blue-50 border border-blue-300 rounded-lg p-4"> <h3 class="font-bold text-blue-800 mb-2">バックエンド層</h3> <p class="text-sm text-blue-900">認証・記事・通知をマイクロサービスに分離。ゲートウェイでルーティング</p> </div> <div class="bg-green-50 border border-green-300 rounded-lg p-4"> <h3 class="font-bold text-green-800 mb-2">データ層</h3> <p class="text-sm text-green-900">PostgreSQL + Redis + メッセージキューの3点セット。非同期処理はキュー経由</p> </div> </div> </div> </div> <script> window.addEventListener('DOMContentLoaded', function() { const umlSource = `@startuml skinparam style strictuml skinparam backgroundColor transparent package "フロントエンド" { [Webアプリ] as Web [モバイルアプリ] as Mobile } package "バックエンド" { [APIゲートウェイ] as GW [認証サービス] as Auth [記事サービス] as Article [通知サービス] as Notify } package "データ層" { database "PostgreSQL" as DB database "Redis" as Cache queue "メッセージキュー" as MQ } Web --> GW Mobile --> GW GW --> Auth GW --> Article Article --> DB Article --> Cache Article --> MQ MQ --> Notify Auth --> DB @enduml`; try { const encoded = plantumlEncoder.encode(umlSource); const imgUrl = `https://www.plantuml.com/plantuml/svg/${encoded}`; const container = document.getElementById('diagram-container'); container.innerHTML = `<img src="${imgUrl}" alt="コンポーネント図" class="max-w-full max-h-full" />`; } catch (error) { console.error('Error encoding PlantUML:', error); document.getElementById('diagram-container').innerHTML = `<p class="text-red-500">Failed to load diagram: ${error.message}</p>`; } }); </script> </body> </html> 差し替えは3箇所だけです。 PlantUML構文 （ const umlSource の中身）を自分の図に差し替える 注釈パネルの内容 （右側の3つのパネル）を自分の設計ポイントに差し替える タイトル を差し替える 注釈パネルは増減しても大丈夫です。3個が収まりいいですけど、2個でも4個でもレイアウトは崩れません。 skinparamについて Mermaid編では themeVariables で図の配色をTailwindのカラーパレットに合わせましたね。PlantUMLでは skinparam が同じ役割です。 skinparam style strictuml skinparam backgroundColor transparent backgroundColor transparent で背景を透明にするだけで、Tailwind側の bg-blue-50 と自然に馴染みます。追加で色をカスタマイズしたい場合はこんな設定もあります。 skinparam packageBackgroundColor #f0f9ff skinparam ArrowColor #3b82f6 skinparam ParticipantBackgroundColor #dbeafe Mermaidの themeVariables ほど細かい制御はできないですけど、背景透明にするだけで大抵は十分です。もっと細かく調整したい人は PlantUML公式のskinparamリファレンス を参照してください。 PlantUML固有の記法 テンプレートのコードで使ってる記法と、他の図で使える記法をまとめておきます。 テンプレートAで使用 : 記法 表示 database "名前" ドラム型DB記号 queue "名前" キュー型記号 package "名前" { ... } パッケージでグループ化 他の図で使える記法 : 記法 用途 == フェーズ名 == シーケンス図のフェーズ分割 alt / else / end 条件分岐ブロック ref over A, B 外部参照 left to right direction ユースケース図の横向きレイアウト テンプレートB: 左右均等型 テンプレートAだと、縦長の図のときに左側のスペースが余ります。アクティビティ図やユースケース図は縦に伸びるんで、横幅を半々にして右側に説明を置くほうが収まりがいいです。 向いてる場面 : 縦長の図（アクティビティ図、ユースケース図）に説明を横に並べたいとき キャンバスサイズ : 1280x720px <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>アクティビティ図: ユーザー登録フロー</title> <script src="https://cdn.tailwindcss.com"></script> <script src="https://cdn.jsdelivr.net/npm/plantuml-encoder@1.4.0/dist/plantuml-encoder.min.js"></script> <style> body { width: 1280px; height: 720px; margin: 0; padding: 0; background-color: white; overflow: hidden; } </style> </head> <body class="flex"> <!-- 左: PlantUML図 --> <div class="w-1/2 flex items-center justify-center p-8"> <div id="diagram-container"></div> </div> <!-- 右: 注釈パネル --> <div class="w-1/2 flex flex-col justify-center p-8 space-y-6"> <h1 class="text-3xl font-bold text-gray-800 mb-4">ユーザー登録フロー</h1> <div class="bg-yellow-100 border-l-4 border-yellow-500 p-4"> <p class="text-gray-800 font-semibold">バリデーション</p> <p class="text-sm text-gray-600 mt-1">フォーム入力後、サーバー側でバリデーション。失敗時はエラーメッセージを表示してフォームに戻す</p> </div> <div class="bg-blue-100 border-l-4 border-blue-500 p-4"> <p class="text-gray-800 font-semibold">DB保存とリトライ</p> <p class="text-sm text-gray-600 mt-1">保存失敗時はエラーログを記録してリトライ画面を表示。ユーザーに再試行の機会を与える</p> </div> <div class="bg-green-100 border-l-4 border-green-500 p-4"> <p class="text-gray-800 font-semibold">完了通知</p> <p class="text-sm text-gray-600 mt-1">保存成功時は完了メールを送信してから完了画面を表示。メール送信は非同期でもOK</p> </div> </div> <script> window.addEventListener('DOMContentLoaded', () => { const plantUmlSource = `@startuml start :ユーザーがフォームを入力; if (バリデーション?) then (成功) :データベースに保存; if (保存成功?) then (はい) :完了メールを送信; :完了画面を表示; else (いいえ) :エラーログを記録; :リトライ画面を表示; endif else (失敗) :エラーメッセージを表示; :フォームに戻る; endif stop @enduml`; const encoded = plantumlEncoder.encode(plantUmlSource); const img = document.createElement('img'); img.src = `https://www.plantuml.com/plantuml/svg/${encoded}`; img.alt = 'アクティビティ図: ユーザー登録フロー'; img.className = 'max-w-full max-h-full'; document.getElementById('diagram-container').appendChild(img); }); </script> </body> </html> 差し替えポイントはテンプレートAと同じ3箇所です。PlantUML構文、注釈パネル、タイトル。実例はアクティビティ図ですけど、ユースケース図を作りたい場合も const plantUmlSource の中身を差し替えるだけです。 テンプレートAとの違いは2つです。 レイアウトが左右均等 （ w-1/2 + w-1/2 ）。図と注釈が50:50で並ぶんで、縦長の図に余裕ができます 注釈のスタイルが border-l-4 （左ボーダーアクセント）。テンプレートAのカード型とは雰囲気が変わります Mermaid編のテンプレートBは縦拡張（1280x1080px）でしたけど、PlantUML編は標準の1280x720pxです。PlantUMLはサーバー側で描画するんで、Mermaidの自動縮小問題がない。CSS transformも不要です。 テンプレート使い分け 条件 テンプレート 横に広がる図（コンポーネント図、シーケンス図） A: 右サイド注釈型 縦長の図（アクティビティ図、ユースケース図） B: 左右均等型 注釈が少ない（2-3個） A 注釈にテキストが多い B 迷ったらテンプレートAで試して、図が窮屈ならBに切り替えてください。 PNG変換 — 3つの手段 手段は3つあります。好みと環境に合わせて選んでください。 手段 自動化 セットアップ 向いてる用途 CLIツール（html-screenshot） できる Python + Playwright 量産やCI/CD Playwright MCP できる MCP設定 Claude Code連携 ブラウザで直接開く 手動 なし 手軽に確認 CLIツール uv run html-screenshot --file template-a.html --output template-a.png 以前の記事 で紹介したhtml-screenshotツールがそのまま使えます。Playwrightの wait_until="networkidle" がplantuml.comからのSVG取得完了を待ってくれるんで、PlantUML図の描画が終わってからスクリーンショットを撮ってくれます。 Playwright MCP Claude CodeからPlaywrightのブラウザ操作を直接呼び出す方法もあります。HTMLファイルを開いてスクリーンショットを撮る操作がMCPのツールで完結します。 Playwright MCPの記事 で詳しく書いてるんで、Claude Code使ってる人はこっちが楽です。 ブラウザで直接開く 一番手軽なのはHTMLファイルをブラウザで直接開くことですね。Tailwind CDNとplantuml-encoder CDNが読み込まれて、PlantUML図がそのまま描画されます。PNG変換は手動（DevToolsやOS標準のスクリーンショット）になりますけど、「ちょっと確認したい」くらいならこれで十分です。 まとめ Mermaid編のテンプレート2種 + 今回のPlantUML編テンプレート2種で、計4種類が揃いました。 テンプレート 図の描画 向いてる図 Mermaid A: 右サイド注釈型 Mermaid フロー、シーケンス、状態遷移 Mermaid B: 下部グリッド注釈型 Mermaid 複雑なシーケンス PlantUML A: 右サイド注釈型 PlantUML コンポーネント、シーケンス PlantUML B: 左右均等型 PlantUML アクティビティ、ユースケース フロー図、シーケンス図、状態遷移図に加えて、アクティビティ図、ユースケース図、コンポーネント図もカバーできるようになりました。特にコンポーネント図の database でドラム型DBアイコンが出せるのは、アーキテクチャ図を書く人にはかなり便利です。 おまけとして、Mermaid編でも触れましたがこのテンプレートで作った図はAI連携にも使えます。PlantUMLもMermaidと同じく宣言的記法なんで、AIが構造を正確に読み取れます。注釈パネルに設計意図を書いておけば、人間が見ても、AIが読んでもどっちにも伝わる。この辺の話は 仕様書の図にソースコードを添える設計パターン で詳しく書いてます。 もう1つ。このテンプレートを毎回コピペするのも手ですけど、Claude Codeの SKILL機能 にreference（参考例）として登録しておくと、「シーケンス図作って」と言うだけでテンプレートに沿った図が出てきます。テンプレートのクオリティがそのままSKILLのクオリティになるんで、良いテンプレートを貯める = 図解の品質を底上げする、という流れができます。コピペ用テンプレートとSKILL化、好きなほうで使ってください。 ほなまた〜 関連ブログ 今回の記事はシリーズの一部です。 Mermaid × Tailwind CSS — ハイブリッド図解の作り方 — 今回の前編。Mermaid + Tailwind CSSのテンプレート2種を紹介してます。まだ読んでない人はこちらから。 ClaudeでMermaid図作成を自動化！プロンプトテンプレート集も公開 — シリーズの出発点。Mermaid記法をAIで生成するところから始めたい人はここから。 図解作成、AIに丸投げしたら「たまに自分より上手い」件 — HTML+Tailwind CSSで図解を丸ごとAIに作らせる方法。フロー図以外の図解（比較図、アーキテクチャ図とか）はこっちが向いてます。 仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン — 仕様書をAIと共有してるチーム向け。図にソースコードと設計意図を添えて、AIの「推測」をなくす方法です。 Claude CodeでPlantUML × VS Code Preview — PlantUMLの基礎とVS Codeでのプレビュー設定。PlantUML自体が初めての人はこちらが入門になります。 Playwright MCPで始めるブラウザ自動化 — PNG変換の手段の1つとして紹介したPlaywright MCP。Claude Codeからブラウザ操作を直接呼び出せます。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post PlantUMLの表現力をTailwind CSSで設計書品質に仕上げる first appeared on SIOS Tech Lab .

Mermaidの見た目、もうちょっとなんとかならんか ども！Mermaidで図を作るたびに「構造は最高なんだけど、見た目がなぁ…」と思ってた龍ちゃんです。 「 Claude CodeでMermaid図を作成する 」でMermaid図の自動生成について書きました。Mermaidはコードで構造を書けるから、フローチャートやシーケンス図がサクッと作れます。AIに「こういう図作って」って言えば一発で出てくるんですよね。 ただ、デフォルトのデザインがシンプルすぎるんですよね。設計書やブログに貼るにはちょっと素朴。 HTML+Tailwind CSSで図解を丸投げする方法 も試したんですよ。装飾の自由度は高いんですけど、フロー図やシーケンス図をCSSで手動配置するのが辛い。特に矢印の表現が鬼の難易度です。Mermaidが自動でやってくれる部分を手で書くのはしんどいです。 じゃあ合体させたらどうだ、と。 Mermaidの構造表現力 + Tailwind CSSの装飾力 。Mermaidに図の構造を任せて、周りの見た目はTailwindで自由に作れます。これを1つのHTMLファイルにまとめてPNGに変換します。 今回の内容です。 コピペで使えるHTMLテンプレート2種（右サイド注釈型 / 下部グリッド注釈型） 色を揃えるカスタマイズのコツ 実際にぶつかった壁と対処法 PNG変換の手段3つ まず完成形を見せます こういうのが作れます。 左がMermaidで描画したシーケンス図、右がTailwind CSSで装飾した注釈パネル。これ、1つのHTMLファイルから出てきます。 ポイントは、Mermaid図の色とTailwind装飾の色が揃ってるところですね。青系で統一してるから、「Mermaidの部分だけ浮いてる」みたいなことにならない。 注釈パネルには設計ポイント、セキュリティ考慮、エラーハンドリングみたいな文脈情報を書けます。Mermaid図だけだと「何が起きてるか」は分かるけど「なぜこうしたか」は伝わらないんですよね。注釈パネルがその「なぜ」を補ってくれます。 関連記事 : 仕様書の図でAIの理解と人間の視認性を両立する方法に関しては「 仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン 」で詳しく書いてます。AIに図の構造を正確に伝えたい人はこちらもどうぞ。 テンプレートA: 右サイド注釈型 ここからが本題です。コピペして使えるHTMLテンプレートを2種類用意しました。 仕組みはシンプルで、1つのHTMLにTailwind CDNとMermaid CDN（ESM版）を同時に読み込んでるだけです。2つのCDNは競合しません（検証済み）。テンプレートをコピペすればそのまま動きます。色のカスタマイズについてはテンプレートの後で説明しますね。 まずはテンプレートA。冒頭で見せた完成形がこれです。左にMermaid図、右に注釈パネルを並べるレイアウトですね。 向いてる場面 : シンプルな図（ノード8個以下）に設計ポイントを3-4個添えたいとき キャンバスサイズ : 1280x720px <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Level 2: Mermaid + Tailwind CSS Decoration</title> <script src="https://cdn.tailwindcss.com"></script> </head> <body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-white"> <div class="w-full h-full flex gap-6 p-10"> <!-- 左: Mermaid図 --> <div class="flex-1 border-2 border-blue-300 rounded-lg p-6 bg-blue-50"> <h2 class="text-xl font-bold text-blue-900 mb-4">認証フローのシーケンス図</h2> <div class="mermaid"> sequenceDiagram participant C as クライアント participant S as サーバー participant DB as データベース C->>+S: ログインリクエスト S->>+DB: ユーザー照合 DB-->>-S: 認証結果 alt 認証成功 S-->>C: アクセストークン発行 else 認証失敗 S-->>C: エラーレスポンス(401) end </div> </div> <!-- 右: 注釈パネル --> <div class="w-72 flex flex-col gap-3"> <div class="bg-yellow-50 border border-yellow-300 rounded p-3"> <h3 class="text-sm font-bold text-yellow-800">設計ポイント</h3> <p class="text-xs text-yellow-700">DB直接参照を避け、サービス層を経由させることで結合度を低減</p> </div> <div class="bg-green-50 border border-green-300 rounded p-3"> <h3 class="text-sm font-bold text-green-800">セキュリティ考慮</h3> <p class="text-xs text-green-700">トークンはJWT形式、有効期限15分で自動失効</p> </div> <div class="bg-red-50 border border-red-300 rounded p-3"> <h3 class="text-sm font-bold text-red-800">エラーハンドリング</h3> <p class="text-xs text-red-700">認証失敗時は具体的なエラー原因を返さない（セキュリティ対策）</p> </div> </div> </div> <script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true, theme: 'base', themeVariables: { primaryColor: '#dbeafe', primaryBorderColor: '#3b82f6', lineColor: '#6b7280', fontFamily: 'system-ui, sans-serif' } }); </script> </body> </html> 使い方はシンプルで、3箇所を差し替えるだけです。 Mermaid記法の部分 （ <div class="mermaid"> の中身）を自分の図に差し替える 注釈パネルの内容 （右側の3つのパネル）を自分の設計ポイントに差し替える themeVariables で色を変えたければカラーコードを調整する 注釈パネルは増減しても大丈夫です。3個が収まりいいですけど、2個でも4個でもレイアウトは崩れません。 色の統一について 完成形の画像を見て「Mermaid図と注釈パネルの色が揃ってるな」と思った人もいるかもしれません。これはテンプレート末尾の themeVariables でMermaid図の配色をTailwindのカラーパレットに合わせてるからです。 themeVariables: { primaryColor: '#dbeafe', // Tailwind blue-100 primaryBorderColor: '#3b82f6', // Tailwind blue-500 lineColor: '#6b7280', // Tailwind gray-500 fontFamily: 'system-ui, sans-serif' } 色を変えたいときはここのカラーコードを差し替えてください。 Tailwindのカラーパレット から持ってくると注釈パネル側と揃えやすいです。 1つ注意点として、 Mermaid図の中にTailwindクラスは効きません 。Mermaid図はSVGとして生成されるんで、外部CSSが適用できないんですよね。色のカスタマイズは themeVariables 経由のみです。 テンプレートB: 下部グリッド注釈型 テンプレートAだと、図が複雑になったときに左側のスペースが足りなくなります。シーケンス図で参加者が4人以上いたり、メッセージが10本近くあると、右の注釈パネルに幅を取られて図が窮屈になるんですよね。 そういうときはテンプレートBです。図を上部に全幅で配置して、注釈パネルは下部にグリッドで並べます。 向いてる場面 : 複雑な図（10ステップ近いシーケンス、状態遷移図）で図に全幅を使いたいとき キャンバスサイズ : 1280x1080px（縦に拡張） <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>OAuth 2.0 認可コードフロー</title> <script src="https://cdn.tailwindcss.com"></script> <style> .mermaid svg { transform: scale(3.2); transform-origin: center center; } </style> <script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true, theme: 'base', sequence: { diagramMarginX: 10, diagramMarginY: 10, actorMargin: 80, messageMargin: 40 }, themeVariables: { primaryColor: '#e0f2fe', primaryBorderColor: '#0284c7', primaryTextColor: '#0c4a6e', lineColor: '#64748b', fontFamily: 'system-ui, sans-serif' } }); </script> </head> <body class="w-[1280px] h-[1080px] m-0 p-0 overflow-hidden bg-white"> <div class="w-full h-full flex flex-col p-8 gap-6"> <!-- 上部: タイトル --> <div> <div class="text-lg font-bold text-gray-800">OAuth 2.0 認可コードフロー</div> <div class="text-sm text-gray-500">ソーシャルログイン実装の標準パターン</div> </div> <!-- 中央: 図（全幅） --> <div class="flex-1 border border-gray-200 rounded-lg p-6 bg-gray-50 flex items-center justify-center"> <div class="mermaid"> sequenceDiagram actor U as ユーザー participant App as Webアプリ participant Auth as 認可サーバー participant API as リソースサーバー U->>App: ログインボタンクリック App->>Auth: 認可リクエスト(client_id, redirect_uri, scope) Auth->>U: ログイン画面表示 U->>Auth: 認証情報入力 Auth->>App: 認可コード(code) App->>Auth: トークンリクエスト(code, client_secret) Auth->>App: アクセストークン + リフレッシュトークン App->>API: APIリクエスト(Bearer token) API->>App: リソースデータ App->>U: ユーザー情報表示 </div> </div> <!-- 下部: 注釈パネル（横並び） --> <div class="grid grid-cols-4 gap-3"> <div class="bg-blue-50 border border-blue-200 rounded-lg p-3"> <div class="text-sm font-bold text-blue-800">フロー概要</div> <div class="text-xs text-blue-700 mt-1">RFC 6749準拠の認可コードグラント。SPAではPKCE拡張を推奨。</div> </div> <div class="bg-amber-50 border border-amber-200 rounded-lg p-3"> <div class="text-sm font-bold text-amber-800">セキュリティ要件</div> <div class="text-xs text-amber-700 mt-1 space-y-1"> <div>state パラメータでCSRF対策</div> <div>client_secret はサーバー側で保持</div> <div>redirect_uri の完全一致検証</div> </div> </div> <div class="bg-green-50 border border-green-200 rounded-lg p-3"> <div class="text-sm font-bold text-green-800">実装チェックリスト</div> <div class="text-xs text-green-700 mt-1 space-y-1"> <div>トークンの安全な保存（httpOnly cookie）</div> <div>リフレッシュトークンのローテーション</div> <div>スコープの最小権限原則</div> </div> </div> <div class="bg-gray-100 border border-gray-200 rounded-lg p-3"> <div class="text-sm font-bold text-gray-700">補足</div> <div class="text-xs text-gray-600 mt-1">アクセストークンの有効期限は15分〜1時間が一般的。期限切れ時はリフレッシュトークンで自動更新。</div> </div> </div> </div> </body> </html> テンプレートAとの違いは3つです。 キャンバスが縦に拡張 （720px → 1080px）。図に余裕ができます 注釈パネルが下部グリッド 。図が全幅を使えるんで、参加者が4人いても窮屈になりません CSS transformでMermaid図を拡大 （ scale(3.2) ）。Mermaidは複雑な図を自動縮小するんで、それを補正してます scaleの調整について テンプレートBの scale(3.2) は、上のOAuth 2.0の例（参加者4人・メッセージ10本）に合わせた値です。自分の図に差し替えたら、scaleも調整が必要です。 Mermaidは図の複雑度に応じて自動縮小するんですけど、その縮小率が図ごとに変わるんですよね。なので 図を差し替えるたびにscaleを微調整する のが前提の設計です。 調整の手順はシンプルで、HTMLファイルをブラウザで開いて、文字が読める大きさになるまで scale の数値を上げ下げするだけです。目安としてはこんな感じ。 図の複雑度 scale目安 シンプル（参加者2-3人、メッセージ5本以下） 1.5〜2.0 中程度（参加者3-4人、メッセージ8本前後） 2.5〜3.5 複雑（参加者4人以上、メッセージ10本以上） 3.0〜4.0 どっちを使う？ 条件 テンプレート 図がシンプル（ノード8以下） A: 右サイド注釈型 図が複雑、横に広がる B: 下部グリッド注釈型 注釈が少ない（2-3個） A 注釈が多い（4個以上） B 迷ったらまずテンプレートAで試して、図が窮屈ならBに切り替える、でいいと思います。 ぶつかった壁と対処 検証してて何度かハマったので、先に共有しておきます。 ノード数には上限がある Mermaidは図の要素が増えると自動で縮小するんですよね。1280pxの幅に収めようとするから、ノードが多いと文字が潰れて読めなくなります。 実際に検証して、このくらいが上限だなというラインが見えました。 図の種類 推奨上限 超えるとどうなるか フローチャート 8-10ノード 文字が小さくなって読めない シーケンス図 4参加者・8メッセージ ラベルが長いと自動縮小される 状態遷移図 8-10状態 縦に伸びてキャンバスからはみ出す 上限を超えそうなときは、図を分割するか、テンプレートBでキャンバスを拡張するのがいいです。 サイズ問題の対策3種 実際にぶつかったサイズ問題と、それぞれの対処法です。 症状 対策 やり方 図がキャンバスからはみ出す キャンバスを拡張する h-[720px] → h-[1080px] に変更。PNG変換時も --height 1080 を指定 図が小さすぎて読めない CSS transformで拡大 .mermaid svg { transform: scale(X); } を追加 右の注釈パネルが図を圧迫する 注釈を下部に移動 テンプレートAからBに切り替える この3つの対策は組み合わせられます。テンプレートBはキャンバス拡張 + CSS transform + 下部グリッドの3つ全部入りですね。制約はあるけど対策は全部見つかってるんで、複雑な図はまずBを試してみてください。 PNG変換 — 3つの手段 HTMLファイルが完成したら、PNG画像に変換してブログや設計書に貼れます。手段は3つあって、好みと環境に合わせて選んでください。 手段 自動化 セットアップ 向いてる用途 CLIツール（html-screenshot） できる Python + Playwright 量産やCI/CD Playwright MCP できる MCP設定 Claude Code連携 ブラウザで直接開く 手動 なし 手軽に確認 CLIツール uv run html-screenshot --file template-a.html --output template-a.png 以前の記事 で紹介したhtml-screenshotツールがそのまま使えます。改修なしでMermaid CDNの読み込みにも対応してました。Playwrightの wait_until="networkidle" がCDN読み込み完了を待ってくれるんで、Mermaid図の描画が終わってからスクリーンショットを撮ってくれます。 テンプレートBのように高さを変えたい場合は --height 1080 を付けます。 Playwright MCP Claude CodeからPlaywrightのブラウザ操作を直接呼び出す方法もあります。HTMLファイルを開いてスクリーンショットを撮る操作がMCPのツールで完結します。 Playwright MCPの記事 で詳しく書いてるんで、Claude Code使ってる人はこっちが楽かもしれません。 ブラウザで直接開く 一番手軽なのはHTMLファイルをブラウザで直接開くことですね。Mermaid CDNが読み込まれて図がそのまま描画されます。PNG変換は手動（ブラウザのDevToolsやOS標準のスクリーンショット）になりますけど、「ちょっと確認したい」くらいならこれで十分です。 まとめ ノード数の上限やサイズ問題はありましたけど、全部対処法が見つかりました。制約を把握しておけばハマることはないです。 今回のポイントです。 「構造はMermaid、装飾はTailwind」の役割分担 。Mermaidが得意な構造の自動レイアウト（矢印の接続、参加者の配置、分岐の描画）はMermaidに任せて、周りの装飾（注釈パネル、色統一、レイアウト）はTailwind CSSで自由に作る。 テンプレートの使い分けはシンプルです。 条件 テンプレート シンプルな図 + 注釈少なめ A: 右サイド注釈型（1280×720） 複雑な図 + 注釈多め B: 下部グリッド注釈型（1280×1080） あと、おまけとして1つ。このテンプレートで作った図はAI連携にも強いです。Mermaidのソースコードは宣言的な記法（ sequenceDiagram 、 graph TD とか）なんで、AIが構造を正確に読み取れます。注釈パネルに設計意図を書いておけば、人間が見ても、AIが読んでもどっちにも伝わる。この辺の話は 仕様書の図にソースコードを添える設計パターン で詳しく書いてるんで、興味あれば読んでみてください。 もう1つ。このテンプレートを毎回コピペするのも手ですけど、Claude Codeの SKILL機能 にreference（参考例）として登録しておくと、「シーケンス図作って」と言うだけでテンプレートに沿った図が出てきます。テンプレートのクオリティがそのままSKILLのクオリティになるんで、良いテンプレートを貯める = 図解の品質を底上げする、という流れができます。コピペ用テンプレートとSKILL化、好きなほうで使ってください。 PlantUML編も書きました。Mermaidが苦手な図種（アクティビティ図、ユースケース図、コンポーネント図）をPlantUMLでカバーする話です。「 PlantUMLの表現力をTailwind CSSで設計書品質に仕上げる 」をどうぞ。 ほなまた〜 関連ブログ 今回の記事はシリーズの一部です。Mermaid図の生成からHTML図解、仕様書への活用まで、一連の流れで読めます。 ClaudeでMermaid図作成を自動化！プロンプトテンプレート集も公開 — 今回の出発点。Mermaid記法をAIで生成するところから始めたい人はここから。プロンプトテンプレートも載せてます。 図解作成、AIに丸投げしたら「たまに自分より上手い」件 — HTML+Tailwind CSSで図解を丸ごとAIに作らせる方法。フロー図以外の図解（比較図、アーキテクチャ図とか）はこっちが向いてます。 仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン — 仕様書をAIと共有してるチーム向け。図にソースコードと設計意図を添えて、AIの「推測」をなくす方法です。 Playwright MCPで始めるブラウザ自動化 — PNG変換の手段の1つとして紹介したPlaywright MCP。Claude Codeからブラウザ操作を直接呼び出せます。 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Mermaidのデザインが物足りない？Tailwindで拡張して設計書品質に first appeared on SIOS Tech Lab .

PlantUMLもClaude Codeで書きたい ども！Claude Codeで仕様書を書く方法を模索している龍ちゃんです。 以前、 ClaudeでMermaid図作成を自動化する記事 を書きました。あの記事のおかげで図解作成がめちゃくちゃ楽になったんですが、しばらく使ってるうちに壁にぶつかりました。 アクティビティ図が作れない。ユースケース図も作れない。 PlantUMLなら作れる。確認はVS Code上のMarkdown Previewで完結する。今回はその設定方法と実践例を紹介します。 Mermaidは便利だけど、対応していない図の種類があるんです。仕様書を書いてると「ここはアクティビティ図で表現したい」「アクターの関係をユースケース図で見せたい」って場面が出てきます。Mermaidのフローチャートで無理やり代用しても、分岐やマージが不自然になる。 そこで PlantUML の出番です。 今回は、Claude CodeでPlantUMLの図を生成して、VS Code上のMarkdown Previewでそのまま確認する方法を解説します。VS Code上に拡張機能を入れるだけですぐ確認できていたのですが、PlantUMLではちょっとしたコツが必要になったので紹介していきます。 この記事でわかること: Mermaidでは作れないアクティビティ図・ユースケース図・コンポーネント図をPlantUMLで作る方法 VS Code上でPlantUML図をプレビュー表示する環境設定（Markdown Preview Enhanced + Kroki.io） Claude Codeと組み合わせた実践的な作業フロー 前提環境 : VS Code 1.85以上、インターネット接続必須（Kroki.ioサーバーとの通信に必要） なぜPlantUMLなのか？ MermaidとPlantUMLの使い分け 全部PlantUMLに乗り換えろという話ではないです。Mermaidが得意な領域はMermaidを使えばいい。PlantUMLが必要になるのは、Mermaidでは作れない図を描くときだけです。 こういう図なら こっちを使う 理由 フローチャート Mermaid 記法がシンプル、学習コスト低い シーケンス図（シンプル） Mermaid 4参加者程度ならMermaidで十分 状態遷移図 Mermaid stateDiagram-v2が使いやすい ER図 Mermaid erDiagramが直感的 パイチャート Mermaid Mermaid専用機能 アクティビティ図 PlantUML Mermaid非対応。if/else分岐の自然な表現 ユースケース図 PlantUML Mermaid非対応。UML標準のアクター記法 コンポーネント図 PlantUML database/queue専用記号が使える 複雑なシーケンス図 PlantUML ==フェーズ分割==、ref over が使える UML準拠が求められる設計書 PlantUML UML 2.0標準に準拠 シンプルな結論: 迷ったらMermaid。アクティビティ図・ユースケース図・コンポーネント図の3パターンだけPlantUML。 PlantUML固有の強み PlantUMLでしか使えない表現がいくつかあります。記事の後半で実際に使いますが、先に紹介しておきます。 database "名前" — ドラム型のデータベース記号。Mermaidでは汎用の四角になる queue "名前" — キュー型の記号。メッセージキューの表現に最適 == フェーズ名 == — シーケンス図をフェーズで区切る。認証→データ取得のような段階を明示できる left to right direction — ユースケース図の横向きレイアウト。縦長にならず収まりがいい if/else/endif — アクティビティ図の条件分岐。ネストも可能 VS Code Preview設定方法 ここが記事の核です。一度設定すれば、あとはMarkdownに書くだけでPlantUML図がプレビュー表示されます。 必要な拡張機能 Markdown Preview Enhanced を使います。 項目 詳細 拡張機能ID shd101wyy.markdown-preview-enhanced バージョン 0.8.20（2025年11月時点） PlantUML対応 Kroki.ioサーバー経由で描画 Mermaid対応 ブラウザ内JSで描画（同時対応） VS Code標準のMarkdownプレビューではPlantUMLは表示されません。Markdown Preview Enhancedの専用プレビューを使う必要があります。 PlantUMLサーバー設定 PlantUMLのコードを画像に変換するサーバーが必要です。 Kroki.io を使います。無料で登録不要です。 注意 : Kroki.ioはパブリックサーバーなので、PlantUMLのコードがインターネット経由で送信されます。社内の機密情報を含む図を描く場合は、 セルフホスト版のKrokiサーバー （Dockerで立てられる）を検討してください。個人のブログ執筆用途であれば問題ないです。 VS Codeの設定で以下を追加します: { "markdown-preview-enhanced.plantumlServer": "https://kroki.io/plantuml/svg/" } これだけです。 devcontainer.jsonへの設定例 devcontainerを使っている場合は、 devcontainer.json に書いておくとチーム全員が同じ設定で使えます。 { "customizations": { "vscode": { "extensions": [ "shd101wyy.markdown-preview-enhanced", "bierner.markdown-mermaid" ], "settings": { "markdown-preview-enhanced.plantumlServer": "https://kroki.io/plantuml/svg/", "markdown-preview-enhanced.previewTheme": "github-dark.css", "markdown-preview-enhanced.mermaidTheme": "dark" } } } } 自分のプロジェクトでは実際にこの設定を使っています。 Markdown Preview Mermaid Support （ bierner.markdown-mermaid ）も入れておくと、VS Code標準プレビュー側でMermaidが表示できて便利です。 動作確認 設定が終わったら、以下の手順で確認します。 以下のコードブロックを書く: Markdown Preview Enhanced のプレビューを開く コマンドパレット（Ctrl+Shift+P）→ Markdown Preview Enhanced: Open Preview to the Side ショートカット: Ctrl+K V Markdownファイルを開く @startuml Alice -> Bob: Hello Bob --> Alice: Hi! @enduml プレビューにシーケンス図が表示されたら設定完了です。表示されない場合は、後述のトラブルシューティングを確認してください。 注意 : VS Code標準のMarkdownプレビュー（Ctrl+Shift+V）ではPlantUMLは表示されません。必ずMarkdown Preview Enhanced のプレビューを使ってください。アイコンが異なるので区別できます。 基本的な作業フロー Claude Code連携の流れ Claude Codeで作業する場合の具体的な流れです。 Markdownファイルを開いた状態でClaude Codeにプロンプトを入力 Claude Codeが plantuml コードブロックを含むMarkdownを生成 VS Code上でMarkdown Preview Enhancedのプレビューを確認 修正が必要なら「この図の〇〇を変更して」と追加指示 完成したらそのまま仕様書・設計書として使える エディタとターミナルの行き来だけで完結するのが強みです。 PlantUML公式エディタで確認する方法 VS Code Previewが本記事のメインですが、ブラウザで手軽に確認したい場面もあります。PlantUMLには公式のWebエディタがあるので紹介しておきます。 PlantUML Web Editor 使い方はシンプルです。 上記URLにアクセス 左側のエディタにPlantUMLコードを貼り付ける 約1.5秒後に右側にプレビューが自動表示される ツールバーからPNG/SVGでダウンロードできる Mermaid版の記事で紹介した「Live Editor」のPlantUML版だと思ってください。URLがそのまま図の共有リンクになるので、チームメンバーに「この図見て」と送るときにも使えます。 ただし自分は普段使いではVS Code Previewのほうを使っています。理由は2つあって、エディタから離れなくていいことと、Markdownファイルにそのまま残せること。公式エディタは「VS Codeの設定がまだの環境で急ぎ確認したい」「誰かに図だけ共有したい」ときの補助ツールという位置づけです。 実践①: アクティビティ図 アクティビティ図とは ワークフローや処理の分岐を表現する図です。フローチャートに似ていますが、UMLの正式な図の1つで、条件分岐（if/else）とマージの表現が自然です。 Mermaidのフローチャートでも似たことはできますが、分岐とマージの接続が不自然になりがちです。PlantUMLのアクティビティ図なら、if/else/endifの構文でネストした分岐も綺麗に描けます。 プロンプト例 以下のワークフローをPlantUMLのアクティビティ図で作成してください。 【ワークフロー】ブログ記事の執筆〜公開プロセス 1. 記事のアウトラインを作成 2. Claude Codeで下書きを生成 3. 内容を確認・修正 4. 判定: 技術的に正確か？ - YES → ライティングチェックへ - NO → 技術検証をやり直して下書き修正 5. 判定: 品質OK？ - YES → サムネイル作成 → WordPress入稿 → 公開 - NO → AIっぽい表現を修正 → 再チェック ```plantuml のコードブロック形式で出力してください。 PlantUMLコード例 @startuml start :記事のアウトラインを作成; :Claude Codeで下書きを生成; :内容を確認・修正; if (技術的に正確？) then (はい) :ライティングチェック; if (品質OK？) then (はい) :サムネイル作成; :WordPressに入稿; :公開; else (いいえ) :AIっぽい表現を修正; :再チェック; endif else (いいえ) :技術検証をやり直す; :下書きを修正; endif stop @enduml VS Code Previewで見ると、こんな感じで表示されます。 分岐のダイヤモンド記号とマージが自然に接続されます。ネストしたif/elseもインデントで表現されるので読みやすい。Mermaidのフローチャートで同じことをやろうとすると、ノード間の矢印を手動で繋ぐ必要があって面倒です。 実践②: ユースケース図 ユースケース図とは システムの機能（ユースケース）と、それを使う人やシステム（アクター）の関係を表現する図です。要件定義の初期段階で「誰が何をするか」を整理するのに使います。 Mermaidにはユースケース図のサポートがないので、PlantUMLの独壇場です。 プロンプト例 以下のシステムのユースケース図をPlantUMLで作成してください。 【システム名】ブログ執筆システム 【アクター】 - エンジニア: 記事執筆、図の生成、コードレビュー - Claude Code: 下書き生成、図の生成、サムネイル作成、SEOチェック、ライティングチェック - レビュアー: コードレビュー 【関係】 - 図の生成と記事執筆にはinclude関係がある - SEOチェックと記事執筆にもinclude関係がある left to right direction で横向きレイアウトにしてください。 ```plantuml のコードブロック形式で出力してください。 PlantUMLコード例 @startuml left to right direction actor "エンジニア" as Engineer actor "Claude Code" as Claude actor "レビュアー" as Reviewer rectangle "ブログ執筆システム" { usecase "記事を執筆" as UC1 usecase "図を生成" as UC2 usecase "コードレビュー" as UC3 usecase "サムネイル作成" as UC4 usecase "SEOチェック" as UC5 usecase "ライティングチェック" as UC6 } Engineer --> UC1 Engineer --> UC2 Engineer --> UC3 Claude --> UC1 : 下書き生成 Claude --> UC2 : Mermaid/PlantUML生成 Claude --> UC4 Claude --> UC5 Claude --> UC6 Reviewer --> UC3 UC2 ..> UC1 : <<include>> UC5 ..> UC1 : <<include>> @enduml VS Code Previewでの表示結果がこちらです。 left to right direction でアクターが左右に配置されて、横長のレイアウトになります。 rectangle でシステム境界を囲って、 ..> + <<include>> でユースケース間の依存関係を表現しています。 棒人間のアクターアイコンはPlantUML固有のもので、UML標準に準拠しています。Mermaidでは表現できません。個人的にはこのアクターアイコンが出るだけで「ちゃんとした設計図」感が出るので気に入ってます。 実践③: コンポーネント図 コンポーネント図とは システムのコンポーネント（サービス、データベース、キューなど）と、それらの依存関係を表現する図です。PlantUMLの database と queue の専用記号が使えるのがここで効いてきます。 Mermaidでもflowchartでシステム構成図を描けますが、データベースもキューも同じ四角形になります。PlantUMLならドラム型のDB記号やキュー記号で一目でわかる図が作れます。 プロンプト例 以下のシステム構成をPlantUMLのコンポーネント図で作成してください。 【システム名】ブログ執筆環境 【レイヤー構成】 - 開発環境: VS Code、Claude Code CLI、Playwright - CLIツール: blog-scraper、html-to-png、svg-to-png、thumbnail-generator - 外部サービス: WordPress（DB）、Kroki.io（キュー）、GitHub（DB） database記号とqueue記号を使い分けてください。 packageでレイヤーを分けてください。 ```plantuml のコードブロック形式で出力してください。 PlantUMLコード例 @startuml package "開発環境（devcontainer）" { [VS Code] as VSCode [Claude Code CLI] as Claude [Playwright] as PW } package "CLIツール" { [blog-scraper] as Scraper [html-to-png] as H2P [svg-to-png] as S2P [thumbnail-generator] as Thumb } package "外部サービス" { database "WordPress" as WP queue "Kroki.io" as Kroki database "GitHub" as GH } VSCode --> Claude : コマンド実行 Claude --> Scraper : 記事取得 Claude --> H2P : 図のPNG変換 Claude --> Thumb : サムネイル生成 Scraper --> WP : スクレイピング H2P --> PW : ブラウザ描画 VSCode --> Kroki : PlantUMLプレビュー Claude --> GH : コミット・プッシュ @enduml VS Code Previewで表示するとこうなります。 WordPressとGitHubがドラム型のDB記号で、Kroki.ioがキュー型の記号で表示されます。 package でレイヤーが囲まれるので、3層構造が一目でわかります。 [コンポーネント名] の記法はUMLコンポーネント記号（角に突起が付いた四角形）で表示されます。Mermaidの ["テキスト"] とは見た目が違って、設計図っぽさが出ます。実はこの図、自分が普段使ってるブログ執筆環境そのものなので、「こういう構成で動いてるんだ」と思いながら見てもらえると嬉しいです。 トラブルシューティング Previewに図が表示されない 症状 原因 対策 コードブロックがそのまま表示される VS Code標準のMarkdownプレビューを使っている Markdown Preview Enhanced のプレビューに切り替える。コマンドパレットで「Markdown Preview Enhanced: Open Preview to the Side」を実行 「Loading…」で止まる Kroki.ioサーバーに接続できない ネットワーク接続を確認。プロキシ環境の場合はVS Codeのプロキシ設定を確認 図が真っ白 plantumlServer の設定値が間違っている 設定値が https://kroki.io/plantuml/svg/ になっているか確認（末尾のスラッシュも必要） エラーメッセージが表示される PlantUMLの構文エラー エラーメッセージをClaude Codeに貼り付けて「修正してください」と依頼 日本語が文字化けする Kroki.ioサーバー側で描画されるため、ローカルのフォント設定は影響しません。Kroki.ioは日本語フォントに対応しているので、通常は文字化けしないです。 もし文字化けする場合は、skinparamでフォントを指定してみてください: @startuml skinparam defaultFontName "Noto Sans JP" ' 以下に図の内容 @enduml 図が大きすぎてプレビューに収まらない 2つの方法があります。 方法1: scaleで縮小 @startuml scale 0.8 ' 80%に縮小して表示 @enduml 方法2: skinparam dpiで調整 @startuml skinparam dpi 150 ' デフォルト（200程度）より小さくする @enduml ノード数が多い場合は、図を分割するのが根本的な解決策です。 プロンプトテンプレート集 コピペして使えるテンプレートです。 アクティビティ図用 以下のワークフローをPlantUMLのアクティビティ図で作成してください。 【ワークフロー名】 [ワークフローの名前] 【ステップ】 1. [ステップ1の内容] 2. [ステップ2の内容] 3. 判定: [条件分岐の内容] - YES → [処理A] - NO → [処理B] ```plantuml のコードブロックで出力してください。 skinparamは不要です。 ユースケース図用 以下のユースケース図をPlantUMLで作成してください。 【システム名】 [システムの名前] 【アクター】 - [アクター1]: [役割の説明] - [アクター2]: [役割の説明] 【ユースケース】 - [UC1]: [機能の説明] - [UC2]: [機能の説明] 【関係】 - [UC間のinclude/extend関係があれば記述] left to right direction で横向きレイアウトにしてください。 ```plantuml のコードブロックで出力してください。 コンポーネント図用 以下のシステム構成をPlantUMLのコンポーネント図で作成してください。 【システム名】 [システムの名前] 【レイヤー構成】 - [レイヤー1]: [コンポーネント一覧] - [レイヤー2]: [コンポーネント一覧] - [データ層]: [DB、キャッシュ、キュー等] database記号とqueue記号を適切に使い分けてください。 packageでレイヤーを分けてください。 ```plantuml のコードブロックで出力してください。 修正依頼用 先ほどのPlantUML図を以下の点で修正してください: 【修正内容】 - [修正点1] - [修正点2] - [修正点3] ```plantuml のコードブロック形式を維持してください。 まとめ Mermaidで作れない図はPlantUMLで作る。確認はVS Code上のMarkdown Previewで完結する。 この記事のポイント: 使い分け : 迷ったらMermaid。アクティビティ図・ユースケース図・コンポーネント図の3パターンだけPlantUML 環境設定 : Markdown Preview Enhanced + Kroki.ioサーバー。devcontainer.jsonに数行設定するだけ 作業フロー : Claude Code → PlantUMLコード生成 → VS Code Preview確認。エディタから離れない PlantUML固有の強み : database/queue専用記号、if/else分岐、ユースケースのアクター記法 Mermaid版の記事では「Live Editorでブラウザに切り替えて確認」でしたが、PlantUML版は「VS Codeのプレビューで確認」です。エディタとターミナルの行き来だけで図の作成が完結するのは地味に楽です。仕様書のMarkdownにそのまま埋め込めるので、図の管理も別ファイルにする必要がありません。 自分はこの仕組みを使って、仕様書や設計書の図解を全部Markdownに集約しています。 ほなまた。 関連ブログ・参考リンク 関連ブログ ClaudeでMermaid図作成を自動化！2時間→5分の劇的時短術 今回の記事の前編にあたる記事です。Mermaidでフローチャート・シーケンス図・パイチャートを自動生成する方法と、Live Editorでの確認フローを紹介しています。Mermaid側の使い方はこちらを参照してください。 図解作成、AIに丸投げしたら「たまに自分より上手い」件 Claude CodeのSKILL機能でHTML図解を自動生成し、CLIでPNG変換する方法を紹介しています。気に入ったデザインをreferenceに保存するだけでスキルが育つ仕組みも解説。図解の品質を上げたい人はこちらもどうぞ。 参考リンク PlantUML公式 Kroki.io — Diagram as Code Markdown Preview Enhanced Mermaid.js公式 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Claude Codeで仕様書のPlantUML図を自動生成 — VS Codeプレビューで完結 first appeared on SIOS Tech Lab .

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

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

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

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

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

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

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

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

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

Claude 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 .

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 .

はじめに こんにちは、サイオステクノロジーの小野です。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 .