brief-outline-generator

Brief Outline Generator

フォーマット済みの.docxファイルとして、コンテンツのアウトラインを生成します。出力は骨組みです。各セクションの見出し、短いトピックの提示、各セクションの切り口を含み、ライターが独自の結論、数値、文章を追加して仕上げます。

これはアウトラインジェネレーターであり、ブリーフジェネレーターではありません。 出力がメモ形式の記事のようになっている場合は、踏み込みすぎです。生成を始める前にreferences/section-rules.mdを読んでください。

DOCXは必ずscripts/generate-brief.pyを実行して生成します。レンダラーを再実装しないでください。インラインでdocxのコードを書かないでください。設定JSONを組み立て、スクリプトを実行してください。

---

入力 — 作業を進める前にユーザーから収集

フィールド	必須	メモ
title	✅	ブログ記事のタイトル。70文字を超える場合は警告してください。
focus_keyword	✅	メインキーワード
sitemap_url	✅	サイトマップの完全なURL。例：https://firefly.ai/sitemap.xml。domain_urlはここから自動的に導出されます。
word_count_range	✅	例：1500-2000
target_intent	✅	Informational、Commercial、Transactional、Navigationalのいずれか
target_product	⬜	製品名。指定すると、製品紹介セクションが追加されます。
secondary_keywords	⬜	事前に指定されたリスト。指定されている場合は生成を省略します。

---

実行ワークフロー — 次の手順を順番に実行

Step 1 — 入力を検証する

• title：空でないこと。70文字を超える場合は警告してください（処理は止めないでください）。
• focus_keyword：空でないこと。
• sitemap_url：空でなく、http://またはhttps://で始まっていること（パスは問いません。.xml、.xml.gz、拡張子のない動的URLはすべて有効です）。
• word_count_range：ハイフン（-）で区切られた2つの正の整数であること（例：1500-2000）。
• target_intent：Informational、Commercial、Transactional、Navigationalのいずれかであること（大文字と小文字は区別しません）。

sitemap_urlから次の2つの値を導出します。

• domain_url — パスを取り除いてオリジンを取得します。例：https://firefly.ai/sitemap.xml → https://firefly.ai。設定JSONで使用します。
• domain_hostname — プロトコルも取り除きます。例：https://firefly.ai → firefly.ai。ホスト名のみが必要なツール呼び出しで使用します（例：site:firefly.ai）。

先に進む前に処理を止め、すべての検証エラーを報告してください。

---

Step 2 — ルールを読む

今すぐreferences/section-rules.mdを最後まで読んでください。 以下が記載されています。

• アウトラインとブリーフの違い（最も重要なルール）
• 箇条書きの必須ルール（12語以内、数値を作り出さない、結論を書かない、emダッシュを使った節を含めない）
• 構成の必須ルール（topic_summaryを含めない、Writer Directivesボックスを含めない、TLDRにはトピックの要点を2～3個記載）
• 4つの型（リスティクル、比較、ハウツー、概念解説）と、それぞれのセクション構成
• セクションごとのルールと箇条書きの良い例・悪い例
• DOCX生成前に実行する最終品質チェック

この手順を省略しないでください。 ルールを読まずに生成すると、毎回ブリーフ形式の出力になります。

---

Step 3 — ドメイン分析

DataForSEOツールの使用は保留されています。呼び出す前に読み込んでください。 この手順の開始時にtool_search(query="on_page content parsing")を呼び出します。

3a — サイトURLを確認する

sitemap_urlに対してweb_fetchを呼び出します。

• 読み取り可能なXML（応答に<loc>タグが含まれる）→ すべての<loc> URLを抽出します。これらがサイトURLです。
• バイナリ／圧縮形式（応答が読み取れない）→ フォールバックとして、keyword="site:{domain_hostname}"（例：site:firefly.ai）を指定してdataforseo:serp_organic_live_advancedを呼び出し、インデックス済みURLをすべて取得します。

上限は20 URLです。20件を超える場合は、ホームページ → 製品／ユースケースのページ → ブログ／リソースのページの順に優先してください。

3b — ページのコンテンツ全体を読む

3aで取得した各URLに対して、enable_javascript: trueを指定してdataforseo:on_page_content_parsingを呼び出します。

ページのテキスト全体（見出し、本文、製品説明など）がレンダリングされて返されます。出力をすべて収集してください。

ページの読み込みに失敗した場合（ボット対策、タイムアウト）は、そのページをスキップして続行してください。処理全体を中止しないでください。

3c — メタタイトルと説明文を抽出する

