documentation-and-adrs

记录架构决策与关键上下文，保存为何这样实现的理由。

把重要的架构决策和关键背景写清楚（比如 ADRs），记录为什么这么做、有哪些权衡和备选方案。每次改 API、上线功能或做重要设计时都该写，方便未来工程师和审查者快速理解来龙去脉。重点不是复述代码，而是保存决策的理由，省去日后反复问询。

# Documentation and ADRs

## Overview

Document decisions, not just code. The most valuable documentation captures the *why* — the context, constraints, and trade-offs that led to a decision. Code shows *what* was built; documentation explains *why it was built this way* and *what alternatives were considered*. This context is essential for future humans and agents working in the codebase.

## When to Use

- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeate