project-knowledge

プロジェクト用語

プロジェクト用語の曖昧さを解消し、確定した決定を記録して、今後の作業で同じ用語を使い、同じトレードオフを何度も検討し直さずに済むようにします。

用語を確定する

GLOSSARY.md が存在する場合は、読みます。

• 曖昧な用語、複数の意味を持つ用語、またはプロジェクト内で解釈が異なる用語について、ユーザーと確認して解決します。
• ドメイン概念間の不明確な関係を、具体的なエッジケースのシナリオを使って検証します。
• 用語が確定したら、必要に応じて GLOSSARY.md を作成し、用語集テンプレートを使って直ちに更新します。
• GLOSSARY.md には、プロジェクト用語とその現在の定義のみを記載します。

決定を記録する

docs/decisions/README.md が存在する場合は、それを読み、現在の作業に関連する対象ファイルのみを読み込みます。

プロジェクトの決定を記録するのは、次のすべてを満たす場合に限ります。

1. 確定済み：その選択肢が提案段階ではなくなっていること。ユーザーが結果を確認したか、この種の決定についてユーザーから明示的に委任された権限のもとで選ばれている必要があります。
2. 再利用可能：今後の作業でも同じ問いに直面する可能性が高く、再検討の条件に該当しない限り、この回答を再利用すべきであること。
3. 自明ではない：根拠がなければ、今後の作業でその問いが再び持ち出されたり、別の選択肢が合理的に選ばれたりする可能性があること。
4. 実際のトレードオフがある：妥当な代替案が存在し、却下した理由を記録することで、同じ評価の繰り返しを防げること。

選択が意図的なものだったと判断する前に、その証拠を求めます。実装されていることや、異議がなかったことだけでは不十分です。

条件を満たす決定ごとに、決定記録テンプレートを使って、docs/decisions/ にある該当する対象ファイルを作成または更新します。元の分析を繰り返さずに今後の作業で決定を適用できるよう、必要な背景情報だけを残します。

デザインのエントリーを最新に保つ

ルートの DESIGN.md は、プロジェクトの価値観、使用中の共有コンポーネント、却下された UI パターン、各表示要素とその要素を管理する判断契約との対応を示すマップなど、デザイン作業の出発点です。あらゆるルールの根拠は契約に置きます。DESIGN.md は契約への参照のみを記載するため、ルールの文面、根拠、しきい値を転記しないでください。

画面契約では、画面上の見た目や動作を決めます。たとえば、色、テキストの役割、余白、アイコン、コンポーネント、コピー、読み込み状態、無効状態、エラー状態、シート、トースト、ヘッダーの動作などです。リポジトリの仕組み、データの所有権、レビューのプロセス、デプロイに関する契約は画面契約ではないため、DESIGN.md には記載しません。UI レビューの基準を定める契約は、却下されたパターンのリンク先にはできますが、マップの要素にはなりません。

画面契約を作成するとき、その契約が対象とする要素を変更するとき、または画面契約や UI レビュー基準の契約で却下される UI パターンを追加・削除するときは、同じ変更内で デザインエントリーテンプレートを使って DESIGN.md を更新します。

• 契約が管理する各要素について、マップの行を追加、修正、または削除します。
• 契約が却下する各パターンについて、エージェントが UI コードに記述する可能性のあるものなら、却下パターンの行を追加または削除します。ルールを lint で適用するといったプロセス上の代替策は、契約にのみ記載します。
• 画面を実装またはレビューする作業では、まず DESIGN.md を読むように、両方のエージェントクライアントに伝えてください。その行を AGENTS.md に記載し、ファイルがない場合は作成します。また、CLAUDE.md が存在し、AGENTS.md をすでに読み込んでいない場合は、そこにも記載します。同じ意味の行がすでにあるファイルは変更しません。

DESIGN.md がまだ存在しない場合は、その時点で作成します。

• 現在の契約だけでなく、判断インデックスにあるすべての既存の画面契約をマップし、それぞれの却下された UI パターンを記載します。
• プロジェクトのトークンソースと共有コンポーネントディレクトリから、価値観と共有コンポーネントをそれぞれ一度だけ転記し、各セクションでソースのパスを明記します。ソースが存在しないセクションは省略します。

作成後は、名前が記されたソースを変更する作業に任せるため、価値観とコンポーネントのセクションには手を加えません。既存の DESIGN.md が別のレイアウトを使っている場合は、書式を変更せず、既存の記載箇所に行を追加します。画面契約がないプロジェクトには DESIGN.md は必要ありません。

フォローアップを記録する

このセッションで適用した回避策が一時的で、根本原因が未解決のままの場合、またはスコープ外の不具合やその原因と疑われるものを根拠とともに確認した場合は、フォローアップを記録します。セッション内で解決した作業、根拠のない推測、現在の変更ですでに修正した不具合は対象外です。

対象となる各項目は、発見した時点で フォローアップテンプレートを使い、症状にちなんだスラッグを付けて、それぞれ独立した docs/follow-ups/<slug>.md に記録します。後のセッションで、この会話を参照せずに対応できる内容にしてください。発見したことを会話で報告するだけでは、記録として残りません。

フォローアップに記録するのは未解決の問いであり、確定した判断ではありません。そのため、結果が独自の経緯で確定するまでは GLOSSARY.md や判断契約に追加しません。作業がリリースされたとき、または項目が仕様フォルダーに昇格したときは、ファイルを削除します。

プロジェクトの事実を守る

• コードがユーザーの発言、GLOSSARY.md、または関連する判断契約と矛盾している場合、黙って一方を選ぶのではなく、不一致を明示します。コードから現在の動作は分かりますが、その動作が意図的かどうかは分かりません。
• コードに合わせてドキュメントを更新するよう求められても、それだけでコードから推測される判断が確定したことにはなりません。
• 確定した判断について関連する情報源同士が食い違っている場合、意図が明示的に確認されるまでは、プロジェクトのナレッジを変更しません。
• 用語や判断が保持されたとみなすのは、対象のファイルが更新された後だけです。