从程序设计到交付：AI 辅助编程的工程实践规范

—— 建立人机协作的标准化流程，让 AI 真正服务于软件质量

---

作者：
CSDN: 拳里剑气纵北原

github: Han QA ovo

1. 引言：AI 辅助编程的定位与边界

AI 编程助手（如 GPT-4、Claude、Gemini、DeepSeek 等）已能深入理解代码上下文，甚至直接修改工程文件。但这并不意味着开发过程的自动化，而是协作模式的升级。本规范旨在为团队与个人提供一套可复用的方法论，覆盖从需求到交付的全生命周期。

核心原则：人机责任分离

责任方	职责
人类开发者	目标定义、架构决策、安全审计、验收确认
AI 助手	信息检索、代码生成、测试填充、文档草拟

所有由 AI 生成的产出物，必须经过提议→审查→采纳循环，方可进入代码库。

---

2. 环境搭建与工具选型

2.1 模型能力评估维度

选择模型时，应从以下维度综合考量：

• 上下文窗口长度：能否一次性加载整个模块或项目。
• 代码理解与生成能力：在 HumanEval、MBPP、SWE-bench 等基准上的表现。
• 工具调用（Function Calling）能力：能否自主操作文件、执行终端命令。
• 指令遵循度：对结构化约束（输出格式、风格指南）的遵守程度。
• 成本与延迟：长上下文高频交互下的经济性。

目前主流模型选型参考：

模型	优势场景
Claude 3.5 Sonnet / Opus	复杂逻辑推理、长上下文代码重构、自主代理
GPT-4o / GPT-4 Turbo	多模态（截图→代码）、广泛生态集成
Gemini 1.5 Pro	超长上下文（1M tokens）、深度代码分析
DeepSeek-V2 / Coder	高性价比、长上下文、中文代码理解

)

2.2 IDE 集成方案

推荐使用 支持工具调用的 AI 插件，使其能主动读取文件、运行命令。

常用插件架构对比：
以vscode系作对比

• Cline (原 Claude Dev)：独立代理模式，能遍历工作区、修改文件、执行 Shell，适合复杂任务。
• GitHub Copilot / Copilot Chat：内联补全 + 对话，生态紧密，侧重编码即时辅助。
• Continue：模块化设计，支持任意 LLM 后端、自定义上下文提供器，适合定制工作流。
• Cursor：基于 VSCode 的分支编辑器，深度集成模型，提供整个项目的智能感知。

配置要点（以 OpenAI 兼容接口为例）：

{
  "apiProvider": "openai",
  "apiUrl": "https://api.your-provider.com/v1",
  "apiKey": "your-api-key",
  "model": "your-model-id"
}

2.3 项目级上下文工程

为让 AI 高效理解项目，必须在仓库中维护结构化上下文文件。推荐在根目录创建 AI_CONTEXT.md 或 .cursorrules，内容应包含：

1. 项目目标与一句话描述
2. 技术栈与版本（语言、框架、数据库等）
3. 目录结构说明（每个顶层目录的职责）
4. 编码规范（命名约定、Lint 规则、架构模式）
5. 关键模块与接口契约
6. 当前开发阶段与已知限制

此文件需随代码一同版本控制，并作为每次 AI 会话的初始上下文加载。
大型工程必须要写readme文档

3. 阶段一：需求与设计 —— 人类主导，AI 辅助

3.1 需求澄清与规格化

人类任务：

• 编写简单架构，分块思想，每一部分分别负责什么
• 定义功能边界、非功能需求、验收标准。

3.2 架构决策记录（ADR）

人类任务：做出关键架构权衡（单体 vs 微服务、同步 vs 异步、数据库选型等）。

AI 辅助方式：

• 提供对比分析：“我需要为高并发交易系统选择数据库架构，请对比 PostgreSQL 分库分表、TiDB、CockroachDB 的优缺点，并给出决策矩阵。”
• 生成 Mermaid 架构草图，加速沟通。
• 根据决策自动生成 ADR 文档初稿，包含背景、决策、后果、备选方案。

3.3 接口与数据模型设计

给定需求后，可使用如下 Prompt 生成接口定义：

 设计用户管理模块的 API，包含创建、查询、更新、删除
 输出包含路径、方法、请求/响应 JSON Schema、状态码、认证需求

对于数据库 Schema，可要求：

生成符合第三范式的 PostgreSQL DDL，包含字段注释、索引建议、外键约束。

所有生成产物必须由开发者人工检查，确保满足业务约束与安全策略。

---

4. 阶段二：编码实现 —— 严格的分步生成与审查

渐进式生成策略

一次性生成大量代码容易失控，应采用分步推进：

