lenneTech/grilling-decisions – 熟成審議

未解決の決定を熟成審議する

計画、チケット、デザインについて、共通認識に達するまでユーザーに徹底的にインタビューします。目的は作業開始前の認識合わせです。間違った前提で構築した変更は、実装全体のコストに加え、レビュー、ブラウザウォーク、マージまで無駄にします。事前に質問すれば1クリックのコストで済みますが、実装途中で同じ質問をするとユーザーのコンテキストスイッチが発生し、復帰するまで実行が停止します。

ユーザーが共通認識を確認するまで、審議対象について一切のアクションを取らないでください。

ループ

1. すべての事実を自分で調べる（事実 vs 決定参照）。コードを把握した上でインタビューに臨みます。
2. 決定ツリーをマッピングする。 未解決の決定はそれぞれ、それにぶら下がる決定に分岐します。
3. チケットと証拠で決まる部分を整理する。 未解決の決定すべてを決定ブリーフの5つのパートに沿って処理します。チケットに明確に記述されていることはそのまま記録し、証拠から選択肢が一意に定まるギャップはBeleg:行で記録します。それ以外はユーザーに委ねます（決定するか質問するか）。
4. 残ったすべての質問を、出す前にソースで再確認する（質問前の再確認）。ソースが既に答えている質問は、ユーザーに不必要な決定を強いることになります。
5. フロンティアを1ラウンドとして質問する。 フロンティアとは、前提条件が既に解決済みの未解決の決定群、つまりまだ聞いていない答えを推測せずに今質問できるものです。別の質問に依存し、その質問が同じラウンドで未解決のままのものは、後のラウンドに属します。
6. 各質問にブリーフを付けて提示する。 ブリーフはあなたの推奨で締めくくられるため、ユーザーは事実を確認しながら、コードを読んだりデザインを一から構成したりすることなく、ワンクリックで決定できます。
7. 各ラウンド後にフロンティアを再計算する。 解決された決定はフロンティアを外側に押し広げ、それに依存していた質問のブロックを解除し、多くの場合、質問を撤回させたり、証拠から十分に明確になって解決可能にしたりします。再確認し、次のラウンドを質問します。
8. フロンティアが空になったら停止する。 すべての分岐を訪問し、暗黙の前提が何も残っていない状態です。決定記録を作成し、ユーザーに確認させます。

決定するか質問するか

チケット（または審議対象の計画や仕様）は命令であり、優先されます。明確に記述されていることは、可能な限り正確に、書かれたとおりに実装します。チケットはしばしば不正確であったり、矛盾していたり、何かを忘れていたりします。それらのポイントが決定されるべき点です。ユーザーが行うべき決定は少なければ少ないほど良く、不明瞭なものはすべてユーザーのものです。決定ブリーフが線引きを行います。すべての未解決の決定について、誰かに質問する前にブリーフを作成し、その結果に基づいてポイントを3つのケースのいずれかに分類します。

1. チケットが明確に答えている場合：書かれたとおりに実装する。 そのポイントは解決済みとみなされ、[Ticket <ID>] とマークします。近隣の機能が異なる方法で実装されていたり、自分なら別の方法を選んだであろう場合でも同様です。誰にも質問しません。

2. チケットが不正確、矛盾している、または結果を見落としている場合：ユーザーが決定する。 表現が複数の解釈を許す場合や「完了」の意味が不明瞭な場合、説明・コメント・受入基準・デザインが一致しない場合、現在のコードに関する記述が実際のコードと異なる場合、または文字通りに実装するとチケットが言及していない何か（他の機能が依存する動作、セキュリティ、既存データ）を壊してしまう場合、ブリーフとともに質問します。チケットの意図はユーザーが決めることなので、自分が一方に傾いていたとしても、これらの質問はユーザーに委ねます。

3. チケットが何も言及していない場合：証拠が明白ならギャップを解決し、そうでなければ質問する。 以下の場合、自分で解決します。

• 別のソースが答えを示している（リンクされたドキュメント、デザイン、プロジェクトドキュメント）、またはコードがこの特定のケースをある確立された方法で処理している（path:line）、
• ソースやコード内に別の方向を示すものがない、
• 他の選択肢に合理的に高く評価できる利点がない、
• 長期的な影響がない（データモデル、マイグレーション、権限デフォルト、他のモジュールやチームが利用するコントラクト）。これらは、たとえ自分の推論に自信があっても、チケットが沈黙している場合は常にユーザーに委ねます。

解決したギャップは、証拠をBeleg:行に記載してAnnahmeとして記録します（決定記録）。ユーザーは記録を確認する際にこれを確認し、そこで覆すことができます。他のすべてのギャップはユーザーにブリーフとともに委ねます。また、自分が確信が持てないポイントもすべて同様に扱います。ポイントが明確かどうか疑わしい場合は、明確ではないということです。

質問前の再確認

