本文件是项目的默认代码规范。任何 Agent 在新增、修改、重构或 Review 代码时都必须遵守;除非用户或项目已有更具体的规则明确覆盖。
所有技术决策按以下顺序取舍:
- 正确
- 容易理解
- 容易 Review
- 容易修改
- 必要复用
- 通用化或炫技
发生冲突时,必须选择优先级更高的一项。
- 不用“更优雅”交换正确性。
- 不用“减少几行代码”交换可读性。
- 不用“以后可能需要”增加当前复杂度。
- 看起来高级不是目标,稳定解决问题才是目标。
- 先确认需求、输入、输出、边界条件和失败行为,再写代码。
- 不猜测现有接口、数据结构或业务规则;优先阅读已有实现与测试。
- 捕获错误时,必须传播错误、转换为调用方可判断的错误,或执行已有的显式降级路径;禁止静默吞掉异常或伪造成功结果。
- 在系统边界校验外部输入;内部代码不要重复无意义校验。
- 修复 Bug 时,必须覆盖导致 Bug 的场景;能写自动化测试时应补测试。
- 未被明确要求时,不破坏已有行为、接口和数据兼容性。
- 没有实际执行的测试或检查,不得声称已经通过。
- 优先使用直接、普通、符合语言习惯的写法。
- 命名表达业务含义,避免无意义缩写、模糊名称和临时编号。
- 一个函数或模块只承担一个连贯职责,但不要为了“短”而机械拆分。
- 控制流保持清晰;优先早返回,减少深层嵌套。
- 代码应尽量自解释;确有必要时,按下一节的规则添加注释。
- 魔法数字、隐含状态和特殊规则必须被命名或集中说明。
- 遵循项目现有风格,避免在同一代码库引入第二套表达方式。
注释用于补充代码无法清楚表达的信息,不是用来掩盖复杂代码。能通过命名、拆分或简化表达清楚时,优先改代码。
应当注释:
- 非显然的业务规则、设计取舍、前置条件和不变量;
- 看似多余但因兼容性、并发、安全、性能或数据一致性而必须保留的代码;
- 外部系统的异常行为、临时绕过方案及其移除条件;
- 公共接口中无法由类型直接表达的单位、副作用、失败行为和使用约束。
不得:
- 把代码逐行翻译成自然语言;
- 为简单、明显的代码添加噪声注释;
- 保留被注释掉的旧代码;应删除并交由版本控制保存;
- 写与实现不一致、无法验证或可能误导 Reviewer 的注释;
- 写没有原因和完成条件的
TODO、FIXME。项目使用 Issue 系统时应附编号。
规则:
- 注释优先解释“为什么”,必要时说明“约束、风险和例外”,少解释“做了什么”;
- 注释放在最接近相关代码的位置,保持简短、具体、可验证;
- 修改代码时必须同步检查并更新相关注释;过期注释视为缺陷;
- 文档注释描述稳定契约,内部注释描述实现原因,不混淆两者;
- 不理解某段代码或注释时,先调查和验证,不得猜测后删除或改写。
示例:
// 差:重复代码含义
retryCount++; // 重试次数加一
// 好:说明保留该逻辑的原因和边界
// 第三方接口偶发返回 429;最多重试 3 次,避免形成请求风暴。
retryCount++;- 只修改完成当前任务所必需的代码。
- 禁止混入无关的格式化、重命名、重构、依赖升级或目录调整。
- 一次变更应有单一、明确的目的。
- 关键假设、行为变化、兼容性影响和已知风险必须显式说明。
- 代码、测试、类型、配置和文档应在同一变更中保持一致。
- 大改动应拆成可独立验证的小步骤,但不得制造无法运行的中间状态。
- 把经常变化的业务规则与稳定机制分开。
- 副作用应集中在边界;核心逻辑尽量保持显式输入和输出。
- 避免隐藏的全局状态、跨模块写入和不透明的隐式行为。
- 接口暴露必要能力,不泄漏无关实现细节。
- 依赖方向必须清晰,避免循环依赖和跨层调用。
- 先写最小可行结构;只有真实变化需求出现后再增加扩展点。
复用不是默认目标。只有同时满足以下条件时才抽象:
- 代码表达的是同一个概念或同一条业务规则;
- 多处实现应当一起变化;
- 抽象后的名称和接口比重复代码更容易理解;
- 抽象确实降低维护成本,而不是隐藏差异。
规则:
- 优先复用项目中已有、稳定、语义匹配的实现。
- 语义不同但代码相似时,允许保留重复。
- 不创建只有一个调用方、且没有明确价值的公共工具层。
- 不为消除少量重复引入复杂继承、回调链或通用框架。
除非当前需求明确需要,否则禁止:
- 为假设中的未来需求设计插件系统、规则引擎或配置平台;
- 引入复杂泛型、反射、元编程、DSL 或深层继承;
- 新增依赖只为替代少量清晰代码;
- 在没有数据证明前进行性能优化;
- 使用团队难以维护的冷门语法或技巧。
任何额外复杂度都必须能回答:它解决了当前哪个真实问题?
Agent 写代码时必须:
- 阅读相关代码、测试和项目约定。
- 明确当前任务的行为边界,不自行扩大范围。
- 选择能正确解决问题的最简单方案。
- 保持变更最小,不顺手重构无关代码。
- 添加或更新必要测试与注释。
- 执行适用的测试、类型检查、静态检查和格式检查。
- 自我 Review 后再提交结果。
- 明确报告:改了什么、验证了什么、哪些内容未验证、是否存在风险。
Agent 不得:
- 编造接口、依赖、测试结果或运行结果;
- 因为偏好某种架构而改写正常工作的代码;
- 在没有必要时增加抽象层、配置项或扩展点;
- 用大规模重构掩盖一个本可局部修复的问题。
- 行为是否正确,边界和失败路径是否处理?
- 是否存在更直接、更容易理解的实现?
- 变更是否仅包含当前任务所需内容?
- Reviewer 能否快速看懂目的、影响和风险?
- 后续修改是否有清晰入口,副作用是否可控?
- 新增抽象是否真的必要?
- 注释是否必要、准确,并与当前实现一致?
- 测试是否覆盖关键行为和本次修复?
- 所有验证结果是否真实、可复现?
当两个方案都能工作时,选择:
更少假设、更少隐藏行为、更小改动、更直白、更容易验证的方案。