本文约 4000 字，分享我在开源 WebCAD 项目中实践 Human-AI 协作工程化的全过程。文章所有案例均来自仓库 firestige/alu_frame_forge,欢迎对照阅读。
引言：从“灵感助手”到“协作产线”需要什么？
过去一年，AI 编程工具像浪潮一样席卷整个行业。几乎每个开发者都把 Copilot、Claude 或 Llama 放在侧边栏，随时抛出一句提示词就能获得一段看似可用的代码。然而，我在实践中越来越清楚地意识到：AI 的问题从来不在于“能不能写代码”，而在于“是否能稳定写对代码”。如果没有工程化约束，AI 极容易制造出结构混乱的代码、冲突的状态管理以及无法复现的 Bug。许多人因此得出“AI 不靠谱”的结论，但我认为真正的问题是“我们缺了一套能够约束 AI 的协作方法”。
为了验证这个观点，我发起了一个完全开源的个人项目：在浏览器里构建一套三维设计器 alu_frame_forge。截至 2025-12-08，仓库记录了 96 次提交、约 16,689 行 TypeScript/TSX 代码和 16,674 行方法论文档，其中 93% 的代码由 AI 生成。我没有把 AI 当成“黑盒自动化工具”，而是尝试把它纳入工程体系，通过文档、流程和度量把它改造成可靠的结对伙伴。本文会把这段经历拆解成可复制的策略，帮助你在团队或个人项目中建立类似的“Human-AI 协作产线”。
背景：AI 编程的真实风险
许多朋友在尝试 AI 编程时，会经历四类常见挫败：
- 架构不可控：AI 会根据自己的偏好组织目录和模块，导致命名混乱、抽象层级断裂。一次随手的 Prompt 可能直接毁掉既有的分层结构。
- 需求不可证：需求往往停留在聊天记录或会议纪要里，AI 实现后缺少可验证的追踪链路。产品和测试只能凭直觉判断功能是否完成。
- 错误不可追：当 AI 生成的代码出错时，人类开发者很难还原 AI 当时的意图，Bug 追踪需要大量猜测和手工排查。
- 经验不可复用：即便偶尔成功，也往往因为缺少沉淀，下一次仍旧需要从零开始调 Prompt，效率难以提升。
我在项目初期同样踩过这些坑：AI 会在 React 组件里直接操作 WebGL 状态，或者把核心服务写在 pages 目录下；需求完成与否全凭“肉眼感觉”；每次排错都像是在重新理解一个陌生人的代码。这些经历最终促使我转向“文档驱动 + 流程约束”的探索。核心理念很简单：如果我们希望 AI 像熟练协作者一样工作，就必须为它提供可执行的规范、可追溯的上下文以及可复盘的反馈机制。
核心方法：文档即约束、分层上下文、错误闭环
方法一：把文档写成 AI 可执行的 ArchitecturePrompt
传统架构文档是写给人看的，它依赖经验和语境。但 AI 无法理解暗示，它需要明确、结构化的指令。因此我把整个架构和编码准则写进了 doc/ArchitecturePrompt.md，内容包含模块职责、命名约定、状态边界和禁止项。例如：
- “Core 层只暴露服务接口，禁止直接操作全局状态”
- “Features 层必须通过服务调用 Core，不允许跨越层级访问”
- “任何涉及 3D 引擎的调用必须通过
renderer子模块完成”
这个 Prompt 会在每次与 Copilot/Claude 对话前粘贴到对话窗口，确保 AI 先读取约束再生成代码。实践下来，AI 生成的文件结构与命名几乎 100% 符合设定，Review 的主要精力转向业务逻辑而非基础架构纠错。更重要的是，任何新增约束都可以在文档中版本化记录，形成“约束-代码-验证”的闭环。
方法二：三层上下文管理，让角色各得其所
我把项目上下文拆成三个层级：
- 战略层：长期不变的内容，如 ArchitecturePrompt、MethodologyFramework、MultiAgentWorkflow。这些文件像“宪法”，定义了协作的基本规则。
- 战术层：迭代期内稳定的内容，如 WorkPlan、QuantitativeAnalysis、ProjectTimeline。它们描述了阶段目标、度量指标和进度快照。
- 执行层：随任务变化的内容，如具体 Prompt、DevelopLog、对话记录。
这种分层带来两点好处：一是不同角色可以直达自己关心的信息，产品和测试在 WorkPlan 中就能看到需求拆分和验收标准；二是 AI 每次只需要喝到相关层级的上下文，减少冗余输入，提高指令一致性。每当上下文发生变化时，我会通过 DevelopLog 记录“变更原因 → 新约束 → 影响范围”，让任何后来者都能快速接手。
方法三：四步错误诊断流程，出现一次错误就改进一次系统
AI 生成错误往往不是因为“不会写”，而是因为“没有被正确约束”。因此每当出现问题，我都会按以下流程处理：
- 复现：从用户视角还原触发路径，录制或记录具体操作。
- 锁定：通过 Git Diff 确认问题文件，关联到具体提交。
- 追溯：在 DevelopLog 或对话记录中找到当时的 Prompt，分析指令是否模糊或缺失约束。
- 修复：更新代码、Prompt 以及相关文档，确保相同问题不会再次出现。
例如，在 Task #3 中，AI 直接在 Toolbar 模块里操作 EventBus，打破了“Command 必须通过服务层调度”的规则。我按照四步流程复盘后，将“禁止直接操作 EventBus”写入 ArchitecturePrompt，并在开发脚本里加入检测。之后同类问题再也没有出现。这种“错误即改进输入”的方式，让 AI 协作的可靠性随着实践不断提高。
实践案例：从架构纠错到知识沉淀
案例一：架构纠错如何一步步变成可复用模板
在实现设计器工具栏时，AI 生成的代码把状态逻辑写在 UI 组件内部，导致 Core 层失去控制。按照错误诊断流程处理后，我不仅修复了代码，还把整个过程写进 DevelopLog.md：包含复现步骤、问题根因、修复提交和 Prompt 更新。随后，这份记录又被整理进 CaseStudyTemplate.md，成为分享材料的一部分。现在每当团队里有人问“AI 写错了怎么复盘”，我只需要把这个案例链接给他即可。
案例二：复杂功能如何拆解成连续的 AI 交付
构建三维场景的相机控制和命令工具栏是一项“高耦合、多状态”的工作。如果完全交给 AI，它很容易把逻辑写得支离破碎。我的做法是先让 AI 输出“数据流图 + 事件流说明”，再按文件粒度逐个生成：服务层、Store、组件、测试。每个步骤都引用了 WorkPlan 中的子任务，确保需求可追踪。最终，这个复杂功能在四天内完成，代码全部符合既定架构，测试也能直接复用生成的交互脚本。
案例三：知识沉淀让个人项目也能像团队一样扩散
项目的每一次重大突破都会被转换成不同形式的产出：面向面试的 ResumeSection.md、面向部门分享的 TeamSharing.md、面向公开社区的 PublicTalk-Script.md。这些文件并不是简单的总结，而是带着路径、数据和可验证链接的“复制手册”。这意味着即便是个人项目，也可以用团队级别的方式积累经验，任何人只要 clone 仓库就能看到“约束 → 代码 → 结果”的完整证据链。
效果与反思：进行中的实验，初见成效
为了避免“故事化”或“神话化”，我一直坚持用数据来衡量 AI 协作的价值：
- 提交数与代码量：32 天内完成 96 次提交，新增约 16,689 行代码。虽然效率提升显著，但更重要的是这些提交都可以被文档追踪。
- AI 参与比例：约 93% 的代码由 AI 生成，人类的主要精力转移到约束设计、架构审查和验证上。
- 返工率：通过错误诊断流程，重复错误数量显著下降，架构层面的返工几乎归零。
- 文档对代码的覆盖：几乎每个核心模块都能在文档中找到来源、目的和关联的 Prompt。
当然，项目仍在进行中，也存在局限：
- 维护成本：保持文档和约束的同步需要持续投入，尤其在快速迭代时必须警惕“文档滞后”。
- 模型差异：不同模型对约束的遵循度不同，需要花时间评估与分工，例如让 Claude 负责架构推理、Copilot 负责 TS 代码。
- 团队协作验证：目前是个人实践，虽然已创建可复制模板，但仍需与更多团队合作验证在多人环境下的可行性。
我把这种状态称为“进行中的实验，初见成效”。它尚未成为标准，但已经证明了“AI 可控”是一条可走的路。
结论：AI 协作的未来属于工程化
如果要用一句话概括这段旅程，那就是：**AI 不是用来取代程序员的，它是用来放大小型团队、甚至个人开发者的工程能力的。**只要我们愿意把注意力放在约束、上下文和反馈系统上，就能把 AI 从随机灵感机器转化为稳定产出的协作者。
我鼓励每一位正在探索 AI 编程的开发者尝试以下步骤：
- 写一份 ArchitecturePrompt，把你对架构的期望转换成 AI 可执行的语言。
- 建立多层文档结构，让不同角色都能找到自己的“单一事实来源”。
- 为每一次错误撰写复盘，更新 Prompt 和文档，把失败变成资产。
- 在 GitHub 或团队内部分享这些流程，让更多人参与改进。
alu_frame_forge 这个项目会继续演进。我也会把新的发现、成功和失败都记录在仓库里。如果你正在寻找一份可验证的 AI 协作实践，或者想一起推进“文档即约束”的落地，欢迎到 Issue 区或者 PR 中交流。让我们把“AI 产出不可控”这件事，变成过去式。