ユーザーに届く質問は決定を委ねるものです。したがって、ラウンドを出す前に、ラウンドの質問を念頭に置いてソースに戻ります。最初の読み取りは要件を探すためのものでしたが、今回は特定の質問に対する答えを探すものであり、一般的な読み取りでは見逃すもの（コメントスレッドの奥深くにある返信、デザインの2つ目のフレーム、特定の方法でしか機能しない受入基準など）を見つけ出します。

1. ラウンドの質問を念頭に置いて、チケットをもう一度全文を読む。 説明、受入基準、すべてのコメントと返信（最新のものだけでなく）、およびそれら内の画像。
2. 各質問の用語について、他のソースを検索する。 ドイツ語と英語、および同義語（エンティティ、フィールド、ロール、画面、状態）を使用：親課題、サブ課題、リンクされた課題、添付ドキュメント、以前の決定コメントや質問ドキュメント、デザインのすべてのフレームと状態、フロー、プロジェクトドキュメント。
3. 既に確定していることから導き出せる答えを探す。 唯一の選択肢としか連携しない別の受入基準、この審議内で以前に下された決定、チケットが変更しないままにしている動作をすでに固定するテストやバリデーション。

次に、各質問を再度決定するか質問するかに従って分類します。チケットが明確に述べている答えは、書かれたとおりに解決します。別のソースにある答えは、Beleg:を付けてギャップを解決できます。再確認で明らかになった矛盾は、両方の引用を含めて、質問のまま残ります。生き残った質問だけがラウンドに入り、そのブリーフのパート3には再確認でカバーした内容が記載されるため、ユーザーは質問が本物であると認識できます。

決定ブリーフ

この順序で5つのパート。各パートは、このセッションで収集した証拠（ブランチ上の現在のコード、今日のソース）から回答します。

1. Ist-Stand im Code（コードの現状）：決定が着地する箇所の現在のコードの動作を、path:lineで示します。まだ存在しないものについては、その旨を述べ、どこを確認したかを示します。チケットが現在の動作をコードと異なる方法で説明している場合は、両方を記載します。そのギャップ自体がしばしば本当の質問です。
2. Geplante Änderung（計画された変更）：何が変更、追加、削除されるのか、どのように、そしてなぜか（それを要求する受入基準またはソース）。既に確定していることと、選択肢が解決する分岐点を区別します。
3. Ticket und Quellen（チケットとソース）：チケット、そのコメント、リンクされたチケットやドキュメント、デザイン、プロジェクトドキュメントがこの点について述べていること。チケットを最初に、„…“で正確に引用し、出典を括弧内に記載します（チケットとセクション、コメント日付、ドキュメントタイトル、Figmaノード、CLAUDE.md:<line>）。段落ではなく、意味のある一文を引用します。ソースが矛盾する場合は、各立場を引用します。どのソースもその点に言及していない場合は、その旨を述べ、再確認でカバーした内容を列挙します。その沈黙こそが質問である理由です。
4. Optionen（選択肢）：2～4つ。質問が提供するものと同じ選択肢。それぞれについて、具体的な意味、利点、欠点、影響（影響を受けるファイルとモジュール、既存データ、他のロールやコンシューマー、テスト、工数、後で元に戻すのが困難かどうか）を示します。フレームワークが既に提供しているオプションもその一つです。
5. Empfehlung（推奨）：あなたが選ぶオプションとその理由を、パート1～3から論じて示します。

各パートは1～3行に抑えてください。ブリーフは1つの決定のためのコンテキストであり、レポートではありません。ブリーフを作成すること自体が決定するか質問するかのテストでもあります。パート3でポイントに答える引用が見つかった場合、またはパート1でコードが既に決定していることが示された場合、そのポイントは解決済みとなり、ラウンドから外れます。

**F1 請求書の削除動作**

1. **Ist-Stand im Code:** `InvoiceService.delete()` は `deleteOne` でハード削除する（`projects/api/src/server/modules/invoice/invoice.service.ts:88`）が、現在どこからも呼び出されていない。 `Payment.invoice` は請求書を参照する（`payment.model.ts:31`）。プロジェクトには両方のパターンがある：`Order` は `deletedAt` によるソフト削除（`order.service.ts:54`）、`Customer` はハード削除（`customer.service.ts:71`）。
2. **Geplante Änderung:** 管理者は請求書リストに削除アクションを得る（AK 3）：新しいエンドポイント `DELETE /invoices/:id`、`InvoiceList.vue` のボタン。誰が削除できるかは確定している。未解決なのは、レコードがその際に消えるかどうか。
3. **Ticket und Quellen:**
   - 「管理者は誤った請求書を削除できるべきである。」（DEV-1234、説明）
   - 「削除は管理者のみ。」（DEV-1234、2026年10月2日コメント）
   - 削除された請求書が保持されるかどうかは、ソースは述べていない（確認済み：説明、3つのコメント、Figmaノード12:345、`docs/`）。
