expectations

Expectations：捕获学习成果

把每一项发现路由到拥有其真相的产物中。不要把某一个项目的架构、交付流程或工具约定变成通用指导。

可复用原则还是局部策略？

• 可复用原则 —— 不依赖某个仓库的名称、路径、工具或发布流程，可跨项目适用。应改进相应的全局技能。
• 局部策略 —— 依赖本产品的领域、架构、风险姿态、工作流或基础设施。应记录在仓库的智能体指引或权威项目文档中。

拿不准时，做范围更窄的局部更新。复用应当由来自多个项目的证据赢得，而不是从一次成功实现中推断出来。

文档框架

在每次重要变更结束时，问一句：「如果一开始就知道，我会希望知道什么？」

只要满足以下任意一条，就应捕获该项学习：

• 能为未来的开发者节省大量时间
• 能预防某一类 bug 或错误
• 揭示非显而易见的行为或约束
• 记录架构理由或权衡
• 记录领域特定知识
• 识别出有效的模式或反模式
• 澄清工具设置或配置陷阱

不要重复记录仓库已经记录的内容：当前代码结构、Git 历史，或从源码和测试中显而易见的行为。

值得捕获的学习类型

• 陷阱（Gotchas）：发现的反常行为（例如「API 返回 null 而不是空数组」）
• 模式（Patterns）：效果特别好的做法
• 反模式（Anti-patterns）：看似不错但引发问题的做法
• 决策（Decisions）：带理由与权衡的架构选择
• 边界情况（Edge cases）：需要特殊处理的非显而易见场景
• 工具知识（Tool knowledge）：设置、配置或使用方面的洞见

每项学习应去往何处

学习内容	目的地	原因
有超越单个仓库证据的跨项目实践	相关的全局技能	可复用指引应保持与提供方和项目无关
项目特定的架构、交付规则、工具设置或陷阱	仓库智能体指引或权威项目文档	局部策略应与其所属项目留在一起
领域术语、定义、别名或命名规则	所属限界上下文的权威术语表	词汇在其上下文范围内只有一处权威
已接受的架构、依赖、平台或「自建还是采用」决策	仓库的已接受 ADR 位置	持久决策保留理由和被否决的备选方案
可观察的行为约束或回归	源码与可执行测试	被维护的行为证明了规则
进行中的阻塞、排序选择或范围变更	当前状态产物或活动计划	临时交付知识随工作结束而失效
面向用户的行为、设置、API 用法或运维	受维护的产品、包或运维文档	读者在所属界面上找到当前真相

如果某个临时产物揭示了一条持久约束，应在删除该产物前把约束提升到其归属地。Git 历史仍是归档。

文档格式

#### Gotcha: [描述性标题]

**Context**: 何时发生
**Issue**: 出了什么问题
**Solution**: 如何处理

// CORRECT - 解决方案
const example = "correct approach";

// WRONG - 导致问题的做法
const wrong = "incorrect approach";

保持条目易于扫读：未来的读者应能在十秒内把握上下文、问题和解决方案。

沟通

• 明确说明不同做法之间的权衡
• 解释重要设计决策背后的理由
• 对偏离指引之处加以说明并给出理由
• 提出符合这些原则的改进建议
• 不确定时，请求澄清而不是假设
• 明确说明某条建议是可复用原则还是局部策略