敵対的検証について

adversarial-verification-skill/
├── adversarial-verification/          # スキル本体（この階層を skills/ 配下にコピー）
│   ├── SKILL.md                       # 必須：メタデータ（name / description）+ 検証手順・出力形式・禁止事項
│   └── references/                    # 任意リソース：発動時に必要に応じて読み込まれる
│       ├── perspectives.md            # 成果物タイプ別（コード / 設計・ADR / リサーチ / 文章）の検証観点カタログ
│       └── standalone-prompt.md       # クロスモデル検証用のスタンドアロン雛形（ChatGPT等に貼る用）
└── INSTALL.md                         # 導入手順（3ツール別の配置場所・反映方法）※スキル外のドキュメント

config.yaml

# adversarial-verification デフォルト設定
# このファイルの値は「デフォルト」。ユーザーがプロンプトで指示した内容が常に優先される。
# 値を変えたら保存するだけで次回発動時から反映（スキル本文の再読み込みは不要）。

# ── エージェント起動 ─────────────────────────────
execution:
  # auto        : サブエージェント/Task機能があれば並列、なければ逐次独立パス
  # subagent    : サブエージェント必須（使えない環境ではその旨を報告して逐次にフォールバック）
  # sequential  : 常に逐次独立パス（トークン節約したいとき）
  mode: auto

  # 起動するスケプティックの数（= 検証観点の数）。1〜5
  agent_count: 3

  # 各観点で反証を試みる主張の最低数（手抜き合格防止）
  min_refutation_attempts: 3

# ── 検証観点 ─────────────────────────────────────
perspectives:
  # auto: 成果物タイプを判定して references/perspectives.md から自動選択
  # fixed: 下の fixed_list を常に使う
  selection: auto
  fixed_list:
    - 読者視点
    - 主張の正しさ
    - 成立性

# ── 接地（グラウンディング）───────────────────────
grounding:
  # always : 事実主張は必ずWeb検索/一次情報/実行で裏取り
  # ask    : 裏取りが必要な主張を列挙し、実行前にユーザーに確認
  # off    : 接地しない（指摘の確度は全て「低」以下に制限される）
  mode: always
  # コードの場合、実際に実行して壊しにいくか
  execute_code: true

# ── 出力 ─────────────────────────────────────────
output:
  language: ja            # ja / en
  format: table           # table（指摘一覧を表で）/ list（箇条書き）
  include_verdict: true   # 総合判定 GO/条件付きGO/NO-GO を出す
  include_survived: true  # 「壊せなかった点」を出す
  # 報告する指摘の最低深刻度: low / medium / high
  min_severity: low

# ── コスト制御 ────────────────────────────────────
cost:
  # 発動前に「多視点検証はトークンを多く消費する」旨を軽い成果物に対して一言添えるか
  warn_on_light_artifacts: true

# adversarial-verification スキル 導入手順

Agent Skillsオープン標準（SKILL.md）準拠のため、**同じフォルダをコピーするだけ**で
Claude Code / Codex CLI / GitHub Copilot CLI の3ツールで動きます。

## 配置場所

| ツール | 個人用（全プロジェクト共通） | プロジェクト用（リポジトリ内） |
|---|---|---|
| Claude Code | `~/.claude/skills/adversarial-verification/` | `.claude/skills/adversarial-verification/` |
| Codex CLI | `~/.codex/skills/adversarial-verification/` | `.codex/skills/adversarial-verification/` |
| Copilot CLI | `~/.copilot/skills/adversarial-verification/` | `.github/skills/adversarial-verification/` |

補足: Codex CLIとCopilot CLIは共通パス `~/.agents/skills/` にも対応しています。
1箇所に実体を置いて他をシンボリックリンクにする運用も可能です（Windowsなら `mklink /D`）。

## セットアップ（個人用の例）

```bash
# Claude Code
mkdir -p ~/.claude/skills && cp -r adversarial-verification ~/.claude/skills/

# Codex CLI
mkdir -p ~/.codex/skills && cp -r adversarial-verification ~/.codex/skills/

# GitHub Copilot CLI
mkdir -p ~/.copilot/skills && cp -r adversarial-verification ~/.copilot/skills/
```

Windows (PowerShell) の場合:

```powershell
New-Item -ItemType Directory -Force "$HOME\.claude\skills","$HOME\.codex\skills","$HOME\.copilot\skills" | Out-Null
Copy-Item -Recurse adversarial-verification "$HOME\.claude\skills\"
Copy-Item -Recurse adversarial-verification "$HOME\.codex\skills\"
Copy-Item -Recurse adversarial-verification "$HOME\.copilot\skills\"
```

## 反映と確認

- **Claude Code**: 再起動で自動認識。会話で「敵対的検証して」と言うか `/adversarial-verification` を明示
- **Codex CLI**: 新規セッションで自動認識。初回はスキル有効化の確認プロンプトが出ます。
  `/skills list` で一覧、`$adversarial-verification` で明示呼び出し
- **Copilot CLI**: セッション内で `/skills reload` → `/skills info adversarial-verification` で確認。
  明示呼び出しは「Use the /adversarial-verification skill to ...」

## 使い方

成果物ができた場面で一言:

```
この設計案を敵対的検証して
```

自動でスキルが発動し、3観点のスケプティック検証（サブエージェント対応環境では並列）が走り、
指摘ごとに深刻度・根拠・確度、総合判定（GO/条件付きGO/NO-GO）、「壊せなかった点」が返ります。

**注意**: 返ってきた指摘は正解ではありません。受ける / 弱めて受ける / 却下する — 
採否を決めるのは人間の仕事です。またマルチ観点検証は通常の3〜10倍のトークンを
消費しうるので、常用はやり直しコストが高い成果物に絞るのが現実的です。

skills

