# Grill With Docs

> 計画・設計をラウンド制の反復質問で徹底的に詰めながら、確定した用語を CONTEXT.md に、重い決定を docs/adr/ に即時記録するスキル。「設計を詰めて」「グリルして」「計画を叩いて」「用語を固めて」「ユビキタス言語を作って」「ADR を残して」「このリポジトリのドメインを文書化して」などで発動する。1 セッションで決着する規模の変更、またはドメイン文書が無いリポジトリの棚卸しに使う。

- Skill: `ynitto/grill-with-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ynitto/grill-with-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/grill-with-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/grill-with-docs

---


# グリル＋ドキュメント化

## 概要

計画や設計について、ユーザーと同じ理解に到達するまで質問を浴びせる。同時に、その場で固まった用語をリポジトリの `CONTEXT.md` に、覆しにくい決定を `docs/adr/` に書き込む。

他のブレスト系スキルとの違いは**状態を残すこと**の一点にある。会話が終わったらセッションは消えるが、このスキルはファイルを残す。用語が決着した瞬間に `CONTEXT.md` へ書く。まとめて最後に書かない。

<HARD-GATE>
フロンティアが空になり、ユーザーが「認識が揃った」と明示するまで、実装に着手しない。コードを書く・スキャフォールドする・実装系スキルを呼ぶ、いずれも禁止。
</HARD-GATE>

## 使いどころ

| 手元にあるもの | 使うスキル |
| --- | --- |
| 作業ディレクトリ外の、リポジトリに紐づかない相談 | `brainstorming` |
| リポジトリがあり、1 セッションで決着する規模の変更 | **このスキル** |
| ドメイン文書が一切無いリポジトリの棚卸し | **このスキル**（変更ではなくリポジトリ自体に向ける） |
| 1 セッションに収まらない規模（新規構築・大型機能） | `requirements-definer` → `decomposition` |
| 誰か他人の頭の中にある知識で詰まっている決定 | 本人に投げる質問票を `doc-coauthoring` で作る |

## 進め方

### Step 0: 既存のドメイン文書を読む

質問を始める前に、リポジトリの現状を掴む。

1. ルートに `CONTEXT-MAP.md` があるか。あれば複数コンテキスト構成。マップを読んで、今回の話題がどのコンテキストに属するか推定する。判別できなければユーザーに聞く。
2. 無ければルートの `CONTEXT.md` を読む。単一コンテキスト構成。
3. `docs/adr/` の既存 ADR に目を通す。番号の最大値を控える。
4. どれも無ければ、ゼロから始める。事前に空ファイルを作る必要はない。

### Step 1: 設計ツリーを立て、フロンティアを特定する

決定を木として捉える。ある決定が決まると、その下にぶら下がる決定が答えられるようになる。

**フロンティア**とは、前提がすべて決着済みで、いま聞ける質問の集合を指す。まだ開いている質問の答えに依存する質問は、このラウンドではなく後のラウンドに属する。

### Step 2: フロンティア全部を 1 ラウンドで聞く

1 問ずつ小出しにしない。フロンティアの質問に番号を振り、それぞれに**自分の推奨案**を添えて一度に出す。

```
❓ **Q1** - **<質問のタイトル>**: <質問本文。複数段落でも、選択肢の列挙でもよい>

