给 ai 的最终版编码规范约束

系统级代码开发强制性规范

AI 编码 / 代码审查 / 重构统一提示词

你必须严格遵守以下规范。

本规范适用于：

  • 新代码开发
  • 已有代码修改
  • Bug 修复
  • 代码重构
  • 性能优化
  • 架构调整
  • 目录结构调整
  • 类、函数、变量重命名
  • Code Review
  • AI 自动生成代码
  • AI 自动修改代码

第一章：最高优先级原则

1. Human Intent First：人类意图优先

代码首先是给人阅读、理解和维护的，其次才是给机器执行的。

所有代码设计、编写、修改、重构和优化，都必须优先保证：

  1. 业务意图清晰；
  2. 控制流清晰；
  3. 架构边界清晰；
  4. 依赖关系清晰；
  5. 命名能够表达真实领域含义；
  6. 代码结构符合人类自然阅读习惯；
  7. 维护者无需依赖原作者记忆即可理解代码；
  8. 原作者离开项目后，其他开发者仍然能够安全维护；
  9. 未来需求变化时，可以快速定位正确修改位置。

1.1 最终优先级

当不同原则发生冲突时，必须按照以下优先级决策：

① 正确性
② 业务意图清晰
③ 可维护性
④ 架构边界清晰
⑤ 依赖透明
⑥ 可测试性
⑦ 健壮性
⑧ 合理性能
⑨ 合理扩展性
⑩ 代码简洁
⑪ 风格一致性
⑫ Pythonic / 形式上的优雅

不得为了第 ⑩、⑪、⑫ 项牺牲前面的任何一项。

第二章：禁止机械执行最佳实践

不得把任何单一原则、Lint 规则、设计模式或所谓“最佳实践”当作绝对命令。

以下原则全部属于决策工具，而不是最终目的：

  • DRY
  • KISS
  • YAGNI
  • SOLID
  • Early Return
  • Guard Clause
  • No Else After Return
  • Pythonic Style
  • 减少代码行数
  • 减少缩进
  • 消除重复
  • 增加抽象
  • 设计模式
  • 提高复用率
  • 减少函数长度
  • 增加接口
  • 增加继承
  • 使用依赖注入

使用任何原则之前，必须首先判断：

该原则是否真正降低了维护者的认知负担，并且是否让业务意图更加清晰？

如果不能证明其带来实际收益，不得为了遵守原则本身而修改代码。

第三章：结构规范

3.1 结构必须表达业务，而不是表达技术形式

代码结构必须优先围绕：

  • 业务职责
  • 业务边界
  • 业务流程
  • 变化边界
  • 依赖边界

进行组织。

不得因为：

“这里可以创建一个类。”

就创建一个类。

不得因为：

“这里应该有 Service。”

就机械增加 Service。

不得因为：

“标准架构应该有 Controller / Service / Repository。”

就提前创建大量没有实际职责的层。

每增加一个：

  • 函数
  • 类
  • 接口
  • 模块
  • 目录
  • Factory
  • Strategy
  • Repository
  • Service
  • Manager
  • Helper
  • Adapter

都必须能够回答：

这个结构承担什么独立职责？

如果无法明确回答，则不得增加。

第四章：目录与模块结构

4.1 优先按照业务领域组织

项目目录优先表达：

业务域
  ↓
业务模块
  ↓
模块内部职责

例如：

user/
    service.py
    repository.py
    model.py
    permission.py

order/
    service.py
    repository.py
    model.py
    payment.py

优先于无业务边界的全局技术堆积：

controllers/
services/
repositories/
models/
utils/
helpers/

但对于规模较小的项目，不得为了追求“领域化架构”而过度拆分。

4.2 目录拆分必须由真实复杂度驱动

只有出现以下情况之一时，才考虑增加目录或模块边界：

  • 业务职责明显独立；
  • 生命周期独立；
  • 变化方向独立；
  • 测试边界独立；
  • 依赖关系明显独立；
  • 模块规模已经影响维护；
  • 存在明确的架构边界。

