当前位置：首页 > news >正文

AI驱动的软件工程（中）：文档驱动的编码与执行

news 2025/7/14 5:48:06

📚 系列文章导航
AI驱动的软件工程（上）：人机协同的设计与建模
AI驱动的软件工程（中）：文档驱动的编码与执行
AI驱动的软件工程（下）：AI辅助的质检与交付（待更新）

大家好，我是阿威。

在上一篇文章 《人机协同的设计与建模》 中，我们探讨了如何与AI协作，将一个模糊的想法，通过一个结构化的三阶段流程，打磨成一套完整、严谨的设计蓝图。我们得到了《需求规格说明书》、《系统设计说明书》以及每个模块的《详细设计说明书》。

这套设计文档，是我们项目的坚实地基。但一个更严峻、也更令人兴奋的挑战随之而来：我们能把这套蓝图直接交给AI，让它自己来完成所有的编码实现吗？

如果你的经验和我最初一样，那么答案可能是否定的。直接把设计文档丢给一个通用的AI助手，然后说“照着这个去写代码”，结果往往是一场灾难。AI会很快忘记文档的细节，它会用自己“喜欢”的方式组织代码，它会在不同模块间创造出不一致的接口。最终，你得到的会是一个难以维护的、拼接起来的“代码怪兽”。

问题出在哪里？问题在于，我们只给了AI一张“地图”（设计文档），却没有给它一套“导航系统和驾驶手册”（开发流程与规范）。一个人类开发者拿到设计文档后，会运用自己脑中的整个软件工程知识体系——版本控制、代码规范、测试、日志记录——来进行工作。而AI的脑中，没有这些隐性的纪律。

要让AI成为真正的核心开发者，我们就必须为它显式地构建这一整套工程纪律。

这就是我在这篇文章中要分享的核心方法论：AIDC（AI-Driven Development and Collaboration）。它的精髓在于，我们不依赖AI那短暂、不可靠的内置记忆，而是通过一系列外部化的文档，为它打造一个持久的“外部大脑”和一套强制执行的“行为准则”。我们不再请求它“写代码”，而是指令它“遵循流程”。

欢迎来到整个体系的“发动机舱”。在这里，我们将见证，设计蓝图是如何被一个遵循严格纪律的AI，一行行地转化为真实可用的代码。

AIDC方法论：为AI打造开发“熔炉”

AIDC的核心，是承认并正视AI的固有局限性，然后用工程化的手段去系统性地解决它们。这个方法论建立在四大原则之上，它们共同构成了一个足以熔炼出高质量代码的“开发熔炉”。

1. 外部化记忆 (Externalized Memory)
AI的记忆是昂贵且善变的。因此，我们将所有关键信息——需求、设计、计划、规范、甚至开发过程中的每一次提交记录——全部持久化为项目内的Markdown文档。这些文档共同构成了AI的“外部长期记忆”。在每一次执行任务前，AI的第一个动作，必须是“阅读”这些记忆。

2. 指令驱动执行 (Instruction-Driven Execution)
我们与AI的交互，不再是开放式的“对话”，而是明确的“指令下达”。通过一份我称之为“标准作业程序（SOP）”的文档，我们将AI的每一步操作都固化为可预测、可重复的指令。这从根本上杜绝了AI在执行任务时的随机性和行为偏差。

3. 自动化守卫 (Automated Guardians)
我绝不会浪费时间去检查AI写的代码有没有遵循PEP8，或者括号是不是对齐了。这些低级但重要的工作，必须交由自动化工具来强制执行。通过在流程中嵌入Linter、格式化器、类型检查器等工具，我们为项目建立了一道“自动化防线”，AI必须自己确保它的产出能通过这道防线。

4. 人机角色明确 (Defined Human-AI Roles)
在编码阶段，我们的角色再次转换。我不再是“架构师”，而是**“项目经理”和“代码审查者”。我负责下达高级别的开发任务（比如“去实现这个模块”），并在关键节点审查代码的业务逻辑。而AI的角色，则是“软件开发者”和“DevOps助理”**，它负责执行SOP中定义的所有具体、繁琐的战术操作。

