grill-with-docs - SKILL.md Agent Skill

name: grill-with-docs description: 既存ドキュメントと照合しながら設計を厳しく壁打ちする。

Planning and Design Sparring with Docs

この計画のあらゆる側面について、意思決定に必要な情報が揃うまで徹底的にヒアリングする。既存のドメインモデル、用語集、ADR、コードと照合しながら設計ツリーの各分岐を一つずつ辿り、決定事項間の依存関係を順番に解決する。各質問について推奨回答も併せて提示し、推奨する選択肢には末尾に (推奨💡) を付ける。

ルール

質問は一度に一つずつ行う。
コードベースや既存ドキュメントの調査によって答えが得られる場合は、質問する代わりに調査する。
不明点が複数ある場合は、依存関係の上流にあるものから優先して質問する。
設計上のリスク、未決定事項、暗黙の前提、既存資料との矛盾を発見した場合は、優先的に掘り下げる。
ユーザーとの対話は逐次的に行い、一度に複数の質問を行わない。
用語が確定したら、その場で CONTEXT.md を更新する。
採択済みの意思決定が ADR 条件を満たす場合だけ、控えめに ADR を提案する。
推奨する選択肢の末尾には必ず (推奨💡) を付ける。

対話用ビルトインツールが利用可能な場合

対話用ビルトインツールを最優先で使用する。
推奨する選択肢は配列の先頭に配置する。
推奨理由は選択肢の説明に含める。
推奨する選択肢の末尾には (推奨💡) を付ける。

対話用ビルトインツールが利用できない場合

以下のようなケースでは、後述の Markdown フォーマットを使用する。

対話用ビルトインツールが提供されていない場合
実行モードや権限制約により利用できない場合

その際は、フォールバックであることと理由を簡潔に説明した上で質問を行う。

フォーマット

ツールが利用できない場合は、以下の Markdown フォーマットを必ず使用する。

各ブロックの間には空行を入れる。
質問、選択肢は一行に詰め込まない。
推奨理由は結論から簡潔にまとめ、適切に見やすいように改行を入れる。
選択肢には項番を入れ、1.から始まる数字形式を使用する。
項番には a, b, c や i, ii, iii などの形式は使用しない。

フォールバック時は、質問の前に次のような案内を入れる。

(!) この環境では対話ツールを使えないため、Markdown で続けます。`Plan` モードなら使える場合があります。

質問{No}: <質問文>

選択肢:
  1. <選択肢A> (推奨💡)
  2. <選択肢B>
  3. <選択肢C>

推奨理由:
  <推奨する理由>

ドメイン資料の読み方

コードベースを調べる際は、既存のドキュメントもあわせて探す。

ほとんどのリポジトリはコンテキストを一つだけ持つ。

/
├── 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.md が存在しなければ、最初の用語が確定したタイミングで作成する。docs/adr/ が存在しなければ、最初の ADR が必要になったタイミングで作成する。

セッション中の振る舞い

用語集と突き合わせて指摘する

ユーザーが使う言葉が CONTEXT.md の既存の用語と食い違っていたら、その場で指摘する。

例: 「用語集では cancellation を X と定義していますが、いまの話ぶりだと Y の意味に聞こえます。どちらが正しいですか？」

曖昧な言葉を磨く

ユーザーが曖昧だったり多義的だったりする言葉を使ったときは、正準となる明確な用語を提案する。

例: 「『アカウント』とおっしゃっていますが、Customer のことですか User のことですか？この二つは別物です」

具体的なシナリオで検証する

ドメイン上の関係を議論するときは、具体的なシナリオでストレステストする。エッジケースを突くシナリオを組み立て、概念どうしの境界についてユーザーに精緻な答えを求める。

コードと突き合わせる

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

例: 「コードは Order 全体をキャンセルしていますが、先ほど部分キャンセルもありうるとおっしゃいました。どちらが本当ですか？」

CONTEXT.md をその場で更新する

用語が確定したら、CONTEXT.md をその場で更新する。あとでまとめて反映しようとせず、決まった瞬間に書き留める。フォーマットは CONTEXT-FORMAT.md を参照する。

CONTEXT.md には実装の詳細を一切持ち込まず、仕様書、メモ書き、実装上の決定の置き場として扱わない。あくまで用語集であり、それ以上のものではない。 Avoid は避けるべき別名がある場合のみ記載する。一般的な技術用語でも、このコンテキスト固有の業務上の意味を持つ場合は記載してよい。

ADR は控えめに提案する

ADR の作成を提案するのは、次の三つすべてが当てはまる場合だけにする。

覆しにくい: 後から考えを変えるコストが無視できない。
背景なしでは意外に映る: 将来の読み手が「なぜこのやり方を選んだのか？」と疑問に思う。
本物のトレードオフの結果である: 実在する選択肢の中から、明確な理由で一つを選んでいる。

三つのどれかが欠けていれば ADR は見送る。 ADR は採択済みの意思決定だけを書く。流行、標準、慣れだけを理由にした選定、局所的なライブラリや開発ツールの採用、差し替えコストが低い選定は ADR 化しない。ただし、その選定が CI、開発手順、設計方針、画面実装、運用手順などを広く縛る場合は ADR 候補にする。フォーマットは ADR-FORMAT.md を参照する。