pipeline 戦略レイヤー設計 — advisor agent と executor skill の接続型

advisor agent を作っただけでは、pipeline には組み込まれない。

八雲のコンテンツパイプラインで @seo-director を agent として定義したとき、最初は何も変わらなかった。agent ドキュメントには keyword 設計の責務が書かれており、Claude Code の agents/ ディレクトリにも配置された。しかし pillar 記事 3 本（reset-timeline / mcluhan-engine / bateson-engine）は SEO 戦略レイヤーのないまま执筆が進み、bateson の brief 確認段階でユーザーの指摘によって発覚した。

原因は単純だった。@seo-director の起動ルートが pipeline JSON に存在しなかった。advisor を「作った」と「pipeline に接続した」は別のことだ。この記事では、advisor agent を pipeline JSON の phase 0 に明文化し、brief YAML を hub として上流の戦略判断を下流の executor skill に継承させる設計パターンを解説する。

→ Claude Code の agents / skills ハーネス設計の全体像は AI エージェントハーネスの設計原則を参照してほしい。

advisor agent が pipeline から欠落するパターン

定義はあるが起動ルートが pipeline JSON にない構造

Claude Code の agents/ ディレクトリに agent を定義するだけでは、pipeline は agent を呼ばない。

blog-ops/config/pipelines/rewrite-tech.json / rewrite-case.json の phase 列を確認したとき、@seo-director への invocation は存在しなかった。唯一 SEO に触れるのが末尾 phase の /blog-meta スキルだけで、「SEO は書いた後で title と description を整える後段処理」という位置づけになっていた。

@seo-director は advisor として存在していたが、orchestration の観点からは「存在しない agent」と同じだった。main thread が能動的に思い出して呼ぶ設計は、忙しいセッションで確実に忘れる。

main thread の能動的呼び出しに依存すると忘れる

advisor の起動を「main thread が判断する」設計にすると、2 つの問題が起きる。

1 つは「いつ呼ぶか」が曖昧になること。@seo-director を brief 生成前に呼ぶのか、書き終わった後に呼ぶのかが pipeline の文書に定義されていなければ、呼ぶタイミングが毎回変わる。

もう 1 つは「呼ぶことを忘れる」こと。pipeline の実行は段階的に進む。phase 1 の brief 生成が終わった後、「そういえば SEO 設計が必要だった」と気づくのは、往々にして phase 2 の執筆が半分終わったときだ。

2026-05-18 に発覚した事故がある。reset-timeline と mcluhan は description retrofit のみ（title/H2/本文変更なし）で公開を迎えた。bateson は brief 段階で発覚したため、公開前に対応できた。対処の commit は cc935f4（2026-05-18 16:28:55）で、seo セクションの retrofit と pipeline JSON への @seo-director 組み込みが同時に行われた（blog-ops/retros/2026-05-18-seo-missing-from-pipeline.md 参照）。

pipeline JSON で advisor を phase 0 として接続する型

phase 0 = advisor、phase 1+ = executor という構造

問題の解決策は、advisor を pipeline JSON の最初の phase として明文化することだ。

new-article-pillar.json と new-article-spoke.json は両方とも 2026-05-18 cc935f4 で新規作成された。git log --follow で確認すると、最初のコミットが cc935f4（2026-05-18 16:28:55）であることが確認できる。

new-article-pillar.json の修正後の構造:

{
  "stages": [
    {
      "phase": 0,
      "step": "seo",
      "runner": "@seo-director",
      "model": "sonnet",
      "trigger": "pipeline 開始時",
      "description": "pillar の cluster SEO 設計。primary_keyword / secondary_keywords / longtail_clusters / search_intent を決定"
    },
    {
      "phase": 1,
      "step": "plan",
      "runner": "blog-plan",
      "depends_on": ["seo"],
      ...
    }
  ]
}

depends_on: ["seo"] が重要だ。phase 1 の brief 生成は phase 0 の SEO 設計が完了していることを前提とする。pipeline の実行エンジンはこの依存関係を見て、phase 0 をスキップして phase 1 に進むことができない。

現在の new-article-pillar.json と new-article-spoke.json は phase 0（@seo-director）から phase 10（blog-graph）まで 13 フェーズで構成されており、phase 0 に @seo-director が接続されている。

advisor の出力フォーマット — brief YAML の特定セクションへの書き込み

advisor agent の出力は、以下の形式で brief YAML の seo: セクションに書き込まれる:

seo:
  primary_keyword: "content cluster persona"
  secondary_keywords:
    - "pillar narrative 設計 audience"
    - "コンテンツ SSOT persona taxonomy"
  longtail_clusters:
    - "cluster と persona の違いとは何か"
  search_intent: "informational"
  serp_title_finalized: "..."
  serp_description_finalized: "..."

@seo-director は素案を main thread に返すアドバイザとして設計されている。実際の YAML 書き出しは main thread が行う。この設計は、advisor が直接ファイルを編集することなく、main thread が最終判断を持つ構造を維持する。

brief YAML を hub にした戦略伝播の設計

各 executor skill が brief の特定セクションを読みに行く契約

advisor の出力を brief YAML に書き込んだだけでは、後段の skill に伝わらない。各 executor skill が brief の特定セクションを「読みに行く」契約を明示することで、上流の戦略が下流に継承される。

blog-tech-write スキルは、ブリーフ駆動モードで以下を実行する:

