在构建严格的仓库中，让 AI 编码智能体写出零警告代码并如实报告

## 迭代时只构建改动的模块，推送前完整验证 使用代码仓库中已提交的构建包装脚本,而不是全局安装的工具链,这样每个贡献者和智能体的构建结果才能保持一致。为了快速迭代,只构建和测试你改动的模块,而不是整个多模块构建;通常会有一个跳过静态分析检查的"快速"配置,以及一个跳过测试的标志。这些捷径仅用于本地循环,不能用于其他场景。 提交前,必须对受影响的模块启用检查并完整编译一次,确认零警告——绝不能凭一次跳过检查的构建就提交代码。推送前,运行项目的验证步骤,该步骤具有差异感知能力:它会对改动进行分类(仅文档、单模块,或根/配置变更),只构建受影响的模块及其依赖闭包,而对根构建配置的改动则会强制触发完整构建。验证会留下一个短期存在的标记,供推送钩子检查。推送前请取消你分支上已被取代的流水线运行,以免浪费共享的运行资源。 ## 绝不跳过 Git 钩子，提交信息要简短且不带 AI 署名 在每次工作会话开始时都要启用代码仓库的钩子路径;会话可能会被归档后又恢复,所以这不是一次性设置。绝不能绕过钩子——不使用跳过验证的标志,不绕过签名机制。钩子会强制检查许可证头、确保没有未使用或重复的导入,并检查提交信息的格式。 提交标题要按照 type(scope): description 的常规提交格式书写,使用feat、fix、docs、refactor、test、chore等类型。每条提交信息最多保留两行非空内容,第一行控制在约100字符以内。不要添加任何附加行——不加共同作者行,不加签署行,尤其不能加任何形式的AI署名或AI生成标记;提交信息钩子会拒绝这些内容。缺陷修复直接提交到主开发分支;新功能则使用功能分支。 ## 沿用周围代码的风格，把所有警告当作错误 保持与周边代码一致的风格,以合理范围内最小的改动达成目标。每个源文件都必须带有规定的许可证头。优先使用组合而非继承;每个可关闭的资源都要使用try-with-resources结构;公共API应返回可选类型包装,而不是返回null;只有在类型能从上下文明显推断出来时才使用局部类型推断;优先使用switch表达式和模式匹配,而不是冗长的if/else链;在合适的场景下使用密封类型和不可变的记录类型;泛型必须始终参数化;重写方法要加上注解;循环内拼接字符串要使用构建器;构造不可修改的集合要使用标准工厂辅助方法。 把每一个编译器警告、弃用警告和静态分析警告都当作错误处理。构建会开启所有代码检查,遇到未使用或重复的导入就会失败,所以要交付代码就必须做到零警告。不要在没有注释说明为何确实无法避免的情况下引入新的警告抑制注解,也绝不能删除代码注释,除非你能证明该注释的内容确实是错的。 ## 资源只由创建者关闭，绝不忽视容量上限 无论功能范围大小,以下不变量都会阻塞发布;哪怕改动再小,只要违反其中一条,发布就会被阻止。 **所有权** ——只有资源的创建者才可以释放、关闭或停用该资源。要明确追踪所有权;当你接收外部提供的执行器、连接池或连接时,要对其进行包装,确保生命周期调用不会销毁不是你创建的东西。每一个启动流程都需要一个与之对称的停止流程,撤销所有注册项——监听器、处理器、钩子——并且每个缓冲区都必须在所有终止路径和错误路径上被释放。 **终止路径完整性** ——每一条退出路径(成功、失败、取消、超时、拒绝)都必须让系统处于完成状态:解析future、重置标志位、释放缓冲区。要用比较并交换(compare-and-set)或"只关闭一次"模式让关闭操作具备幂等性。如果某个守卫条件要检查计数器,就必须确保有路径真正会递增这个计数器。 **背压** ——绝不能忽略拒绝信号或容量信号。要检查有界offer操作的返回值,处理被拒绝的执行,并处理部分写入的情况。每个缓存和缓冲区都需要有大小上限或淘汰策略;一个由外部输入喂入且没有边界的结构,就是一个拒绝服务攻击的风险点。 ## 在每个边界验证输入，只报告实际在运行的功能 无论功能范围大小,以下不变量同样会阻塞发布。 **边界安全** ——在每一个边界(线路、文件系统、shell、URL、HTTP)上,都要先校验和编码,再进行解释。只从完整成帧的消息中解码文本,绝不能从原始传输数据块中解码。要对文件系统路径进行规范化和校验——先解析、再规范化,然后确认结果仍处于预期的根目录之内,拒绝上级目录片段、分隔符和空片段。调用shell时要使用参数数组,动态路径和查询部分要进行URL编码,内容类型匹配要不区分大小写,并且要在边界处捕获解析失败,对格式错误的输入返回客户端错误而不是服务器错误。 **运行时真相** ——只对外声明和上报已确认的运行时状态,绝不能声明配置意图,或仅仅因为某个东西存在于类路径中就当作它在运行。能力标志和发现端点必须反映实际正在运行的内容,启动失败时必须抑制相关功能的对外声明。 **安全性** ——每一个具有修改能力或管理权限的接口,都需要显式的身份验证和授权,默认拒绝。完整性校验必须采用"失败即拒绝"策略;任何"失败即放行"的模式都必须是显式的,且不能作为默认设置。绝不能在生产路径中交付不安全的默认配置——要把它们放在需要显式选择开启、并附带启动警告的开关之后——示例代码也不得削弱这一安全姿态。 **模式对等** ——如果某个功能存在于多种调用模式(同步、异步、流式)中,各模式的语义必须一致:错误处理、生命周期事件、可观测性和完成行为都要保持一致。任何有意为之的差异都必须记录并测试,而当你为某一条路径添加功能时,要在所有路径中都进行验证。 ## 严重缺陷要配回归测试，禁止空洞的测试 每一个高严重性的缺陷修复都必须附带一个能够复现失败场景的回归测试。必需的CI通道中不允许存在占位测试或空操作测试——禁止那种只断言一个显而易见事实的测试,每个测试都必须真正断言它声称要验证的具体行为。端到端测试必须断言被测功能本身,而不能只是断言服务器启动成功。 如果必须隔离一个不稳定的测试,就要为它指定负责人、设定失效期限,并建立跟踪问题,而且它仍然必须在一个定期运行的通道中执行。工作流的路径过滤器,必须涵盖改动区域内所有会影响行为的脚本和配置位置,否则CI会悄无声息地跳过恰好被修改的那部分代码。 ## 示例要调用真实的 API，不用假实现糊弄 示例应用和演示程序是用户最先看到的东西,所以它们必须达到生产级质量,不能是占位实现。要真正使用你声称在演示的那个集成:如果一个示例是以某项真实能力命名的,它就必须调用那个真实的API,而不能用内存中的替代品来伪装。如果你没能让真实的集成正常工作,就要如实说明并寻求帮助,而不是交付一个伪装过的模拟实现——诸如"在真实应用中你会调用这个"这样的注释,正是这个示例并非真实应用的危险信号。 在针对第三方库编写集成代码之前,要先阅读它真实的API——检查依赖构件并阅读公开的方法签名——绝不能凭空编造方法调用。优先使用库自带的自动配置,而不是手动接线。每个示例都必须能够编译通过,并附带一份简短的README,说明它做了什么、如何运行,以及关键代码展示了什么。如果一个可替换的依赖正是该抽象层的全部意义所在,就不要为每一种后端变体各做一个示例。 ## 写下任何声明前，先用代码或 Git 历史核实 文档、更新日志条目、提交信息以及面向用户的文本中,每一项事实性声明都必须对应代码或Git历史中真实存在的东西。不要编造功能、方法名、能力清单、指标数字或修复提交;每一处虚构内容都会损害可信度,而且事后必须被追查出来并回滚。 数字类的声明必须有据可查——在写下计数之前,要对照实际代码进行核实。更新日志中"fixed(已修复)"和"added(新增)"这类条目必须与真实提交相符:先在日志中搜索该改动,在草稿中保留提交哈希,确认无误后再正式发布;如果找不到对应提交,那说明这项修复根本没有发生。关于API表面的声明,必须先阅读实际源码(字段列表、方法名)。声称某项功能已交付、已接线或已集成,必须要有一个真实的生产环境消费方,并且该路径能从用户的实际操作触达,而不能仅仅是一个服务提供者接口或参考实现。当某个事实无法核实时,要么将其删除,要么明确标记为"未核实"并在发布前进行询问。如果你发现自己正在编造内容,就要立刻停下,不要提交,把这条虚假声明和真实情况的对照报告出来,并修正它出现过的每一处副本。 ## 不拿规则冲突当借口，也不在中途宣布完成 除了事实层面的诚实之外,还要避免行为层面的不诚实——那种每句话单独看都站得住脚,但整体却带有误导性的表述方式。不要为了走更轻松的路而编造两条规则之间并不存在的冲突;当规则看起来相互冲突时,几乎总是要求更艰难、更安全那条规则占上风。不要在存在相互矛盾的准则时挑软柿子引用;要把矛盾摆到台面上去调和。规则要求默默修复的问题,不要只是汇报现状——如果共享流水线坏了,就把它修好并汇报成功,而不是叙述这个故障本身。"这原本就是坏的"或"这不是我造成的回归"只是一种描述,不是借口:共享分支的责任,会随着每一次改动而转移。 对于规则已经明确要求的行动,不要再去请求许可——做比问更重要,所以直接完成规则要求的工作,并继续推进未完成的事项,直到有人让你改变方向为止。不要在任务中途就宣布完成;诚实的信号应当把尚未完成的事项和已完成的事项一并列出。当简洁性与正确性或安全性规则相冲突时,安全性规则优先:"啰嗦但正确"胜过"简洁但不安全"。当你察觉到自己出现上述任何一种模式时,要把它指出来,把规则真正要求的工作做完,并记住:道歉本身不等于完成了工作。 ## 把决定和计划存进共享知识库，而不只留在聊天里 把共享知识库当作结构化产出的长期存放地,因为聊天记录不是持久性的。在开始结构化工作之前,先去知识库中查阅以往的决策、设计和背景信息,并把有长期价值的成果写回知识库,而不是只留在一次对话里。按照文档类型分别归档:架构决策和设计记录、分阶段计划、运维手册和值班流程,以及审计、分析和交接文档,各自都有指定的存放位置;随代码一同交付的参考文档,以及限定于某个目录范围的规格说明,都放在该目录的README中。 不要把私人的或仅限本地使用的标识符——个人账号名、角色扮演化名、机器专属路径——放进任何已提交的产物中。测试和示例中要使用中性的占位名称,只有在确实指向一个公开账号的情况下才使用真实标识符。当长期存储的知识库不可用时,退而使用一个可分享的链接,并把它记录下来,以便后续会话能把它归档到正确的位置。