4. **Optionen:**
   - **A ソフト削除** `deletedAt` を使用、`Order` と同様。利点：履歴と `Payment` 参照が有効のまま。欠点：すべてのクエリにフィルターが必要。影響：モデル、サービス、3つのリストクエリが変更される。マイグレーションは不要、フィールドはオプション。
   - **B ハード削除**、`Customer` と同様。利点：追加フィールド不要、フィルター不要。欠点：請求書は完全に消失。影響：`Payment` 参照が無効になり、独自の処理が必要。
5. **Empfehlung:** A。なぜなら、支払いが請求書を参照しており、削除された請求書がなければ追跡不可能になるため。

チケットは沈黙しており、プロジェクトには両方の前例があり、選択はデータモデルを形成するため、このギャップはユーザーに委ねられます。説明に「削除された請求書は保存され、単に非表示になる」と書かれていれば、チケットはそれを解決していたでしょう。ソフト削除、書かれたとおりに実装、[Ticket DEV-1234] とマーク、質問なし。コメントが反対を要求していた場合は、矛盾が両方の引用とともにパート3の下でユーザーに委ねられていたでしょう。

ラウンド形式

AskUserQuestion を使用します。ラウンドごとに1回の呼び出し、最大4つの質問。各質問は推奨オプションを最初に、(Recommended) を接尾辞として付け、各オプションの説明には影響を1行で記載します。自動提供される「その他」エントリは自由記述の回答を受け付けます。フロンティアに4つ以上の質問がある場合、最も上流の質問から先に尋ねます。それらの回答によって、残りのいくつかが通常は解消されます。

ラウンドのブリーフは、呼び出しと同じメッセージ内で、その直前に、番号を付けて（F1、F2、…）配置します。これにより、ユーザーは質問を開いた状態でブリーフを読むことができます。

ユーザーだけが保持する事実（観察したこと、使用したアカウント）やワークフローの選択（レビューの実行、マージ方法）を収集するだけの質問にはブリーフは不要です。オプションのラベルに重要な情報が含まれます。

AskUserQuestion がない場合（プレーンチャット、非インタラクティブランナー）、同じ形式でラウンドを出力し、回答を待ちます。

事実 vs 決定

事実を見つけるのはあなたの仕事です。自分で読めたはずのことをユーザーに尋ねると、インタビューが尋問のように感じられます。そして、記憶から得られる回答はリポジトリにあるものよりも信頼性が低くなります。

自分で調べる	決定する（証拠から解決するか、質問する）
サービスが既に許可しているロール（@Restricted、@Roles、securityCheck）	許可すべきロール
エンティティ、DTO、生成型の現在の形状（types.gen.ts、sdk.gen.ts）	フィールドが追加、名前変更、または置換されるかどうか
エンドポイント、ページ、コンポーザブルが既に存在するかどうか	拡張するか、横に構築するか
チケット、そのコメント、リンクされたFigmaノードが実際に何を言っているか	チケットが曖昧な場合、その意味は何か
近隣の機能が同じ問題をどのように解決したか	この機能がその前例に従うべきかどうか
現在影響を受けるパスをカバーするテストはどれか	新しいテストはどのシームに配置すべきか
記述された欠陥がまだ再現するかどうか	代わりに正しい動作は何か

質問する前に、Read、Grep、Glob、Linear MCP、Figma MCPにアクセスしてください。ルックアップが広範囲に及ぶ場合は、サブエージェントにそれをディスパッチし、ブロックしないでください。実行中のルックアップは未解決の前提条件です。したがって、それに依存する質問だけが待機し、フロンティアの残りは今すぐ質問されます。

質問の質

• ハッピーパスではなく、エッジを探る。 空、null、非常に大きな値、同時実行、未承認、オフライン。ハッピーパスは誰もが既に同意している部分です。
• チケットを超えて存続する影響を表面化させる。 後でマイグレーションが困難なデータモデル、先例となる権限デフォルト、他のチームが利用するコントラクト。
• 新しいnest-serverプロジェクトは、このラウンドでデータベースを確定する。 チケットまたはルートの CLAUDE.md の ## Database セクションが名前を指定しない限り、データベースとSQLエンジンは質問です（どのチケットよりも長生きします）。generating-nest-servers→reference/choosing-a-database.md の手順に従ってブリーフを作成します。パート3のソースからのシグナル、パート5の決定ステップ。MySQL/MariaDB の場合、プロジェクトが何を放棄するかも含みます。独自のデータを持つ新しいモジュールは、質問なしでプロジェクトのデータベースに留まります。ソースが別のデータベース（ハイブリッド）を指している場合のみ、質問になります。確認された回答は決定記録と、ルートの CLAUDE.md の ## Database として記載されます。
• 実装がそれ以外で停止するものをカバーする。 クローズする前に、計画された作業を頭の中で一度ウォークスルーします（モデル、エンドポイント、権限、UI状態、テスト）。そして、そうしなければ一時停止するであろうすべてのポイントを決定するか質問するかにかけます。これにより、その後の実行が質問のないものになります。

ユーザーに連絡が取れない場合

不明確な決定はユーザーに属するため、ブロッキングな決定が代理で答えられることはありません

…

[翻訳のため省略]