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

yannsugi Updated Sep 22, 2026

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add yannsugi/propose-with-diagram

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/yannsugi/propose-with-diagram.svg)](https://skillmd.com/skills/yannsugi/propose-with-diagram)

Trust & safety

Audits pending

Not yet audited · commit 4604ccf

Permissions this skill uses

Documentation only
No scripts, network access, or credentials are involved.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

propose-with-diagram

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

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

入力契約

読んでよいもの(全列挙):

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

読んではいけないもの:

期待の変更履歴の往復の中身(結論だけが期待に蒸留済み)
会話履歴

手順

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

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

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

---name: propose-with-diagramdescription: 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---# 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 のルートからの相対

yannsugi/claude-skills/tree/main/plugins/github-flow/skills/propose-with-diagram commit 4604ccf039

Frequently asked questions

npx skillmds@latest add yannsugi/propose-with-diagram