用 AI 辅助开发这段时间，我越来越明显地感受到一件事：
AI 最大的问题，往往不是“不会写代码”，而是很容易在需求不清、上下文丢失、过程不可追踪的情况下跑偏。
为了尽量解决这些问题，我尝试整理了一套面向 AI + 人类协作 的项目框架，叫做 Agentic-Project-Framework。
它不是一个单纯的代码仓库，而是一套从 需求、设计、计划、执行、验证到归档 的完整流程，目标是让 AI 协作项目变得 可追踪、可恢复、可交付。
一、为什么我要做这套框架
之所以会有这个想法，是因为我在实际做项目时发现，AI 辅助开发最缺的其实不是“生成代码”的能力，而是“项目治理”的能力。
很多时候，问题并不出在某一行代码上，而是出在整个流程上：
- 需求一开始就不够清楚，AI 会顺着上下文自己补
- 项目做到一半暂停，再回来时上下文容易丢失
- 功能虽然做出来了，但过程没有记录，后面很难复盘
- 需求变更了，却没有统一的修改记录
- 项目越来越大以后，临时沟通很容易把整个协作链条弄乱
这些问题在小任务里可能不明显，但一旦项目稍微复杂一点，或者中途需要暂停、回滚、修改，就会变得非常明显。
所以我开始想：与其每次临时和 AI 对齐，不如直接设计一套统一的项目框架，把需求、设计、计划、执行和归档都固定下来。
这样至少可以保证，项目不会“做着做着就散掉”。
二、这个框架到底解决了什么问题
这套框架最想解决的，其实就是 AI 协作开发里最常见的几个问题：
1. 需求容易漂
很多项目一开始说的是 A，做着做着就变成了 B。
原因往往不是开发能力不行，而是需求本身没有明确边界。
2. 过程容易断
AI 协作很依赖上下文，如果没有记录机制，任务中断后再恢复会很痛苦。
你可能会忘记：
- 上次做到哪一步
- 为什么这么设计
- 这版改动是为了解决什么问题
3. 结果难复盘
很多项目最后虽然“能跑”，但过一段时间以后，你根本说不清：
- 哪些决定是怎么来的
- 哪些地方是临时方案
- 哪些地方以后还能复用
4. 变更容易失控
当需求频繁变化时，如果没有统一的流程，就会出现：
- 一个地方改了，另一个地方忘了改
- 设计文档和实现代码不一致
- 新增功能把旧逻辑冲掉
5. 交付缺少闭环
做完以后如果没有归档，项目就只停留在“做过”，而不是“沉淀过”。
所以，Agentic-Project-Framework 的意义，不是让 AI 写更多代码，而是让 AI 和人一起把一个项目稳定地做完。
三、这个框架是什么
如果要用一句话来定义：
Agentic-Project-Framework 是一套面向 AI + 人类协作的项目治理框架。
它不是：
- 不是单纯的代码仓库
- 不是单纯的文档仓库
- 不是 prompt 集合
- 也不是某种“神奇的 AI 自动化工具”
它更像是一套项目操作系统，把整个开发过程拆成几个清晰的层次，让不同阶段都有对应的产物和记录。
四、我给这套框架设定的几个原则
在整理这套框架的时候，我给自己定了几条原则：
1. Spec-first
先需求，再设计，再计划。
不要一上来就直接开写代码。
2. Evidence-first
所有关键结论都尽量有记录、有依据。
不要只靠聊天记录和临时记忆。
3. Traceable
每一个关键决策都能追踪。
比如为什么这么设计、为什么改成这样。
4. Recoverable
项目中断以后能接着做。
不会因为上下文没了就完全重来。
5. Reusable
流程、模板、规范都尽量可复用。
不要每次都从零开始。
6. Isolated work
复杂任务尽量隔离处理。
避免上下文污染，把问题拆小、拆清楚。
五、仓库结构是怎么设计的
这套框架最核心的一点，是把不同类型的信息放到不同目录里，让项目的生命周期更清晰。
1. project/
这里放的是项目画像，主要包括：
- 项目目标
- 技术栈
- 团队约束
- 适用范围
- 统一规范
这一层相当于项目的“说明书”。
2. specs/
这里放的是需求和设计相关文档，比如：
- 需求说明
- 产品规格说明
- 设计文档
- 执行计划
- 变更请求
- 中断恢复信息
这一层的作用是把“想做什么、为什么做、怎么做”写清楚。
3. rules/
这里放的是规则和约束，比如：
- 代码风格
- 测试要求
- 安全基线
- 质量门禁
- AI 协作规范
这一层的作用是保证项目不会因为协作对象不同而标准不一致。
4. skills/
这里放的是可复用的工作流能力，比如：
- brainstorm
- spec writing
- design review
- plan writing
- debugging
- code review
- finishing branch
你可以把它理解为：
给 AI 和团队准备的一组标准化“操作技能”。
5. logs/
这里放的是过程记录，比如：
- 任务日志
- 变更日志
- 验证日志
- 决策日志
这一层很重要，因为它解决的是“事后能不能追溯”的问题。
6. archives/
这里放的是最终沉淀：
- 最终版本
- 已完成的文档
- 关键结论
- 交付结果
项目做完以后，不只是结束，而是沉淀。
7. examples/
这里放的是示例：
- 示例项目
- 示例任务
- 示例变更
- 示例模板
这一层主要是为了让新成员或者后来的人能快速上手。
六、一次完整闭环是怎么跑的
这套框架不是只有目录，而是有完整流程的。
我把它理解成一个从头到尾的闭环：
1. 收到需求
先不要急着做，先确认：
- 要解决什么问题
- 目标是什么
- 约束是什么
- 什么不做
如果一开始边界不清，后面会很难收住。
2. Brainstorm
这一步是发散思考：
- 有没有更好的方案
- 这个问题有没有隐藏前提
- 是否存在更简单的实现方式
不是直接拍板，而是先把可能性展开。
3. 写 Product Spec
把需求写成清晰的规格说明：
- 功能目标
- 使用场景
- 输入输出
- 验收标准
- 非目标
这一步的意义是让“我们到底要做什么”不再模糊。
4. 写 Design Doc
在需求明确后，开始设计方案：
- 数据结构怎么设计
- 模块怎么拆
- 接口怎么定义
- 异常怎么处理
- 风险点有哪些
这一步对应的是“怎么做”。
5. 写 Exec Plan
把设计拆成可执行任务：
- 任务顺序
- 每一步的目标
- 每一步的依赖关系
- 预估风险
这一步对应的是“按什么顺序做”。
6. 开始执行
根据计划开发、修改、验证。
执行过程中不只是写代码，还要留痕。
7. 测试与验证
看结果是否满足需求：
- 功能是否正确
- 是否有回归
- 是否满足验收标准
- 是否存在明显风险
8. 质量检查
确认是否达到交付标准：
- 代码是否规范
- 文档是否完整
- 变更是否可追踪
- 结果是否可复用
9. 归档
最后把关键内容沉淀下来：
- 结果归档
- 过程归档
- 经验归档
这样以后遇到类似问题时，不需要重新摸索。
七、一个很现实的例子
举个简单例子，假设你要做一个“用户登录功能”。
如果没有框架，常见情况可能是：
- 先让 AI 直接写接口
- 中间发现要加验证码
- 又发现要加 token
- 再发现前端状态管理没接上
- 最后虽然能跑，但过程非常乱
而如果按照框架来：
第一步：先写需求
明确：
- 登录方式是什么
- 账号密码还是验证码
- 是否需要记住登录状态
- 是否需要失败限制
第二步：写设计
明确：
- 接口怎么设计
- token 怎么生成
- 失败怎么处理
- 前端怎么保存状态
第三步：写计划
拆成：
- 后端接口
- 前端表单
- 状态管理
- 错误提示
- 测试用例
第四步：执行 + 记录
每一步都留痕，方便后面追踪。
第五步：归档
以后如果再做注册、重置密码、权限管理，就能直接复用这一套思路。
你会发现，框架真正带来的不是“更快写完”，而是更稳定、更可控、更容易复用。
八、它适合谁，不适合谁
适合的人
这套框架比较适合：
- AI 辅助开发项目
- 多人协作项目
- 长周期项目
- 需要追踪和复盘的项目
- 经常发生变更的项目
不太适合的人
如果你只是：
- 写一个一次性小脚本
- 做一个临时任务
- 只想快速验证一个想法
那这套框架可能会显得有点重。
也就是说，它不是给所有任务准备的，而是给需要稳定交付的项目准备的。
九、如果你也想落地，建议怎么开始
如果你也想自己做一套类似的东西，我建议不要一开始就做得很大。
第一步：先做 specs/
先把需求文档和设计文档写起来。
这是最关键的基础。
第二步：加上 logs/
让过程可追踪。
哪怕只是简单记录，也比没有强。
第三步：再补 archives/
把最终结果收起来，形成沉淀。
第四步：逐步补全 rules/ 和 skills/
等前面跑顺了，再逐渐加入规范和能力模板。
第五步：先跑一个小项目
不要一上来就想把框架做得特别完整。
先让它真的跑通一次，比什么都重要。
十、我自己的下一步想法
这套框架现在还在持续完善中。
我后面可能会继续补充：
- 更多模板
- 更多示例项目
- 更细的变更流程
- 更明确的验证机制
- 更适合 AI 协作的标准工作流
我希望它最后不是一个“看起来很完整”的仓库，而是真正能帮助我和别人把项目做稳的工具。
结语
最后也想坦白说一下，这套 Agentic-Project-Framework 虽然已经整理出了一套比较完整的结构，但我自己其实还只是一个在摸索阶段的新人，很多地方肯定还有考虑不周、设计不够成熟，甚至有些细节是我现在还没意识到的。
所以这篇文章更像是我在实践过程中的一次阶段性总结，而不是一个“已经完全定型”的标准答案。
如果你对这个框架感兴趣，或者也在做 AI 协作开发，欢迎来我的 GitHub 看看目前的实现和整理内容：
GitHub： github.com/whchim/Agen…
我也很希望能通过持续迭代，把这个项目慢慢补完整。
如果你在阅读过程中发现了更好的思路、遗漏的地方，或者有更适合 AI 协作开发的做法，也欢迎交流指正。
对我来说，这个项目不仅是一个实践记录，也是一个不断学习、不断修正的过程。