---
name: adversarial-verification
description: >-
  成果物（設計案・ADR・リサーチ結果・コード・記事・提案書など）に対して「課題がある」前提で
  反証を試み、指摘ごとに深刻度・根拠・確度を付けた判定を返す敵対的検証スキル。
  ユーザーが「敵対的検証して」「反証して」「壊してみて」「この案の穴を探して」「本当に正しいか疑って」
  「スケプティックレビュー」「出す前に一度疑いたい」「adversarial verification」「red team」などと
  依頼したとき、または重要な成果物の最終チェック・公開前チェック・意思決定ドキュメントの
  検証を求められたときに必ずこのスキルを使うこと。単なる「レビューして」でも、公開・リリース・
  意思決定などやり直しコストが高い文脈であればこのスキルの利用を提案する。
---

# Adversarial Verification（敵対的検証）

あなたはこの成果物を作った本人ではない。**独立した懐疑的検証者（skeptic）**として振る舞え。
目的はレビューや改善提案ではなく**反証**である。成果物の主張・前提・結論を壊しにいき、
壊せたか壊せなかったかの**判定と根拠**を返せ。

## 成立要件（4原則）

1. **独立性** — 成果物を作った文脈・経緯・作者の意図を引き継がない。貼られた/指定された
   テキストとコードだけを対象にする。同一セッション内で自分が作った成果物を検証する場合も、
   「作成時の推論は一切正当化に使わない」と宣言してから検証する。
2. **反証の役割づけ** — 「良い点」は書かない。「どこかに課題がある」前提で、成立しない
   可能性のある箇所だけを探す。
3. **接地（グラウンディング）** — 事実の主張（数値・仕様・API・外部の事実）は記憶で判定しない。
   Web検索・一次情報・原典・実コードの実行/読解で裏を取る。確認できなければ「未検証」と
   明記し、推測で断定しない。
4. **判断可能な出力** — すべての指摘に深刻度と根拠と確度を付け、人間が採否を決められる形で返す。

## 実行手順

### 0. 設定を読み込む
このスキルのディレクトリにある `config.yaml` を読み、デフォルト設定として適用する。
優先順位は次のとおり（上が強い）:

1. **ユーザーのプロンプト指示**（例:「5体立てて」「英語で出して」「接地なしで」）
2. **プロジェクトルートの `.adversarial-verification.yaml`**（リポジトリ単位の上書き。存在すれば）
3. **スキル内の `config.yaml`**（グローバルデフォルト）
4. このSKILL.md本文の既定値（config.yamlが無い/読めない場合）

読み込んだ設定のうち既定値から変更されている項目があれば、検証開始時に1行で報告する
（例:「設定: agent_count=5, grounding=ask で実行します」）。
config.yamlの編集をユーザーに依頼された場合は、コメントを保持したまま該当キーだけ書き換える。

### 1. 対象を特定する
「敵対的検証して」とだけ言われた場合は、直近の成果物（このセッションで作成した設計案・
コード・文書）を対象とする。曖昧なら1問だけ確認する。

### 2. 成果物タイプを判定し、検証観点を選ぶ
`perspectives.selection` が `auto`（既定）なら `references/perspectives.md` を読み、
タイプ（コード / 設計・ADR / リサーチ / 文章・提案書）に応じて `execution.agent_count` 個
（既定3）の検証観点を選択する。`fixed` なら `fixed_list` をそのまま使う。
ユーザーがプロンプトで観点を指定した場合はそれが最優先。

### 3. 検証を実行する（`execution.mode` に従う）
- **auto（既定）**: サブエージェント/Task機能があれば subagent、なければ sequential として動く
- **subagent**: 観点ごとに1体、計 `agent_count` 体のスケプティックを fresh context で
  並列起動する。各エージェントには成果物本文と観点のみ渡し、作成経緯は渡さない。
  機能が使えない環境では、その旨を1行報告して sequential にフォールバック。
- **sequential**: 観点ごとに独立した検証パスを逐次実行する。各パスの冒頭で
  「前パスの結論と作成時の文脈を破棄する」と明示し、観点ごとにゼロから反証を試みる。

各観点で最低限行うこと：
- 主張を列挙し、重要度の高い上位の主張から順に、最低 `min_refutation_attempts` 件
  （既定3）の反証を試みる
- 反例・例外ケース・暗黙の前提・一般化のしすぎ（n=1を法則として語っていないか）を探す
- 事実主張は `grounding.mode` に従って接地する（原則3）。`always` なら必ず裏取り、
  `ask` なら裏取り対象を列挙して確認、`off` なら接地しない代わりに全指摘の確度を
  「低」以下に制限する。コードは `grounding.execute_code: true` のとき実行・テスト・
  境界値で実際に壊しにいく

### 4. 結果を統合して出力する
`output` 設定に従う: 言語は `language`、指摘一覧は `format`（table/list）、
`min_severity` 未満の指摘は省略、`include_verdict` / `include_survived` が false の
セクションは出さない。以下は既定（table, ja, 全セクションあり）の形式:

```
## 敵対的検証結果

**対象**: <成果物名>
**検証観点**: <観点1> / <観点2> / <観点3>

### 指摘一覧
| # | 指摘 | 深刻度 | 根拠 | 確度 |
|---|------|--------|------|------|
| 1 | 何が成立しない可能性があるか（一言） | 高/中/低 | なぜそう言えるか。一次情報を確認した場合は出典 | 高/中/低 |

深刻度: 高=結論が覆る / 中=修正が必要 / 低=条件つきで成立
確度: 推測を含むなら低。未検証の事実主張は根拠欄に「未検証」と明記

### 総合判定
GO / 条件付きGO / NO-GO — 判定理由を2〜3行で

### 反証を試みたが壊せなかった点
1〜2行（なければ「なし」）。これは成果物の最も堅い部分の証明であり、
全指摘が反証で埋まっていないかの過剰指摘センサーでもある

### 採否はあなたが決めてください
受ける / 弱めて受ける / 却下する — の判断材料として上記を使ってください
```

## 禁止事項・失敗モード対策

- **偽陽性の禁止**: 確信の持てない指摘は出すな。False positives erode trust.
  健全な成果物にも指摘を出そうとして無理にひねり出すのは失敗である。
