AI 辅助编程指引

发布于 2025-05-01 · 更新于2026-05-01 12 分钟阅读
AI 编程Vibe Coding工程方法论Prompt EngineeringAI生成

🚧 AI生成内容，全文构建中 ing。AI 风明显

核心命题：AI 时代，开发者的核心壁垒已经从”代码编写能力”转移到”系统架构设计与工程拆解能力”。写代码是整个开发流程中技术含量最低的一环。

引言：为什么你的 AI 编程总是以混乱收场？

这篇文章的目标读者，是已经在用 AI 写代码、但经常感觉结果失控的开发者。你不是新手，你知道怎么写代码，你也用过 Cursor 或 Claude。但你会发现，项目稍微复杂一点，AI 生成的代码就开始出现各种问题：模块之间的接口对不上，第三方库版本冲突，改了 A 又坏了 B，最后不得不推倒重来。

这个死循环的根源，通常不是 AI 不够聪明，而是你给它的上下文根本不足以支撑它做正确的决策。

当前的 LLM 有一个关键特性：在单个函数、单个模块的局部生成上极其强大，但在全局架构把控和跨文件逻辑连贯性上容易”顾此失彼”。一个经典的失败案例：你让 AI 搭了一个 Express 后端，三天后你又让它加一个功能，它给你的代码里用了完全不同的错误处理风格，因为它已经不记得第一天定下来的约定了。这不是 AI 的 bug，而是 LLM 无状态的本质特性——它只能看到当前对话窗口里的内容。

应对这个特性的唯一有效策略，是把系统边界、模块划分和关键约定显式地写出来，每次都带进对话。

这就是本文想讲的事：如何在动手写代码之前，把该想清楚的东西想清楚，然后用工程化的方式把它传递给 AI。

第一阶段：谋局——需求收敛与架构推演

1.1 奉行 MVP 原则：做减法，砍掉伪需求

在写下第一行代码之前，先问自己：这个东西最核心要解决什么问题？

每个人都知道 MVP 这个词，但真正执行的时候往往做不到。你会发现自己的需求列表越写越长，每一项看起来都”很合理”、”不多”。这是正常的认知偏差——功能在脑子里是免费的，只有在实现的时候才会暴露真实成本。

几个具体场景，说明”砍”到什么程度才够：

场景 第一直觉（容易犯的错） 真正的 MVP
做一个内部工具管理构建产物 支持多用户、权限分级、历史版本对比 一个 CLI 脚本，能列出指定目录的产物并打标签
做一个博客系统 评论、标签、RSS、SEO 优化、暗色模式 能写 Markdown、能发布、能看，其他都是后来的事
实现一个渲染效果 降噪、时序稳定、参数化 UI 先跑出一张正确的静态结果图，哪怕有噪点

MVP 砍的不是最终目标，而是此刻不验证核心假设就不应该存在的复杂度。

1.2 架构选型：六个问题，每个都要有答案

定 MVP 之后，不要直接让 AI 写代码。先用几轮对话把架构锁定。以下六个问题，每一个没有答案之前，都不应该进入实施阶段：

① 最终形态
Web App、桌面工具、CLI 脚本、还是 Agent 流程？形态决定了整个技术栈的选型方向，一旦确定很难中途改变。

② 运行环境
本地运行还是云端服务？依赖什么硬件资源？这直接影响部署方案和冷启动成本。

③ 数据流转
输入从哪里来？中间状态怎么存？结果交给谁？如果说不清楚数据流，你的模块边界就还没想清楚。

④ 模块分工
UI 与核心逻辑解耦了吗？哪些职责天然属于不同的层？混在一起的代码，每次需求变更都是一场手术。

⑤ 技术栈约束
已有哪些基础设施？绑定了哪些语言或框架版本？这些约束要在最开始就告诉 AI，否则它会给你推荐一个”更好的”但和你现有系统完全不兼容的方案。

⑥ 扩展性边界
哪些地方要留扩展接口，哪些地方坚决不做过度设计？这个问题的价值在于逼你想清楚哪些东西”可能变”，从而保护它们。

遇到技术路线不确定的情况，让 AI 给出 2-3 个方案并做横向对比（开发速度、架构复杂度、上线难度）。你做最终决断，AI 提供备选项。注意：AI 给出的方案往往偏向”通用成熟解”，在高度定制化或性能敏感的场景里，这个倾向可能会把你带偏——这一点后面单独讨论。

1.3 架构收敛对话的实际样子

场景 A：做一个团队内部的构建产物管理 CLI 工具

1
2
3
4
5
6
7
8
9
10
11
12
13
14
第一轮：
"我想做一个内部工具，帮助团队管理 CI 产出的构建产物。
目前每次构建完，产物散落在不同的临时目录里，没有统一索引。
你能给我 2-3 种可行的架构方案，并对比它们的实现成本和维护成本吗？"

第二轮：
"方案一（本地 SQLite 索引 + CLI）看起来最轻量。
不选方案二（REST API + 数据库服务）的最大理由是什么？
方案一最可能在什么情况下撑不住需要升级？"

第三轮：
"好，锁定方案一。在我动手之前，
请帮我列出这个工具需要定义哪些核心数据结构，
以及 CLI 的命令集应该包含哪些操作。"

场景 B：在现有渲染管线里增加一个屏幕空间效果（GPU 场景）

1
2
3
4
5
6
7
8
9
10
11
第一轮：
"我在 Unity 6 URP 里实现一个屏幕空间全局光照（SSGI）效果。
有哪几种接入管线的方式？分别说明开发周期和对原有管线的侵入程度。"

第二轮：
"ScriptableRendererFeature + Compute Shader 的方案我比较熟悉。
这个方案在 Forward Rendering Path 下有什么已知的限制？"

第三轮：
"好，锁定这个方向。当前阶段只做最基础的漫反射 GI 雏形，
不做降噪和时序稳定。请帮我列出第一阶段需要实现的最小模块集合。"

两个场景，同一个对话结构：先发散获取选项，再收敛锁定方向，最后确认第一阶段边界。完成这三轮之后，才开始写代码。

第二阶段：落地——标准化 AI 开发工作流

架构锁定之后，进入实施阶段。这里有一件真实发生过的事，可以说明”不拆分模块”有多危险：

我曾经做一个数据处理脚本，因为觉得逻辑”不复杂”，就一次性让 AI 生成了包含数据读取、清洗、转换和写入四个部分的完整脚本。代码看起来没什么问题，但运行之后发现转换逻辑有一个边界条件的 bug。修这个 bug 时，AI 给的修复代码意外改动了数据读取部分的逻辑（因为它们耦合在一起），导致又引入了一个新问题。来回折腾了一个多小时，最后还是把四个部分拆开重写才解决。如果一开始就分模块实现，每个模块单独验证，这个问题不会超过十分钟。

核心教训：模块不拆分，不只是”代码不好看”的问题，而是调试成本的数量级差距。

2.1 任务拆解的实际模式

将系统按职责边界切分为可独立验证的最小单元，并确立依赖顺序。

以构建产物管理 CLI 为例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
阶段 0：数据层
  └── 定义产物的数据结构（schema）
  └── 实现 SQLite 的初始化与基础 CRUD

阶段 1：采集层
  └── 实现目录扫描逻辑
  └── 将扫描结果写入数据库（调用阶段 0 的接口）

阶段 2：查询层
  └── 实现按条件查询的逻辑
  └── 格式化输出到终端

阶段 3：CLI 入口层
  └── 用 argparse / click 包装以上功能
  └── 处理参数校验和错误提示

阶段 4：优化（最后处理）
  └── 大目录下的性能优化
  └── 配置文件支持

每个阶段的完成标准在进入下一阶段之前必须明确。”能运行”不等于完成，要有具体的验收条件（见第三阶段的 Prompt 模板）。

2.2 逐模块执行的节奏

1
2
3
4
5
6
7
8
9
向 AI 描述单一模块的需求（附带约束和验收标准）
    ↓
本地运行，验证当前模块
    ↓
如有问题：把完整的错误信息/实际行为与预期行为的差异粘贴给 AI
    ↓
当前模块通过验证
    ↓
进入下一模块（带上已完成模块的接口约定作为上下文）

特别注意最后一步：每次进入新模块时，把已完成模块的关键接口约定带进对话。不要假设 AI 记得上一轮说了什么，因为它不一定记得，或者它记得的和你理解的不完全一致。

2.3 重构窗口：跑通之后，专门留一次对话

功能跑通之后，单独开一次对话专门做代码质量提升，而不是边实现边优化。混在一起做的结果，往往是两件事都没做好。

重构对话的清单：

  • 消除魔法数字，提取为具名常量
  • 识别跨模块的重复逻辑，提取为公共函数
  • 检查资源的申请和释放是否对称（文件句柄、数据库连接、GPU 资源等）
  • 补充对非直觉性逻辑的注释（算法选择的理由、边界条件的处理原因）

第三阶段：利器——构建工程级 Prompt 说明书

“帮我写一个 XXX” 这种 Prompt 能解决的问题，是那种你自己十分钟也能写完的问题。一旦需求稍微复杂，这类 Prompt 的实际效果是：AI 在没有约束的情况下自由发挥，你拿到的代码和你真正想要的东西之间，隔着一堆隐含假设的鸿沟。

一个高质量的执行 Prompt，本质上是 PRD（产品需求文档）和 Technical Spec（技术规格文档）的融合。把这两份文档的核心信息塞进一次对话，模型的输出稳定性会发生质变——不是因为 AI 变聪明了，而是因为搜索空间被收窄了：模糊的输入对应巨大的可能性空间，AI 只能猜；清晰的输入约束了解空间，AI 才能精确执行。

3.1 完整 Prompt 的 10 个核心要素

下面用一个具体场景（构建产物管理 CLI 工具的阶段 0）演示完整的 Prompt 结构：

① 项目背景与目标

1
2
3
我在开发一个团队内部使用的构建产物管理 CLI 工具。
核心问题：每次 CI 构建完成后，产物散落在不同临时目录，没有统一的索引和查询方式。
最终目标是提供一个命令行工具，能注册、查询和清理构建产物。

② 目标用户

1
2
使用者是熟悉命令行的后端/DevOps 工程师，
不需要 GUI，不需要面向新手的冗余提示。

③ 核心需求（当前阶段 MVP）

1
2
3
4
5
当前阶段（阶段 0）只需要实现数据层：
1. 定义构建产物的数据结构（含：构建 ID、产物路径、构建时间、Git commit hash、标签列表）
2. 实现 SQLite 数据库的初始化（表创建，幂等）
3. 实现基础 CRUD：insert_artifact / get_artifact_by_id / list_artifacts / delete_artifact
不实现 CLI 入口，不实现查询过滤逻辑，这些在后续阶段处理。

④ 架构设定

1
2
3
4
形态：本地 CLI 工具（单机使用，不需要服务端）
数据存储：SQLite（文件路径从环境变量或配置文件读取）
语言：Python 3.11+
模块结构：数据层单独放在 db/ 目录，对外只暴露函数接口，不暴露 ORM 对象

⑤ 技术约束

1
2
3
只使用标准库（sqlite3）和 dataclasses，不引入 SQLAlchemy 或其他 ORM
Python 类型注解全覆盖
不使用全局变量；数据库连接通过函数参数传递

⑥ 非功能要求

1
2
函数签名设计要方便单元测试（可注入 in-memory SQLite）
错误处理：数据库操作失败时抛出自定义异常，不吞掉错误

⑦ 实施计划（当前任务范围）

1
2
本次只输出阶段 0 的数据层代码。
文件：db/schema.py（数据结构定义）+ db/repository.py（CRUD 函数）

⑧ 输出要求

1
2
3
输出完整代码，不省略任何函数实现。
每个函数附一行 docstring 说明其用途和返回值。
同时输出一个最小的使用示例（放在 if __name__ == "__main__" 块里）。

⑨ 验收标准

1
2
3
Python 3.11 下无语法错误和类型警告。
使用 in-memory SQLite 可以直接跑通使用示例。
insert 后 list 能查到，delete 后 list 查不到。

⑩ 限制条件（Anti-goals）

1
2
3
4
不要：引入任何第三方库
不要：实现 CLI 参数解析（那是阶段 3 的事）
不要：为"将来可能需要"的字段提前加列
不要：一次性输出所有阶段的代码

这个 Prompt 的信息密度，和”帮我用 Python 写一个 SQLite 的构建产物管理工具”相比，差距是量级的。前者让 AI 在一个清晰定义的解空间里工作，后者让它在几乎无限的可能性里随机漫步。

附录：关于 AI 架构推荐的信任边界

这是这篇文章里最容易被忽视但实际上最重要的一节。

“让 AI 帮你做架构选型”这个建议是成立的，但有一个前提：你需要知道在什么情况下可以信任它的推荐，在什么情况下必须自己审核。AI 的架构建议有一个系统性偏向——它倾向于给出”通用成熟方案”，因为这是训练数据里最多的解法。但最通用的方案不等于最适合你当前约束的方案。

一个判断框架，分三类情况：

可以高度信任 AI 的架构推荐

场景的通用程度高、技术栈成熟、社区案例丰富。例如：

  • 标准的 REST API 后端（CRUD 为主，无特殊性能要求）
  • 常规的前端 SPA（React/Vue + 标准状态管理）
  • 脚本类自动化工具（数据处理、文件操作、CI 集成）

在这些场景里，AI 的推荐通常稳健，你可以直接采纳并追问细节。

需要自己审核 AI 的架构推荐

场景有明确的非功能性约束，AI 可能忽略或低估它：

  • 有延迟 SLA 的实时系统（AI 倾向于推荐”更易实现”的方案而非”更低延迟”的方案）
  • 有内存预算约束的嵌入式或移动端开发
  • 需要与特定版本的现有系统深度集成（AI 对版本兼容性细节不总是准确）

在这些场景里，把 AI 的方案当作”初稿”，用你自己的工程判断审核关键假设。

必须自己主导、AI 只做实现的场景

技术路线的正确性高度依赖领域知识，且错误决策代价极高：

  • 高性能 GPU 计算管线（线程组划分、内存访问模式、同步策略）
  • 自定义内存分配器或数据结构（性能 profile 驱动的设计决策）
  • 安全敏感的认证/加密架构

在这些场景里，架构决策必须由你主导。AI 是你的实现者和橡皮鸭，不是你的决策者。如果你在这类场景里完全依赖 AI 的架构推荐，你最终得到的往往是一个”看起来能用”但在关键路径上暗藏性能陷阱或安全漏洞的系统。

后记

用这套方法做了几个项目之后，我发现最大的转变不是”AI 生成的代码变好了”，而是我自己在动手之前想得更清楚了。把需求、约束、验收标准写清楚的过程，有时候会逼出一些在直接写代码时根本不会注意到的矛盾和盲区——而这些矛盾如果到实现阶段才发现，返工成本往往是前期思考成本的十倍。

这大概是 AI 编程工具带来的一个意外收获：它把”把需求想清楚”这件事变得比以前更加重要，因为你必须用语言把它表达出来，而不是”先写写看”。

你能把问题拆解得多清晰，AI 就能帮你做到多少。