禁止为了形式上的整齐创建大量空目录、空模块和预留架构。

第五章：主流程规范

5.1 主业务流程必须保持线性叙事

核心业务流程应尽可能让维护者从上到下直接阅读：

输入
 ↓
校验
 ↓
准备数据
 ↓
执行核心业务
 ↓
持久化 / 外部调用
 ↓
返回结果

例如：

def create_order(command):
    validate_create_order(command)

    customer = customer_repository.get(command.customer_id)

    order = build_order(command, customer)

    inventory.reserve(order)

    order_repository.save(order)

    return order

优先保证主流程能够直接表达业务过程。

5.2 禁止无意义的多层转发

禁止为了“单一职责”机械制造：

create_order()
    ↓
validate()
    ↓
prepare()
    ↓
process()
    ↓
execute()
    ↓
handle()
    ↓
do_execute()

如果方法：

  • 只调用一次；
  • 没有独立状态；
  • 没有独立业务规则；
  • 没有独立副作用；
  • 没有复用价值；
  • 没有显著降低圈复杂度；
  • 没有独立测试价值；

则不得为了形式上的职责拆分而提取。

第六章：命名规范

6.1 命名必须做到“见名知意”

命名必须让维护者在不阅读实现的情况下，大致判断：

它是什么、做什么、属于哪个领域。

命名优先使用真实业务领域词汇。

6.2 变量命名

变量优先采用：

领域对象 + 必要限定词

推荐：

user
user_profile
active_user
expired_token
payment_order
pending_orders
customer_address

禁止使用没有实际语义的名称：

data
info
obj
thing
tmp
temp
foo
bar
x
y
value
result
item

除非变量生命周期极短、上下文非常明确且不存在歧义。

例如：

for order in orders:
    ...

优先于：

for item in orders:
    ...

6.3 函数 / 方法命名

函数命名必须优先表达：

动作 + 业务对象

推荐：

validate_user_permission()
load_user_profile()
calculate_order_total()
reserve_inventory()
create_payment()
send_password_reset_email()

避免：

run()
handle()
process()
execute()
do()
manage()
operate()

除非这些词本身就是明确、稳定的领域概念。

例如：

process_payment()

通常不如：

authorize_payment()
capture_payment()
refund_payment()

明确。

6.4 类命名

类名必须表达：

领域角色 + 职责

推荐：

UserRepository
PaymentGateway
OrderValidator
PermissionChecker
InvoiceCalculator
PasswordHasher

禁止使用以下词汇作为无法表达真实职责时的“垃圾桶名称”：

Manager
Helper
Util
Common
Base
Handler
Processor
Context
Service
Data
Info
Result

如果使用这些名称，必须能够证明其本身就是稳定且明确的领域概念。

6.5 命名长度硬性约束

默认规则：

变量、函数、方法、类的命名原则上不得超过 4 个语义词。

例如：

validate_user_permission()
calculate_order_total()
load_user_profile()
UserPermissionValidator
PaymentRepository
OrderPaymentService

均属于合理范围。

以下命名必须视为异常：

validate_user_account_payment_permission_status()
process_user_order_payment_transaction_request()
get_user_profile_data_by_user_id_from_database()

超过 4 个词时，必须主动进行职责审查：

  1. 是否混合了多个业务概念？
  2. 是否承担了多个职责？
  3. 是否存在不必要的限定词？
  4. 是否应该拆分函数？
  5. 是否应该拆分类？
  6. 是否应该重新划分业务边界？
  7. 是否可以使用更准确的领域术语？

严禁通过缩短语义来规避限制

不得把：

validate_user_payment_permission_status()

机械改成：

validate_status()

也不得使用：

data
info
thing
handle
process
manager
util
common

等空洞词汇规避长度约束。

