Bizdoc

bizdoc

ユーザー入力（topic 文字列 / URL / ローカルファイルパス / 直前会話）を起点に、白基調・図解付き1枚 HTML のビジネス文書を生成し、doc-hub（node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs"）に保存する orchestrator。

1. Input / Output

• Input: $ARGUMENTS = topic 文字列 / URL / ローカルファイルパス のいずれか。空または曖昧なら直前会話を context として拾う。
• Output: doc-hub に保存済みのドキュメント。保存先パスは Phase 5 の hub.mjs add の stdout（保存先 index.html の絶対パス1行）で確定する。会話の最後にこのパスをユーザーへ提示する。
• 副産物（doc-hub には保存しない）: 調査結果 context.md、構成案 outline.json。スクラッチ領域の一時ファイルとして扱い、doc-hub に保存するのは組み立て済みの最終 HTML のみ。

2. 最重要（compaction 対策）

• 1 ターンで Phase 0〜5 を完走する（フェーズ間で応答を終了しない）。Phase 0 の目的・読者・種別が会話から一意に定まる場合は AskUserQuestion で止めず即着手する。
• 1枚 HTML 縛り（CDN 禁止。CSS は <style> にインライン、SVG も文書内にインライン。外部ファイル参照や <link> での読み込みはしない）
• 図解の既定は gpt-image-2（B2 高密度インフォグラフィック） — 次点 drawio（厳密文字・再編集要件）、手書き SVG は型に収まる単純図のみ（2026-08-20 オーナー決定）。適していると判断したら確認せずに使う（1ターン完走を止めない）。基準と spec は §7

詳細な落とし穴は §11 Gotchas に集約する。

3. いつ使う / いつ使わない

判断基準: 「業務の意思決定・報告・引き継ぎに使う、フォーマルな文書か」= bizdoc。「わかりやすさ優先のカジュアルな解説か」= run-explainer-page。

4. Phase 0: 目的確定

会話から次の4項目を確定する。ここで確定した内容が .cover（表紙相当）の中身になり、Phase 2 で各ブロックに書く why の判定基準になる。

1. 目的（なぜ作るか。例: 予算承認を得る／進捗を共有する／手順を周知する）
2. 読者（誰が読むか。例: 経営層／情報システム部／現場担当者）
3. 文書種別（提案書 / 報告書 / 解説 / 手順書 / 議事録 のいずれか、または相当するもの）
4. トーン（フォーマル度・断定の強さ。読者との関係性から判断）
5. 決裁レイヤー判定（会話から自動判定。質問しない）: 目的に「承認を得る・決裁を仰ぐ・予算を獲得する」が含まれるか。含まれれば決裁レイヤー on（exec-summary への依頼1項目・終端の判断材料ブロック・cover meta の宛先/版数。本文の構成規範は変えない — §6 のモード表参照）。含まれなければ理解優先の既定構成のみで作る。あわせて読者の抵抗を判定する: 結論が読者の既存方針・利害と対立する題材なら高抵抗とし、exec-summary の項目を「発見」に留めて推奨を終端の判断材料ブロックへ置く

4項目が会話から一意に定まらないときだけ、AskUserQuestion で1問に絞って確認する。選択肢は「種別 × 読者」の組合せ候補（例: 「提案書・経営層向け」「報告書・現場向け」等）にし、自由記述の余地も残す。定まっているときは質問せず即 Phase 1 へ進む（§2 の1ターン完走を優先）。

5. Phase 1: 調査

入力をパースし、以下のいずれか or 両方の subagent を起動する。親は要約だけ受け取り、探索結果の全文を主コンテキストに吸わせない。

判定ルール

• 入力が社内のコードベース・システム・ローカルファイルに関する題材 → Explore エージェント
• 入力が抽象的なトピック・社外事情・市場動向など → general-purpose エージェントによる web research
• 両方ありうるなら 1 メッセージで並列 fire

Explore エージェントの呼び方（コードベース・社内システム題材）

Agent({
  description: "bizdoc Phase 1 code research",
  subagent_type: "Explore",
  prompt: "<対象コードベース/システムで何を読んで欲しいか具体的に。例: '<repo>の認証まわり\
           (src/auth/*) を読んで、報告書の読者（情報システム部）が知りたい実装状況・\
           残課題を300語以内で。数字（件数・所要時間等）は取得元を明記して。仕様書や\
           コメントの文は自分の言葉に言い換え、原文のまま残すのは短い語句 1 つまで'>"
})

Web research subagent の呼び方（抽象トピック・社外事情）

Agent({
  description: "bizdoc Phase 1 web research",
  subagent_type: "general-purpose",
  prompt: "<下記の指示文をそのまま渡す>"
})

指示文テンプレ:

あなたはビジネス文書（種別: <Phase0で確定した種別>）作成のための調査役。
トピック: 「<TOPIC>」/ 目的: <Phase0で確定した目的> / 読者: <Phase0で確定した読者>

以下を500語以内のサマリで返す:
1. 読者が前提として知っておくべき事実（3-5点）
2. 数字（価格・実績・比較値等）— 必ず出典 URL と取得日を併記する。出典が確認できない数字は
   「未確認」と明記し、断定形で書かない
3. 論点・リスク・反対意見になりうる材料
4. 意思決定や行動を後押しする材料（推奨・比較の根拠になりうるもの）
5. 図解にできそうな構造（比較・時系列・構成・手順・関係・分類 のどれに近いか）

6. 出典の言葉の扱い: 各ソースの内容は自分の言葉で 1〜2 文に言い換える。原文のまま残すのは「」付きの短い語句を
   1 つまでとし、出典（URL・取得日）を添える。正解例（1 行）:
   　同社の決算説明資料（URL, 2026-09-03 取得）は国内売上の伸びを主因に挙げ、業界誌の解説記事（URL, 2026-09-03 取得）は同じ数字を「一時的な特需」と評した。
   — 2 つの出典を間接話法で対比し、原文のまま使ったのは「」付きの短い語句 1 つだけ。

出力はマークダウン書式。親が context.md に統合する。

縮退モード

Agent ツールが使えない文脈（自分がサブエージェントとして実行されている等）では、subagent を起動せず自分で調査して context.md を書く: ローカル題材は Read / Grep で読み、社外事情は WebSearch / WebFetch で公式情報を取得し、上記 6 項目（出典の言葉の扱いを含む）を自分で埋める。

context.md への統合

subagent の要約（または縮退モードでの自前調査）を、スクラッチ領域の context.md に統合する。数字には必ず出典 URL と取得日を添える（出典なしの断定は禁止）。

6. Phase 2: アウトライン

context.md を読んで outline.json をスクラッチ領域に Write する。構成は毎回ゼロから設計し、順序付きの章立てテンプレは書かない（「提案書は背景→課題→提案→効果→費用の順」のような固定型を持ち出さない）。

必須要素はビジネス文書の作法として次の2つだけ:

1. 表紙相当（タイトル・日付・目的・読者。.cover で表現する）
2. 結論先出し（.exec-summary。文書の要点を冒頭で言い切る）

それ以外の構成は ${CLAUDE_PLUGIN_ROOT}/templates/components.md を伝達目的（比較させる／時系列・計画を示す／判断を促す／根拠・数値を示す／全体像を掴ませる／手順を追わせる／注意を促す／規模感・絞り込みを示す／関係・体制を示す）で毎回引き、その文書の目的・読者に効くブロックだけを選ぶ。各ブロックに why（目的・読者にどう効くか1行）を必須とし、書けないブロックは削る。

構成規範（「チープな構成」の禁止則）

• 見出しはメッセージにする: 各セクションの見出しは「読者への主張を言い切る文」にする（例: 「品質は目視の頑張りではなく、2つの決定論ゲートが守る」）。トピックラベル（「背景」「構成」「使い方」「まとめ」）を見出しにしない
• 見出しのレジスター（文体水準）を縛る: 「メッセージにする」は主張の強さの規範であり、圧縮の免罪符ではない。以下の各則は見出し1本ごとに評価し、文書全体で機械的に同時充足させない（v0.9.0 — 全節で満たそうとすると構文が収束する。下の「構文を散らす」を参照）。A/B 実測で bizdoc 見出しの認知負荷が高いと評された残存要因は、格式を漢語の圧縮で出そうとする癖にある — 格式は内容の確かさで出す。対象はセクション見出し（h2・outline の主張文）のみで、§8 の目次短縮形（25字要約・体言止め可）は対象外
  • 1見出し1主張: ダッシュ（—）の後ろに置けるのは主張の補強・限定まで。独立した2つ目の主張は .sec-lede か本文へ落とす（または節を分ける）
  • 用言で言い切る: 体言止め・名詞化（「〜の拡大」「〜済み」「〜の活用開始」）をやめ、動詞で終える（「〜が増えた」「〜を確認する」）。断定の常体で書けば口語にはならない
  • 未解決要素を1つ残す: 見出しは主張文のまま、本文が回収する未解決要素（なぜ／どうやって／何を捨てたか）を1つ残す。目次を上から読んだとき全見出しが「答えの言い切り」で完結している outline は差し戻す（見出しを読んだ時点で本文を読む理由が消える）
  • 疑問形の許可: 読者が自発的に抱かない問いを文書側が起こす節では、疑問形見出し（「なぜ〜のか」— 用言終止として合法）を使ってよい。その場合 .sec-lede に1行の答えを必ず置く。節数のおよそ3分の1まで（v0.9.0 で1〜2節から緩和）。答えの伴わない問いは引き続き禁止
  • 構文を散らす（v0.9.0）: 上の各則を全見出しで同時に満たそうとすると、構文が1つに収束する。実測（7節の報告書）で7見出しすべてが「Xは〜する」の平叙断定になり、うち3つが否定・逆接で終わった — 個々は規範を満たしているのに、目次で並ぶと単調になる。同一構文が3節連続したら、そのうち1つを別の型へ替える。使える型は次の3つ:
    • 平叙断定（既定。「原価は QR が読まれた回数で動く」）
    • 疑問形（上記の許可枠内。「なぜ上限に当たっても気づけないのか」）
    • 機能ラベル（「1本あたりの内訳」「判断が要る3点」）— 下の許可条件を満たす節に限る
  • 機能ラベル見出しの条件付き許可（v0.9.0）: 「トピックラベル禁止」は、主張を持てる節が主張を放棄することへの禁止であって、主張が本来無い節にまで断定を強いる則ではない。次のいずれかに当てはまる節は機能ラベルにしてよい:
    • 一覧・カタログの節 — 内訳表・確度一覧・用語集など、読者が「探しに来る」節（主張は既に別の節が述べている）
    • 判断材料を並べる節 — 選ばせるのが目的で、書き手が1つに決めない節
    • 構文の反復を断つため（上記「構文を散らす」の適用） 許可した場合も .sec-lede は主張文で書く（節が何も主張しない状態は作らない）。この3条件のどれにも当たらない節でのラベル化は、従来どおり禁止
  • 骨格可読性: 見出し＋sec-lede だけの拾い読みで文書の論旨が再構成できること（Phase 5 の検査項目）
  • 漢語のアドホック連結禁止: 漢字5字以上の連結語は、一語として定着した語（「費用対効果」等）・固有名詞・数値単位を除き見出しに置かない。「分析対象範囲拡大」型の即席連結は動詞へ開く（「分析する範囲が広がった」）
  • 長さ上限: 見出し全体で全角35字以内、ダッシュ前の主節は20字以内を目安。超えるときは語を削って圧縮するのではなく、主張を1つに絞る
  • 改稿例: 「費用増の原因は特定済み — モデルの問題ではなく、分析対象の拡大」→「費用が増えた原因は、モデルではなく分析対象が増えたことにある」／「効果は月額 −42%（試算）— 停止分の費用削減と、用件分類の活用開始を同時に行う」→「費用は試算で月額 42% 下がる」（ダッシュ後半は .sec-lede へ落とす）