3b で解析したホームページのコンテンツから、以下を抽出します。

• ページの <title> → meta_title
• <meta name="description"> の内容 → meta_description

文字数が推奨範囲外の場合は、注意事項を表示します。

• meta_title が 50～60 文字の範囲外 → 「注意：取得したメタタイトルは N 文字です（推奨：50～60 文字）。」
• meta_description が 150～160 文字の範囲外 → 「注意：取得したメタディスクリプションは N 文字です（推奨：150～160 文字）。」

これらは meta_title と meta_description として設定に渡され、メタデータの表に表示されます。

3d — domain_context を作成する

解析したすべてのページコンテンツから、以下を抽出して保存します。

• 製品名と中核となる価値提案
• サイトで使用されている主要な技術用語と語彙
• 想定読者を示す情報（言及されている職種、チームの種類、ユースケース）
• 既存のコンテンツのトピック — アウトラインの重複を避けるために使用します

domain_context として保存します。**出力ドキュメントには domain_context を表示しないでください。**すべての取得に失敗した場合は、domain_context = null に設定して続行します。

---

Step 4 — タイトルのアーキタイプを分類する

タイトルのパターンに基づいて、次のいずれかを選択します。

• リスト記事／ツールまとめ — 「Top N」「Best X」「X Alternatives」
• 比較／対決 — 「X vs Y」「X or Y」
• ハウツー／実装ガイド — 「How to X」「How do X teams Y」「Implementing X」
• 概念／解説 — 「What is X」「Designing X」「[Function/Pattern]: Designing X」

複数のパターンに当てはまるように見える場合は、section-rules.md のデフォルトを使用します。それでも不明な場合は、ユーザーに確認します。

生成前に、選択したアーキタイプをユーザーに1行で伝えます。例：「検出されたアーキタイプ：ハウツー。導入部 → 戦略 → ケーススタディ → 実装 → FAQ の構成でアウトラインを生成します。」 ユーザーが同意しない場合は、変更できるようにします。

---

Step 5 — キーワードの検索ボリュームを取得する

DataForSEO を使用して、フォーカスキーワードと各セカンダリーキーワードの米国における月間検索ボリュームを取得します。

DataForSEO ツールは呼び出す前に読み込む必要があります。

1. tool_search(query="keyword search volume google ads") を呼び出して、DataForSEO のキーワードツールを読み込みます。
2. キーワード（フォーカスキーワードとすべてのセカンダリーキーワード）の全リストを1回の呼び出しで指定し、dataforseo:kw_data_google_ads_search_volume を呼び出します。米国を指定するには location_code に 2840 を使用します。
3. レスポンスから、各キーワードの search_volume フィールドを抽出します。
4. 各ボリュームは、3桁ごとに区切った文字列に整形します（例：3400 → "3,400"）。1,000 未満のボリュームは、数字のみの文字列にします（例："500"、"30"）。ボリュームが 0 の場合は、"N/A" ではなく "0" と表示します。これは実際のデータポイントです。
5. キーワードのデータが返されない場合は、そのボリュームを "N/A" に設定して続行します。処理全体を中止しないでください。
6. tool_search で DataForSEO ツールが返されない場合（コネクターがインストールされていない場合）は、すべてのボリュームを "N/A" に設定し、1行の警告を表示します：「DataForSEO コネクターを利用できません — キーワードの検索ボリュームを N/A に設定しました。」

**どのキーワードでもボリュームフィールドを省略しないでください。**すべての行に必ず含めます。

**検索ボリュームの不一致を通知します。**フォーカスキーワードのボリュームが、いずれかのセカンダリーキーワードのボリュームより10倍を超えて小さい場合は、生成前にユーザーに伝えます：「注意：フォーカスキーワードのボリュームは X ですが、セカンダリーキーワード Y のボリュームは Z です。Y をフォーカスキーワードにするか検討してください。」 判断はユーザーに委ね、自動で入れ替えないでください。

次のように保存します。

"focus_keyword_volume": "2,400",
"secondary_keywords": [
  { "keyword": "disaster recovery plan", "volume": "1,900" },
  { "keyword": "cloud DR strategy",      "volume": "N/A"   }
]

セカンダリーキーワードが指定されていない場合は、フォーカスキーワードの基本語句、ドメインの主要用語、修飾語（"best practices"、"guide"、"checklist"、"for teams"、現在の年）を組み合わせて5つ生成します。その後、同じ方法で検索ボリュームを取得します。

---