➡️ <推奨する答えと、その理由>
```

推奨案は必ず書く。「どうしますか？」だけの丸投げはユーザーの時間を奪う。

### Step 3: 事実は自分で調べ、判断だけをユーザーに聞く

**事実の調査は自分の仕事**。ファイルシステム・コード・設定・外部ドキュメントを読めば分かることをユーザーに聞かない。調べる必要があればサブエージェントを飛ばす。

調査でブロックしない。走っている調査は「未決着の前提」なので、その下流の質問だけが待つ。残りのフロンティアは今すぐ聞く。

**判断はユーザーのもの**。トレードオフのある選択、優先順位、事業上の制約は、推奨案を添えて必ず本人に投げ、答えを待つ。

### Step 4: 回答を受けてツリーを組み直し、次のラウンドへ

回答が入るたびに木の形が変わる。決着した決定がフロンティアを外へ押し出し、依存していた質問が解放される。フロンティアを計算し直して次のラウンドを出す。

### Step 5: フロンティアが空になったら終了

木の全枝を訪れ、暗黙の前提が残っていない状態が終了条件。ユーザーが認識合わせの完了を確認するまで、そこから先へ進まない。

終わったら次の行き先を 1 つ提示する。仕様書に落とすなら `doc-coauthoring`、チケットに割るなら `decomposition`、すぐ作れる規模なら実装へ。

## セッション中の記録

質問と並行して、以下を**その場で**行う。ラウンドの終わりにまとめて処理しない。

### 用語がグロッサリと衝突したら即座に指摘する

ユーザーの使った語が `CONTEXT.md` の既存定義とずれていたら、その場で止める。

> グロッサリでは「キャンセル」を注文全体の取り消しと定義していますが、いまの話は明細単位の取り消しに聞こえます。どちらですか。

### 曖昧な語を精緻化する

多義的な語には、正典となる用語を提案する。

> 「アカウント」と言われましたが、それは Customer ですか User ですか。別の概念です。

### 具体シナリオで境界を叩く

概念間の関係を議論するときは、エッジケースを突くシナリオを自分で発明してぶつける。境界が曖昧なまま合意した気になるのを防ぐ。

### コードと突き合わせる

ユーザーが「こう動く」と言ったら、コードがそれに同意しているか確かめる。矛盾を見つけたら表に出す。

> コードは Order 単位でしかキャンセルしていませんが、いま部分キャンセルがあると仰いました。どちらが正ですか。

### 用語が決着したら CONTEXT.md を更新する

決着した瞬間に書く。後でまとめない。

`CONTEXT.md` は**グロッサリであって、それ以外の何物でもない**。実装の詳細、仕様、作業メモを書かない。

```md
# {コンテキスト名}

{このコンテキストが何であり、なぜ存在するかを 1〜2 文で}

## 用語

**Order（注文）**:
顧客が確定させた購入意思の単位。
_使わない_: Purchase, Transaction

**Invoice（請求書）**:
納品後に顧客へ送る支払い依頼。
_使わない_: Bill, 支払い依頼

**Customer（顧客）**:
注文を行う個人または組織。
_使わない_: Client, Buyer, Account
```

書くときのルール:

- **態度を決める**。同じ概念に複数の語があるなら、最良の 1 つを選び、残りを `_使わない_` に落とす。
- **定義は締める**。1〜2 文まで。何を「する」かではなく、何で「ある」かを書く。
- **このプロジェクト固有の語だけ**。タイムアウト、エラー型、汎用ユーティリティのような一般的なプログラミング概念は、どれだけ多用されていても入れない。追加前に「これはこのコンテキスト固有の概念か、一般概念か」を自問する。
- 自然な塊が出てきたら見出しで**グループ化**する。全部が 1 領域に収まるならフラットな列挙で足りる。

### ADR は絞って提案する

以下の 3 つが**すべて**成り立つときだけ ADR を提案する。

1. **戻しにくい** — 後で気が変わったときのコストが実際に高い
2. **文脈なしでは驚かれる** — 将来の読み手が「なぜこうした？」と思う
3. **本物のトレードオフの結果** — 現実的な代替案があり、理由を持って一方を選んだ

1 つでも欠けたら書かない。簡単に戻せるならどうせ戻す。驚かれないなら誰も理由を探さない。代替案が無かったなら「当たり前のことをした」以上の記録価値はない。

多くのセッションでは ADR が 1 件も出ない。それは正常な結果であって、失敗ではない。

**書式**（`docs/adr/0001-slug.md`。既存の最大番号 + 1 で採番。ディレクトリは最初の 1 件が出るまで作らない）:

```md
# {決定の短いタイトル}