• ピラミッドを張る: .exec-summary の各結論は、それを支える本文セクションを最低1つ持つ。どの結論とも対応しないセクションは、削るか結論側に昇格させる
• 1セクション = 1メッセージ、1画面 = 1ビート: 見出しの主張を超える話題を同じセクションに詰めない。各節はおおよそ1ビューポート（900px 目安）を1ビートとし、節の完了条件（この画面を読んだら読者が言えること）を1つだけ持つ。2つ言えるなら節を分割する。同一画面に新しい用語・新しい因果・例外を同時に出さない（例外・注記は次ビートか付録へ）
• .sec-lede は半歩先のスポイラー: 見出しの主張の「意外な一点」（何が常識と違うか・何を変えないか）を1行で書く。手続き文（「〜を要約します」）・免責・換算前提はここに置かない（本文末尾か出典行へ）。決裁レイヤー on のときは二重契約 — 逐次読者への半歩先スポイラーであると同時に、途中参入する決裁者が「この節の問いと答え」を局所復元できる形にする
• 密度規範（床と波形）: スクロール1画面（目安 900px）ごとに視覚要素（図・表・カード・KPI）を最低1つ置き、ベタ段落だけのセクションを作らない（床）。加えて密度の山は1節1つまでとし、高密度要素（表・コード・複雑図）の直前に1行のフレーム（何を見るか）、直後に1行の回収（「つまり〜」）を置く。情報を削って密度を下げるのではなく、到着レートを波形で整形する
• 視覚要素の役割固定: 図=構造、表=数値比較、callout=判定・洞察（「この表の下2行が設計の芯」）と役割を分け、同役ブロックの連続（kpi-grid 直後の table 等）を禁じる。callout はセクション末の判定・洞察専用スロットとし、コンプライアンス注記・手続き連絡を置かない。callout は器幅（表・図と同じ右端）で組まれるため本文は4行以内に収める — 超えるなら本文段落か .card へ移す
• 初手は構造図: 文書の最初の視覚要素は数値カード群でなく構造図（Before/After・全体像）にする。kpi-grid は読者が構造モデルを得た後の効果まとめ・実績報告に限る。新出概念が3つ以上ある文書は、最初の構造図を「登場概念のラベル付き地図」を兼ねる形にし、専門用語の初出を図中ラベルと同時にする（本文だけで定義しない）
• 前方参照禁止・証拠はその場: 「詳細は後述」「（N章）」「（別紙N）」のみを根拠として表セル・本文に置くことを禁止する。品質・効果の主張には、その場で最小の裏どり（実測値1つ＋確認手段1語）を添える。集約評価の節は置いてよいが、証拠の初出の場にしない。後方参照も同じ: 「節Nの図で見たとおり」で根拠を運ばず、必要な値・判定は1句でその場に再掲する（ブラインド審査の実測で、審査員2名が同一の後方参照箇所を往復として計上した）
• タイトルの数値は本文と同じ丸め: 見出しや表題で「半分」等に丸めた数値が本文の実数（42% 等）と食い違うと、読者は照合の往復を強いられる（同・審査実測）。丸めるなら本文も同じ語で通し、実数を使うならタイトルも実数にする
• 読者に演算・照合をさせない: 同一事実は1つの単位系で示し、換算・検算（増加率の積・円換算等）は書き手が済ませて結果だけ添える。番号参照（「施策②」等）は定義の後にのみ使う。表・図・終端に出る語の初出には1句の説明を付ける
• 短い呼び名: 反復参照される系・コンポーネント・施策が2つ以上あるときは、初出（できれば表の先頭列）で短い呼び名（A/B・①②③等）を与え、以後それで通す。字面の似た長い複合名を無短縮で反復しない
• 手続き隔離と結論ブロック: 手続き情報（機密表示・宛先・版数・承認事項・添付一覧・期限約束）は .cover の meta 行と終端の2箇所に隔離し、exec-summary・sec-lede・callout に混ぜない。文書末尾には exec-summary の各項を1行ずつ回収する結論ブロック（.conclusion — ダーク地の終端パネル）を置き、手続き・残課題で文書を終えない（承認節・残課題節の後に結論を置く）。冒頭の .exec-summary を終端に再利用しない — 地図（冒頭）と締め（終端）は視覚で区別する
• redundancy と橋のスコープ: 同一内容をリード・本文・図キャプションで繰り返さない（黙読文書の冗長は純粋な外在負荷）。ただし節の橋は例外: 節冒頭で直前の節の結論を1行以内で再掲して受けるのは接続装置であり冗長ではない
• 本編と付録の二層化: 本編は結論・根拠・図で完結させ、経緯・例外・手法・生データは付録節へ隔離する。<details> は画面向け補足に限定し、印刷必須の情報を入れない（Chromium は閉じた <details> を印刷でも展開しない）。付録は「読まなくても本線は閉じる」と明示する

配置規範（「読みにくい」の実測要因への対処）

同一トピックで run-explainer-page 出力と A/B 実測した結果、bizdoc が「難しい」と評された原因は 文章量でも文の長さでもなく（実測: 本文 4,247字 対 4,426字、1文の中央値 33字 対 40字といずれも bizdoc の方が簡潔）、 冒頭の重さと、表への長文詰め込みだった。次の2つを数値規範として守る。

• 冒頭要約の予算: .exec-summary は 3項目・各1文を既定とする。<small> の補足を付けるのは 多くても1項目まで（実測: 全項目に付けた文書は冒頭だけで 576字あり、explainer の TL;DR 203字の 2.8倍で、文書中で最も重いブロックになっていた）。補足したい内容はピラミッド原則上それを支える本文 セクションが必ずあるので、そちらへ落とす

• 表セルの上限: <td> は 40字以内。列数は 4列を上限とする。表幅は本文より広いが列で割られるため （4列なら1列 ≈ 190px・font-size: 13.5px）、40字を超えるセルは必ず3行以上に折り返して「一覧して比べる」 機能を失う。超える説明は本文の <p> か .card へ移し、表には結論だけを残す

• 数値の泣き別れを作らない（執筆時）: 数値と直後の助数詞・和文は詰めて書く（「9回」「97件」「2週間」— 間の半角スペースは折返し点になり「4 /回」型の泣き別れを生む）。「約・月・年 + $金額」のような分離できない和欧の組は   で繋ぐ（「約 $4,730」）。それ以外の和欧間スペースは通常どおりでよい（折れても泣き別れにならない）

文の長さの規範は置かない — 上記のとおり実測で bizdoc の文は既に簡潔であり、本文の文を短くする規範を 足すと事実に反する矯正になる。直すのは器（版面・配置）と見出しのレジスター（構成規範を参照）であって、 文の長さではない。

言葉づかいの規範（v0.9.0 追加。長さではなく語の選び方）

器は数値で縛るのに文章には一切規範が無い、という非対称が v0.8 まで残っていた。結果として 版面は毎回整い、言葉の質だけが書き手ごとにぶれる。以下は文を短くする則ではなく、 同じ長さのままどちらの語を選ぶかの則である。

• 読者の語で書く: 読者が普段その物事を呼ぶ名前を使い、実装側の呼称に寄せない （「QR が読まれた回数」であって「セッション発行数」ではない。「上限に当たる」であって 「予算リミットに到達する」ではない）。社内の実装名・テーブル名・変数名を本文の主語にしない — 出所として示すときは <code> と .src 行に置く
• 具体が抽象に勝つ: 「大幅に削減」「柔軟に対応」「適切に管理」を、数値・固有名・動作に置き換える。 置き換えられないなら、その一文はまだ何も言っていないので削る
• 主語を立てる: 「〜が行われる」「〜と考えられる」を避け、誰が・何がそうするのかを書く。 受動で書いてよいのは、主体が本当に問題でないときだけ（「上限は DB 側で締めてある」は可）
• 一度だけ言う: 見出し・.sec-lede・.callout は器が近接しているため、同じ主張を 3回書きやすい（実測: 1つの節で見出し「障害としては見えない」／lede「警告として出ない」／ callout「何も起きていないように見える」の三重反復）。同じ節の中で主張を言い換えて繰り返さない — 見出しが主張、lede が意外な一点、callout が判定・含意と、役割で書き分ける
• 修飾を疑う: 「非常に」「極めて」「まさに」「〜的」「〜性」は、無くても意味が変わらないなら削る。 強調は語ではなく事実の並べ方で作る
• カタカナ語は言い換えを1度試す: 定着語（コスト・リスク・データ）はそのまま使ってよい。 「アグリゲート」「ジャストアイデア」型は日本語へ開く

