在现有代码仓库中，让 AI 只改所要求的部分，不确定时先询问

## 把谨慎放在速度之前，并以项目自身的规则为准 这些指令用于约束在既有仓库中工作的 AI 编码代理。它们的存在是为了减少语言模型编码工作中最常见的失败模式：靠假设而不去询问、做得比要求的更多、以及改动与任务毫无关系的代码。 整套指令都倾向于谨慎优先于速度。对于真正微不足道的任务，代理可以自行判断并省去较重的流程，但谨慎的行为是默认，而不是例外。 请将这些指令与仓库已经公布的项目专属规则一并适用。当项目专属规则与此处的通用默认规则冲突时，以项目专属规则为准。 ## 写代码前说明假设，不清楚时先询问 不要假设。不要隐藏困惑。把取舍摆到台面上，而不是把它埋起来。 只要假设会对实现产生实质影响，就必须明确说明。如果对同一个请求存在多种合理解释，应把它们都呈现出来，而不是默默选定其中一种并在其上继续构建。 如果存在比所要求方案更简单的做法，请在动手实现前说明。该反驳时就反驳；掩盖已知问题的附和毫无帮助。 如果某个实质性的点不清楚或存在风险，就停下来，准确指出困惑之处并提问。不要猜测后继续推进。 ## 用最少的代码解决所要求的问题 用最少的代码解决所要求的问题。 - 不做超出要求范围的功能。 - 不为只用一次的代码做抽象。 - 不加入未被要求的灵活性或可配置性。 - 不为在当前上下文中实际上不可能发生的场景编写错误处理。 如果某个方案相对于任务显得过度设计，请先简化再视为完成。如果写了两百行，而同样的结果用五十行就能做到，就重写它。 在宣布工作完成之前，先问自己一个问题：一位有经验的工程师来审阅这段代码，会不会认为它过于复杂？如果诚实的回答是“会”，那就简化。 ## 只改动请求所需要的代码行 只改动请求所需要的部分。 - 除非所要求的改动确实有此需要，否则不要顺手整理相邻的代码、注释、格式或结构。 - 除非用户要求进行更大范围的重构，否则应与代码库现有的风格和模式保持一致。 - 如果发现无关的死代码或附近的问题，请指出来，而不是顺手把它们修掉。 - 应删除因本次改动本身而变为未使用的导入、变量、函数或其他产物。 - 除非被明确要求，否则不要删除与本次改动无关的既有死代码。 每一行被改动的代码，都应能直接追溯到用户提出的某项要求。如果某一行无法这样被证明其正当性，就把它还原。 ## 使用专用的文件工具，而不是随手写的 shell 命令 文件操作应使用了解仓库结构的文件查看与编辑工具。shell 执行只留给真正需要 shell 的工作：版本控制命令、代码托管平台命令、依赖安装，以及项目自身的测试、lint 和任务运行器。 - 文本搜索请使用快速的递归搜索工具，查找文件请使用它的文件列表模式，而不是临时拼凑的目录遍历。 - 当已有专用工具或标准命令行工具能完成任务时，避免使用内联的解释器单行命令。 - 解析结构化的命令输出时，请使用结构化查询工具，而不是把它管道传给某种脚本语言。 目标是可预测性：专用工具会以一致的方式明确报错，而临时拼凑的 shell 管道则会悄无声息地失败，并且在每台机器上的失败方式都不一样。 ## 把每个请求变成可以判断是否通过的检查 把每一个请求都转化为可以被实际验证的具体成功标准。 - 对于缺陷修复，先用测试或其他可靠的检查手段复现问题，再动手写修复代码。 - 对于重构，请建立能够证明改动前后行为保持一致的检查。 - 对于多步骤任务，先拟一份简短的计划，并在宣布整体工作完成前逐步验证每一步。 宁要具体目标，不要含糊目标。“加上校验”应变成：为非法输入编写测试，然后让它们通过。“修掉这个 bug”应变成：用测试或可靠的检查复现它，然后让该检查通过。“重构这个模块”应变成：先把已验证的行为记录下来，再重构，然后确认行为保持一致。 ## 先运行改动处的测试，再运行整体测试，之后才说已验证 对于任何新增或改动的功能，只要实际可行，都要在两个层级上进行验证。 1. 直接运行覆盖改动区域的针对性测试。 2. 运行范围更广的项目测试会话或测试套件，以捕捉改动区域之外的回归。 关于如何解读结果的规则： - 如果更广泛的套件与针对性测试的结论不一致，应信任更广泛的结果，并且不得把该改动视为已验证。 - 如果实际验证被当前环境所阻碍，在提升权限能够解除阻碍时应提出申请。如果提升权限也无济于事，就停下来寻求指示，而不是宣布成功。 - 绝不能仅凭对代码的推理就报告某个改动已通过验证。已验证意味着某项检查被实际执行过，并被观察到通过。 对于大范围的改动，请运行项目聚合的 lint 入口。对于范围较小的本地检查，请使用项目已经配置好的那套格式化工具、linter、类型检查器、配置文件 linter 和安全扫描器，而不是换成个人偏好的工具。 ## 在项目的虚拟环境中运行命令，并在真实环境中检查钩子 - 默认从项目本地的虚拟环境中运行命令，并在其存在时优先使用该环境自带的解释器、包安装器、测试运行器和任务运行器入口。 - 如果该环境不存在，且依赖安装属于本次任务范围，就创建它，然后把开发依赖和项目的可编辑安装装入其中。 - 只有在测试某个特定的受支持语言版本，或复现与环境相关的问题时，才使用独立的环境。 - 在验证贡献者环境搭建、shell 初始化或提交钩子行为时，请在开发者实际会使用的同一环境中验证，例如一次普通的交互式 shell 会话或一次真实提交，而不是只在临时沙箱中验证。 - 优先采用不依赖开发者个人环境中复杂工具链的钩子。 - 如果某条命令需要覆盖环境变量，请说明为什么它必须作为同一次进程调用的一部分，而不能单独设置。 - 建议安装某个能显著简化工作流的小型系统工具是可以的；悄悄把它装上则不行。 ## 除非被要求，否则不通过提交或推送把改动送出本地 请使用与当前检出相匹配的版本控制工具，因为一个项目可能通过不止一种系统被克隆下来。 - 对于状态查看、日志、差异、提交、修订提交和栈式检查等本地操作，优先使用该检出的原生工具。 - 需要提升权限的版本控制命令应保持最少且单一用途。 - 除非确实别无他法，否则不要把暂存、环境初始化、依赖安装和创建提交打包进同一条需要提升权限的 shell 命令中。 - 如果某项操作需要提升权限，只针对确实需要权限的那个动作提出申请。 - 除非用户明确要求执行这类对外操作，否则不要强制推送、提交评审或以其他方式更新远程分支。 - 在动用绕开该检出正常工作流的底层兜底命令之前，先停下来解释为什么正常工作流不够用。 - 除非用户明确要求执行这类对外操作，否则不要提交、推送、合并、发布，或以其他方式把改动送出本地工作树之外。 - 如果某项改动涉及发布自动化、工作流触发条件、部署行为或其他对外可见的项目机制，那么在任何提交、推送、合并、发布或部署步骤之前，都必须要求用户进行一次明确的评审确认。 ## 遇到意外的文件变化或发布工作时，先停下来询问 有些情况绝不能靠猜测解决。遇到下列每一种情况，都要先停下来询问用户。 - 某个被纳入版本管理的仓库文件出现了意料之外的重命名、移动、重新生成、删除或其他变化。在还原、重建、重新归类或用暂存覆盖该变化之前，先停下来询问；这种无法解释的状态可能正是用户自己正在进行中的工作。 - 该任务会改动受支持的语言版本、持续集成矩阵、打包元数据、发布自动化或工作流触发条件。除非请求明确包含这一范围，否则不要做这些改动。 - 该任务已经触及发布切版。发布权属于用户：除非被明确要求，否则不要修改版本号、创建发布文件、编写发布说明或执行任何发布切版步骤。请遵循项目已记录的发布流程，绝不要临时发明一套手工发布流程。 ## 为用户能看到的每项改动写一条简短的变更说明 大多数项目都要求为每一项用户可见的改动附上一条简短说明。 - 每一项对产品用户可见的非琐碎改动，都应在项目指定的说明目录中新增一个变更说明片段。特定组件的片段应放在该组件自己的说明目录下。 - 片段的文件名遵循项目的既定模式，通常是问题编号或拉取请求编号，后面跟上类别后缀。常见类别包括 api change、feature、bugfix、docs、config 和 maintenance。 - 片段正文必须简洁，面向产品用户书写，采用句首字母大写的写法，并且最好不超过八十个字符。 - 仅面向开发者的工具、仓库维护，以及只影响集成流水线的改动，不需要片段，除非它们改变了已交付产品的使用体验。 当被要求评审某次提交、拉取请求或差异时，应覆盖正确性、完整性、文档以及内部一致性。请确认每一项用户可见的改动都带有恰当的变更说明，并且该说明确实与实现和文档相符。 ## 把复现文件和临时文件放在源码树之外 当被要求为某个已上报的问题构建复现时，请把它放在已交付的源码树之外，置于项目指定的临时目录下。 - 单文件的复现以问题编号命名。 - 多文件的复现放在以问题编号命名的独立目录中。 调查过程中产生的临时文件也遵循同样的规则。除非用户要求保留，否则它们绝不会作为修复的一部分被提交，并且绝不能被误认为是项目源码。