基于这四大原则，AIDC的开发生命周期被划分为四个清晰的阶段。

阶段一我们已经完成。现在，我们从阶段二开始，看看如何一步步为AI铺设好轨道。

奠基与初始化：AI的第一次DevOps任务

在正式编码前，我需要AI为我创建一个专业、规范的开发环境。这本身就是对AIDC方法论的一次小型演练。

我会给AI下达第一个指令：

“根据我们已经完成的设计，请初始化AgentWeaver项目。你需要：

创建标准的项目目录结构（例如 agentweaver/, docs/, tests/）。
将我们之前生成的所有设计文档，归档到 docs/ 目录下。
初始化Git仓库。
创建一份专业的 .gitignore 文件、一份包含基础依赖的 requirements.txt 和一份包含项目简介的 README.md。”

AI会像一个DevOps助理一样，使用它的文件操作和终端工具，精确地完成这些任务。这个过程的产出，是一个结构清晰、已纳入版本控制的项目仓库骨架。更重要的是，它让AI从一开始就进入了“被指令、被管理”的工作模式。

规范与流程定义：锻造AI的“SOP”

这是整个方法论最核心、最关键的一步。我们要在这里，和AI一起，创造出未来将要严格“统治”AI自身行为的一系列“法律文件”。这些文件将构成它的“外部大脑”，是后续所有开发活动的基石。

我会指示AI创建以下几份核心治理文档：

《AI开发者标准工作流程(SOP).md》：这是给AI自己看的“用户手册”，是“指令驱动执行”原则的最终体现。它用最明确的指令语言，规定了AI从接收任务到完成提交的每一个步骤。后文我们会详细拆解这份SOP的内容。

# AI 开发者标准工作流程 (SOP)**版本: 1.0**## 1. 核心指令本文档是指导你在 AgentWeaver 项目中执行开发任务的标准操作流程（SOP）。**你必须严格、完整地遵循以下所有步骤**。在每个新会话开始时，用户会将此文档作为核心指令提供给你。---## 2. 阶段一：上下文同步与理解 (强制执行)在开始任何编码之前，你必须首先完成对项目状态的全面同步。这是强制性步骤，不可跳过或部分执行。-   **指令 1.1：理解高层设计**-   [ ] 读取并完全理解 `docs/需求规格说明书.md`。-   [ ] 读取并完全理解 `docs/概要设计说明书.md`。-   **指令 1.2：理解模块详细设计**-   [ ] 读取并完全理解当前任务分配的模块详细设计文档，例如 `docs/详细设计-X-模块名.md`。-   **指令 1.3：遵循开发规范**-   [ ] 读取并完全理解 `docs/开发编码规范.md` 。你后续的所有代码输出都**必须**严格遵守此规范。-   **指令 1.4：回顾开发历史**-   [ ] 读取并完全理解 `docs/开发日志.md` ，了解项目此前的关键决策和问题。-   **指令 1.5：明确当前进度**-   [ ] 读取并完全理解 `docs/项目开发计划.md` ，找到你将要开发的任务条目，明确其当前状态和依赖关系。---## 3. 阶段二：计划制定与任务执行在完全理解上下文后，开始进行计划和编码。-   **指令 2.1：制定开发计划**-   [ ] 基于以上所有文档，为你当前要开发的模块制定一个详细的、分步骤的执行计划。-   [ ] **必须**使用你的 `todo_write` 工具，将此计划转化为一个代办事项清单。清单的粒度应足够细，例如到**函数级别**或**接口级别**。-   **指令 2.2：执行开发任务**-   [ ] 严格按照你创建的代办事项清单，逐项完成开发。-   [ ] 使用 `edit_file` 工具进行编码。-   [ ] 每完成一个清单项，立即使用 `todo_write` 工具更新其状态为 `completed`。---## 4. 阶段三：代码验证与版本提交在模块核心功能开发完成后，或在每个有意义的节点，执行以下验证和提交流程。-   **指令 3.1：代码质量检查**-   [ ] **必须**使用 `run_terminal_cmd` 工具执行以下命令：1.  格式化代码: `black .`2.  静态检查与修复: `ruff check . --fix`-   [ ] 如果命令执行后报告任何错误，你**必须**修复它们，并重新运行检查，直到所有检查都通过。-   **指令 3.2：提交到版本控制**-   [ ] 使用 `run_terminal_cmd` 工具执行 `git add .`。-   [ ] 执行 `git commit`。**提交信息（commit message）必须严格遵循以下格式**：-   **格式**: `<类型>(<范围>): <主题>`-   **示例**: `feat(api): 实现创建任务的POST端点`-   **类型**: `feat` (新功能), `fix` (bug修复), `docs` (文档), `style` (格式), `refactor` (重构), `test` (测试), `chore` (构建或工具)。-   **主题**: **必须使用中文书写**，简明扼要地描述本次提交的内容。---## 5. 阶段四：项目状态归档与更新每次成功提交后，你**必须**立即更新项目的状态记录，以确保信息的实时同步。-   **指令 4.1：更新开发日志**-   [ ] 使用 `edit_file` 工具打开 `docs/开发日志.md`。-   [ ] **必须**在文件**末尾追加一行**，记录本次开发。**严禁修改历史日志**。格式如下：-   `YYYY-MM-DD HH:MM - <模块名>: <本次开发的简要总结，包括遇到的关键问题和解决方案>`-   **指令 4.2：更新项目开发计划**-   [ ] 使用 `edit_file` 工具打开 `docs/项目开发计划.md`。-   [ ] 找到与本次开发相关的任务条目（可以是模块、功能或接口）。-   [ ] 将其状态从“待开发”更新为“**完成**”。-   [ ] 如果开发中遇到问题导致阻塞，则更新为“**搁置**”或“**错误**”，并**必须**在同一行附上简要原因。---
**流程结束。此工作流是确保你高效、可靠地参与本项目的核心。请在每次会话中严格遵循。**