ステップ 6 — アーキタイプのセクション構成を使ってアウトラインを作成する

ステップ 4 で選んだアーキタイプのセクション構成を使います。すべてのトピックをハウツーのテンプレートに無理に当てはめないでください。 リスト記事には「問題」や「ケーススタディ」のセクションはありません。比較記事には「実装手順」はありません。

各セクションオブジェクトの形式：

{
  "heading": "H2",
  "title": "Section Title",
  "rules": ["short topic prompt 1", "short topic prompt 2"],
  "subsections": [
    {
      "heading": "H3",
      "title": "Subsection Title",
      "rules": ["..."],
      "subsections": []
    }
  ]
}

前のスキーマから削除されたフィールド（使用しないでください）：

• topic_summary — 削除されました。アウトラインに概要は含めません。
• directives — 削除されました。箇条書き自体に方向性を示します。
• visual — 削除されました。ビジュアルが重要な場合は、箇条書きのプロンプトとして記述します：「比較表を含める：軸 × ツール」。
• faqs — 削除されました。FAQ は質問のみです（rules 内）。回答は執筆者が作成します。

rules 内の箇条書きは、section-rules.md の厳格なルールに従います：

• 1 項目につき 12 語以下
• 具体的で、考えが完結していること
• 数字を捏造しないこと
• 結論を含めないこと — トピックのプロンプトのみ
• 説明のための挿入句に em ダッシュを使わないこと

長さは固定の上限ではなく、内容に従います。 セクションに必要な数だけ箇条書きを使います — 2 項目必要なら 2 項目、9 項目必要なら 9 項目です。section-rules.md の「一般的な範囲」は目安であり、制限ではありません。目標数に達するために水増しするのも、目標数に合わせて短縮するのも誤りです。

TLDR セクション： TLDR の見出しを含め、執筆者が TLDR で取り上げる内容を示す短いトピックの要点を 2〜3 個記載します（各 12 語以下）。要点はトピックであり、完成した結論ではありません。記事の中心的な緊張関係、読者が行うべき主な転換、実践的な次のステップを取り上げます。良い例・悪い例については、references/section-rules.md の TLDR セクションを参照してください。

FAQ セクション： rules フィールドに質問の文字列をリスト形式で記載します — 回答は含めず、質問のみです。実際の回答は執筆者が作成します。各質問は 1 つの箇条書きにします。質問の表現方法に重点を置きます。具体的で行動につながる質問（「Claude スキルをインストールするにはどうすればよいですか？」など）にし、抽象的な質問（「Claude はどのスキルを呼び出すかをどのように判断しますか？」など）にはしません。ユーザーが指定したすべてのキーワード（主キーワードと各副キーワード）を、実際に検索する人が入力しそうな言い換えで、キーワードを詰め込まずに、質問全体へ自然に含めます。通常は 5〜8 個の質問を記載しますが、固定の上限はありません。例については、section-rules.md の FAQ セクションを参照してください。

---

ステップ 7 — 最終的な品質チェックを行う

設定を組み立てる前に、アウトラインを確認し、次の項目を検証します（section-rules.md より）：

1. 接続詞を足すだけで、執筆者がそのまま公開できますか？ → はいの場合は、内容を削って簡潔にします。
2. すべての箇条書きが文ではなく、トピックのプロンプトとして読めますか？（FAQ の質問は自然な完全な文なので除く）→ いいえの場合は書き直します。
3. 各箇条書きの意味を、執筆者が 3 通りに解釈できますか？ → はいの場合は抽象的すぎます。具体的な対象（ファイル、コンポーネント、技術用語）を明記します。
4. 音読したとき、各箇条書きは考えが完結していますか？ → 意味が通じない文の断片（「対象読者：X を行う開発者」など）の場合は、考えを最後まで書きます。
5. 技術的な主張はすべて正確ですか？ → スキルはフォルダーではなくパッケージです。Claude はスキル全体を先読みするのではなく、SKILL.md を読み取ります。確信がない場合は、その主張を避けるように書き換えます。
6. 捏造した数字はありませんか？ → 削除します。
7. H2 見出しとして扱うべきサブ項目はありませんか？ → 該当項目を H2 に昇格させます。
8. H2 タイトルは記事のトピックに特化していますか（一般的な動詞句になっていませんか）？ → 「タスクを絞り込む」ではなく、「スキルに何をさせるかを定義する」とします。
9. セクションの順序はアーキタイプと一致していますか？ → 確認します。
10. topic_summary、directives、faqs フィールドは含まれていませんか？ → 含まれている場合は削除します。FAQ の質問は rules 内にフラットな箇条書きで記載します。
11. ユーザーが指定したすべてのキーワード（主キーワードと各副キーワード）が、FAQ の質問全体に自然に含まれていますか？ → 抜けているものがあれば、そのキーワードを含めるよう質問を書き換えます。
12. FAQ の質問は抽象的ではなく、具体的で行動につながるもの（「インストールするにはどうすればよいですか？」「〜との違いは何ですか？」など）ですか（「Claude はどのように判断しますか？」など）？ → 曖昧な質問は書き換えます。

