expectations

学びを記録する際の指針

各発見を、その真実を担う成果物に記録してください。あるプロジェクトのアーキテクチャ、デリバリープロセス、ツールの慣習を、普遍的な指針にしてはいけません。

再利用可能な原則か、ローカルポリシーか？

• 再利用可能な原則 — あるリポジトリ固有の名前、パス、ツール、リリースプロセスに依存せず、複数のプロジェクトに適用できます。関連するグローバルスキルを改善してください。
• ローカルポリシー — このプロダクトのドメイン、アーキテクチャ、リスク許容度、ワークフロー、インフラに依存します。リポジトリのエージェント向けガイダンス、またはプロジェクトの正式なドキュメントに記録してください。

迷った場合は、範囲の狭いローカルな更新を選んでください。再利用可能な原則とするには、複数のプロジェクトから得られた証拠が必要です。1つの成功した実装から推測してはいけません。

ドキュメントの枠組み

重要な変更が終わるたびに、「最初に知っておきたかったことは何か？」と問いかけてください。

次のいずれかに当てはまる学びを記録してください。

• 今後の開発者の時間を大幅に節約できる
• 一連のバグやエラーを防げる
• 見落としやすい挙動や制約が明らかになる
• アーキテクチャ上の根拠やトレードオフを記録できる
• ドメイン固有の知識を記録できる
• 効果的なパターンやアンチパターンを特定できる
• ツールのセットアップや設定に関する落とし穴を明確にできる

リポジトリにすでに記録されている内容、つまり現在のコード構造、Git の履歴、ソースコードやテストから明らかな挙動を重複して記載しないでください。

記録する学びの種類

• 落とし穴：発見した予期しない挙動（例：「API は空の配列ではなく null を返す」）
• パターン：特にうまく機能したアプローチ
• アンチパターン：有効に思えたものの、問題を引き起こしたアプローチ
• 決定事項：根拠とトレードオフを伴うアーキテクチャ上の選択
• エッジケース：特別な処理が必要だった、見落としやすい状況
• ツールに関する知識：セットアップ、設定、使用方法に関する知見

学びの記録先

学び	記録先	理由
1つのリポジトリを超える証拠に裏付けられた、プロジェクト横断の実践	関連するグローバルスキル	再利用可能なガイダンスを、プロバイダーやプロジェクトに依存しないものに保てます
プロジェクト固有のアーキテクチャ、デリバリールール、ツールのセットアップ、または落とし穴	リポジトリのエージェント向けガイダンス、またはプロジェクトの正式なドキュメント	ローカルポリシーを、それを担うプロジェクトに置けます
ドメイン用語、定義、別名、命名規則	所有する境界づけられたコンテキストの正式な用語集	用語の権威を、1つのコンテキストに限定できます
承認済みのアーキテクチャ、依存関係、プラットフォーム、または自作と採用の決定	リポジトリで定められた ADR の保存先	永続的な決定に、その根拠と却下した選択肢を残せます
観測可能な動作上の制約またはリグレッション	ソースコードと実行可能なテスト	維持される動作によってルールを立証できます
進行中のブロッカー、作業の順序に関する選択、またはスコープの変更	現在のステータス成果物、または進行中の計画	一時的なデリバリー情報は、その作業とともに役目を終えます
ユーザー向けの挙動、セットアップ、API の使用方法、または運用	維持管理されているプロダクト、パッケージ、または運用ドキュメント	読者が情報を担う場所で最新の情報を確認できます

一時的な成果物から長期的に有効な制約が明らかになった場合は、その成果物を削除する前に、制約を適切な記録先へ移してください。Git の履歴はアーカイブとして残ります。

ドキュメントの形式

#### Gotcha: [Descriptive Title]

**Context**: When this occurs
**Issue**: What goes wrong
**Solution**: How to handle it

// CORRECT - Solution
const example = "correct approach";

// WRONG - What causes the problem
const wrong = "incorrect approach";

項目はざっと読めるようにしてください。後から読む人が、10秒以内に背景、課題、解決策を把握できるようにします。

コミュニケーション

• アプローチごとのトレードオフを明確にする
• 重要な設計上の決定について、その根拠を説明する
• ガイドラインから逸脱する場合は、その理由を添えて明示する
• これらの原則に沿った改善を提案する
• 判断に迷った場合は、推測せずに確認を求める
• 推奨事項が再利用可能な原則なのか、ローカルポリシーなのかを明示する