一、什么是文档驱动？

文档驱动是一种开发方法论：先写文档，后写代码。

说到主要思路。在动手实现之前，先用自然语言把“要做什么、怎么做、边界在哪里”描述清楚，接下来以文档为合同来驱动实现。

与测试驱动的对比

主要价值 & 使用者痛点嵌入

1. 迫使提前思考写文档时才会发现“我其实没想清楚这个场景”，从而避免了后期大量返工的痛点。话说回来，
2. 对齐成本前置在写代码前拉对齐。而不是代码写完再争论需求，减少沟通成本。
3. 契约优先文档即合同。调用方可以并行开发，消除接口不一致导致的集成难题。
4. 降低返工率改文档比改代码便宜得多，解决了维护成本高的问题。
5. User Pain Point 1：项目中常出现“需求变更导致上线延迟”的情况，文档先行可将变更风险降到最低。
6. User Pain Point 2：团队成员因缺少统一规范导致实现不一致，采用文档驱动可形成全局共识。
7. User Pain Point 3：技术债务堆积，使得新功能上线困难；通过完整契约可快速定位和修复。

传统流程 vs 文档驱动流程

从`非文档驱动来看，需求 → 实现代码 → 写文档（事后补充，容易腐烂)` 再看`文档驱动。需求 → 写文档 → 评审对齐 → 实现代码 → 文档与代码同步校验`

二、写文档即思考 — 痛点剖析与实践建议

"写完后再说" 的做法往往导致:

• 发现问题时已投入数天甚至数周的实现工作；修改代价高昂，不过，在编写阶段即完成需求描述，可把发现问题的代价降到几行文字的编辑。
  
• 团队认为“写文件浪费时间”，但它是减少后期冲突的关键。将 “写文件” 与 “评审” 合并为一个工作流，以此提高整体效率。不过，
• 缺乏持续同步导致业务理解偏差。在每一次迭代前进行“同步评审”，确保所有人对同一版本保持一致。

三、AI 文档驱动的主要机制 — 如何让 AI 成为你的最佳伙伴?

Ai 的加入。让“良好的文档”能自动补充提问信息，将模糊的提问 为精确的问题。没有足够上下文化身就像给 AI 一个孤立的问题； 有了完善的项目文件夹，AI 就能提供针对性的答案。从而明显提高产出质量和速度。

AI 文档驱动工作流

`写文档→ 提问 AI → 核查结果 → 发现问题 → 调整策略写入文档 → 下次更高效`

• AI 回答偏离实际需求时往往需要人工反复校正；通过继续调整 “Plan” 能显著减少这一步骤所需时间。

项目结构拆分 —— 两个角色协同工作

• Doc 项目: 包含枚举定义、表结构、proto 定义及业务方法描述——这份内容是给 AI 和开发者阅读的“说明书”。按理说，
• Code 项目: 包含实际业务实现——执行层面实现 Doc 项目里所描述的一切功能。

四、三层级式架构 — 从机器可执行到人类易读，再到 AI 可理解

再看第一层。可执行契约

`maldini-proto/services/{svc}/{svc}.proto` 是整个程序的主要契约，不仅是接口说明，更是编译器验证标准。Truss 与 gogoproto 等工具会根据它生成骨架代码。一旦字段号或类型变更就会直接报错，为团队提供即时安全网。

第二层这方面。人类可读业务规格

• `maldini-proto/services/{svc}/docs/{resource}.md`: 接口说明书及表结构预览，在实现之前就已存在为开发者和产品经理提供统一视图。

• `maldini-proto/services/{svc}/{svc}.json`: 枚举定义。用于生成 Go 常量，让类型安全成为可能。

• .claude/plans/: 用于记录业务分析与讨论上下文化。同步团队共识，在功能上线后可以归纳清理，只保留最有价值的信息。

第三层的观点是，驱动 AI 行为的规则文件

📌 User Pain Point 1：The team often faces “无规范导致集成失败”的困境，此机制通过明确禁止手工改 .pb.go 来消除该风险。话说回来，

📌 User Pain Point 2：The team spends too much time on manual field mapping during feature sync;our rule files automate this step.

📌 User Pain Point 3：The lack of a shared contract leads to duplicate work across teams;using proto as a single source of truth solves this.

五、完整流转链路 — 从需求到最终交付

需求讨论 ↓ 思考成熟后业务规格 ↓ proto 契约化机器可执行合同 ↓ truss + TestGen* 骨架代码 ↓ AI 按 commands/ 流程执领域务实现 （domain/ + handlers/ + router/) ↓ /apipost skill 推送 Apipost ↓其他协作方直接查阅调试

两种最终产物分别服务不同受众：

计划文件 plans/

注意事项

markdown

• Plan 模式审查 ：多文件改动时务必在 AI 执行前生成临时 Plan 输出，仔细审查 Plan 确认无误再放行。

• Windows CLI 调整 ：默认 CMD 新标签页默认使用者跟目录不友好；调整为从项目终端启动以保证初始工作目录一致。