《项目开发计划.md》：这是一个高阶的路线图。我会让AI基于《系统设计说明书》中的模块列表，生成这份计划。它通常是一个Markdown表格，包含模块名、负责人（默认是AI）、状态（如：待开发、进行中、完成）、依赖关系和预计完成日期。这份文档是“外部化记忆”的一部分，用于宏观地追踪项目进度。

该项目计划文档完全由AI自主生成并在开发完成某个模块时遵循《AI开发者标准工作流程(SOP).md》规则自主更新，无需人类干预

《开发日志.md》：这是一份严格按时间顺序、只增不改的日志文件。我要求AI在每一次代码提交后，都必须在这里追加一行记录，注明时间、开发的模块，以及对本次工作的简要总结。这份日志提供了宝贵的、可追溯的开发历史。

开发日志文档也完全由AI遵循《AI开发者标准工作流程(SOP).md》自主生成、更新

《开发编码规范.md》：这份文档定义了代码风格、命名约定、注释标准等。我会提供一些初步的规则，然后让AI将其扩充和完善，并保存成正式文档。在后续的开发中，AI必须严格遵守这份它自己参与制定的规范。

该规范文档由人类指导AI完成，在AI进行编码时会依据《AI开发者标准工作流程(SOP).md》定义的流程规则完全遵守该开发编码规范

当这四份文档创建完成后，我们就拥有了一套完整的项目治理体系。AI不再是一个自由的“艺术家”，而是一个有法可依、有章可循的“工程师”。

迭代开发循环：SOP驱动下的AI一日

现在，万事俱备。我们终于可以进入激动人心的编码阶段了。让我们以开发“AIFactory”模块为例，完整地走一遍AI在SOP驱动下的标准工作流程。

我的任务下达过程非常简单，我只需要对AI说：

“任务：实现‘AIFactory’模块。请严格遵循《AI开发者标准工作流程(SOP)》进行操作。”

接下来，所有事情都将由AI根据SOP自动完成。

步骤一：上下文同步（强制）

这是SOP中的第一条，也是最重要的一条指令。AI必须首先阅读所有相关的“记忆”文档，以构建完整的上下文。它会依次执行：

读取 docs/需求规格说明书.md
读取 docs/系统设计说明书.md
读取 docs/详细设计-AIFactory模块.md （本次任务的核心依据）
读取 docs/开发编码规范.md
读取 docs/开发日志.md （了解历史）
读取 docs/项目开发计划.md （明确当前任务的位置）

这个看似冗余的步骤，恰恰是解决AI“失忆症”的唯一有效方法。它确保了AI在开始工作时，脑子里装的是项目的全局视图，而不仅仅是我刚刚下达的一句简单指令。

步骤二：制定计划（TODO List）

在完全理解了上下文之后，SOP指令AI进行任务分解。
AI会基于详细设计-AIFactory模块.md中的内容，使用它的todo_write工具，为自己生成一份细粒度的、精确到函数级别的执行计划。

这份TODO清单可能会是这样：

[ ] 在 agentweaver/core/ 目录下创建 ai_factory.py 文件。
[ ] 在 ai_factory.py 中定义抽象基类 BaseLLM。
[ ] 实现 OpenAIModel 类，继承自 BaseLLM。
[ ] 实现 LocalHFModel 类，继承自 BaseLLM。
[ ] 实现核心类 AIFactory。
[ ] 在 AIFactory 中实现 register_model 方法。
[ ] 在 AIFactory 中实现核心方法 get_model，包含缓存逻辑。
[ ] 为模块添加必要的异常类，如 ModelNotFoundError。

这份清单不仅让任务的执行过程变得透明、可控，也再次强化了AI的短期记忆，让它对即将开始的工作有了清晰的步骤规划。

步骤三：执行编码

AI会严格按照它自己创建的清单，逐项进行编码。它会使用edit_file工具，一次只专注于一个最小化的任务，比如创建文件、实现一个类或一个方法。

每当它完成一项，比如实现了BaseLLM类，它就会再次调用todo_write工具，将对应项的状态更新为completed。

[x] 在 agentweaver/core/ 目录下创建 ai_factory.py 文件。
[x] 在 ai_factory.py 中定义抽象基类 BaseLLM。
[ ] 实现 OpenAIModel 类，继承自 BaseLLM。
…

这个过程会一直持续，直到清单上的所有任务都被勾选完成。

步骤四：自我检查（自动化守卫）

在模块的核心功能编码完成后，SOP中一个强制性的验证流程被触发。
AI必须使用run_terminal_cmd工具，在项目根目录下执行以下命令：

black . (代码格式化)
ruff check . --fix (静态检查与自动修复)

如果这些命令返回任何错误或警告，SOP要求AI必须自行修复这些问题，然后重新运行检查，直到所有检查都干净通过。我，作为人类，完全不需要介入这个过程。自动化工具成为了保证代码基础质量的第一道，也是最有效的一道防线。

步骤五：版本提交

通过所有自动化检查后，代码进入了提交阶段。
SOP要求AI使用run_terminal_cmd工具执行git add .和git commit。

其中，commit message必须严格遵循我在《开发编码规范.md》中定义的格式。
例如：feat(core): 实现AI工厂模块的核心功能

类型(type): feat (新功能), fix (bug修复), docs (文档) 等。
范围(scope): 影响的模块，如core, api。
主题(subject): 用中文简明扼要地描述本次提交。

这种规范化的提交信息，使得我们的Git历史清晰、可读，为未来的代码考古和自动化工具集成打下了良好基础。

步骤六：状态归档

一次成功的提交，并不意味着一个开发循环的结束。SOP的最后一步，也是“外部化记忆”原则的最后一道保障，是让AI立即更新项目的状态记录。

AI会使用edit_file工具，执行两个操作：

更新开发日志: 在docs/开发日志.md文件的末尾追加一行新记录，严禁修改历史。

2023-10-27 15:30 - AIFactory模块: 完成了核心功能的开发，包括模型注册和基于配置的动态加载。关键是实现了缓存机制以提高性能。
更新项目开发计划: 在docs/项目开发计划.md中，找到“AIFactory模块”这一行，将其状态从“进行中”更新为“完成”。

至此，一个完整的、闭环的、可追溯的开发循环才算真正结束。从上下文同步到状态归档，每一步都在SOP的严格规定下进行，AI的行为是可预测的，其产出是高质量且符合规范的。