これは推敲の則であって、執筆を止める則ではない。 書き上げてから Phase 5 の骨格検査と 合わせて1度通す（書きながら1文ごとに点検すると筆が止まり、かえって痩せた文章になる）。

文書種別ごとの「読者が最初に知りたい問い」（構成のヒント。順序ではない）

構成を組み立てる前に、この文書の読者が最初に何を知りたがるかを自問する。以下は例であり、固定の章立てではない — 実際の問いは Phase 0 の目的・読者に応じて毎回立て直す。

outline.json の形

{
  "slug": "kebab-case-slug",
  "type": "提案書",
  "approval_layer": false,
  "budget": { "sections": 6, "figures": 4, "raster": 1 },
  "cover": {
    "title": "...",
    "date": "2026-07-31",
    "purpose": "Phase0で確定した目的",
    "reader": "Phase0で確定した読者"
  },
  "exec_summary": {
    "why": "結論を冒頭で言い切ることで、多忙な読者が本文を読まなくても要点を掴めるため",
    "points": ["...（各項目に本文でしか解けない緊張語を1つ残す）"],
    "request": "決裁レイヤー on のときだけ: 何をいつ承認してほしいか1文"
  },
  "blocks": [
    {
      "purpose_key": "根拠・数値を示す",
      "expression": "kpi-grid",
      "why": "<この目的・読者にどう効くか1行>",
      "q": "<この節が回収する読者の問い（前節が開いたもの）1行>",
      "opens": "<この節の締めが次節へ開く問い1行。最終節は空でよい>",
      "content": { "...": "..." }
    }
  ]
}

budget は器の予算（節数・図の枚数）を生成前に宣言するもの。超過したときは情報を削らない — extraneous（冗長・帳簿仕事・装飾）を削るか、情報を付録へ移すか、図を分割する（生成文書は放置すると饒舌側に膨らむため、予算は「足す」でなく「移す・整形する」編集を強制する装置）。

アクセント色は outline.json では決めない（Phase 4 で hub 側の既存プロジェクト状態を見て決める。§8 参照）。

blocks の並びは主題の分類でなく読者の問いの発生順で決める（固定順は持たない）。位置 X の読者は X より上で確立したことしか知らない前提で書く。outline 段階で次の2つを検査する:

1. question chaining 検査: 各節が末尾に残す問いを1行ずつ書き出し（outline.json の opens）、次節の見出しがその問いを受けているか（次節の q）確認する。受けない節は並べ替えるか接続文を足す
2. 反論の即時回収: 主張が誘発する最強の反論（「なぜもっと安い案にしないのか」等）は評価章へ先送りせず、その主張の直後に専用の節を立てて回収する

expression は components.md に列挙された表現名（kpi-grid / compare-cols / steps / SVG パターン名 等）を使う。

7. Phase 3: SVG 図解

outline.json の blocks のうち SVG 表現を選んだものについて、埋め込む前に必ず ${CLAUDE_PLUGIN_ROOT}/templates/svg-patterns/README.md（全パターン共通の予防則。現在10項目）と、該当パターンファイル（例: ${CLAUDE_PLUGIN_ROOT}/templates/svg-patterns/process-flow.md）を Read してから書く。

• 各パターンファイルが定めるラベル文字数上限を守る（超える場合はラベルを短くするか図を分割）
• 図の密度規範（副ラベル・順路・終端判定・実データ標本・1点強調）は svg-patterns/README.md 予防則11〜15 に従う
• 色は var(--accent) 等 tokens.css の CSS 変数で参照する（アクセントは1色のみ。唯一の例外が var(--warn) で、超過・未達・要対処の1要素にだけ使える。予防則5）
• 同一文書内に複数の SVG を貼るときは marker id の衝突がないか確認する（README.md 参照）
• kpi-cards は SVG ではなく .kpi-grid（HTML）に委譲するパターンなので Phase 4 で直接組み立てる

図解手段の選び方（既定は gpt-image-2。2026-08-20 オーナー決定）

優先順位は gpt-image-2 → drawio → 手書き SVG（3案比較でオーナーが確定した順序）。 選んだら確認を挟まず使う（判断を人に投げない）。

判断の順序:

1. まず gpt-image-2（B2 spec）で作れないか考える — 「ラスタ=文字なしの雰囲気画」という旧運用は廃止。正確な日本語ラベル・副ラベル・数値・判定マーク入りの高密度インフォグラフィックを作らせる（【入れる文字】一字一句列挙方式）
2. gpt-image-2 を降りるのは次の3つだけ（いずれも drawio へ）: (a) 金額・件数・コードなど一字も間違えられない文字が図の主体 (b) 公開後に文言修正が入る見込みが具体的にある (c) 文字化け検査に2回連続で落ちた
3. 手書き SVG は「型に完全に収まり、かつ文書内の他の SVG と様式を揃えたい」ときの選択

枚数の目安: 1文書あたり gpt-image-2 1〜3枚を基本に、drawio 0〜2枚・手書き SVG 0〜2枚。 生成物の検品: gpt-image-2 の図は Read で目視し、日本語の文字化け・指定外ラベルの混入・情報の薄さを検査する（不合格は再生成2回まで → drawio に切替）。

drawio で図を作る

経路は 2 つ。Mermaid で書いて変換（自動レイアウト。フロー・シーケンス・ER 向き）か、 確定座標で組む（AWS 構成図のように列と帯で並べる図。drawio-bridge の xml-builder.js と references/layout-rules.md に従う）。どちらも後段の検証・変換・整形・検品は drawio-bridge に任せ、 自前で SVG を整形しない（2026-09 実測: 手動で id を付け替えた SVG は AWS アイコンのタイルが消えた。 draw.io は勾配の塗りを属性と style の両方に書き、片方だけ付け替えると勾配が失われる）。

drawio-bridge の所在（未導入なら導入する）