12 項目すべてに合格したら、次に進みます。

---

ステップ 8 — 設定 JSON を組み立てる

完全な設定を /home/claude/brief-config.json に書き込みます。

{
  "title": "...",
  "focus_keyword": "...",
  "focus_keyword_volume": "N/A",
  "domain_url": "...",
  "word_count_range": "...",
  "target_intent": "...",
  "target_product": "...",
  "archetype": "how_to",
  "meta_title": "...",
  "meta_description": "...",
  "secondary_keywords": [
    { "keyword": "...", "volume": "N/A" }
  ],
  "output_path": "/mnt/user-data/outputs/outline-{file_slug}.docx",
  "outline": [ ... ]
}

スラッグに関する注意： スラッグは内部で 2 種類生成されます。

• URL スラッグ（メタデータ表に表示）— focus_keyword をもとに生成されます。例："cloud disaster recovery" → cloud-disaster-recovery。
• ファイルスラッグ（ファイル名に使用）— title をもとに生成されます。例："How Do Platform Teams Implement Cloud Disaster Recovery" → outline-how-do-platform-teams-implement-cloud-disaster-recovery.docx。

設定内の output_path には、タイトルをもとにしたファイルスラッグを指定します。

設定に domain_context を含めないでください。 これは上流の生成処理に使用され、レンダリングされたドキュメントには表示されません。

---

ステップ 9 — 生成スクリプトを実行する

python /path/to/skill/scripts/generate-brief.py --config /home/claude/brief-config.json

スクリプトが DOCX のレンダリングをすべて処理します。docx のコードは自分で書かないでください。

スクリプトが 0 以外の終了コードを返した場合は、stdout/stderr のエラーを報告し、フォールバックとしてアウトラインをプレーンテキストで表示してください。

---

ステップ 10 — ファイルを提示する

出力パスを指定して present_files を呼び出します。次を報告してください。

✅ Outline generated: outline-{file_slug}.docx
   Archetype:     {archetype}
   Slug (URL):    {url_slug}  (from focus keyword)
   Slug (file):   {file_slug}  (from title)
   Audience:      {audience}
   Focus KW:      {focus_keyword} ({volume})
   Secondary KWs: {kw} ({vol}), ...
   Sections:      {N} sections

---

スクリプトがレンダリングする内容（参考のみ — 再実装しないでください）

スクリプトは次の内容を含む .docx を生成します。

1. メタデータ＋キーワード表 — 3 列：Field | Value | USA Search Volume。標準行（Title、URL Slug、Word Count、Target Intent、Target Audience、Meta Title（50-60 chars）、Meta Description（150-160 chars））では、2 列目と 3 列目が結合されます。URL スラッグはタイトルではなく、focus_keyword をもとに生成されます。 フォーカスキーワードと各セカンダリーキーワードはそれぞれ独立した行になり、3 列目に検索ボリュームが表示されます（アンバーの背景）。Domain と Domain Context の行は表に含まれません。
2. H1 タイトル
3. セクション — 各 heading フィールドは、グレーの [H2] または [H3] ラベル接頭辞＋見出しテキストとしてレンダリングされます。rules は箇条書きとしてレンダリングされます。topic_summary ブロックと Writer Directives ボックスはありません — これらはフォーマットから削除されています。

---

参考ファイル

• references/section-rules.md — アウトライン優先のルール、アーキタイプ、セクションごとのルール、良い例と悪い例。何よりも先にステップ 2 で読んでください。
• scripts/generate-brief.py — DOCX レンダラー。必ずこれを実行してください。再実装しないでください。
• examples/ — 基準となる良いアウトライン。参考のみです。箇条書きの長さ、密度、トーンを調整するために参照してください。セクション構成、見出し、トピックをコピーするためのものではありません。現在のトピックの構成は、references/section-rules.md のアーキタイプのルールに従ってください。トピックが似ている場合でも、ユーザーのアウトラインのテンプレートとして例のアウトラインを使用しないでください。