- **手抜き合格の禁止**: ろくに検証せず「合格」と判定するのは検証者の最大の失敗モードである。
  各観点で最低3つの主張に対して具体的な反証を試みた記録を残せ。
- **迎合の禁止**: 「これまでの流れ」やユーザーの期待に合わせて判定を甘くするな。
  NO-GOと判断したらNO-GOと書け。
- **越権の禁止**: 指摘の採否を勝手に決めて成果物を書き換えるな。検証と修正は別タスク。
  ユーザーが採否を決めた後、依頼されたら修正する。

## 単一チャットツール向けの雛形

サブエージェントもこのスキルも使えないツール（ChatGPT等）でクロスモデル検証をしたい
場合に渡せるスタンドアロン版プロンプトが `references/standalone-prompt.md` にある。
ユーザーが「他のモデルでも検証したい」「クロスモデルで」と言ったらこれを案内する。

## コストと使いどころ

多視点検証はシングルパスの3〜10倍のトークンを消費しうる。ユーザーが軽い成果物に
使おうとしていたら、「お試しは何にでも、常用はやり直しコストが高い成果物
（公開前の記事・意思決定ドキュメント・リリース前のコード）に絞る」ことを一言添える。

standalone-prompt.md

# スタンドアロン敵対的検証プロンプト（クロスモデル検証用）

スキル機能のないツール（ChatGPT等）や、普段と別のモデルで検証したいときに使う。

## 使い方（3ステップ）

1. **新規セッションを開く**（成果物を作った会話は使わない）
2. **成果物だけを貼る**（経緯・意図の説明は貼らない）
3. 以下の雛形を貼る

## 雛形

```
あなたはこの成果物を作った本人ではなく、独立した懐疑的なレビュアー（skeptic）です。
目的はレビューや改善提案ではなく「反証」です。先ほど貼った成果物の
主張・前提・結論を壊しに行ってください。

ルール:
1. 作者の意図や生成の経緯は考慮しない。貼られたテキストだけを対象にする
2. 「良い点」は書かない。成立しない可能性のある箇所だけを挙げる
3. 事実に関する主張（数値・仕様・外部の事実）は、可能な限りWeb検索や一次情報・
   実データに当たって裏を取る。確認できなければ「未検証」と明記し、推測で断定しない
4. 確信の持てない指摘は無理に出さない。偽陽性は信頼を損なう
5. ろくに検証せず「合格」と判定する手抜きも禁止。最低3つの主張に反証を試みた
   記録を残す

出力形式（指摘ごとに必ずこの4項目を付ける）:
- 指摘: 何が成立しない可能性があるか（一言で）
- 深刻度: 高（結論が覆る）/ 中（修正が必要）/ 低（条件つきで成立）
- 根拠: なぜそう言えるか。一次情報を確認した場合はその出典
- 確度: 高 / 中 / 低（推測を含むなら低）

最後に:
- 総合判定: GO / 条件付きGO / NO-GO（理由2〜3行）
- 「反証を試みたが壊せなかった点」を1〜2行（なければ「なし」）
```

## クロスモデル検証を推奨する場面

検証する側とされる側が同じモデルだと、モデルの知識自体の誤りは盲点として共有される。
重要な成果物（公開前の記事、意思決定ドキュメント、リリース前のコード）では、
普段Claudeを使っているならCodexやGemini、普段Codexを使っているならClaudeなど、
**別のモデルの新規セッション**にこの雛形を貼って検証させると盲点が減る。

perspectives.md

# 成果物タイプ別 検証観点カタログ

タイプごとに標準3観点を定義する。ユーザー指定があればそちらを優先。
複合的な成果物（例: コード付き設計書）はタイプを跨いで観点を組み合わせてよい。

## コード（実装・PR・スクリプト）

1. **正しさの反証** — 境界値・異常系・並行実行・null/空/巨大入力で壊れるケースを探す。
   可能なら実際に実行して壊す。再現手順を根拠に書く。
2. **セキュリティ/破壊的変更** — インジェクション、認可漏れ、秘密情報の露出、
   既存呼び出し元を壊す変更、ロールバック不能なマイグレーション。
3. **前提の検証** — 依存ライブラリのAPI仕様・バージョン互換を一次情報（公式ドキュメント・
   実際のコード）で確認する。「動くはず」の根拠が記憶だけの箇所を洗い出す。

## 設計案・ADR・アーキテクチャ提案

1. **代替案との比較耐性** — 却下された代替案は本当に劣るか。比較軸が結論に有利に
   選ばれていないか。「やらない理由」が検証されているか。
2. **スケール・運用の反証** — 10倍の負荷・データ量・チーム規模で成立するか。
   障害時・部分故障時の挙動。運用コストが過小評価されていないか。
3. **前提と制約の妥当性** — 「〜のはず」「一般的に」で済まされている前提を列挙し、
   一次情報か実測で確認できるものは確認する。

## リサーチ結果・調査レポート

1. **出典の実在と文脈** — 引用された数値・主張を一次情報まで遡って確認する。
   出典が実在しない/文脈を落として引用すると意味が変わる箇所を探す。
2. **一般化のしすぎ** — n=1やケーススタディを法則として語っていないか。
   「〜してくれる」は「私の環境ではこうなった」に格下げすべきでないか。
3. **反対証拠の探索** — レポートの結論と矛盾する情報を能動的に検索する。
   見つかったら深刻度を付けて報告。見つからなければ「探したが見つからず」と記録。

## 文章・記事・提案書・企画メモ

1. **読者視点** — 想定読者にとって主張が再現可能か。前提知識のギャップ。
   タイトル/冒頭の約束と本文の中身が一致しているか。
2. **主張の正しさ** — 事実主張の裏取り（リサーチと同じ）。断定と推測の混同。
3. **成立性** — 主張を支える証拠が本文内に足りているか。結論が根拠から
   論理的に導けるか。反論に1段も耐えない主張はどれか。

スキルガイド

# adversarial-verification スキル 使い方ガイド

## 基本の使い方

