用途:这是编写、编辑或审查任何代码时的统一标准,适用于需要判断代码质量与一致性的开发场景。
主要能力:给出不可协商的编码规则。清晰优先于技巧,需要注释才能理解的行应重写;只做完整解决问题的最小改动,保持 diff 聚焦可审查;禁止死代码,包括注释掉的块、未使用或不可达代码、遗留调试/控制台语句;避免重复,把修复集中到一处可复用抽象,但不过度抽象;用守卫子句和提前返回来扁平化嵌套。
要求与限制:必须完整实现所要求内容,不留 TODO、占位或缺失部分,并在报告完成前验证可用;若请求与项目约定冲突,应指出并提出符合约定的替代方案,而非默默破坏;命名要揭示意图,避免 a、b、tmp、data 之类的泛化名;函数保持小而专注,只做一件事、处于同一抽象层级;遵循 KISS/YAGNI,按任务真实需要构建最简可行方案。
注释规则:默认零注释,写自解释代码;不得添加复述代码行为的注释;仅当存在代码本身无法承载的非显而易见的原因(如绕过方案、刻意权衡、边界情况引用)时才写一条短注释。禁止把需求、规格或文档转抄进代码注释,功能需求、验收标准、工单或规格文本的摘要都不是合理的 why;如需溯源,用简短稳定的 id(变更/工单 slug)指向规格。
其他要求:离开时让每个文件比来时更整洁,编写可测试代码并由自动化测试支撑,以便无惧重构。对象设计中有判断力地应用 SOLID:单一职责、开闭(优先复用或扩展现有共享组件/模块,而非重复造轮子,“新代码”指新的扩展点)、里氏替换、接口隔离、依赖倒置。