documentation-and-adrs

记录架构决策与必要文档，保存设计背景与权衡。

把重要的架构选择和设计背景写清楚，不只是记录代码还交代为什么这么做、有哪些权衡与备选方案。用在做架构决策、改公共 API、发布新功能或需要给未来同事/agent留上下文时。特别之处是聚焦“为什么”和“取舍”，让后来者少走弯路并能看懂设计来龙去脉。

# 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