成果物ができた場面で、**同じセッションのまま一言**頼むだけです。

    この設計案を敵対的検証して

description のトリガー語（「敵対的検証して」「反証して」「壊してみて」「穴を探して」など）に
反応して自動発動します。発動しない場合は明示呼び出し:

| ツール | 明示呼び出し |
|---|---|
| Claude Code | `/adversarial-verification` またはそのまま「敵対的検証して」 |
| Codex CLI | `$adversarial-verification この設計案を検証して` |
| Copilot CLI | `Use the /adversarial-verification skill to verify this design doc` |

## 返ってくるもの

- **指摘一覧**: 指摘ごとに 深刻度（高=結論が覆る/中=修正必要/低=条件つき）・根拠・確度
- **総合判定**: GO / 条件付きGO / NO-GO + 理由
- **壊せなかった点**: 成果物の一番堅い部分（過剰指摘のセンサーにもなる）

## ユースケース別の頼み方

### 1. リリース前のコード・PR
    このPRの差分を敵対的検証して。境界値と異常系は実際に実行して壊しにいって

→ 正しさの反証 / セキュリティ・破壊的変更 / 依存APIの前提検証 の3観点。
テストを書いて実行できる環境なら再現手順付きで指摘が返ります。

### 2. 設計案・ADR
    このADRを敵対的検証して。却下した代替案が本当に劣るかも疑って

→ 代替案との比較耐性 / スケール・運用 / 前提の妥当性。
「比較軸が結論に有利に選ばれていないか」まで踏み込みます。

### 3. AIに任せたリサーチの裏取り
    さっきの調査結果を敵対的検証して。一次情報に当たって

→ 出典の実在確認 / 一般化のしすぎ検出 / 反対証拠の能動探索。
「一次情報に当たって」を添えると接地（Web検索・原典確認)が強く効きます。

### 4. 公開前の記事・提案書・企画メモ
    このBOOTH商品ページの説明文を敵対的検証して

→ 読者視点 / 主張の正しさ / 成立性。
「タイトルの約束と本文が一致しているか」を読者目線で叩きます。

### 5. クロスモデル検証（重要成果物向け）
検証側と作成側が同じモデルだと知識の誤りが盲点として共有されます。
`references/standalone-prompt.md` の雛形を **別モデルの新規セッション** に
成果物と一緒に貼れば、そのままクロスモデル敵対的検証になります。
（普段Claude Codeなら→Codexで検証、など）

## 結果の受け取り方（重要）

指摘は正解ではありません。指摘ごとに:

- **受ける** — 深刻度・高で根拠が具体的なもの
- **弱めて受ける** — 主張を「私の環境では」に格下げする等の部分対応
- **却下する** — 成果物のキモとトレードオフになる指摘は根拠を見て切る

**採否を決めるまでやって完成**です。「合格」と言われても最後は自分の目で見ること。

## 使いどころの目安

| 使う | 使わない（通常レビューで十分） |
|---|---|
| 公開前の記事・商品ページ | 下書き・ブレスト段階のメモ |
| リリース前のコード・マイグレーション | 使い捨てスクリプト |
| 意思決定ドキュメント・ADR | 日常の小さなリファクタ |
| 顧客向け提案書 | 社内向けの軽い共有 |

多視点検証は通常の3〜10倍のトークンを消費しうるため、
**お試しは何にでも、常用はやり直しコストが高い成果物に絞る**のが現実的です。

以下は別件

作業前にメタ認知を一度行う。この依頼で引っ張られそうなバイアスや定型回答を1〜2行で自己申告してから始める。

与えられた前提・常識・スキーマを疑う。依頼文の前提が怪しければ、黙って従わず先に指摘する。

曖昧な両論併記で終わらせず、根拠の上ではっきり立場を表明する。

局所最適ではなく全体最適を、短期的解決ではなく長期的視点を優先する。

「動くはず」を信用しない。実行・実測できるものは必ず実行して確かめ、実測結果を報告に含める

# Codex CLI だけでプロジェクト説明用 PowerPoint を自動生成する完全手順書

**対象読者**:Codex CLI を使ったことはあるが、スライド自動生成は初めての人。
**ゴール**:要件定義〜実装の資料一式から、上司・関係者向けの PowerPoint を「outline を1回レビューするだけ」でほぼ完成させる。

---

## 目次

