【谨慎运用】拒绝AI过度工程手册-第一章【未完】

05/1848 浏览开发心得

拒绝 AI 过度工程——约束 AI 行为的提示词与沟通策略手册

Preventing AI Over-Engineering: Constraint Prompts Handbook

版本 v4.2 | 2026-05-18

================================================================================

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

前言

【一句话定义】

过度工程 = 代码解决的问题比你实际拥有的问题更多。

【为什么 AI（Claude）特别容易过度工程】

BUG 是显性破坏：能看见、能定位、能修复。

过度工程是隐性破坏：代码能跑，看起来"更完善"，但在每次未来修改时

都向你收取复利式的认知成本。

Claude 的过度工程有三个结构性来源：

1. 训练数据偏差

互联网上的代码示例天然展示"完整方案"。Stack Overflow 上被高赞的答案

通常是通用的、防御性的。Claude 从这些数据学习，默认复现这种风格。

2. "有帮助"的错误激励

Claude 被训练为让用户满意。"多给一些"在表面上看起来比"少给一些"

更负责任。Claude 无法感知你项目的规模和生命周期，

于是默认按"大型生产系统"的标准设计一个周末项目。

3. 用复杂度对冲不确定性

当 Claude 不确定如何干净地实现某个功能时，它会通过增加抽象层来

"保留退路"。这些抽象不是为你服务的，是为 Claude 自己的不确定性

服务的。→ 详见第一章 1.13（最重要的 AI 特有模式，含完整分析）

过度工程的真实成本：

┌──────────────────────────────────────────────────────────────────┐

│ 短期：代码量翻倍，审查时间翻倍，理解成本翻倍 │

│ 中期：需求变化时，多余的抽象层成为修改障碍而非助力 │

│ 长期：项目因复杂度失控被放弃，或维护成本超过重写成本 │

│ 隐性：每次回来看自己的项目时，你需要更长时间"重新进入状态" │

└──────────────────────────────────────────────────────────────────┘

【本手册援引的核心原则】

- YAGNI（You Ain't Gonna Need It）—— Ron Jeffries，XP 方法论

- KISS（Keep It Simple, Stupid）—— 美国海军设计哲学，1960s

- Rule of Three —— Martin Fowler《重构》：第三次重复才值得抽象

- Gall's Law —— 「能运作的复杂系统都从能运作的简单系统演化而来，

跳过简单阶段直接设计复杂系统的尝试，从未成功过。」

- Second System Effect —— Fred Brooks《人月神话》：

「工程师在第二个项目中，倾向于把第一个项目里所有

"想加但没加"的东西全部塞进去。」

第一章：AI 过度工程的 15 种典型模式（含简化前后对比）

本章识别"是什么"。干预句式见第四章，决策框架见第六章。

────────────────────────────────────────────────────────────────────────────────

1.1 不必要的抽象层

触发信号：「为了更好的可扩展性…」「为了遵循 SOLID…」「为了便于替换…」

❌ Claude 给出（60 行）：

interface EmailSender { send(to, subject, body): Promise<void> }

class SmtpEmailSender implements EmailSender { ... }

class EmailSenderFactory { static create(): EmailSender { ... } }

✅ 实际需要（8 行）：

async function sendEmail(to, subject, body) {

await transporter.sendMail({ from, to, subject, text: body })

}

判断标准：接口只有一个实现 → 接口是多余的。

▶ 干预见第四章 4.1「打断不必要的抽象」

1.2 为"可能的需求"设计（YAGNI 违反）

触发信号：「考虑到未来可能…」「虽然现在不需要，但…」「为了以后方便…」

❌ Claude 给出（Python 场景）：

class StorageBackend(ABC): # 「以后可能换 S3」

@abstractmethod

def save(self, key, data): ...

class LocalStorageBackend(StorageBackend):

def save(self, key, data): ...

class S3StorageBackend(StorageBackend): # 「备用，还没接入」

def save(self, key, data): ...

✅ 实际需要（你只有本地存储）：

def save_file(path, data):

Path(path).write_bytes(data)

Rule of Three：同一逻辑出现第 3 次，且三处会同步修改时，才值得抽象。

▶ 干预见第四章 4.1「打断不必要的抽象」

1.3 过度的错误处理

触发信号：「为了健壮性…」「为了防止极端情况…」「虽然通常不会出错，但…」

❌ Claude 给出（内部函数加了公网级别的防御）：

function double(n: number): number {

if (n === null || n === undefined) throw new Error('n is null')

if (typeof n !== 'number') throw new TypeError('n must be number')

if (!isFinite(n)) throw new RangeError('n must be finite')

if (n > Number.MAX_SAFE_INTEGER / 2) throw new Error('overflow risk')

return n * 2

}

✅ 实际需要（内部函数，调用方保证类型）：

const double = (n: number) => n * 2

原则：只在信任边界处校验（用户输入、外部 API 响应）。

内部函数的调用方已保证合法性时，校验是冗余成本，不是"健壮性"。

▶ 干预见第四章 4.1「打断不必要的错误处理」

1.4 过度的配置化

❌ Claude 给出（Lua 场景）：

local Config = {

maxRetries = 3, -- 你永远不会调整这个

retryDelay = 1000, -- 你永远不会调整这个

timeout = 5000, -- 你永远不会调整这个

enableLogging = true, -- 你永远不会调整这个

}

function fetchData(url, options) -- options 有 12 个可选字段

options = options or {}

...

end

✅ 实际需要：

function fetchData(url)

return http.get(url, { timeout = 5000 })

end

标准：只有「这个值在不同环境或不同时间真的会变」时才做成配置。

▶ 干预见第四章 4.1「打断过度配置化」

1.5 不请自来的重构

触发信号：「我顺便…」「我还改进了…」「趁这次机会优化了…」

危险：范围外的每次修改都是新 BUG 的潜在来源，且无法归因。

❌ 你要修 line 42 的一个变量，Claude 额外做了：

· 重命名了 15 个变量（"更清晰"）

· 提取了 3 个新函数（"更可读"）

· 调整了文件结构（"更符合规范"）

· 加了 JSDoc 注释（"便于维护"）

✅ 你要修 line 42，Claude 只改 line 42。

▶ 干预见第四章 4.1「打断不请自来的重构」

1.6 过度的注释

❌ 噪音注释（增加阅读负担，降低信噪比）：

-- 将 userId 赋值给 userId 变量

local userId = user.id

-- 返回 userId

return userId

✅ 有价值的注释（解释"为什么"而非"是什么"）：

-- 用 floor 而非 round：业务要求不足1元不计，避免多收费

local fee = math.floor(amount * rate)

1.7 引入不必要的依赖

❌ 为一行逻辑引入整个库：

import _ from 'lodash'

const copy = _.cloneDeep(obj) // 仅此一处使用 lodash

✅ 原生 API 足够时：

const copy = structuredClone(obj)

每个额外依赖 = 安全风险 + 升级负担 + 包体积 + 许可证风险。

1.8 类型系统滥用（TypeScript）

❌ Claude 给出（为一个只用一次的函数写了 10 行类型体操）：

type UserId = string & { readonly _brand: 'UserId' }

function createUser<T extends Record<string, unknown>>(

data: Omit<T, 'id'> & Partial<Pick<T, 'createdAt'>>

): T & { id: UserId } { ... }

✅ 实际需要：

function createUser(data: { name: string; email: string }) {

return { ...data, id: crypto.randomUUID() }

}

1.9 过度的日志框架

❌ 个人脚本引入企业级日志：

const logger = winston.createLogger({

level: 'info',

format: winston.format.combine(

winston.format.timestamp(),

winston.format.json()

transports: [ new winston.transports.File({ filename: 'app.log' }) ]

})

✅ 个人脚本：

console.log('Processing:', args)

1.10 设计模式滥用

触发信号：「使用 XXX 模式可以…」

❌ 简单 if/else 被强行包装成策略模式（Python 场景）：

class SortStrategy(ABC):

@abstractmethod

def sort(self, arr): ...

class BubbleSort(SortStrategy):

def sort(self, arr): ...

class Sorter:

def __init__(self, strategy: SortStrategy): ...

# 实际只调用一次，排序算法固定为冒泡

✅ 实际需要：

arr.sort()

1.11 过度的安全加固

❌ 内网 CLI 工具加了公网级防护：

app.use(helmet())

app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }))

app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(',') }))

原则：安全措施应针对真实的攻击面，而非想象的攻击面。

1.12 架构提前复杂化（Big Design Up Front）

Gall's Law：「能运作的复杂系统都从能运作的简单系统演化而来，

跳过简单阶段直接设计复杂系统的尝试，从来不会成功。」

❌ MVP 阶段直接设计微服务：

用户服务 / 订单服务 / 通知服务 / API 网关 / 消息队列 / 服务发现...

✅ MVP 应该是：

一个应用 + 一个数据库，跑通核心流程再演进。

（何时演进 → 见第六章 6.6 演进触发条件）

────────────────────────────────────────────────────────────────────────────────1.13 用复杂度对冲不确定性（Claude 特有模式，最核心）

这是 Claude 独有的过度工程模式，人类工程师极少这样做。

【机制】

当 Claude 不确定如何干净地实现某个功能时，它会通过增加抽象层来

"保留退路"：接口可以换实现，工厂方法可以切换策略，配置项可以在

运行时调整。这些抽象不是为你服务的，是为 Claude 自己的不确定性

服务的。

【Claude 特有的表现形式】

· 给出一个 Claude 自己也无法解释"为什么要这样"的复杂结构

· 解释听起来很合理（"这样更灵活"），但追问具体场景时开始模糊

· 实现中包含多个"可选扩展点"，但你从未要求过扩展性

· 方案里有一层或多层"中间件"，职责是纯转发

【识别方法】

追问：「如果去掉这层抽象，会发生什么具体问题？」

如果 Claude 的回答变得模糊，说明这层抽象是不确定性的护身符。

❌ 触发信号：

「我设计了一个 Pipeline 结构，这样各步骤可以灵活组合…」

（你只需要顺序执行 3 个步骤，而这 3 个步骤从来不需要重新组合）

► 专项干预：

「你的方案是否是因为你不确定这段逻辑最终长什么样，

所以用抽象层保留了灵活性？如果是的话，请告诉我你不确定的地方，

我们先确定需求，再写代码。」

（→ 使用模板 4 挖掘不确定性根源）

1.14 测试过度工程

过度工程不只发生在实现代码里，测试里同样常见。

❌ Claude 倾向给出：

· Mock 一切（包括不需要 mock 的内部函数）

· 测试实现细节而非行为（断言内部变量的值，而非函数的输出）

· 为每个私有方法写单独的测试

· 100% 覆盖率的强迫症（覆盖了永远不会出错的 getter/setter）

· 设置 / 拆除代码比实际测试代码还长

✅ 好的测试：

· 测试行为（给定输入，验证输出），不测试实现

· 只 mock 外部依赖（网络、数据库、时钟）

· 测试对重构透明——你重构实现，测试不需要改

► 干预句式：

「你的测试是在测试这个函数"怎么实现的"还是"做了什么"？

如果我重构实现但保持行为不变，这些测试需要改吗？

如果需要，说明测试耦合了实现细节，请重写。」

1.15 修复过程中的范围蔓延（Scope Creep in Repair）

与 1.5（不请自来的重构）的区别：

1.5 是"修改时顺便重构"，是风格上的扩展。

1.15 是"修复 BUG 时把修复范围越扩越大"，Claude 会声称这些都是

"BUG 的根本原因"或"必要的修复"，因此比 1.5 更难拒绝。

❌ 你要修一个变量名拼写错误，Claude 给出：

「问题根源在于整个模块的状态管理方式。我将：

1. 修复拼写错误（你要的）

2. 重构状态管理为 Redux 模式（「防止类似问题」）

3. 加入单元测试（「确保修复有效」）

4. 更新接口定义（「保持一致性」）」

✅ 你要修拼写错误，Claude 只改那一个拼写错误。

【关键判断】：1~3 是真的 BUG 原因？还是 Claude 趁机把待办清单里

的"改进项"塞进来？追问：「拼写错误修好之后，2/3/4 各自单独

会在什么地方出什么 BUG？」

► 干预句式：

「只修复这一个 BUG，其他所有"改进"算作独立任务，

现在不做。修复完成后，我来决定是否处理那些改进。」