该技能提供一套通用编码规范,供实现功能、审查代码或重构时使用,用于检测代码异味、反模式和可读性问题。
一、反模式识别。检测到代码质量、设计类反模式(如三次以上重复代码、单文件多职责、多文件重复定义、注释禁用代码、吞掉错误、滥用类型断言、打补丁式实现、表面修复、无计划大改等)时,应暂停实现,记录触发模式、受影响的当前需求、最小合规替代方案及恢复验证条件。
二、基本原则。先广泛探索,再收敛到生命周期成本最低、可满足当前用户/运维/维护价值的方案。重构仅限阻塞当前结果、被当前任务改动或未通过质量检查的代码,采用保持行为的小步。只写当前需求所需的代码(YAGNI)。新增持久状态、公共契约、复用抽象等前,记录现有能力已提供什么、为何不足、为何该新增最小。
三、注释与错误处理。注释写“为什么”而非“什么”,保持时效与简洁;采用快速失败,传播失败或返回带原始诊断上下文的显式类型化错误。重复代码按三次法则处理。
四、调试与类型安全。用5 Whys追溯根因至可观察证据。优先 unknown 加类型守卫,其次泛型、联合/交叉类型,类型断言为最后手段。字段数≤20、可选比例≤30%、嵌套≤3层。
五、重构与测试。按重复代码消除、大函数拆分、复杂条件简化、类型安全提升排序;采用红-绿-重构,先写失败测试。测试遵循 Arrange-Act-Assert,一个用例验证一个行为,用合成非敏感数据,单元测试打桩外部依赖。
六、安全。密钥走环境变量或密钥管理器,使用参数化查询与标准加密库,入口处校验输入、按渲染上下文编码输出,每个资源访问都校验授权,遵循最小权限。
限制:详细实现方法需参考语言与框架特定规则;文中未提供具体安装命令、收费与平台信息。