- [全体像(まずこれだけ理解する)](#全体像)
- [STEP 0. 環境準備(初回のみ・約30分)](#step-0)
- [STEP 1. プロジェクトのフォルダを整える](#step-1)
- [STEP 2. AGENTS.md を置く(コピペでOK)](#step-2)
- [STEP 3. 共通ツール一式を Codex に作らせる(初回のみ)](#step-3)
- [STEP 4. カスタムプロンプト /deck を登録する](#step-4)
- [STEP 5. 実行する(会話例つき)](#step-5)
- [STEP 6. outline.yaml をレビューする(ここが本番)](#step-6)
- [STEP 7. ビルドと自動修正ループ](#step-7)
- [STEP 8. 挿絵(GPT画像)の差し替え](#step-8)
- [STEP 9. 納品前チェックリスト](#step-9)
- [STEP 10. 2回目以降の運用(5分で終わる)](#step-10)
- [精度を上げる小技集(20連発)](#小技集)
- [トラブルシューティング](#トラブルシューティング)

---

<a name="全体像"></a>
## 全体像(まずこれだけ理解する)

```
docs/(設計資料一式)
   │
   │ ① Codex が読んで要約
   ▼
docs_digest/(資料ごとの要約)──── コンテキスト節約 & 精度向上
   │
   │ ② 構成案を生成
   ▼
deck/outline.yaml ◄────【あなたがレビューするのはここだけ】
   │
   │ ③ 承認後、自動ビルド
   ├─► deck/diagrams/*.png (Mermaid → 図)
   ├─► deck/output.pptx    (slide_kit 経由で組み立て)
   │        ▲    │
   │        │    ▼ ④ lint_deck.py(ズレ・あふれ検査)
   │        └── 違反0まで自動修正ループ
   ▼
deck/image_requests.md ──► ⑤ GPT画像で挿絵生成 → 差し替え再ビルド
```

**崩れないための3原則**(この手順書の全てはこの3つのため):

1. **座標を LLM に書かせない** — 事前定義のレイアウト関数(slide_kit)しか使わせない
2. **手直しはテキスト段階(outline)に寄せる** — pptx になってから直さない
3. **完成品を機械検査する** — 目視ではなく lint スクリプトでズレ・あふれを検出→自動修正

---

<a name="step-0"></a>
## STEP 0. 環境準備(初回のみ・約30分)

### 0-1. インストールするもの

| ツール | 用途 | 確認コマンド |
|---|---|---|
| Python 3.10+ | pptx 生成 | `python --version` |
| python-pptx ほか | ライブラリ | 下記 0-2 |
| Node.js(nvm-windows 導入済ならOK) | Mermaid 図生成 | `node --version` |
| @mermaid-js/mermaid-cli | `.mmd` → 画像 | `mmdc --version` |
| LibreOffice(任意・推奨) | pptx→PNG 変換で最終目視 | `soffice --version` |

```bash
# Python ライブラリ(バージョン固定して後述の requirements.txt にも保存)
pip install python-pptx pyyaml jsonschema pillow

# Mermaid CLI
npm install -g @mermaid-js/mermaid-cli
```

### 0-2. Windows での注意(ハマりどころ)

- **Git Bash で mmdc が動かない場合**:`mmdc.cmd` を呼ぶか、PowerShell で実行する。
- **Mermaid の日本語が「豆腐(□□)」になる場合**:後述 STEP 3 で作る `mermaid.config.json` にフォント指定を入れる(手順書に含めてあるので Codex が自動対応)。
- **LibreOffice の PATH**:標準では `C:\Program Files\LibreOffice\program\soffice.exe`。PATH に追加するか、AGENTS.md にフルパスを書く。
- **Codex CLI の実行許可**:`mmdc` や `soffice` の実行に毎回承認を求められて面倒な場合は、ワークスペース書き込み+コマンド実行を許可するモード(例:`codex --full-auto`)で起動する。ただし信頼できるリポジトリでのみ。

### 0-3. 完了チェック

- [ ] `python -c "import pptx, yaml, jsonschema; print('ok')"` → ok
- [ ] `mmdc --version` → バージョン表示
- [ ] (任意)`soffice --version` → バージョン表示

---

<a name="step-1"></a>
## STEP 1. プロジェクトのフォルダを整える

対象プロジェクト直下を、この形にする(deck/ 以下は STEP 3 で Codex が作るので空でOK):

```
project/
├── docs/                     # ★既存の設計資料をここに集める(コピーでよい)
│   ├── 01_要件定義.md
│   ├── 02_非機能要件.md
│   ├── 03_データ構造.md
│   ├── 04_API仕様.md
│   ├── 05_アーキテクチャ仕様書.md
│   ├── 06_ディレクトリ構造書.md
│   └── 07_詳細設計書.md
├── src/                      # 実装コード
├── deck/                     # 生成物一式(STEP 3 で自動作成)
└── AGENTS.md                 # STEP 2 で設置
```

**ポイント**

- 資料は**連番プレフィックス**を付けてリネームしておく。Codex が読み込み順・対応関係を誤認しなくなる(地味に効く)。
- Word/Excel の資料しかない場合は、先に Codex に「docs/ 内の .docx/.xlsx を Markdown に変換して」と頼んでテキスト化しておく(pptx 生成とは別セッションで)。
- 会社の PowerPoint テンプレートがあれば `deck/assets/template.pptx` に置く(STEP 3 でフォルダができてから)。**これが見た目の完成度を最も上げる一手**。

---

<a name="step-2"></a>
## STEP 2. AGENTS.md を置く(コピペでOK)

プロジェクトルートに `AGENTS.md` を作り、以下を貼る。Codex CLI は起動時に自動で読む。
(既に AGENTS.md がある場合は、末尾にセクションとして追記すればよい)

````markdown
# スライド生成ルール(deck-builder skill)

## 役割
docs/ 配下の設計資料から、上司・関係者(非エンジニア含む)向けの
説明用 PowerPoint を生成する。技術詳細の羅列ではなく
「何を解決し、どう作られていて、今どこまで進んでいるか」を伝える。

## 想定オーディエンス
- 意思決定者。知りたいのは「目的・効果・全体像・進捗・リスク」
- コードは読まない。専門用語には初出時に一言の注釈を付ける

## 絶対ルール
1. **座標・サイズの直書き禁止。** 配置は deck/slide_kit.py の関数のみ使用。
   無いレイアウトが必要なら、先に slide_kit に関数を追加し単体テストしてから使う。
2. **3段階生成。** docs → docs_digest(要約)→ outline.yaml → pptx の順。
   outline.yaml 生成後は**必ず停止してユーザー承認を待つ**。
3. **1スライド1メッセージ。** 箇条書き最大5項目・各全角40字以内。
   タイトル全角20字以内。詳細は Appendix スライドへ。
4. **図表優先。** 比較・一覧・仕様=表。構造・流れ=図。
   地の文だけのスライド禁止(表紙・まとめを除く)。
5. **図は pptx 内で描かない。** Mermaid(.mmd)→ mmdc で PNG(scale=2, 背景白,
   deck/mermaid.config.json 使用)を deck/diagrams/ に生成して貼る。
   - アーキテクチャ: flowchart(横向き LR、ノード最大12個。超えたら階層分割)
   - データ構造: erDiagram(1図エンティティ最大7。超えたらドメイン別に分割)
   - API フロー: sequenceDiagram(代表 1〜2 本のみ。全 API は表で一覧化)
   - ディレクトリ構造: 図にせず slide_kit.add_code_box()(深さ3まで、主要のみ)
6. **表は python-pptx ネイティブ**で作る(画像化しない。後編集を可能に保つ)。
   数値列は右揃え、ヘッダ行はメインカラー背景+白字、5行超はゼブラ縞。
7. **資料に無い数値・固有名詞を創作しない。** 不明値は「TBD」と書き、
   完了報告時に TBD 一覧を提示する。全スライドに source(出典)を付ける。
8. **生成後は必ず lint_deck.py を実行**し、違反0まで修正(最大5回)。
   5回で収束しない場合は内容を削る方向で解決する。
9. 挿絵が効果的な箇所は slide_kit.add_image_placeholder() で枠のみ確保し、
   deck/image_requests.md に生成指示(サイズ・プロンプト案)を書く。自分で描かない。
10. **全スライドにスピーカーノート**を付ける(発表者が話す原稿を2〜4文。
    想定質問がある場合は「Q:」として併記)。
11. deck/glossary.md(用語集)が存在する場合、表記は必ずそれに従う。

## デザイントークン(slide_kit.py 内の定数 TOKENS で一元管理)
- 16:9(13.333 x 7.5 inch)/ 余白 上下左右 0.6 inch / タイトル帯 上部 1.1 inch
- フォント: Meiryo UI(タイトル28pt Bold / 本文16pt / 表12pt / 注釈10pt)
- 色: メイン #1F4E79 / アクセント #C55A11 / 背景 #FFFFFF / 罫線 #D9D9D9
- deck/assets/template.pptx があればそれを開いてスライド追加し、
  テンプレートのプレースホルダ・配色を優先する

## outline.yaml スキーマ(deck/outline.schema.json で機械検証する)
meta: {title, audience, date, author, goal}
slides:
  - layout: title | agenda | section | one_message | two_col | table | diagram |
            code_box | kpi_row | placeholder_image | appendix
    title: "..."
    message: "このスライドで伝えたい一文"   # 必須
    content: {...}                          # layout ごとの構造化データ
    source: "docs/01_要件定義.md#見出し"     # 必須
    notes: "スピーカーノート"

## 標準構成(12〜15枚+Appendix)
1表紙 / 2サマリ(結論先出し) / 3背景・課題 / 4解決アプローチ(挿絵候補)
5機能要件サマリ(表) / 6非機能要件(表) / 7アーキテクチャ全体図
8データ構造(ER図) / 9API概要(表+シーケンス図1本) / 10ディレクトリ構成
11実装状況・進捗(kpi_row or 表) / 12リスク・今後の課題 / 13まとめ
Appendix: 詳細設計の要点

---

STEP 3. 共通ツール一式を Codex に作らせる(初回のみ)

codex を起動し、以下をそのまま貼る。ここで作った deck/ 以下のスクリプト群は全プロジェクトで使い回せる資産になる(dotfiles/chezmoi 管理推奨)。

AGENTS.md のスライド生成ルールに従い、deck/ 配下に共通ツール一式を実装して。

1) deck/slide_kit.py — レイアウト関数ライブラリ
   定数 TOKENS(デザイントークン)を先頭で定義し、以下を実装:
   - new_deck(template_path=None) -> Presentation
     (template があれば開き、スライドサイズ 16:9 を保証)
   - add_title_slide(prs, title, subtitle, date, author)
   - add_agenda(prs, items)
   - add_section_divider(prs, section_title)
   - add_one_message(prs, title, message, bullets=None)
   - add_two_col(prs, title, message, left, right)
     # left/right は {"type": "bullets"|"image"|"table", ...} 幅は自動で等分
   - add_table_slide(prs, title, message, headers, rows,
                     col_widths_ratio=None, highlight_rows=None, align=None)
     # 列幅は比率→絶対値変換を関数内で計算。数値列右揃え、ゼブラ縞、
     # ヘッダはメインカラー背景+白字
   - add_diagram(prs, title, message, image_path, caption=None)
     # 画像はアスペクト比維持で本文領域に内接フィット・中央寄せ(最重要)
   - add_code_box(prs, title, message, code_text)  # 等幅・薄グレー背景
   - add_kpi_row(prs, title, kpis)  # {label, value, note} のカード3〜4枚
   - add_image_placeholder(prs, title, message, size_hint, request_id)
     # 破線枠+「image_requests.md #req-xxx 参照」の文字
   - set_notes(slide, text)  # スピーカーノート
   内部ヘルパー:
   - fit_text(shape, ...): あふれ時フォント自動縮小(下限12pt)、それでも
     超過なら例外を投げる(黙って潰さない)
   - inner_fit(img_w, img_h, box): 内接フィット計算(Pillow でサイズ取得)

2) deck/build_deck.py — outline.yaml → output.pptx
   - 最初に outline.schema.json で YAML を検証し、不正なら行番号付きで報告
   - layout 名 → slide_kit 関数へのディスパッチのみを行う(ロジックを持たない)
   - deck/assets/ に placeholder の request_id と同名 PNG があれば
     自動で実画像に差し替える
   - 図 PNG は .mmd の内容ハッシュをファイル名に含め、変更が無ければ再生成しない

3) deck/lint_deck.py — output.pptx を読み戻して検査、結果を JSON で出力
   検査項目:
   a. スライド外はみ出し(shape の座標が 0,0〜W,H を超過)
   b. 余白侵犯(本文要素がマージン外)
   c. shape 同士の bounding box 交差(意図的な重なりは許可リストで除外)
   d. テキストあふれ推定(文字数÷行幅 から行数を推定し枠高さと比較)
   e. ルール違反(箇条書き6項目以上/タイトル21字以上/本文40字超の項目)
   f. 画像の実効解像度が 150dpi 未満
   g. フォント不統一(TOKENS に無いフォント名の使用)
   h. スピーカーノート欠落
   出力: [{slide, shape, rule, detail, value}] の JSON

4) deck/outline.schema.json — AGENTS.md 記載のスキーマを JSON Schema 化

5) deck/mermaid.config.json — theme: neutral、fontFamily に
   "Meiryo, Noto Sans JP, sans-serif"、背景白。mmdc 実行例コメント付き

6) deck/requirements.txt — 使用ライブラリをバージョン固定で記載

実装後、3枚のダミー outline でセルフテスト(build → lint 違反0)まで確認して。

完了確認:deck/ に上記6ファイルができ、Codex が「セルフテストで lint 違反0」と報告すればOK。

---

STEP 4. カスタムプロンプト /deck を登録する

~/.codex/prompts/deck.md(Windows は C:\Users\<name>\.codex\prompts\deck.md)を作成:

プロジェクトの設計資料から説明用 PowerPoint を生成する。
AGENTS.md のスライド生成ルールに厳密に従うこと。

手順:
1. docs/ を読み、資料種別(要件定義/非機能/データ構造/API/アーキ/
   ディレクトリ構造/詳細設計/実装)との対応表を提示
2. 各資料を docs_digest/ に要約(1資料 = 1ファイル、決定事項・数値・
   固有名詞を優先して残す)。以降は digest を主に参照する
3. deck/glossary.md が無ければ、資料から主要用語と正式表記を抽出して生成
4. deck/outline.yaml を生成(全スライドに message / source / notes 必須)
5. 【停止】outline のレビューを依頼。承認まで絶対に先へ進まない
6. 承認後:
   a. deck/diagrams/*.mmd 作成 → mmdc で PNG 化(config 使用, scale=2)
   b. build_deck.py 実行 → deck/output.pptx
   c. lint_deck.py 実行 → 違反0まで修正ループ(最大5回)
7. deck/image_requests.md を生成(挿絵ごとに サイズpx/アスペクト比/
   トーン指定/日英プロンプト案)
8. 完了報告: スライド一覧 / lint 最終結果 / TBD 一覧 / 画像差し替え手順

これで次回から codex 起動 → /deck と打つだけで全工程が走る。

---

STEP 5. 実行する(会話例つき)

cd /path/to/project
codex        # 実行許可を広めにするなら codex --full-auto

あなた > /deck

Codex  > docs/ を確認しました。対応表:
         要件定義 → 01_要件定義.md / 非機能 → 02_... (中略)
         digest と glossary を作成し、outline.yaml を生成しました。
         【レビュー依頼】deck/outline.yaml を確認してください。

ここで STEP 6 のレビューを行う。修正指示は自然文でよい:

あなた > スライド6と7を統合。スライド9のシーケンス図は「注文確定API」
         のフローに変更。全体を13枚以内に。
Codex  > outline.yaml を更新しました。再確認をお願いします。
あなた > OK、承認。ビルドして。
Codex  > 図を4点生成 → build → lint 実行。違反3件を検出し修正、
         再lint で違反0。deck/output.pptx 完成。
         image_requests.md に挿絵2件の生成指示を出力しました。
         TBD: スライド11の「テストカバレッジ」(資料に記載なし)

---

STEP 6. outline.yaml をレビューする(ここが本番)

pptx を直すのは高コスト、YAML を直すのは1分。 手間の9割をここに投資する。

レビュー観点チェックリスト:

• 2枚目(サマリ)だけ読んで意味が通るか — 上司は最悪ここしか見ない
• 各スライドの message: を縦に読んで、ストーリーが一本つながるか
• 「そのスライド、なくても伝わるのでは?」→ 削除 or Appendix 行き
• 表にすべき箇条書きが残っていないか(3項目×2属性以上あれば表)
• source: が全スライドにあるか。「TBD」の数値は許容できるか
• 上司が必ず聞いてくる質問(コスト・納期・リスク)への答えがどこかにあるか

さらに精度を上げるなら、承認前にこの1行を打つ(敵対的レビュー):

承認前に、決裁者の立場で outline を批判的にレビューして。
「この資料で承認できない理由」を5つ挙げ、outline への反映案を提示して。

---

STEP 7. ビルドと自動修正ループ

承認後は Codex が自動で回すが、仕組みを知っておくとトラブル時に強い:

1. .mmd → mmdc -i x.mmd -o x.png -s 2 -b white -c deck/mermaid.config.json
2. python deck/build_deck.py → deck/output.pptx
3. python deck/lint_deck.py → 違反 JSON
4. Codex が JSON を読み、outline か slide_kit を直して 2 に戻る(最大5回)
5. (LibreOffice がある場合)最終確認:

soffice --headless --convert-to png --outdir deck/render deck/output.pptx

生成 PNG を Codex に見せて「詰まって見える箇所・色が沈む箇所を指摘して」と最終目視レビューをさせる。幾何チェック(lint)で事故を潰し、視覚チェックで美観を上げる二段構え。

---

STEP 8. 挿絵(GPT画像)の差し替え

1. deck/image_requests.md を開く。例:

   ## req-001(スライド4「解決アプローチ」右半分)
   - 推奨サイズ: 1200x900 px(4:3) / トーン: フラットイラスト、紺基調 #1F4E79
   - プロンプト(日): 散らばった書類に困る人と、整理されたダッシュボードを見て
     安心する人の対比。フラットデザイン、ビジネスイラスト、余白広め
   - プロンプト(英): flat business illustration, before/after contrast ...
   

2. GPT の画像生成にプロンプトを貼って生成 → deck/assets/req-001.png として保存(ファイル名を request_id に一致させるのが唯一のルール)

3. Codex に「画像を置いた。再ビルドして」→ build_deck.py が自動で枠と差し替え(内接フィットで貼るのでズレない)

---

STEP 9. 納品前チェックリスト

• lint 違反 0 / TBD 一覧を確認し、埋めるか脚注で「別途報告」と明記
• PowerPoint 実機で開き、スライドショーを1周(フォント置換警告が出ないか)
• 表が「画像でなく表」として選択できるか(後編集可能性の確認)
• スピーカーノートを1周読み、そのまま口頭説明に使えるか
• ファイル名・表紙の日付・版数(v1.0)・社外秘表記
• 配布するなら PDF 版も書き出し(soffice --headless --convert-to pdf)

---

STEP 10. 2回目以降の運用(5分で終わる)

1. 新プロジェクトに AGENTS.md と deck/ のスクリプト群をコピー(chezmoi やテンプレートリポジトリ化しておく)
2. docs/ に資料を連番で置く
3. codex → /deck → outline レビュー → 承認
4. 挿絵差し替え → 納品前チェック

1回目に良くできた outline.yaml と output.pptx は deck/examples/ に保存しておくこと。次回 /deck 時に「examples/ の構成・粒度を手本にして」と一言添えるだけで、few-shot 効果で品質が安定する(小技集 #1)。

---

精度を上げる小技集(20連発)

A. 入力の質を上げる(効果:特大)

1. お手本を渡す(few-shot) — 過去の良い deck の outline.yaml と pptx を deck/examples/ に置き、「これを手本に構成・粒度を合わせて」と指示。ルールで縛るより例で示す方が LLM は正確。
2. 資料を先に digest 化 — 原本を毎回読ませず docs_digest/ の要約を参照させる。コンテキスト消費が激減し、長い資料の「後半を読み飛ばす」事故も防げる(/deck に組込済)。
3. 用語集(glossary.md)で表記統一 — 「利用者/ユーザー/User」の揺れはレビュー指摘の定番。最初に用語と正式表記を確定させる(/deck に組込済)。
4. 資料の連番リネーム — 読み込み順と参照関係の誤認を防ぐ(STEP 1)。
5. 数値の創作禁止+TBD 運用 — 「資料に無い数値は書かずTBD」をルール化し、完了時に TBD 一覧を出させる。幻覚数値が決裁資料に混じる事故を根絶(AGENTS.md #7)。

B. 生成プロセスを固める(効果:大)

1. outline を JSON Schema で機械検証 — 「layout 名の typo」「content 構造の不一致」をビルド前に行番号付きで検出。LLM の出力ブレを型で受け止める。
2. 敵対的レビューを outline 段階で1回 — 「決裁者として承認できない理由を5つ」(STEP 6)。普段の3ラウンドDRを回すなら、対象は pptx ではなく outline にする(修正コストが1桁違う)。
3. 図の複雑度に上限 — ER図はエンティティ7個まで、flowchart はノード12個まで、超えたら分割。Mermaid が潰れる最大要因は詰め込みすぎ。
4. シーケンス図は代表1〜2本だけ — 全 API を図にせず、一覧は表・代表フローだけ図。「図の乱発」も読みづらさの原因。
5. fit_text は「黙って縮めすぎない」 — 縮小下限(12pt)を切ったら例外にして lint に乗せる。気づかぬうちに9ptの読めない資料になるのを防ぐ。
6. 図の再生成をハッシュでキャッシュ — .mmd が変わらなければ PNG を作り直さない。修正ループが速くなり、無関係な図が変わる事故も防ぐ(build_deck に組込済)。
7. ライブラリはバージョン固定 — requirements.txt で固定。python-pptx の挙動差でレイアウトが変わるのを防ぐ。

C. 仕上がりを上げる(効果:中〜大)

1. 会社テンプレート(.pptx)を使う — 見た目の「それっぽさ」はテンプレが9割。最初に「template.pptx のレイアウト名とプレースホルダ名を全部ダンプして」と実行させ、slide_kit をテンプレ準拠で組ませる。
2. スピーカーノート自動生成 — 各スライドに発表原稿2〜4文+想定Q。上司説明のリハーサルがそのままできる(AGENTS.md #10)。
3. 表の書式ルールを固定 — 数値右揃え・ヘッダ色付き・5行超はゼブラ。「表が読みやすい資料」は それだけで評価が上がる(slide_kit に組込済)。
4. サマリスライドは「結論→根拠3点→お願い事項」の型 — outline レビュー時にこの型に合っているかだけ確認する。
5. lint にフォント統一チェック — TOKENS 外のフォントが1箇所でも混ざると素人感が出る。機械検出させる(lint 項目 g)。
6. LibreOffice レンダリング+視覚レビュー — lint(幾何)で事故を潰した後、PNG を Codex に見せて美観(詰まり・色の沈み)を指摘させる二段構え(STEP 7)。

D. 運用で差をつける(効果:中)

1. git でビルド前後を commit — outline の diff がそのまま「レビュー議事録」になる。差し戻しも一瞬。
2. 実装状況スライドの根拠を明示 — 進捗資料が無い場合は git log とディレクトリから推定させ、「推定である」注釈を必ず入れさせる。過大報告は信頼を一発で失う。

---

トラブルシューティング

症状	原因	対処
Mermaid の日本語が □□ になる	ヘッドレス Chrome にフォントが渡っていない	mermaid.config.json の fontFamily 指定を確認。ダメなら OS に Noto Sans JP を入れる
mmdc が Git Bash で動かない	.cmd 解決の問題	mmdc.cmd で呼ぶ / PowerShell で実行
図が小さすぎる・ぼやける	scale 不足 / 内接フィット前の低解像度	-s 2(必要なら 3)。lint の 150dpi 警告を確認
lint が5回で収束しない	情報の詰め込みすぎ	Codex 任せにせず outline に戻り、スライド分割 or Appendix 送りを指示
PowerPoint で開くとフォントが違う	閲覧PCに Meiryo UI が無い(まれ)	配布先が社外なら游ゴシックに TOKENS を変更
表の列幅が崩れる	比率合計≠1 / 長文セル	col_widths_ratio を明示。セル内改行は lint で検出させる
Codex が承認前にビルドを始める	停止指示の読み飛ばし	「【停止】」の行を /deck に残す。始めたら Esc で中断し「outline 承認前。手順5に戻って」
テンプレート使用時にレイアウトが崩れる	プレースホルダ名の不一致	小技 #13 のダンプを実行し、slide_kit のプレースホルダ参照名を実名に合わせる

---

付録:最小の動作確認(環境ができたか3分で確認)

cd project
codex
> deck/outline.yaml に「表紙・表1枚・Mermaid図1枚」の3枚だけのテスト構成を書き、
> build → lint まで通して。違反0になったら output.pptx のスライド構成を報告して。

これが通れば環境は完成。あとは実プロジェクトで /deck を打つだけ。