grill-with-docs

ドキュメントを使ったグリル

対話を通じて依頼された計画を徹底的に検証し、合意したドメイン用語と長期的な決定事項をプロジェクトのドキュメントに記録します。

ローカルのガイダンスを読み込む

質問と決定事項の依存関係には grilling スキルを、用語とアーキテクチャ記録には domain-modeling スキルを、利用可能な場合に使用します。利用可能なスキルカタログから、このリポジトリに属するスキルを探し、提示された場所または読み込み方法を使ってください。兄弟ディレクトリを推測しないでください。どちらかのスキルを利用できない場合は、以下の手順を組み合わせて進めてください。外部のスキルを取得したり、代わりに使用したりしないでください。

ドキュメントの対象範囲を定める

このワークフローを使用する依頼には、ユーザーが決定事項を固めるのに合わせて、ローカルの用語集とアーキテクチャ決定記録を更新することも含まれます。これらのドキュメント作成ルールは、補助スキルを使用する場合にも適用されます。読み取り専用モードまたは編集案の提示のみを行うモードでは、提案する文章を会話内にとどめ、ファイルを作成・編集しないでください。ユーザーが書き込み対象を特定のドキュメントに限定した場合は、そのドキュメントのみを更新し、その他の記録案は会話内にとどめてください。

既存の用語集、コンテキストマップ、関連する ADR、および議論の根拠となる範囲のコードのみを確認します。既存のドキュメントの配置場所と形式に従ってください。慣例がない場合は、ドメイン用語には CONTEXT.md を、該当する決定事項には docs/adr/ を使用します。記録する内容について合意が得られた場合にのみ、ファイルを作成してください。

質問し、解決し、記録する

1. ユーザーが解決したい決定事項を明確にし、すでに得られた回答を再利用します。前提条件が確定している質問をし、重要なトレードオフを説明します。根拠がある場合は回答を推奨します。入力情報が判明するまで、依存する質問は保留します。
2. ユーザーに調べれば分かる情報の提供を求めるのではなく、利用可能なコードとドキュメントから事実を確認します。検証済みの動作、変更案、未解決の仮定を区別します。プロダクトの意味とトレードオフを決めるのはユーザーです。推奨や未回答の質問は合意ではありません。
3. 各回答のラウンド後に、意味を変えうる曖昧さや矛盾がないか確認します。その矛盾を解消するのに必要な確認のみを行います。明確な回答は、記録のためだけに再確認を求めず、合意として扱います。
4. 合意した結果を以下のルールに従って記録し、続いて、それによって判断可能になった質問に進みます。回答によって以前の決定が変更された場合は、議論とドキュメントの内容が一致するよう、影響を受ける記録を更新します。

記録する内容

• ドメイン用語： プロジェクト固有の概念が確定したら、その意味と誤解を招く類義語を、該当する用語集に記録します。実装上の選択、未解決の質問、会話履歴は含めないでください。既存の用語集の形式が定められていない場合は、domain-modeling スキルが利用可能であれば、その形式のガイダンスに従います。利用できない場合は、簡潔な定義と避けるべき用語を記載すれば十分です。
• アーキテクチャ上の決定： 変更を撤回するコストが大きく、そう決めた理由がなければ不明瞭になり、実際のトレードオフを解決するか、外部制約によって明白な選択肢が排除された場合に、確定した選択を記録します。決定内容、選択した理由、記録に残す価値のある重要な影響や却下した代替案を含めてください。既存の ADR 形式が定められていない場合は、domain-modeling スキルが利用可能であれば、その形式のガイダンスに従います。利用できない場合は、短いタイトルと選択内容および理由を説明する段落で十分です。回答すべてについて ADR を作成しないでください。
• その他の回答： 定型的な選択、暫定的な提案、未解決の質問は、ユーザーが別の記録先を指定していない限り、会話内にとどめます。自動的に用語集の定義、承認済み ADR、仕様、トラッカーの課題に変換しないでください。

ドキュメントを変更するたびに内容を読み返し、ユーザーの意図が保たれ、推測が合意済みの要件として扱われていないことを確認してください。既存のドキュメント作成権限の範囲内で作業を続けてください。提案する書き込みがその権限を超える場合に限り、再度確認してください。

完了

依頼された決定に必要な重要事項が確定または明示的に保留されるか、ユーザーが議論を中断した時点で完了とします。確定した結論、残る重要な質問、変更したドキュメントを報告してください。読み取り専用モードまたは編集案の提示モードでは、提案するテキストとその配置先を示し、保存したと主張しないでください。

設計への合意と記録の許可は、実装、コミット、プッシュ、外部公開を許可するものではありません。そうした作業を続けるのは、ユーザーが許可した場合に限ります。