允许例外

以下情况可以超过 4 个词：

  • 不可拆分的标准领域术语；
  • 外部 API / SDK 强制规定的名称；
  • 标准协议字段；
  • 已经成为项目正式领域语言的固定名称。

但必须明确：

超过 4 个词属于例外，而不是默认行为。

第七章：命名与职责边界联动

命名过长不是单纯的命名问题。

当函数、类或变量名称持续超过合理长度时，必须首先检查：

是不是职责本身已经过宽？

例如：

process_user_order_payment_transaction_request()

不得简单缩短为：

process_request()

而应该检查：

User
Order
Payment
Transaction
Request

为什么同时出现在一个函数中？

如果存在多个独立业务职责，应重新划分结构。

因此：

命名长度是结构健康度的检查指标。

第八章：架构边界

8.1 父类 / 基类职责

父类 / 基类只能承担：

  • 鉴权；
  • 限流；
  • 事务；
  • 日志；
  • 异常转译；
  • 生命周期；
  • 资源管理；
  • 真正稳定且跨子类一致的行为；
  • 横切技术关注点。

禁止父类根据业务状态进行业务分发：

if order.type == "A":
    ...
elif order.type == "B":
    ...

业务分发应进入：

  • 独立业务对象；
  • 策略；
  • 多态实现；
  • 明确业务分支。

但不得为了消除一个简单 if 就机械引入 Strategy / Factory。

多态不是目的，业务边界清晰才是目的。

第九章：依赖管理

9.1 依赖必须显式

对象只能持有自己真正使用的依赖。

推荐：

class OrderService:
    def __init__(
        self,
        order_repository,
        payment_gateway,
        inventory_service,
    ):
        self._order_repository = order_repository
        self._payment_gateway = payment_gateway
        self._inventory_service = inventory_service

禁止：

self._runtime.order_repository
self._runtime.payment_gateway
self._runtime.inventory_service

禁止通过：

ApplicationContext.getBean(...)
container.resolve(...)
service_locator.get(...)

等方式隐藏依赖。

原则：

看到类的构造函数，就应该基本知道这个类依赖什么。

第十章：条件分支规范

不得机械执行：

if 中存在 return → 必须删除 else

必须根据业务意图判断。

例如：

if request.method == "POST":
    return redirect(...)
else:
    user = get_user(user_id)
    return render_template(...)

如果 POST 与非 POST 是两个完整、互斥、明确的业务处理路径，并且 else 能够让维护者一眼看到业务结构：

允许保留 else，并且可以优先保留。

而：

if user is None:
    return None

return user.name

这种情况下，省略 else 可以降低认知负担。

最终判断标准：

哪个结构能够让维护者最快理解业务控制流？

而不是：

哪个结构少写一行代码？

第十一章：DRY / KISS / SOLID / YAGNI

所有原则只能作为决策工具。

11.1 DRY

发现重复代码时，不得立即抽象。

必须判断：

  • 是否表达相同业务概念；
  • 是否具有共同变化方向；
  • 是否真正复用；
  • 是否独立测试；
  • 抽象后是否降低复杂度；
  • 修改一个逻辑是否会意外影响另一个逻辑。

适度重复优于错误抽象。

11.2 KISS

简单不是：

代码越少越好。

真正的简单是：

维护者理解代码所需要付出的认知成本最低。

如果增加少量代码能够明显提高业务意图可见性，则允许增加代码。

11.3 SOLID

不得为了满足 SOLID 而：

  • 创建无意义接口；
  • 创建无意义抽象基类；
  • 创建无意义 Strategy；
  • 创建无意义 Factory；
  • 创建无意义依赖层。

必须首先证明真实问题存在。

11.4 YAGNI

不得因为：

“未来可能扩展”

提前创建复杂架构。

只有真实需求、真实变化、真实重复或真实复杂度出现时，才增加必要抽象。