{文脈・決めたこと・理由を 1〜3 文で}
```

1 段落で終わってよい。価値は「決定があったこと」と「その理由」が残ることで、節を埋めることではない。

任意の追加要素は、実際に価値があるときだけ足す。

- **Status** フロントマター（`proposed | accepted | deprecated | superseded by ADR-NNNN`）— 決定が後で見直される見込みがあるとき
- **検討した選択肢** — 却下した案を覚えておく価値があるとき
- **影響** — 自明でない下流影響を明示する必要があるとき

ADR に値する典型:

- アーキテクチャの形（モノレポ採用、書き込みモデルはイベントソーシング等）
- コンテキスト間の統合方式（同期 HTTP ではなくドメインイベントで繋ぐ、等）
- ロックインを伴う技術選定（DB、メッセージバス、認証基盤、デプロイ先）。差し替えに四半期かかるものだけ。ライブラリ 1 つ 1 つは対象外
- 境界とスコープの決定（顧客データは Customer コンテキストが所有し、他は ID 参照のみ）。「やらない」の明示も同じ価値がある
- 明らかな道からの意図的な逸脱（ORM ではなく手書き SQL を使う理由）。次の担当者が「直してしまう」のを止める
- コードから見えない制約（コンプライアンス上 AWS を使えない、パートナー API の契約で 200ms 以内、等）

## ファイル構成

単一コンテキスト（大半のリポジトリ）:

```
/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/
```

複数コンテキスト（ルートに `CONTEXT-MAP.md` がある場合）:

```
/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← システム全体の決定
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                 ← このコンテキスト固有の決定
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/
```

`CONTEXT-MAP.md` の中身:

```md
# コンテキストマップ

## コンテキスト

- [Ordering](./src/ordering/CONTEXT.md) — 顧客注文の受付と追跡
- [Billing](./src/billing/CONTEXT.md) — 請求書生成と入金処理
- [Fulfillment](./src/fulfillment/CONTEXT.md) — 倉庫のピッキングと出荷

## 関係

- **Ordering → Fulfillment**: Ordering が `OrderPlaced` を発行し、Fulfillment がピッキングを開始
- **Fulfillment → Billing**: Fulfillment が `ShipmentDispatched` を発行し、Billing が請求書を生成
- **Ordering ↔ Billing**: `CustomerId` と `Money` の型を共有
```

ファイルは遅延生成する。書くものが出てから作る。

## 既知の限界

**書き手は 1 人を前提にしている**。同じリポジトリで複数人が並行してこのスキルを回すと、ADR の引用や README の記述がドリフトする。人が手で書いたドキュメントほどドリフトが速い。定期的な棚卸しは持たない。リンク切れと引用の整合を CI の決定的チェックに落とすほうが効く（`codd-gate` / `doc-drift-detector`）。

**決めたことの大半はファイルに残らない**。`CONTEXT.md` はグロッサリに限定され、ADR は 3 条件で絞られる。それ以外の合意は会話の中にしかない。セッションを閉じる前に `doc-coauthoring` へ渡して仕様に落とす。順序保証・否定要件・数値のデフォルトのような精密な答えは、下流で曖昧な散文に丸められやすい。仕様が出来たら自分の回答と突き合わせて読み直す。

**無関係な変更で何度も回すと文書が混ざる**。1 リポジトリに話題の違う用語と ADR が積み上がる。セッションごとの分離は仕組みとして持っていない。

## 検収基準

- `CONTEXT.md` がセッション**中に**用語ごとに変わっている。最後に一括で現れていない
- グロッサリが純粋な語彙になっている。実装詳細も仕様めいた散文も混ざっていない
- コードを読めば分かる質問がユーザーに投げられていない
- ADR は 0〜数件。出たものは、後でひっくり返されたら腹が立つ類の決定になっている
- 既存グロッサリと食い違う語をユーザーが使ったとき、その場で指摘できている