実装後の "なんか違う" を、実装前の10分で消す
Claude Code にコードを書かせると、動くが構造・命名・責務の切り方のどこかが「そういうことじゃない」という状態で返ってくることがあります。修正を一つ指示するたびエージェントが別のズレを作り、ループが続きます。
問題は出発点にあります。合意が薄いまま実装が始まった、それだけです。
エージェントは仮定を補完して動く
人間が設計を話すとき、頭の中にある仮定を言語化しないまま進みます。
「ユーザーはログイン済みのはず」「このAPIは冪等のはず」「キャンセルは注文単位のはず」
エージェントはこのギャップを自分で埋めます。コードベースを探索し、それらしい答えを選ぶ。補完が意図と合っていれば問題ないが、合っていなければ動くが間違ったコードが出来上がります。
設計がズレていてもテストは通ります。レビューも通り抜けやすく、チームは気づかないまま次の実装の前提にします。
mattpocock/skills について
「なんか違う」のループは、実装前の合意が取れていれば起きません。そのための手段として mattpocock/skills があります。
mattpocock/skills は Matt Pocock が公開しているスキル集です。スキルとは、AI コーディングエージェントに読み込ませる小さな指示ファイルで、特定の作業パターンをエージェントに教えます。
skillsCLI でインストールします。
npx skills@latest add mattpocock/skills
複数のスキルが含まれており、実装前の合意を固めるために使うのが
grill-meと
grill-with-docsです。
セッション内で
/grill-meまたは
/grill-with-docsと入力することで起動します。
grill-me
── 決定ツリーを一問ずつ確定する
/grill-me
スキルの指示は短い。
Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask the questions one at a time. If a question can be answered by exploring the codebase, explore the codebase instead.
（訳：プランのあらゆる側面を、共有理解に達するまで容赦なく質問する。決定ツリーの各枝を依存関係を解決しながら一本ずつ確定する。各質問には推奨回答を添える。一問ずつ聞く。コードベースで答えられる質問はコードを探す。）
Claude は質問を一つずつ出し、回答が返るまで次へ進みません。前の回答が次の質問の前提になるため、思い込みが積み重なるのを防げます。Claude は各質問に推奨回答を添えるので、判断は YES か NO かだけで足ります。
コードベースで答えられる内容は、Claude が自分でコードを探して解決します。「このモデルはどこで定義されていますか？」とユーザーに聞きません。判断が必要な問いにだけ時間を使う設計です。
grill-with-docs
── 語彙を合わせながら進む
/grill-with-docs
grill-meとは解決する問題が違います。プロジェクトが育つにつれ、会話・コード・ドキュメントの中の言葉がズレていきます。「Order」がある文脈では受注を指し、別の文脈では購買依頼を指す。「Account」が UI では取引先を指し、API では認証ユーザーを指す。
語彙がバラバラのまま指示を出すと、正しく指示したつもりでもエージェントは別の概念でコードを書きます。
grill-with-docsは CONTEXT.md と
ADRをリポジトリから読み込み、グリリング中に語彙の衝突を検出します。
CONTEXT.md はリポジトリルートに置くドメイン用語集です。プロジェクトで使う言葉とその定義を書きます。コードの実装詳細は書かず、ドメイン専門家が読んで意味がわかる言葉だけを載せます。ファイルがない場合、
grill-with-docsは最初の用語が確定したときに作ります。
ADR（Architecture Decision Record） は、設計上の重要な判断を記録する短いドキュメントです。なぜその判断をしたか、どの代替案を検討してどう選んだかを残します。
docs/adr/ディレクトリに連番で置くのが一般的です。将来の自分やチームが「なぜこうなっているのか」を調べるときに使います。
語彙の衝突を見つけると、Claude はこう確認します。
あなたのグロッサリーでは "cancellation" はXと定義されていますが、今おっしゃっているのはYのことですか？
確定次第、Claude がその場で
CONTEXT.mdを書き換えます。セッション末にまとめて更新する運用は、語彙の衝突を見落とす原因になります。
ADR を作る三つの条件
ADR を作るのは以下の三つがすべて揃ったときだけです。
- 後から変更するコストが大きい
- 文脈なしでは意図が伝わらない
- 本物のトレードオフがあった
この三つで絞ることで、形だけのドキュメントが蓄積するのを防ぎます。
どちらを選ぶか
| 状況 | 選ぶスキル |
|---|---|
| 新機能の設計をエージェントに渡す前 | grill-me |
| プロジェクト固有のドメイン語彙が絡む | grill-with-docs |
CONTEXT.mdや ADR がすでにある |
grill-with-docs |
| リポジトリがまだ小さく語彙の定義が少ない | grill-me |
どちらのスキルも起動するのは実装前の10分です。そこで確定した仮定の数だけ、後の修正作業が減ります。