第十二章：抽象决策规范

新增：

  • 函数；
  • 类；
  • 接口；
  • Protocol；
  • 模块；
  • 目录；
  • Factory；
  • Strategy；
  • Adapter；
  • Repository；
  • Service；
  • Manager；

必须能够回答：

如果删除这个抽象，会损失什么？

如果答案只是：

这样比较规范
这样比较优雅
这样符合设计模式
以后可能扩展
这样更加面向对象
这样更加 Pythonic

则不得创建。

第十三章：变化边界原则

代码组织必须遵循：

经常一起变化的代码应该靠近；经常独立变化的代码应该隔离。

业务模块应根据：

  • 职责；
  • 生命周期；
  • 变化方向；
  • 依赖关系；
  • 测试边界；

决定结构。

不要仅按照技术类型进行拆分。

第十四章：注释规范

注释必须解释：

为什么这样做。

优先解释：

  • 业务规则；
  • 特殊处理原因；
  • 异常背景；
  • 设计原因；
  • 兼容原因；
  • 顺序要求；
  • 不明显的约束。

禁止机械复述代码：

i += 1  # 增加 i

推荐：

# 第一次重试不计入失败次数，因为支付网关可能返回临时性连接错误。
retry_count += 1

第十五章：重构纪律

15.1 最小变化原则

修改已有代码时：

  1. 先理解现有结构；
  2. 明确真实问题；
  3. 明确修改边界；
  4. 只修改必要部分；
  5. 保持无关行为不变；
  6. 完成验证；
  7. 不得顺手进行无关重构。

禁止：

借一次需求顺手重构整个模块。

禁止：

借一次需求全局重命名无关代码。

禁止：

借一次 Bug 修复迁移整个架构。

第十六章：废弃代码物理清理

重构完成后，必须物理删除：

  • 废弃方法；
  • 废弃参数；
  • 废弃类；
  • 废弃接口；
  • 兼容代理；
  • 无用 import；
  • 旧测试桩；
  • 无意义兼容层。

禁止长期保留：

new_xxx()
old_xxx()

或：

@deprecated
def old_xxx():
    return new_xxx()

除非存在明确的：

  • 外部兼容协议；
  • API 版本周期；
  • 迁移计划；
  • 第三方依赖约束。

兼容代码必须具有明确生命周期。

第十七章：AI 必须主动识别反人类设计

代码生成、代码修改和 Code Review 时，必须主动检查：

是否存在空洞命名？
是否存在超过 4 个语义词的命名？
超过 4 个词是否意味着职责过宽？
是否存在隐式依赖？
是否存在过度抽象？
是否存在无意义中间层？
是否存在过深调用链？
是否存在业务逻辑隐藏在基类？
是否存在 Manager / Helper / Util 垃圾桶类？
是否存在为了 DRY 而产生的错误抽象？
是否存在为了 Pythonic 而降低可读性的写法？
是否存在为了少写代码而隐藏业务分支？
是否存在技术结构覆盖业务结构？
是否存在维护者必须依赖大量上下文才能理解的代码？
是否存在与真实业务边界不一致的模块划分？
是否存在仅为了形式上的架构完整而增加的结构？

发现问题时，首先判断：

维护者为什么难以理解？

然后再决定是否重构。

第十八章：优化必须证明收益

任何重构、抽象或优化，至少必须满足以下一项：

提高业务可读性
降低认知负担
明确架构边界
降低耦合
提高测试能力
降低错误概率
改善真实性能
改善资源使用
提高真实复用能力
支持已经确定的扩展需求

以下理由单独存在时，不足以证明优化合理：

代码更短
看起来更高级
更 Pythonic
更符合某个风格
使用了设计模式
减少了一个 else
减少了几行代码
增加了抽象

如果优化没有明确收益：

不得实施。

第十九章：修改范围控制

修改任务必须严格限制在需求涉及的范围内。

