Wade-DevCode 核心纪律
何时用
- 接到任何新的编码或改码任务，动手前先过一遍本文。
- 发现自己想"顺手"重构无关代码、提取公共抽象时。
- 不确定某个库函数/字段是否真实存在时。
- 准备交付代码或提 PR 前做最终自查。
核心规则
1. 不造 API
规则： 只调用真实存在的库函数、类、字段——不确定就先查文档或读源码，禁止凭记忆编造。
为什么： AI 的训练数据存在截止日期，且会在不同库之间混淆接口。常见事故：把 pandas 的方法名张冠李戴到 polars，把 Node.js v16 已删除的 API 当作现行 API 调用，编造根本不存在的 requests.get(...).json_body 字段。这类代码在 review 时看起来合理，跑起来立刻抛 AttributeError / TypeError，且错误定位成本很高。
怎么做：
- 不确定方法签名 → 用
help()、IDE 补全、或直接读源码确认。 - 不确定返回结构 → 先
print/console.log或写一个小测试确认再用。 - 若无法查证，在代码注释中明确标注
# TODO: 请核实此 API 是否存在，不要默默造假。
2. 外科手术式改动
规则： 只改与当前任务直接相关的代码行，不顺手触碰无关部分。
为什么： AI 极容易在"顺手"时引入意外回归：重排 import 导致循环依赖，格式化改动污染 git blame，重命名变量破坏下游引用。改动面越大，reviewer 越难判断哪些变化是必要的，哪些是噪音，review 成本指数级上升。
怎么做：
- diff 提交前逐行确认：每一处改动都必须有对应的任务理由。
- 不改格式（缩进、引号风格、trailing comma），除非任务本身就是格式化。
- 不重排、增删无关 import。
- 若发现真实 bug 但不在本次任务范围内，新建 issue 记录，不在当前 PR 里修。
3. 拒绝过度工程
规则： 只实现当前需求的最小方案，不预留"将来可能用到"的抽象或扩展点（YAGNI）。
为什么： AI 倾向于生成"通用"、"可扩展"的代码——Strategy 模式、插件系统、多层配置——即使需求只是"把这个数字加一"。这些提前抽象几乎从不被用到，却带来维护负担、理解成本，以及因过度复杂而埋下的 bug。
怎么做：
- 问自己：「当前的具体需求是什么？」写刚好满足它的代码。
- 不引入新的间接层（额外的 interface、factory、wrapper）除非现有需求直接要求。
- 配置项只在真的有多个合法取值时才加，不为"灵活性"提前加开关。
- 泛型/模板只在当前就有两种以上具体类型时才抽象。
4. 显式暴露假设
规则： 动手前列出关键假设；假设有歧义先问清楚，不闷头猜。
为什么： AI 在上下文不足时会悄悄做假设并写进代码：假设某字段不会为 null、假设列表非空、假设调用方已鉴权。这些假设在 happy path 下不报错，在边界场景下造成生产事故，且事后难以溯源（代码里看不到这个"决策"是在哪里做出的）。
怎么做：
- 开始前写出假设列表，例如：
假设： - user.profile 在此处一定非 null（由上游鉴权中间件保证） - items 列表至少有 1 条（调用方已校验） - 对于数据形状不确定的，用
assert/ TypeScript 类型守卫 / Zod schema 在代码中显式检查。 - 若某个假设无法当场验证，暂停并向用户提问，不要继续。
5. 改前先读
规则： 修改任何文件前先完整读一遍，理解现有约定再动手。
为什么： AI 经常在没读完文件的情况下就开始写代码，结果：重复定义已有的工具函数、违反项目既有的错误处理约定、用与周围代码不同的命名风格引入风格割裂。这些问题单独看不严重，积累起来会让代码库越来越难维护。
怎么做：
- 用 Read 工具读取目标文件全文，重点关注：已有的同类函数、命名规范、错误处理模式、import 风格。
- 改多个文件时，每个文件都先读，不要假设"它和另一个文件一样"。
- 读完后在心里（或明文写出）总结「此文件的约定」，再开始改。
正例 / 反例
反例：编造不存在的库方法
# 反例 — AI 凭记忆编造了 httpx 不存在的 .json_body 属性
import httpx
resp = httpx.get("https://api.example.com/data")
payload = resp.json_body # ❌ AttributeError: 'Response' object has no attribute 'json_body'
user_id = payload["id"]
# 正例 — 查过文档，使用真实存在的 .json() 方法
import httpx
resp = httpx.get("https://api.example.com/data")
payload = resp.json() # ✅ httpx.Response.json() 是真实 API
user_id = payload["id"]
反例：过度工程——为一个简单需求引入不必要的抽象
# 需求：给用户名加前缀 "user_"
# 反例 — AI 预留了"将来可能需要不同策略"的扩展点
from abc import ABC, abstractmethod
class PrefixStrategy(ABC):
@abstractmethod
def apply(self, name: str) -> str: ...
class UserPrefixStrategy(PrefixStrategy):
def apply(self, name: str) -> str:
return f"user_{name}"
class PrefixFactory:
_registry: dict = {}
@classmethod
def register(cls, key: str, strategy: PrefixStrategy):
cls._registry[key] = strategy
@classmethod
def get(cls, key: str) -> PrefixStrategy:
return cls._registry[key]
PrefixFactory.register("user", UserPrefixStrategy())
def format_username(name: str, strategy_key: str = "user") -> str:
return PrefixFactory.get(strategy_key).apply(name) # ❌ 三层间接，零复用
# 正例 — 最小实现，直接满足需求
def format_username(name: str) -> str:
return f"user_{name}" # ✅ 清晰、可测、够用
自查清单
- 我调用的每一个库函数/字段，都经过文档或源码确认真实存在。
- 本次 diff 里的每一处改动，都能对应到当前任务的某个具体要求。
- 没有引入任何"将来可能有用"的抽象、配置项或泛型参数。
- 所有关键假设（数据形状、调用前置条件、边界）已在代码注释或类型注解中显式标注。
- 修改的每个文件，我都读过全文并理解了其中的命名和错误处理约定。
- 没有顺手改格式、重排 import 或重构与任务无关的代码。
- 若存在无法当场验证的假设，已向用户提问而非自行猜测。