expectations

经验总结：记录学到的内容

将每项发现记录到其事实来源所属的文档中。不要把某个项目的架构、交付流程或工具约定变成通用指南。

可复用原则还是本地策略？

• 可复用原则 — 不依赖某个仓库的名称、路径、工具或发布流程，可适用于多个项目。完善相关的全局技能。
• 本地策略 — 取决于该产品的领域、架构、风险取向、工作流或基础设施。将其记录在仓库的 Agent 指南或项目权威文档中。

如有疑问，选择范围更窄的本地更新。只有在多个项目中都有证据，才值得复用；不要仅凭一次成功的实现就推断可以复用。

文档框架

每次重大变更结束时，都要问：“我希望一开始就知道什么？”

出现以下任一情况时，记录经验：

• 能为后续开发者节省大量时间
• 能防止某类 Bug 或错误
• 揭示了不明显的行为或限制
• 记录了架构考量或权衡
• 记录了特定领域的知识
• 指出了有效模式或反模式
• 说明了工具设置或配置方面的注意事项

不要重复记录仓库已有的信息：当前代码结构、Git 历史，或从源代码和测试中一目了然的行为。

要记录的经验类型

• 注意事项：发现的意外行为（例如：“API 返回 null，而不是空数组”）
• 模式：特别有效的方法
• 反模式：看似不错但实际造成问题的方法
• 决策：有理由和权衡依据的架构选择
• 边界情况：需要特殊处理的不明显场景
• 工具知识：设置、配置或使用方面的经验

各类经验的记录位置

经验	目标位置	原因
有多个仓库佐证的跨项目实践	相关的全局技能	可复用指南应与提供方和项目无关
项目特定的架构、交付规则、工具设置或注意事项	仓库的 Agent 指南或项目权威文档	本地策略应归属于负责该策略的项目
领域术语、定义、别名或命名规则	所属限界上下文的权威术语表	词汇应由一个上下文范围内的权威来源统一维护
已采纳的架构、依赖、平台或自建与采用决策	仓库中存放已采纳 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";

保持条目易于浏览：未来的读者应能在十秒内了解背景、问题和解决方案。

沟通

• 明确说明不同方案之间的权衡
• 解释重大设计决策背后的理由
• 如有偏离指南的情况，应说明理由
• 提出符合这些原则的改进建议
• 不确定时，应询问澄清，而不是擅自假设
• 明确说明一项建议属于可复用原则还是本地策略