修改有多个实现的单一代码库，并让各实现保持一致

## 修改前，先弄清单一代码库的结构和本地规则 - 按产品、语言、功能领域、共享工具区域、测试套件、发布工具和配置梳理代码库。 - 确定哪些目录属于各个实现，以及哪些顶层规则适用于整个代码库。 - 编辑嵌套区域前，阅读其局部智能体指南、贡献指南和配置；局部规则可以细化基准，但不得削弱基准。 - 特定语言的构建、样式和测试规则只能应用于用该语言编写的代码。 - 选择命令或依赖项前，找到工作区定义、根级脚本和产品专用说明。 ## 把用户可见的改动同步到每个实现 - 将同一用户产品的并行实现视为地位相等的唯一事实来源。 - 只要可能，就在同一变更请求中把每项用户可见的更改同步到所有实现。 - 用户可见行为包括标志、默认值、环境处理、错误码与错误消息、工具使用的日志、文件和状态格式、存储布局及钩子语义。 - 内部重构、仅影响实现内部的性能工作，以及特定实现的测试清理，不需要人为镜像到其他实现。 - 如果无法立即完成等效工作，应准确说明对等差距、差距保留的原因，以及合并前必须完成的工作。 - 绝不能让某个实现成为另一实现未注明的下游移植版本。 ## 重新构建测试实际运行的产物，避免测到旧代码 - 信任测试结果前，通过代码库规定的初始化路径安装依赖项并完成编译。 - 在快速迭代期间，如果仅编译受影响的软件包就能生成所选测试实际使用的相同产物，可以只编译该软件包。 - 确认端到端测试执行的是源代码产物、软件包产物，还是捆绑后的可执行文件。 - 如果端到端测试使用捆绑产物，每当其组成软件包发生更改后都要重新构建捆绑产物；否则测试可能运行过时代码。 - 对每个已更改实现执行对应语言的适当构建。 - 对过时生成产物执行并通过的测试不能作为有效证据。 ## 只测试受影响的部分，并查清每项失败 - 默认不得运行大型代码库的整个测试套件。应从受影响的项目、文件或命名测试用例开始。 - 只有依赖关系、共享契约或观测到的失败证明有必要时，才扩大测试范围。 - 使受测运行环境、构建产物和实现与待验证的主张相匹配。 - 调查每项失败，不得在没有证据时将其归为无关问题或既有问题。 - 如果失败在更改前就已存在，应找出原因，并在授权范围内修复或报告具体阻碍；绝不能悄然跳过。 - 记录准确的命令、受影响目标和结果，使其他贡献者能够复现证据。 ## 先看安全、再看性能，评审已更改的代码 - 遵循代码库的评审指南，并将发现限定在受更改影响的代码及其直接后果。 - 除非项目规则有更严格的要求，否则先评审安全性，再评审性能。 - 对于安全问题，应说明可到达的输入、信任边界、利用路径和影响。 - 对于性能问题，应指出热点路径、发生频率、分配或I/O成本，以及可能产生的用户影响。 - 将测试、发布意图和跨实现行为对等验证纳入验收。 - 不得提出无法与已更改行为建立联系的推测性问题。 ## 添加代码或依赖项前，先找现有的 - 实现非简单逻辑前，搜索共享软件包、文件系统辅助工具、密码学工具、文本工具和邻近领域模块。 - 如果已有导出的工具拥有所需行为，应复用该工具。 - 如果相似逻辑被限制在某个软件包中，应把共同契约提取到范围最窄且合适的共享位置，而不是复制逻辑。 - 对于常见功能，如果现有依赖项适用、足够轻量且代码库策略允许，应优先使用维护良好的现有依赖项。 - 将新依赖项添加到需要它的最具体软件包中；只有多个软件包确实共享时才将其上移。 - 不得添加只为现有操作改名或转发、却没有增加任何契约的包装层。 ## 遵守提交信息规则，不绕过提交钩子 - 使用代码库规定的提交消息约定，并选择能反映用户影响的变更类型。 - 提交前，确认代码库钩子已经安装并处于启用状态；新检出的工作副本可能尚未注册钩子。 - 绝不能绕过失败的提交守卫、禁用钩子或添加抑制文件。应修正根本的消息或更改。 - 避免只写数字的问题引用，因为托管平台可能把它链接到错误的代码库；应使用包含代码库的限定引用或绝对URL。 - 将类似用户名的代码标识符放入行内代码格式，或移除不必要的提及，避免一次提交通知无关人员。 - 枚举项目时，使用不带引用标记的列表编号。 ## 已发布的软件包有改动时，添加发布记录 - 只要更改影响已发布软件包，就必须添加发布意图条目。 - 列出每个受影响软件包，并从缺陷修复、向后兼容功能或破坏性更改中选择版本影响。 - 面向用户简洁编写该条目；将实现理由写在提交消息中。 - 当代码库策略要求时，对主要实现的更改还应包含主命令行软件包。 - 对于特定实现的更改，只列出实际发生变化的产品。对等更改必须列出每个受影响实现的软件包。 - 遵守稳定版和预发布版发布通道、固定版本组及代码库的正式晋级流程。 ## 注释只写代码本身说明不了的理由 - 优先使用名称、类型、辅助函数边界和控制流，让代码自身说明含义。 - 不得添加重复描述操作、复述被调用方文档或讲解明显语法的注释。 - 在共同所有者处记录一次共享理由，不要在每个调用位置重复。 - 使用文档注释说明前置条件、后置条件、边界情况和不明显的保证。 - 将重构历史和已移除设计的说明保留在版本控制历史及变更消息中，不要写入当前源代码注释。 - 添加说明文字前，先判断重命名、调整结构或提取是否能更可靠地表达该概念。 ## 按代码库的格式和错误处理规则写代码 - 使用代码库的格式化工具和特定语言的样式指南；保持既有的导入分组和顺序。 - 如果代码库惯例如此，应优先使用函数而不是有状态类，并用带类型的选项对象替代过长的参数列表。 - 对用户可触发的失败使用稳定的领域错误类型，保留错误码，包含相关上下文，并且绝不能吞掉意外错误。 - 只捕获预期的错误条件，并在虚拟化测试环境中使用跨上下文安全的原生错误检查。 - 函数名称使用动词，保持术语一致；概念的契约发生变化时，在所有位置同步重命名。 - 对简单解析使用简单字符串操作；对于需要回溯的语法，使用现有结构化解析器。 - 让可配置值通过配置层传递，使命令处理器独立于表现层，并避免硬编码策略。 - 使用异步I/O，并发执行彼此独立的操作，等待必须完成的操作，并把循环中的不变量工作移到循环外。 ## 让变更请求在合并前始终与实际改动一致 - 使用代码库模板创建变更请求，保留必填部分，只移除模板明确标为可选的内容。 - 每次重大更新后，使标题和说明与实际更改保持同步。 - 对已处理的评审对话，先回复解决方式和支持该结论的修订，再将对话标记为已解决。 - 根据代码库策略标记由智能体编写的远程内容，同时不得暴露敏感的实现上下文。 - 使用代码库批准的冲突解决流程，确保基准分支最新、生成的锁定数据以确定性方式重新构建，并验证可合并性。 - 手动检查非生成文件中的冲突。任何强制更新或其他远程历史重写都必须获得明确授权，并确认目标无误。