SEO_SECTION=$(python3 -c "
import yaml
d = yaml.safe_load(open('blog-ops/articles/{slug}.yaml'))
seo = d.get('seo', {})
print(f\"primary_keyword: {seo.get('primary_keyword', '')}\")
print(f\"secondary_keywords: {seo.get('secondary_keywords', [])}\")
")

取得した SEO 情報を LLM プロンプトに渡し、H2 タイトルへの primary_keyword の自然な組み込みと、本文中への secondary_keywords の配置を指示する。

seo セクションが tech-write / review / meta に継承される例

brief の seo セクションは以下の形で各 executor に継承される:

executor	seo セクションの使い方
`blog-tech-write`	H2 タイトルに primary_keyword を反映、secondary_keywords を本文に自然配置
`blog-review`	`serp_title_finalized` の文字数・keyword 整合を検証
`blog-meta`	`serp_title_finalized` / `serp_description_finalized` を初期値として title / description を最終化

この継承チェーンは、advisor（@seo-director）の出力が執筆・レビュー・meta 設定まで一貫して反映されることを保証する。advisor を差し替えても（例: @seo-director の実装を更新した場合）、各 executor の実装は変更しなくてよい。brief YAML が hub として機能しているからだ。

hub 設計の利点

advisor と executor が brief YAML を介して通信する設計の利点は、coupling が弱いことだ。

@seo-director は brief YAML の seo セクションを書き込む責務だけを持つ。blog-tech-write は brief YAML の seo セクションを読む責務だけを持つ。両者は brief の schema を共通インターフェースとして参照するだけで、お互いの実装を知る必要がない。

これは、パイプラインのモジュール性を保つための重要な設計だ。advisor の出力仕様が変わった場合、変更箇所は brief schema と @seo-director の実装だけで、各 executor は brief schema の変化を自動的に読み取って対応できる。

gate による戦略セクション欠落の検出

blog-gate G11: pillar の seo セクション欠落を fail にする

advisor を phase 0 に明文化しただけでは、advisor が実行されたかどうかを保証できない。実行を強制する構造として、gate を使う。

scripts/blog-gate.ts の G11 拡張（seo セクション版）は、is_pillar: true の brief で seo.primary_keyword / seo.secondary_keywords / seo.search_intent / seo.serp_title_finalized の 4 フィールドのいずれかが欠落している場合に fail を返す。

G11 拡張: pillar の seo セクション必須チェック
  条件: brief.is_pillar === true && seo セクションの必須 4 フィールドのいずれかが欠落
  結果: fail
  理由: pillar は cluster の keyword 軸を持つ。SEO 設計なしで執筆した pillar は後追い retrofit が必要になる

gate で seo セクションを保護することで、@seo-director を phase 0 で実行していない場合は pipeline が先に進めない構造になる。advisor の実行が構造的に強制される。

戦略セクションを gate で保護することで advisor の実行が強制される

advisor を「呼ぶかどうか」を main thread の判断に委ねると、忙しい日には呼ばれない。gate で「advisor が出力した証拠（seo セクション）がなければ先に進めない」設計にすることで、advisor の実行は pipeline の構造的な前提条件になる。

この「判断（advisor）と実行（executor）の分離」は、コスト分離でもある。「AI Subscription Time Bomb」の調査によれば、GitHub Copilot は 2026 年 6 月 1 日から使用量ベース課金へ移行しており、OpenAI は 2029 年までに 1150 億ドルの累積現金焼却見込みとされる。advisor を Opus で 1 回走らせ、executor を Sonnet / Haiku に振る pipeline 設計は、そのまま「高コストモデルの使用を判断フェーズに限定する」トークン戦略になる。固定サブスクリプションが補助金として機能している時代が終われば、この分離の有無が運用コストに直接効く。

G11 の一部として実装されている。checkG11_PillarSeoSection() が cluster / audience.primary / seo セクションの 4 フィールドをまとめてチェックする。blog-gate.ts のコメントに「G11: pillar 記事の brief に cluster / audience.primary / seo セクション欠落」と明記されている（L572-577）。

cc935f4 の git show --stat で確認すると、pipeline JSON は new-article-pillar.json（新規）、new-article-spoke.json（新規）、rewrite-case.json（修正）、rewrite-tech.json（修正）の計 4 ファイルだ。同 commit には .claude/agents/seo-director.md、関連する 3 skill ファイル、scripts/blog-gate.ts、src/content/config.ts 等も含まれる。

まとめ — advisor を pipeline に接続する 3 要素

advisor agent が pipeline に組み込まれて初めて機能する。その設計に必要な要素は 3 つだ。

pipeline JSON への phase 0 明文化: advisor の起動ルートを pipeline の最初の phase として宣言する。depends_on で後段 executor が前段 advisor の完了を前提とする
brief YAML を hub にした戦略伝播: advisor の出力を brief の特定セクションに書き込み、各 executor が brief を読みに行く契約を明示する。advisor と executor が直接通信しない疎結合設計
gate による戦略セクション欠落の検出: advisor が実行された証拠（brief の特定セクション）がなければ pipeline を fail にする。advisor の実行が構造的に強制される

この 3 要素が揃うことで、advisor は「存在するが使われない agent」から「pipeline の設計に組み込まれた戦略レイヤー」へと変わる。

advisor を作った後に「なぜ使われていないのか」と疑問に思ったなら、まず pipeline JSON を確認してほしい。起動ルートがなければ、advisor は動かない。

→ cluster 単位の SEO keyword 設計と keyword マップ保守の詳細については cluster SEO 実装 — pillar primary を spoke secondary に降ろす設計を参照してほしい。