Claude Codeに専門知識を仕込む：調査→構造化→注入の設計パターン

ども！最近 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プロンプトを繰り返すうちに、「これ毎回やるなら仕組み化した方がいいな」と思って作ったのがこのパイプラインです。

ポイントは、一度このパイプラインを通すと、あとは 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/ は「使えるナレッジ」。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 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 なしだと、タイトル案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 のカテゴリはこんな感じです。

技術リファレンス（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効かない？ドメイン注入を設計思想から見直す