1. 签章先行：先生成函数签名、类型定义、文档字符串，确认接口设计。
2. 骨架填充：生成仅含步骤注释的逻辑轮廓。
3. 逐块实现：对每个步骤逐一要求实现。
4. 测试驱动：先让 AI 生成测试用例，再驱动实现代码。

上下文窗口利用原则

任务规模	上下文策略
单函数修改	仅提供该函数及引用的类型/工具函数
跨文件功能添加	使用插件自动收集最小依赖文件集合
全项目级别重构	先让 AI 分析影响范围，再分批处理；始终带上 AI_CONTEXT.md
长对话会话	每 10 轮左右用“请总结到目前为止的进展与待办”压缩要点，重置上下文

代码审查清单（最重要）

任何 AI 生成的代码进入仓库前，必须逐项通过检查：

• 逻辑正确性：正常路径、异常路径、边界条件。
• 安全性：注入漏洞、认证授权、敏感信息泄露、依赖安全。
• 性能：算法复杂度、数据库查询计划、资源释放。
• 可维护性：命名清晰、职责单一、注释与实现一致、测试覆盖。
• 风格合规：通过 Linter/Formatter，与项目规范一致。

推荐使用 git diff + AI 进行二次审查：

请审查以下 diff，按严重程度列出问题，并给出修复建议。

4.5 安全重构流程

1. 让 AI 识别代码坏味道（圈复杂度、重复代码、过长函数）。
2. 要求给出“小步重构计划”，每一步需说明前置测试保证。
3. 执行重构 → 运行测试 → 提交，每一步均可由 AI 生成具体代码，但必须人工确认。

---

5. 阶段三：测试与调试 —— 系统性提升质量

测试用例自动生成

• 单元测试：提供函数实现，要求“使用 {pytest/JUnit/…} 参数化，覆盖典型值、边界值、异常抛出，共 N 个场景”。
• 集成测试：描述数据流，让 AI 生成端到端测试脚本，包括数据库 fixtures 或 Mock。
• 模糊测试思路：要求分析函数输入空间，指出高风险输入区间，生成初始种子。

调试辅助

• 将错误信息、堆栈跟踪、相关函数源码一并交给 AI，要求定位根因。
• 对于并发/异步 Bug，可描述预期时序与实际表现，AI 能帮助推理竞态窗口。
• 使用“橡皮鸭”模式：让 AI 解释代码逻辑，往往可在解释过程中自我发现问题。

---

6. 阶段四：文档与交付 —— 知识沉淀

6.1 从代码到文档

• 生成 API 文档：提供源码，要求输出 OpenAPI 3.0 规范或 Markdown 手册。
• 生成 README：自动提取项目结构、安装步骤、使用示例。
• 注释补充：对未注释的公共接口，生成符合 JSDoc/Google Docstring 的注释。

6.2 变更管理

• 提供 git log --oneline 输出，AI 自动分类为 Features / Fixes / Chores / Breaking Changes，生成 CHANGELOG.md。
• 根据里程碑生成 Release Note，包含新功能描述、升级注意、贡献者致谢。

---

7. 反模式与风险防控

反模式	实际风险	正确做法
盲目信任生成代码	安全漏洞、逻辑缺陷	严格执行审查清单，零信任策略
一次要求生成整个系统	偏离架构意图，难以验收	分而治之，每步验证
忽略上下文污染	回答质量下降，引入幻觉	定期压缩/重置关键上下文
用 AI 代替官方文档	使用了过时或虚构的 API	生成后必须与官方文档交叉验证
不维护项目上下文文件	AI 每次均需重新探索项目	版本化 AI_CONTEXT.md，强制更新
在敏感项目中使用云端模型	数据泄露风险	使用本地部署模型或严格脱敏

---

8.说点人话 ：

在ai辅助中，最重要的部分就是代码审查，无论是沙箱的openclew，还是编译器的插件类的agent，最重要的是代码审查，ai的代码数据库学到了很多一些奇妙的代码风格比如忽略内存溢出，神秘死循环代码，并且指不定谁在他的github项目里塞的那点史都被ai学过去了，比如最近的api-key泄露等等，如果不想让你的电脑变板砖就不要放掉所有权限，必须人工审查终端命令和ai生成的代码，如果你连内存分配环境配额什么都不懂，对ai编程的理解仅仅停留在全部yes的阶段，还是老老实实用豆包别用openclew装b了

ps:deepseekv4 token 大甩卖，梁圣的恩情还不完

9. 结语

AI 辅助编程的本质，是把开发者从重复性的细节中解放出来，以便投入更高阶的抽象思考与决策。无论选择哪种模型或工具，科学的方法、严谨的流程、持续的人工审查，才是保障软件质量不变的基石。

优秀的工程师不是驾驭工具，而是驾驭复杂性。
AI只是增高了上限，而不是减少了所有人的下限。