DB=$(ls -d "$HOME"/.claude/plugins/cache/haboshi-skills/drawio-bridge/*/ 2>/dev/null | sort -V | tail -1)
# 未導入なら: /plugin install drawio-bridge@haboshi-skills
# 導入できない環境では、配布元リポジトリ（claude-code-skills）の drawio-bridge/ を DB に指定する
[ -d "$DB/node_modules" ] || npm install --prefix "$DB" --silent   # 初回のみ（配布物に node_modules は無い）
node "$DB/scripts/drawio.js" --help

drawio-bridge も配布元も無い環境では「drawio-bridge が無い」と報告し、gpt-image-2 か手書き SVG に切り替える。 draw.io Desktop（brew install --cask drawio）は export と check-overlap の .drawio 入力に要る。

手順（決定論ゲート 3 つ）

# Mermaid 経路: .mmd → .drawio（自動レイアウト）
node "$DB/scripts/drawio.js" export --in fig1.mmd --out fig1.drawio --format xml
# 座標経路: xml-builder.js で .drawio を生成（references/examples/aws-architecture.example.js が完成例）

node "$DB/scripts/drawio.js" validate --in fig1.drawio                              # ゲート 1: 構造
node "$DB/scripts/drawio.js" export   --in fig1.drawio --out fig1.svg --no-embed
node "$DB/scripts/drawio.js" check-overlap --in fig1.svg                            # ゲート 2: 重なり 0 件まで座標を直す
node "$DB/scripts/drawio.js" inline   --in fig1.svg --id-prefix fig1 --max-width 1050 --out fig1-embed.svg  # ゲート 3: 埋め込み整形

• check-overlap は辺×ラベル・ラベル×ラベルの交差を列挙し、あれば exit 1。0 件にしてから PNG を目視する。 目視で直すのは色と語だけにする（座標は機械判定に従う）
• inline は width/height の除去、id の付け替え（属性と style 内の url("#…") の両方）、日本語フォント、 色のライト固定を行う。draw.io の素の SVG は閲覧環境がダークだと線が白く飛ぶ（検品の Chrome でも起きる）
• --max-width は figure の器幅 918px に対する上限。font-size 16 の図は viewBox 幅 1050 まで（実表示 14px）。 超えるなら図を分けるか、viewBox 座標系の font-size を上げる（予防則 9）
• --id-prefix は図ごとに変える。同じ HTML に 2 枚貼ると id が衝突する

埋め込み

整形後の SVG をそのまま <figure> に貼る（viewBox 基準なので figure svg { width:100% } が効く）。 例外は 2 つ。SVG が 1MB を超える場合（AWS アイコン 40 個で約 1.8MB。保存物が重くなる）と、 公式アイコンを画像として渡す方が読み手に確実な場合は、export --format png --border 12 の PNG を <img> で埋める。PNG は編集できないので、.drawio を文書と同じ場所に残す（次の版で文言だけ直せる）。

ラスタ画像の画風 spec（B2 ビジネスフラット高密度 — 文書内で固定）

ラスタ採用を確定したら、アクセント色（§8）を Phase 3 の生成前に前倒しで確定し、spec に埋め込む（Phase 4 を待つと図と本文の色が揃わない）。複数枚は 1 回の codex exec にまとめる（分けるとスタイル統一が壊れる）。共有 STYLE spec は再走時も変えない。

spec の前に、描く内容（題字／各ゾーンの要素と数値／下段の要点3〜4個／決め数値1個）を全文字列で列挙してから、以下を続けて渡す:

横16:9 の日本語ビジネス図解インフォグラフィック。背景は画面全域を純白 #FFFFFF にする。
手描き感のない、輪郭が均質でエッジの立ったフラットベクター描画（角丸長方形・幾何学的ピクトグラム・
直線とエルボーの矢印。線幅は全図で統一）。配色はダークグレー #1f2937（線・本文）＋アクセント1色
<確定した accent 値> ＋薄グレー #eeeeee の塗りのみ。
構図は縦3ゾーン:
(1) 最上段に結論を言い切る題字1行（20字以内）。
(2) 中段（面積の約6割）は対比または構造の本体。Before/After 型なら左右または上下に2分割し、
    Before 見出し帯は濃灰・After 見出し帯はアクセント色。全ボックスに「名詞＋数値」の副ラベルを
    付ける（例: 要約系 4回）。処理の反復は同一アイコンをその個数分だけ実際に並べる（5回なら5個描く）。
    読み順は丸数字①②③…で明示。流れの終端には必ず ✗（問題・未達）か ✓（解決・到達）を置く。
    設定値・パス・コマンド等の実データ文字列は monospace 風で一字一句正確に描き、強調は該当部分
    だけをアクセント色の点線枠で囲む。問題点は短い吹き出しで注釈する。
(3) 下段は要点3〜4連ボックス帯（各=小アイコン＋10字以内の短文）。Before/After 型なら「課題」「改善」
    の対見出しを付ける。決め数値が1つあれば右下にアクセント色の枠バッジで最大級に描く（例: −51%）。
    決め数値のない題材では省略してよい。
アイコンはダークグレー＋アクセント色の2色フラットピクトグラム。影・立体感なし。
文字: すべて日本語（技術固有名詞の英字は可）。最小文字サイズは画像高の 1/45 以上。
冒頭で列挙した文字列以外のテキストを描かない。誤字・存在しない漢字を作らない。
禁止事項: クリーム色・生成り・ベージュ・和紙テクスチャの背景は禁止（背景は必ず純白 #FFFFFF）。
手描き風の線の揺れ・ラフスケッチ調・鉛筆テクスチャ禁止。グラデーション・ドロップシャドウ・3D・
写実表現禁止。アクセント色は1色のみ（2色目のアクセント禁止。ただし超過・未達を示す1要素に限り
警告色 #c2740a を使ってよい）。列挙にない英語の飾りテキスト
（Overview 等）を勝手に追加しない。余白だけの大きな領域を作らない。

密度の基準: 1枚に主張1つ＋それを支える根拠2〜3要素（下段の要点帯を含む）。詰め込みで縦に伸びるなら2枚に分ける。 一次情報の正本は本文/SVG 側に置く（図=入口、本文=記録）。厳密文字の網羅が図の骨子そのものである図（構成図・ER・実パス一覧）は引き続き drawio か SVG。

ラスタ画像の生成手順（marker 検証つき）

codex-imagegen スキルの標準実行コマンド（env -u OPENAI_API_KEY codex exec によるサブスク枠生成 + Claude 側コピー）に倣い、偽装防止の marker 検証を必ず行う:

# Step 0: 偽装検証用の開始マーカー
touch /tmp/bizdoc-imagegen-start.marker

# Step 1: 生成（プロンプトは内容+テイスト+品質バーのみ渡し、レイアウトは委譲する）
env -u OPENAI_API_KEY codex exec --skip-git-repo-check -C "$(pwd)" \
  -c model_reasoning_effort=high \
  -o /tmp/bizdoc-imagegen-last.txt \
  '<プロンプト本文> 画像は必ず image_gen ツールで生成すること。SVG/HTML/コードでの自作や既存ファイルの流用は禁止。失敗時は何も作らず IMAGEGEN-UNAVAILABLE とだけ報告して終了。生成後、保存された最終PNGの絶対パスだけを最後に1行で報告して。 $imagegen'

# Step 2: マーカーより新しい実ファイルのみ採用（偽装・流用・失敗を弾く）
SRC=$(grep -oE "${HOME}/.+/generated_images/[^ ]+\.png" /tmp/bizdoc-imagegen-last.txt | tail -1)
if [ -n "$SRC" ] && [ -n "$(find "$SRC" -newer /tmp/bizdoc-imagegen-start.marker 2>/dev/null)" ]; then
  cp "$SRC" "<保存先の一時ディレクトリ>/<kebab-name>.png"
else
  echo "警告: image_gen 未実行の疑い（偽装/流用/失敗）— コピー中止、同じプロンプトで再実行する"
fi

検証に落ちた画像は文書に使わない。コピー後は Read で目視し、文字化け・情報の薄さがないか確認する。

8. Phase 4: HTML 組立

<head> に <style data-bizdoc="tokens"></style> とだけ書く（中身は空のまま）。CSS 本体とアクセント色は Phase 5 の hub.mjs add が注入する — tokens.css を Read して手で書き写さない（毎文書 9,000 字超の出力を払うことになり、テンプレを直しても既存文書に反映できなくなる）。

スクラッチ段階のファイルは無スタイルで正しい。完成形になるのは hub に保存された後で、§2 の「1枚 HTML 縛り」は保存物について不変（保存後は外部参照ゼロの自己完結ファイル）。

アクセント色の決め方

Phase 5 の add に --accent "#rrggbb" を渡すだけでよい。判断は CLI 側が持つ:

• そのプロジェクトに既に accent があれば既存値が優先される（同一プロジェクトの文書間でぶれない）
• 未設定のときだけ --accent が採用され、project.json へ書き戻される
• --accent-soft は accent から決定論的に導出される（手で指定しない）

project.json を直接読み書きしたり、reindex を手で追加実行したりしない。

未設定のプロジェクトでは、案件の色に寄せられないか一度だけ確かめる。 既に accent があるときは この手順を飛ばす（何を渡しても既存値が勝つので、走らせるだけ無駄になる）。未設定かどうかは list --json の accent が null かで判定する — #2563eb が入っていれば既に確定済みで、対象外。

node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs" list --json   # 対象プロジェクトの accent が null か見る
node "${CLAUDE_PLUGIN_ROOT}/scripts/accent-candidates.mjs" <プロジェクトルート> --limit 3

スタイル定義から候補色を集める。このスクリプトは候補を出すだけで、色を決めない。 実測（2026-08-31・社内5案件）で、変数名から自動選択させると 3 件中 1 件しか人の選択と一致せず、 和名の体系（--shu 朱 / --ai 藍）を持つ案件では色相が 76.8° ずれた。一方で除外は確実に効く — hover 用の --accent: 243 244 246（gray-100）も本文色 --text-primary も、機械が落とす。

• 候補が出たら AskUserQuestion で1問だけ聞く。第1選択肢を1位の候補にし、既定 #2563eb を残す 選択肢も必ず添える。ラベルには色と変数名を出す（例:「#147b73（--teal / 対白 5.11:1）」）。 AskUserQuestion の選択肢は4つが上限なので、--limit 3 で候補を3件に絞り、4つ目を既定にする
• 候補が空なら聞かない。既定のまま進めるか、トピックに合う色を渡す
• 候補は既にコントラスト 4.5:1 と --warn からの色相 45° を満たしている。この2条件を外して 独自に色を作らない — v0.9.0 で警告色が入り、暖色の accent は「推奨」と「要検討」のバッジが 判別できなくなる（tokens.css の --warn 節を参照）
• 聞くのはそのプロジェクトの初回文書のときだけ。2本目以降は write-once で自動的に黙る

組み立て

outline.json の cover → .cover、exec_summary → .exec-summary、blocks を順番どおりに components.md / svg-patterns のスニペットへ差し込んで本文を組み立てる。数値ブロックには <p class="src">※ 出典: ...</p> を必ず添える（Phase 1 で確認した出典）。ただし ※ 出典 行はセクションにつき原則1本、節末に集約する。同一出典を要素ごとに繰り返さない（KPI カード内に個別出典行を置かず、グリッド直後に1本で束ねる）。

• 表紙は .kicker（種別）→ h1（メッセージ性のあるタイトル）→ .lede（2文以内の機能記述。広告コピー調にしない）→ .meta（日付・読者・種別など）の定型で組む
• 図は <figure> + <figcaption> で包む（枠と「図N」採番は tokens.css が自動付与）。figcaption は図と本文を繋ぐ1行のナレーションにする — 図の主張を1文で言う（「売上推移」型の名詞ラベルは禁止。「値引き後もリピート率は上がっていない」のように言い切る）。本文は図中ラベルをそのままの語で主語に使い、言い換えない。SVG は svg-patterns/README.md 予防則9の規範（font-size 14.5 以上。viewBox 幅 780 以下なら無条件で合格し、超える場合は同項の式で実表示 14px 以上を確認する）に従う
• コマンド・コード: 複数行は <pre><code>…</code></pre> で包み、文中の識別子1個（--scope local 等）だけを <code> 単独で使う。<pre> 無しの <code> を複数行にまたがらせない（inline のチップ装飾が行ごとに分断される）。長い行は手で改行を入れて折らない — 横スクロールに任せる（コマンドは折ると貼り付けて動かなくなる）。HTML なので < & はエスケープする。コードブロックは器幅の視覚要素なので、密度規範では図・表と同じく1画面1つの枠として数える
• 目次: <section> が 5個以上なら .exec-summary の直後に <nav class="toc"> を置く（4個以下は省略）。 各 <section> に id="s-01" 形式（h2 の採番と同じゼロパディング）の id を振り、<a href="#s-01"> で飛ばす。 .conclusion は採番対象外なので id も振らず目次にも載せない（h2 の番号と id を同じ規則で数える）。
• セクション番号・図番号の機構（v0.11.1 / v0.11.2）: 番号は tokens.css の CSS カウンタ（section > h2 { counter-increment: sec }）で付く。 祖先に counter-reset: sec が無いと各 h2 がカウンタを新設して全部「01」になる。tokens.css は body でリセットするため <main> の有無に依存しない（<main> を書いてもよいが必須ではない）。図番号 fig も同じ body の 1 宣言（counter-reset: fig sec）でリセットする — 別規則で重ね書きすると後勝ちで先の宣言が消える（v0.11.2 で直した「全部 図1」の原因）。終端の .conclusion は <section class="conclusion"> / <aside class="conclusion"> のどちらで書いても番号を消費しない。hub.mjs add は h2 の数と目次リンク数の不一致を stderr に warn する。 目次項目は h2 の全文ではなく 25字程度に要約した短縮形を使う（メッセージ見出しはそのままでは2カラムに収まらない）。 紙ではページ番号を持たないため tokens.css が印刷時に非表示にする — 画面用の地図として置く

<nav class="toc">
  <h2>目次</h2>
  <ol>
    <li><a href="#s-01">費用増の原因は分析対象の拡大</a></li>
    <li><a href="#s-02">現状は1通話に最大9回の解析</a></li>
  </ol>
</nav>

• 末尾に <footer>（生成元・日付などの文書管理情報）を置く

本文・フッターに OS のユーザーホーム配下を指すフルパスや個人アカウント名を書かない（~/ 表記か論理名を使う。題材がローカルファイルの場合も同様）。

組み立てた HTML はスクラッチ領域の一時ファイル（例: セッションのスクラッチディレクトリ、または mktemp で作った一時パス）に Write する。次の Phase でこのファイルパスを hub.mjs add に渡す。

9. Phase 5: hub 保存 + 検証

# 保存（SVG 検証→manifest→reindex まで CLI が実施。出力 = 保存先 index.html のパス）
node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs" add "<組み立てたHTML>" \
  --project "$(pwd)" --title "<タイトル>" --slug "<英語kebab-caseスラッグ>" \
  --type "<種別>" --tags "<a,b>" --accent "#rrggbb"

# 決定論ゲート2: 全体を 2000px ごとのセグメント PNG に分けて撮り、図・表を DOM 位置から切り出して 2 倍で書き出す
node "${CLAUDE_PLUGIN_ROOT}/scripts/screenshot.mjs" "<保存先index.html>" "<scratchpad>/shot"

• <組み立てたHTML> = Phase 4 でスクラッチ領域に書き出した一時ファイルのパス
• <タイトル> / <英語kebab-caseスラッグ> / <種別> / <a,b> = Phase 0/2 で確定した内容
• hub.mjs add は内部処理の最初に SVG の XML 妥当性を検証する（決定論ゲート1。stdout の1行目＝保存先パスのことではない）。不正な SVG があれば add がここで中止するので、Phase 3 のスニペットを見直す
• add は保存時に tokens.css と hub ナビを注入する。保存物のスクリーンショット上部に「← doc-hub 一覧」のバーが出るのは正常（hub 配下のパスでのみ表示され、メール添付などで持ち出したコピーでは自動的に消える。印刷にも出ない）。tokens.css を更新しても保存済み文書には自動で届かない（注入時の CSS が焼き込まれる）ので、テンプレートを直したら hub.mjs retheme で貼り直す（例: v0.11.2 の図番号修正）
• スクリーンショットが無スタイル（素の HTML に見える）なら、<style data-bizdoc="tokens"></style> を書き忘れているか、プラグインのキャッシュが古い
• 同じ slug のドキュメントが既にあると add は既定で停止する（勝手に上書きしない）。ユーザーの意図が更新なら --update、別ドキュメントとして残すなら --new を確認してから付ける
• <scratchpad>/shot = 一時的な出力ディレクトリ（mktemp -d 等）。screenshot.mjs は full-NN.png（全体を上から 2000px ごとに分割・幅 1280・等倍。Read が縮小せず本文が読める）と crop-NN-<figure|table|div.kpi-grid>.png（各図表を前後の本文 2 行分込みで 2 倍解像度に再ラスタライズ）を書き、stdout に JSON（height・segments・各 crop の tag/top/height/truncated/skipped）を返す。Chrome CLI の --screenshot は使わない（ビューポート分しか撮れず、実文書の大半が 4000px を超えるため下半分の図表が写らない。2026-09-03 実測 10/10 文書。1 枚撮りは 16384px 超で先頭の複製に化けるため分割する）
• JSON の crops の件数が文書内の図表の数（figure / table / 数値カードの .kpi-grid）と一致するか先に確かめる。0 件ならそれらの要素で組んでいない（--selector で対象を足せる）。truncated: true（高さ 2400px 超で先頭しか撮れていない）か skipped: true の crop が 1 件でもあれば、その要素は表を分割するか --selector で単独指定して撮り直してから判定する

セグメント PNG は骨格と位置の確認に使い、図表の判定は crop 側で行う。目視の印象ではなく数えて確認する項目:

全体 PNG（full-NN.png を順に Read する。文字を読む検査は保存 HTML への grep と併用する）で:

• 本文1行の文字数が 45字を超えていないか — 超えていれば --measure（tokens.css）が効いていない （section > p 等に当たっているか、<p> が <section> の直下にあるかを確認する）。 .callout / .callout-warn と .exec-summary / .conclusion のパネル内テキストは器幅で組む 視覚要素なのでこの検査の対象外（約60字/行が正常）。代わりに囲みの本文が4行以内かを数える
• 骨格検査: 見出し＋sec-lede だけを拾い読みし、(a) 論旨が再構成できるか、(b) 全見出しが「答えの言い切り」で完結して読む理由が消えていないか（未解決要素が残っているか）を確認する
• 見出しの構文検査（v0.9.0）: 見出しを縦に並べ、同一構文が3節連続していないか数える。連続していれば §6「構文を散らす」に戻り、1つを疑問形か機能ラベルへ替える
• 言葉づかいの検査（v0.9.0）: §6「言葉づかいの規範」を1度通す。特に (a) 同じ節で見出し・lede・callout が同じ主張を3回言っていないか、(b) 「大幅に」「適切に」など具体へ落とせる抽象語が残っていないか、(c) 実装側の呼称が本文の主語になっていないか
• 警告色の検査（v0.9.0）: --warn / .callout-warn / tr.warn / .tag-warn の使用箇所を数え、意味が「超過・未達・停止・要対処」に限られているか、1図につき1要素までかを確認する
• 前方参照検査: 保存 HTML に grep -nE '後述|（[0-9０-９]+ ?章）|別紙' を実行し、根拠が参照だけのセル・本文が残っていないか確認する（残っていれば §6 の前方参照禁止に戻る）
• 番号が通し採番になっているか（v0.11.2） — セクション番号 01, 02, 03 … と図番号 図1, 図2 … を上から数える。全部 01 / 全部 図1 なら tokens.css のカウンタリセットが効いていない（counter-reset の重複宣言か、tokens 未注入）
• コードブロックが行ごとの角丸チップに割れていないか — 割れていれば <pre> で包み忘れている（<code> 単独で複数行を囲っている）

図表の crop PNG（crop-NN-*.png。1 枚ずつ Read する）で:

• 表のセルが3行以上に折り返していないか — 折り返していれば §6 の配置規範（1セル40字以内・4列以内）に 戻り、長文セルを本文か .card へ移す
• 図中テキストの実表示サイズ — crop には前後の本文が含まれているので、図中文字が本文と同等以上の大きさで読めるか・複数の図の間で文字サイズが揃っているかを本文と並べて比べる。viewBox 幅が figure の実幅（W=918px）より大きい SVG は縮小表示される（縮小率の高い図は viewBox 座標系の font-size を上げる。svg-patterns/README.md 予防則9）。数値で先に当たりを付けるなら、実表示サイズ ≒ font-size × 918 ÷ viewBox 幅
• 文字化け・アクセント色の破綻・はみ出し

崩れがあれば HTML を修正し、--update を付けて add を再実行する。再保存後は再度 screenshot.mjs → Read の確認を、崩れがなくなるまで繰り返す（修正後の再検証なしで完了しない）。この検品は Phase 5 のスクリーンショットに限る（PDF は §10 の手順で目視する）。最後に保存先を open し、doc-hub 全体の一覧（node "${CLAUDE_PLUGIN_ROOT}/scripts/hub.mjs" open --project "$(pwd)" で開ける）の場所をユーザーに案内する。

10. Phase 6: PDF（要求時のみ）

「PDF でも」「配布用に」と言われたときだけ実行する。

# 主経路: 全ページに「文書タイトル ｜ ページ番号/総ページ」フッター付きの A4 PDF
node "${CLAUDE_PLUGIN_ROOT}/scripts/print-pdf.mjs" \
  "<保存先index.html>" "$HOME/Downloads/<slug>.pdf" --title "<タイトル>"

印刷レイアウトは画面より高密度になる（tokens.css の @media print が余白・行間・部品を圧縮する）。ページ数をさらに絞りたい要望があれば --scale 0.9 を付けて全体を縮小できる（既定 1）。

Chrome が既定パスにない等で主経路が失敗したときだけ、フォールバック（ページ番号なし）を使う:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \
  --print-to-pdf="$HOME/Downloads/<slug>.pdf" --no-pdf-header-footer \
  --virtual-time-budget=20000 "file://<保存先index.html>"

（フォールバックでは --no-pdf-header-footer を必ず付ける — Chrome 既定のフッターは file:// のフルパスを印字してしまい path-privacy 違反になる）

書き出し後は Read で先頭・中間・末尾ページを目視し、次を確認する:

• フッターのタイトル・ページ番号が全ページに入っているか（主経路）
• 図・表・カードが不自然に分断されていないか（長い表は行単位で改ページし、ヘッダ行が次ページに繰り返されるのは正常）
• 白基調の面色（exec-summary・表ヘッダ等）が抜けていないか・日本語の文字化けがないか
• 図送りによる大きな余白が出ていないか — 図はページ残量に入らないと丸ごと次ページへ送られ、直前に余白が生まれる。目立つ場合は組版調整を行う: 図の直前の段落を図の後ろへ移す／該当セクションに .page-break を付けて頭出しする／図が viewBox 高さ 500 超なら2枚に分割する（予防則10）。調整したら --update で再保存し、PDF を再書き出しして再確認する

PDF は一時配布物なので manifest に記録しない（hub.mjs add を再実行しない）。ラスタ画像（codex-imagegen 生成分）を使った文書は、そのまま書き出すと容量が膨らむため、印刷用の一時コピーを作って画像だけ軽量化してから書き出す（元の HTML・保存済みドキュメントは変更しない）。書き出し後は Read で先頭数ページを目視し、分断・色抜け・文字化けがないか確認する。

11. Gotchas

• 図番号が全部「図1」になったら tokens.css を疑う — body の counter-reset は fig sec を 1 つの宣言に持つこと。v0.11.1 は fig と sec を別の宣言に分けたため後の宣言が前を消し、全図が 図1 になった（v0.11.2 で修正、tests/figure-numbering.test.mjs が固定）
• draw.io の SVG を自前で整形しない — id の付け替え・色固定・幅の除去は drawio-bridge の inline に任せる。手動の正規表現置換は style 属性内の url("#…") を取りこぼし、AWS アイコンのタイルが消える（2026-09 実測）
• 同じ slug の再生成は勝手に上書きしない — hub.mjs add が既定で停止する。ユーザーに更新意図を確認してから --update（別ドキュメントとして残すなら --new）を付ける
• 見出しの「言い切り完結」も仕上げ段階で直す — 目次と見出しだけ読んで疑問が1つも残らなければ、本文は読まれない。§6 の「未解決要素を1つ残す」検査に戻る
• 見出しのトピックラベル化は仕上げ段階でも直す — Phase 5 の PNG 確認時に見出しだけを拾い読みし、主張の文が並んでいなければ Phase 2 の構成規範に戻って書き直す
• アクセントは1色のみ — 複数のアクセント色を併用しない（tokens.css の --accent を1つだけ振る）。唯一の例外が --warn（v0.9.0）で、超過・未達・停止・要対処にだけ使う。良好・情報を示す色は作らない（信号機にしない）。accent が橙〜赤褐色のプロジェクトでは warn（色相 34.6°）と近接する（テラコッタ #A6472B で 20.9°・橙 #ea580c で 14.0°）ので、同一画面に両方を並べない
• 図=入口、本文=記録 — 構造を主張する節は図を節頭（sec-lede 直後）に置き、本文は図中ラベルの語をそのまま主語に使って図を歩く。ただし要点が図にしかない状態は禁止（本文が正式な記録。検索・選択・読み上げの正本は本文）
• 表に長文を詰めない — 表は本文より広いが列で割られるため、1セル40字超は必ず3行以上に折り返して読み物化する。 A/B 実測で「bizdoc は難しい」と評された主因のひとつだった（explainer 側は td 最長35字・40字超ゼロ、 bizdoc 側は最長75字・40字超5個）。表は一覧して比べる道具であり、読ませる器ではない
• 数字に出典なし断定禁止 — Phase 1 で出典が確認できなかった数字は「未確認」と明記し、<p class="src"> を省略しない
• SVG の入れ子禁止 — hub の SVG 検証（xmllint 経由）が入れ子に対応しない。1文書内で <svg> は並列に配置する
• SVG は必ずインライン — <img src="pattern.svg"> にすると var(--accent) 等の CSS 変数が解決できず無色・黒塗りになる
• project.json の accent は既存値があれば上書きしない — 同一プロジェクトの文書間でアクセントがぶれるのを防ぐ
• codex-imagegen の marker 検証を省略しない — 省略すると偽装・流用画像をそのまま納品してしまう
• PDF の紙面余白は目視でなく実測で確かめる — Chrome の Page.printToPDF は、文書が @page の margin を明示していると CDP の margin* パラメータを無視して CSS 側を優先する。かつて print-pdf.mjs は「二重適用を避ける」つもりで @media print{@page{margin:0}} を注入しており、それが勝って余白が完全に消えていた（2026-08-07 実測で左右 0.0mm）。現在は同スクリプトの MARGIN_*_MM を唯一の正とし、@page への注入と CDP の両方をそこから導出している。余白を変えるときは必ずこの定数を触り、書き出し後に実測する:

  python3 -c "
  import fitz; d=fitz.open('<out.pdf>'); mm=25.4/72; p=d[0]; r=p.rect
  bb=None
  for g in p.get_drawings(): bb = g['rect'] if bb is None else bb | g['rect']
  print(f'L{bb.x0*mm:.1f} R{(r.width-bb.x1)*mm:.1f} T{bb.y0*mm:.1f} B{(r.height-bb.y1)*mm:.1f} mm')"
  

  ページ画像の目視ではこの種の欠落を見落とす（本文が紙面いっぱいでも「そういうデザイン」に見えてしまう）
• スキルを直したら version を上げる — プラグインキャッシュ（~/.claude/plugins/cache/）は version が変わらないと再取得されない。配布元リポジトリだけ直してもセッションには反映されず、「直したつもりで直っていない」状態になる（上記の余白バグは、値だけ 15mm に修正済みなのにキャッシュが 13mm のまま、かつ根本原因も残っていた実例）