用途
这套规则适用于任何语言、任何项目，既用于新写的代码，也用于你正在改动的代码。它明确要求：不要仅仅为了符合规则而重排无关代码。
核心原则
顶层函数体现意图与业务顺序
顶层函数读起来就像用例本身：按顺序排列的简短业务步骤列表。每一行调用一个用领域词汇命名的步骤，具体机制放到辅助函数里。一个函数保持在同一抽象层级；出错时提前返回，让正常路径保持平坦。
意图函数与实现细节分离
意图函数承载业务决策及其顺序，尽量保持纯函数：不做 I/O、不产生隐藏状态变化。机制函数处理 I/O、序列化、重试、日志、并发和框架胶水，不做业务决策。意图函数调用机制函数；机制函数永远不决定业务规则。意图函数按领域含义命名，机制函数按技术职责命名。避免使用含义模糊的名称，如 utils、helpers、manager、process、handle，除非含义确实精确。在意图函数中测试重要的决策与边界情况。
实现之前
简要写下：用例意图、业务规则、副作用、哪些函数是意图函数、哪些是机制函数。
注释规范
默认不写注释。只有当代码本身无法表达要点时，才加一行简短说明。注释解释原因、不变量、契约或非显而易见的行为，不要叙述代码、复述代码或添加显而易见的 TODO。重构所触及的代码块时，同一次改动中删除叙述性注释（如“现在调用 X”“这会返回 Y”）。只复述名称与签名的文档注释属于叙述，应删除；保留说明不可见契约（新实例、隔离、线上格式、轮询而非休眠的原因）的从句。测试中的阶段标记（// given、// when、// then，或 arrange/act/assert）是必需结构而非叙述，应保留；当三个阶段从测试布局本身看不出来时还应补上。此条优先于“默认不写注释”和“删除叙述性注释”。
消除重复
在写 getter 或小函数之前，检查是否已有同类函数仅差一个值。如果是，就把共享形状提取为一个函数，让每个同类函数变成一行调用。两个兄弟入口点以相同的“加载并处理错误”前言开头时，把前言移入一个辅助函数，入口点只保留各自不同的决策。命名了概念的內联闭包应变成具名函数，让调用方读起来就是意图；保持内联的一次性匿名函数也必须能一口气读懂。
重构门槛
风格重构在推送前要证明行为未变：构建、linter、完整测试套件。以每文件净行数报告差异。任务说明只改实现时，不得触碰测试文件；此时现有测试约束设计：选择形状前先读懂它们断言了什么。若某测试断言了去重改动所改变的报错文本，应在代码中补回缺失部分而非修改测试，用 %w 包装并追加测试用 grep 查找的精确后缀。按文件或批次分别提交，提交之间保持门槛通过；一次性推送一个 PR。中间提交损坏会破坏 bisect，而 CI 在监视分支，因此你能控制的是提交之间的本地绿灯。读文件前先机械扫描：超过约 50 行的函数、以相同“收尾并返回”块结尾的兄弟分支、重复的“调用后再包装错误”前言、下划线前缀名称、叙述性注释（测试阶段标记不计：given/when/then、arrange/act/assert）。然后只读被标记的文件。若本轮工作被委派，应作为一次委派批量处理：文件清单、扫描命中项、按文件命名的仓库受保护不变量（经评审加固的逻辑、承重的错误字符串）。被委派方按文件应用改动，每批后跑门槛，并报告每文件行数增量。你须亲自重跑每个门槛才可采信其报告；本轮范围严格限定为用户选定的规则子集，并按陈述顺序每文件一个提交、最简单的在前，使历史能显示哪次改动破坏了门槛。重构那些校验顺序被测试固定的代码（例如先拒绝再构建）时，即便每个提取出的辅助函数都正确，也会破坏测试；移动任何校验步骤前先读固定顺序的测试。注释删除后，对被触及文件重跑格式化与 lint 文档注释规则：删一行可能让导出符号失去文档而触发先前通过的 lint，此时小幅后续提交补回文档行是预期行为而非错误（例如 Go 的 revive 这类文档注释 linter）。
最小改动
做能解决请求的最小可读差异。写新代码前先复用已有代码。不添加任务不需要的接口、工厂、层、文件或依赖。优先使用显式控制流，而非取巧的压缩代码。
本地风格
遵循文件与仓库中已有的模式，使用项目的格式化工具、linter 和测试。
可见性
每个符号从任务允许的最紧可见性开始（private、未导出或模块内部），只有当该边界之外的调用方需要时才放宽。为真实的外部调用方导出，不为可能的未来使用导出。
冲突顺序
规则冲突时：安全第一，其次是本地一致性，然后是本规则，最后是最小改动。当懒散或仅靠 YAGNI 的捷径会破坏本规则时，本规则优先。
守卫与门槛：只做诚实的活（用户规则）
规则与语言无关；示例中的工具名是 Go 实例。绝不要绕过守卫、门槛、钩子或检查：修复被门槛拒绝的工作。绝不要为让测试套件通过而删除、跳过、削弱或注释掉测试。因世界变化而失败的测试应更新为新的正确预期，并记录原因。绝不要关闭 lint 规则、从配置中移除 linter，或缩小检查范围使违规不再被报告。绝不要用抑制标记（nolint、@ts-ignore、# noqa、#[allow] 或语言等价物）让门槛沉默。真实问题就修代码；误报就修代码让工具认同，或将配置改动作为明确记录的决定提出。绝不要绕过钩子（--no-verify、HUSKY=0、禁用的 CI 步骤）或重构命令使门槛不运行。红灯门槛是信息：报告精确输出、修复根因、重新运行。阻止正当工作的守卫应作为带证据的决定交给用户，绝不自行消除。关于表驱动子测试的复杂度 lint：把每个用例拆成自己的顶层测试函数（Go 中 t.Run 用例变为 TestX_SubtestName），在你正要输入抑制标记的那一刻重构。校准排除项作为明确记录的决定放在 linter 配置中，绝不顺手添加；限定其范围（测试文件路径过滤、特定 linter、精确消息文本），注释说明签名为何固定，并用一次 lint 运行验证排除项匹配。
文件结构
语言允许时按此顺序排列顶层声明（仅在习语要求时调整）：导入、常量、变量、结构体或类、构造函数、方法。类别内按以下优先排序（更强者胜）：调用顺序，调用方在被调用方之上，文件自上而下按调用顺序阅读；在该层级上，仅当调用顺序未决定时公开先于私有（这不构成导出的理由，见可见性）；更新者靠下，当调用顺序仍未决定时，把更新的代码放在文件或区块靠下位置。
单元测试：黑盒、given/when/then、不用 mock（用户规则）
只通过公共 API 测试。仅当用户明确要求时才测试私有辅助函数；看起来需要直接测试的私有函数是设计信号：要么公共入口已覆盖它，要么它做得太多。每个测试读作 given / when / then：given 是可选准备，when 是必需的被测动作，then 是必需的断言结果。若指不出 when 或 then，测试应从头重写而非打补丁。尽可能让结构贯穿代码设计；保留阶段标记注释（见注释部分）。避免 mock：测试真实行为。需要 mock 的单元测试通常是伪装的集成测试，应针对真实协作者重写。mock 仅保留给单元测试完全无法运行的东西（网络、时钟、随机性、硬件），且保持轻薄。
适用场景与限制
适用于多种语言、多种项目的代码编写与改动，可作为代码评审、重构和测试编写的风格依据。规则本身不绑定具体工具；示例中的工具名为 Go 实例。它是一份风格约定，不是自动执行工具，需要开发者与流程配合落地（构建、linter、测试作为门槛）。资料未提供安装命令、配置方式或价格、平台等信息。