# Propose With Diagram

> Use when an Issue's 期待 has been approved at human gate ① and the next step is to propose how to realize it — before any implementation, when a human must judge "is this the right way forward" at gate ② from a single diagram

- Skill: `yannsugi/propose-with-diagram` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yannsugi/propose-with-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yannsugi/propose-with-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yannsugi (https://skillmd.com/u/yannsugi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yannsugi/propose-with-diagram

---


# propose-with-diagram

実現案フェーズ。承認済みの期待に対して「進み方」を提示し、人間がゲート②で仮説として採択できる形にする。
思想は `${CLAUDE_PLUGIN_ROOT}/DESIGN.md` の「実現案の提示仕様」節。実現案は違和感の検出器として設計する。

**核**: L1 の図1枚だけで NG 判断が成立すること。期待の語彙で書き、実装語彙は L3 に隔離する。却下案と⚠を自分で名指しする。

## 入力契約

読んでよいもの(全列挙):
- 対象 Issue の「## 期待」節(承認済み)と「## コンテキスト」節(調査結果・技術判断の根拠・依存グラフ)
- `docs/system-map.md`(あれば)、コードベース(実現手段の確認のため)
- 同じ親 Issue の他の単位の実現案(インターフェース契約を揃えるため)
- `${CLAUDE_PLUGIN_ROOT}/DESIGN.md`

読んではいけないもの:
- 期待の変更履歴の往復の中身(結論だけが期待に蒸留済み)
- 会話履歴

## 手順

1. **変更タイプを判定する** 期待の「影響画面・入口」から決める。複合なら、Tobe の行が最も多く依存する入口のタイプを主にする。入口が複数のシステムを跨ぐ流れそのものなら「データ」。残りのタイプは L3 に落とす

   | タイプ | L1 の図形式 | Mermaid |
   |---|---|---|
   | 画面 | Before / After の状態遷移 | `stateDiagram-v2` を Before と After の2枚 |
   | API | シーケンス + スキーマ差分 | `sequenceDiagram` + 差分表 |
   | IaC | 構成図の差分 | `flowchart` で追加要素を `:::add`、削除を `:::del` で塗る |
   | データ | 流れの Before / After | `flowchart LR` を2枚 |

2. **候補を2つ以上立てる** 1案しか無い状態で書き始めない。却下案が無い実現案は比較の痕跡が無く、違和感の検出器として働かない
3. **L1 を書く** 図1枚(Before/After 形式なら2枚で1組)と、その下に3文以内の要約。ノードのラベルは期待の語彙(利用者・入口・振る舞い)で書き、クラス名・設定キー・ライブラリ名は使わない。図の中に「変わる場所」が視覚的に分かること
4. **L2 を書く** 判断根拠(なぜこの案か)、却下案と却下理由(1案1行。採用案の部分集合を却下案に並べてよい)、⚠(最大3。リスク・低確信・解釈が入った箇所)。⚠ は「何が崩れると案が成り立たないか」の形で書く。実現案固有のものだけを書き、期待側の⚠に依存するときは番号で参照して再掲しない
5. **L3 を書く** 実装計画。触るファイル、順序、検証方法。実装語彙はここにだけ書く。単位が大きく水平分割するなら、インターフェース契約(API スキーマ・ファイル形式・イベント名)をここで凍結する
6. **期待→手段の対応表** 期待節の Tobe・制約・非機能の各行に、それを満たす手段(L1 のどの要素か)を1対1で付ける。対応の無い行があれば案は未完成。原因未確定などで本案では途中までしか満たせない行は、手段欄に「本案は〜まで。残りは次段で確定」と範囲を明記する(空欄にも、満たす振りにもしない)
7. **出力** 次の書式でコメント文面を成果物として提示する。`gh issue comment <n>` での投稿は、利用者が明示的に指示した場合にのみ実行する

試走でローカルファイル `<name>.md` を対象にする場合は、同じディレクトリの `<name>.proposal.md` に書く。本文中のパスは対象 repo のルートからの相対で書く。

## 出力書式

以下は骨格(外側の `~~~~` は出力に含めない)。

~~~~
## 実現案

### L1
```mermaid
(図1枚)
```
(3行以内: 何を、どこで、どう変えるか)

### L2
- 根拠: …
- 却下案: 案B=…(却下理由)/ 案C=…(却下理由)
- ⚠1: …
- ⚠2: …

### 期待→手段
| 期待の行 | 手段(L1 の要素) |

<details><summary>L3 実装計画(人間は原則読まない)</summary>
- 触るファイルと順序
- インターフェース契約(分割時のみ)
- 検証方法
</details>
~~~~

## よくある失敗

- L1 が無く、本文を全部読まないと判断できない → 図を先に描き、本文は図の説明に留める
- 方針の節に設定キー・環境変数名・フック名が出る → L3 へ移す。L1/L2 は期待の語彙だけ
- リスクが「残課題」「注意点」として文中に散る → ⚠ として上に集め、3つに絞る
- 「判断してほしい点」として人間に質問を並べる → 実現案は仮説の提示。解釈で埋めた箇所は⚠に書き、質問にしない。ビジネス判断が本当に要るなら clarify-expectation に差し戻す
- 段取りと工数見積りを書く → 承認の対象ではない。書くなら L3
- 出力に絶対パスを書く → 対象 repo のルートからの相対