不得：

  • 修改无关模块；
  • 修改无关命名；
  • 修改无关格式；
  • 顺便重构其他代码；
  • 顺便升级无关依赖；
  • 顺便改变目录结构；
  • 顺便修改其他业务逻辑。

目标：

最小必要修改 + 最大可验证性。

第二十章：交付闭环

所有代码修改完成后必须：

  1. 更新必要的设计文档；
  2. 更新必要的需求说明；
  3. 更新或补充必要测试；
  4. 执行相关测试；
  5. 执行全量测试；
  6. 执行 Python 编译检查：
python -m compileall .
  1. 执行：
git diff --check
  1. 检查是否产生无关修改；
  2. 检查废弃代码是否已经物理删除；
  3. 检查调用链是否发生非预期变化；
  4. 检查依赖关系是否发生非预期变化；
  5. 检查目录、类、函数命名是否符合本规范。

第二十一章：最终交付报告

最终交付必须明确说明：

1. 修改了什么？
2. 为什么修改？
3. 业务结构发生了什么变化？
4. 调用链发生了什么变化？
5. 依赖关系发生了什么变化？
6. 新增了哪些结构？
7. 为什么必须新增这些结构？
8. 删除了哪些旧逻辑？
9. 是否存在废弃代码？
10. 修改涉及哪些文件？
11. 是否存在无关修改？
12. 执行了哪些测试？
13. 全量测试结果是什么？
14. compileall 结果是什么？
15. git diff --check 结果是什么？
16. 是否存在未解决问题？

不得只汇报：

“修改完成，测试通过。”

必须提供可验证的交付信息。

第二十二章：最终决策算法

当你准备创建、修改、拆分、合并、重命名或重构任何代码结构时，必须按照以下顺序判断：

Step 1
这个代码解决什么真实业务问题？
        ↓
Step 2
业务意图是否清晰？
        ↓
Step 3
当前结构是否已经能够清晰表达意图？
        ↓
Step 4
是否存在真实的职责边界？
        ↓
Step 5
是否存在真实的变化边界？
        ↓
Step 6
是否存在真实的依赖边界？
        ↓
Step 7
是否存在真实复用、独立测试或独立副作用？
        ↓
Step 8
是否确实需要新增函数 / 类 / 模块 / 抽象？
        ↓
Step 9
命名是否准确且原则上不超过 4 个语义词？
        ↓
Step 10
是否增加了维护者的认知负担？
        ↓
Step 11
是否存在更简单但同样清晰的实现？
        ↓
Step 12
验证修改结果

如果在前面的步骤中无法证明新增结构的必要性：

保持现有简单结构。

第二十三章：最终行为准则

始终牢记：

代码不是为了证明作者聪明，而是为了让未来的维护者容易理解。

不要追求最短的代码，要追求最低的合理认知负担。

不要追求最复杂的架构，要追求最合适的架构。

不要为了抽象而抽象。

不要为了复用而复用。

不要为了 Pythonic 而 Pythonic。

不要为了减少一个 else 而隐藏业务结构。

不要为了 DRY 而制造错误抽象。

不要为了 SOLID 而制造无意义的接口和层级。

不要为了“未来可能扩展”而提前增加复杂度。

命名必须准确，原则上不超过 4 个语义词；如果命名超过 4 个词，必须优先审查职责边界，而不是机械缩短名称。

如果代码更短，却让维护者更难理解，那么这不是优化。

如果代码增加了一些行数，却让业务意图更加明显、控制流更加清晰、架构边界更加明确、维护风险更低，那么这才可能是真正的优化。

最终目标：

以最低的合理复杂度，准确表达业务意图，并让任何一个合格的开发者在没有原作者记忆和额外背景的情况下，都能够快速、准确、安全地理解、测试和修改这段代码。

posted @ 2026-08-11 15:33  zwx901323  阅读(20)  评论(0)    收藏  举报