这是我在过去一段时间里反复验证、迭代出的一套与 AI 协作开发小工具的完整方法。它不需要你是一个资深程序员（比如我本人就是个产品经理），但它能帮你像一个拥有完整开发团队一样，从零到一交付一个可用的产品。
注：本文由碳基生物口述，硅基生物整理，硅基含量60%
写在前面
很多人用 AI 写代码的方式是：打开对话框，说一句"帮我写一个XXX工具"，然后把生成的代码复制粘贴，跑不通就再问一句，如此循环。
这种方式的问题在于——你把 AI 当成了一个代码片段生成器，而不是一个可以承担完整工程角色的协作者。
我的核心思路是：用"角色扮演 + 文档驱动"的方式，让 AI 在一个项目中依次扮演高级开发、产品经理、架构师、前端工程师、后端工程师、测试工程师和项目经理，通过一系列标准化文档将整个开发流程串联起来。
整个过程分为五个阶段：
阶段一：与 AI 进行需求对话——让想法从模糊变清晰
核心理念
你脑海里的 idea 几乎一定是模糊的。你可能知道"我想做一个XX"，但你不清楚交互细节、边界情况、技术选型。而这些模糊地带，恰恰是项目后期返工的最大根源。
所以第一步，不是让 AI 动手写代码，而是让它扮演一个高级开发工程师，跟你进行多轮对话，把所有需求细节"逼"出来。
具体做法
打开一个新的 AI 对话，使用如下 Prompt 开场：
"你现在是一位拥有 10 年经验的高级全栈开发工程师。我有一个工具的想法想和你讨论。请你不要急于给出方案，而是像一个负责任的技术合伙人一样，针对我的描述，不断追问细节、挑战我的假设、帮我理清需求边界。我们的目标是：在对话结束时，所有的功能需求、交互细节、技术约束都已经清晰无歧义。"
然后你只需要描述你的想法，哪怕只有一句话。比如：
"我想做一个 Chrome 插件，可以一键把网页内容总结成笔记，保存到我的 Notion 里。"
AI 会开始追问你一系列问题：
- 目标用户是谁？只有你自己用，还是要给别人用？
- "网页内容"的范围是什么？是全文？还是用户选中的部分？如果是文章类网页，要不要自动提取正文？
- "总结"的粒度是什么？摘要？要点列表？还是用户可以选择？
- Notion 的哪个数据库？页面结构是什么样的？
- 离线场景怎么办？Notion API 调不通时怎么处理？
- 是否需要登录态？OAuth 还是直接填 Token？
- ……
关键原则：你需要老老实实地回答每一个问题，不要跳过，不要说"先不管这个"。 你在这里偷的每一个懒，都会变成后面开发阶段的混乱。
这个对话通常会持续 20-40 轮。当 AI 开始说"我认为需求已经比较清晰了，我来帮你整理一下"的时候，这个阶段就可以收尾了。
我的实际经验
在我的实践中，几乎每次都会在这个环节被 AI 问到我从未想过的问题。有一次我想做一个"自动整理浏览器书签"的工具，AI 问我："如果两个书签的 URL 不同但内容高度相似（比如同一篇文章的不同转载），你算它们是重复的吗？"——这个问题直接改变了我整个工具的去重逻辑设计。
阶段二：将对话整理成 PRD.md——从对话到文档
核心理念
对话是线性的、零散的，而文档是结构化的、可回溯的。PRD（产品需求文档）是整个项目后续所有工作的"单一事实来源"（Single Source of Truth）。 后续 AI 扮演的每一个角色，都将以这份文档为基准来工作。
具体做法
在需求对话接近尾声时，直接告诉 AI：
"请根据我们刚才的所有对话，整理一份完整的产品需求文档（PRD.md）。要求包含以下章节：项目概述、目标用户、核心功能列表（按优先级排列）、详细功能描述（含交互细节和边界情况）、非功能性需求（性能、安全、兼容性等）、技术约束与假设、暂不实现的功能（明确标注）、术语表。"
PRD.md 应包含的核心结构
| 章节 | 内容说明 |
|---|---|
| 项目概述 | 一段话说清楚这个工具是什么、解决什么问题 |
| 目标用户 | 谁会用它、在什么场景下用 |
| 核心功能列表 | P0 / P1 / P2 分级，每个功能一句话描述 |
| 详细功能描述 | 每个功能的交互流程、输入输出、异常处理 |
| 非功能性需求 | 性能指标、安全要求、浏览器兼容性等 |
| 技术约束 | 比如"必须用 React"、"后端用 Cloudflare Workers" |
| 不做的事 | 明确写出"这个版本不做什么"，防止范围蔓延 |
| 术语表 | 对齐双方（你和 AI）对关键术语的理解 |
为什么这一步至关重要
很多人会觉得"我跟 AI 聊完了，它应该都记住了，直接开始写代码不就行了？"
不行。原因有三：
- AI 的上下文窗口有限，长对话中早期的信息可能被"遗忘"或降权。
- 文档是可以跨会话传递的，你可以在新的对话中直接喂入 PRD.md，让 AI 从零开始就拥有完整上下文。
- 文档是你审查需求的最后机会。当需求以文档形式呈现时，你经常能发现对话中遗漏的矛盾和空白。
拿到 PRD.md 后，务必通读一遍，用你自己的话检验每个功能描述是否与你的预期一致。 发现问题，直接在文档上修改或与 AI 再讨论一轮。
阶段三：基于 PRD 生成架构与设计文档——让 AI 当你的技术团队
核心理念
这一步是整个流程中信息密度最高的环节。你要让 AI 分别戴上不同的"帽子"，从不同的专业视角审视同一份 PRD，产出多份互相关联的技术文档。这些文档的作用不是给人看的——它们是给后续执行阶段的 AI "看"的。
需要生成的文档清单
你需要在这个阶段产出以下文档（通常每个文档开一轮新对话，带入 PRD.md 作为上下文）：
1. 前端设计原则文档 frontend-guidelines.md
Prompt 示例：
"你现在是一位资深前端架构师。请阅读附件中的 PRD.md，并输出一份前端设计原则文档。内容需包含：UI/UX 设计规范（配色、字体、间距体系）、组件设计原则、状态管理策略、响应式方案、无障碍（a11y）标准、前端性能预算。"
这份文档确保了 AI 在后续编写前端代码时，不会每个组件的风格都不一样，也不会做出交互不一致的 UI。
2. 后端架构原则文档 backend-guidelines.md
Prompt 示例：
"你现在是一位资深后端架构师。请阅读 PRD.md，输出后端架构原则文档。内容需包含：技术栈选型及理由、API 设计规范（RESTful / GraphQL）、数据库 Schema 设计、认证与授权方案、错误处理规范、日志规范、部署方案。"
3. 整体架构设计文档 architecture.md
Prompt 示例：
"你现在是系统架构师。请基于 PRD.md、frontend-guidelines.md 和 backend-guidelines.md，输出一份整体架构设计文档。包含系统架构图（用文字描述即可）、模块划分、数据流向、第三方服务集成方案、关键技术决策记录（ADR）。"
4. 项目开发规范 claude.md（或叫 dev-rules.md）
这是一份"写给 AI 的规矩"，它的作用类似于团队的编码规范，但专门针对 AI 的行为特点进行了优化。
核心内容应包含：
- 代码风格：缩进、命名规范、文件命名规范
- 绝对禁止事项：比如"不要使用 any 类型"、"不要硬编码密钥"、"不要删除已有的注释"
- AI 特别注意事项：比如"修改代码时，只修改必要部分，不要重写整个文件"、"每次修改后列出所有改动点"
- Git commit 规范
- 文件组织结构
这份文档是我整个方法论中最被低估但最有价值的一环。 没有它，AI 在执行阶段会"自作主张"，比如你让它改一个 bug，它顺手把你的代码结构重构了；你让它加一个功能，它把你之前的某个逻辑偷偷改了。有了这份文档，你可以在每次对话开头带入它，相当于给 AI 戴上了"紧箍咒"。
5. 测试文档 test-plan.md
Prompt 示例：
"你现在是一位高级 QA 工程师。请阅读 PRD.md 和架构设计文档，输出一份测试计划。包含：测试策略（单元测试 / 集成测试 / E2E 测试的覆盖范围）、核心功能的测试用例列表（含正常流程和异常流程）、性能测试方案、验收标准。"
文档之间的关系
所有文档共同构成一个完整的"项目知识库"。 后续每次让 AI 执行具体的开发任务时，你需要将相关文档作为上下文提供给它。这就是"文档驱动开发"的核心——AI 的表现上限，取决于你提供的上下文质量。
阶段四：任务拆解——让 AI 当你的项目经理
核心理念
再好的架构设计，如果不拆成可执行的、有序的、粒度合适的任务，执行的时候还是会乱。这一步的目标是产出一份 todo-list.md，它既是你的施工图纸，也是 AI 的执行指令集。
具体做法
Prompt 示例：
"你现在是一位经验丰富的项目经理。请阅读以下所有文档：PRD.md、architecture.md、frontend-guidelines.md、backend-guidelines.md、test-plan.md、claude.md。请将整个项目的开发工作拆解为一份 todo-list.md，要求：
1. 按开发顺序排列（考虑依赖关系） 2. 每个任务的粒度控制在 AI 单次对话可以完成的范围内 3. 每个任务需注明：任务描述、输入文件、输出文件、验收标准 4. 对于 AI 执行时容易出错的环节，用 ⚠️ 标注特别提醒 5. 使用 checkbox 格式，方便逐项勾选"
todo-list.md 的样式参考
## Phase 1: 项目初始化
- [x] 任务 1.1: 初始化项目结构
- 描述: 按照 architecture.md 中的目录结构创建项目骨架
- 输出: 完整的目录结构 + package.json
- 验收: 能成功运行 npm install
- [ ] 任务 1.2: 配置开发环境
- 描述: ESLint + Prettier + TypeScript 配置
- 输入: claude.md 中的代码规范章节
- ⚠️ 注意: TS 配置中 strict 必须为 true，不要用 any
## Phase 2: 核心功能开发
- [ ] 任务 2.1: 实现用户认证模块
- 描述: 按照 backend-guidelines.md 的认证方案实现
- ⚠️ 注意: Token 不要硬编码，必须从环境变量读取
- 验收: 单元测试全部通过
...
# 你的工作流程：
1. 得到todo之后，先根据todo的内容，判断是增加功能还是修改功能，并在PRD.md 中基于todo更新PRD
2. IMPLEMENTATION_PLAN.md 中基于todo更新实现计划
3. 具体开发工作需要基于specs中的所有文档指导来进行
4. 每次执行一条 ##任务列表 中未完成的任务，并在任务完成时，对这个任务标记已完成，移动到 ##已完成任务 列表中
5. 修改代码后，需要进行单元测试，如果没有通过单元测试，则需要调整优化代码
6. 在 specs 的各个文档中同步需求变更，确保所有文档都能及时更新
7. 完成上一条任务执行后，需要继续执行任务，直到所有任务都标记【已完成】
8. 需要特别关注lessons.md 中记录的过去的错误，需要严格避免
关于"⚠️ AI 特别注意"标注
这是我在反复实践中总结出的一个非常关键的技巧。AI 在执行具体编码任务时，有一些"高频翻车点"：
- 覆盖已有代码：你让它改 A 功能，它可能把 B 功能的代码也改了
- 遗忘上下文中的约束：你在 claude.md 里说了"不要用 any"，它在第 15 个任务时又开始用了
- 自作主张添加功能：你让它实现一个简单的列表，它给你加了排序、搜索、分页
- 忽略错误处理：happy path 写得很好，异常情况完全没处理
在 todo-list.md 中提前标注这些风险点，相当于在每个关键路口提前立了路标。
同时准备两份空文档
在正式开始执行任务之前，先创建两份空文档：
lessons.md —— 错误清单与解决方案
# Lessons Learned
## [日期] 问题简述
- 现象:
- 根因:
- 解决方案:
- 经验规则: （提炼为一条可复用的规则，后续加入 claude.md）
这份文档的核心价值在于"经验规则"这一栏。 踩坑后，如果发现是可以被抽象成规则的“坑”，你应当把解决方案抽象成一条通用规则，然后反向补充到 claude.md 中。这样，随着项目推进，你的开发规范会越来越完善，AI 犯同样错误的概率会越来越低。这是一个自我进化的正反馈循环。
举个真实的例子：
我在某次开发中发现，AI 每次修改某个组件时，都会把我手动调整过的 CSS 样式覆盖掉。我把这个问题记录到
lessons.md后，提炼出一条规则："修改组件逻辑时，不要触碰已有的 style 部分；如需修改样式，必须单独说明并获得确认。" 然后把它加进了claude.md。从那之后，这个问题再也没有出现过。
buglist.md —— Bug 追踪表
# Bug List
## BUG-001: [Bug 标题]
- 发现日期:
- 严重程度: P0 / P1 / P2
- 复现步骤:
1.
2.
3.
- 期望行为:
- 实际行为:
- 关联任务: todo-list.md 中的任务编号
- 状态: 🔴 待修复 / 🟡 修复中 / 🟢 已修复 / ✅ 已验证
- 修复方案:
#你的工作
1. 从#bug List中，选择未解决的任务解决，直到bug完全被解决，将已经解决的任务标注为已解决，移动到##已解决任务，格式为：`- [x] 任务描述`
1. 记录本次错误和原因到specs/lessons.md，格式参考文档中现有的格式内容，未来需要严格避免
你可能会问：一个小工具至于用这么正式的 Bug 追踪格式吗？
至于。 原因不在于流程本身，而在于你需要给 AI 提供精确的 Bug 上下文。当你对 AI 说"首页有个 bug，你修一下"时，它大概率会修出新的 bug。但当你把上面这份结构化的 Bug 描述喂给它时，它的修复准确率会大幅提升。Bug 描述的质量直接决定了修复的质量。 并且通过将bug原因记录在lessons中，可以让AI避免再次犯错。
此时你的项目文件夹应该长这样
my-tool/
├── docs/
│ ├── PRD.md # 产品需求文档
│ ├── architecture.md # 架构设计文档
│ ├── frontend-guidelines.md # 前端设计原则
│ ├── backend-guidelines.md # 后端架构原则
│ ├── test-plan.md # 测试计划
│ ├── claude.md # 开发规范（AI 的"紧箍咒"）
│ ├── todo-list.md # 任务清单
│ ├── lessons.md # 经验教训（初始为空）
│ └── buglist.md # Bug 清单（初始为空）
└── src/ # 代码目录（即将开始填充）
请注意：到目前为止，你还没有写过一行代码。 但你已经拥有了一个比大多数个人项目都完善的项目文档体系。这不是过度工程化——这是在为后续的"AI 自动化执行"铺路。没有这些文档，你就只能一行行手动指挥 AI 干活；有了这些文档，你可以批量地、可预测地驱动 AI 完成任务。
阶段五：迭代验收——边用边修，循环收敛
核心理念
终于到了写代码的阶段。但这个阶段的核心不是"写"，而是"验"。你的角色从需求方、设计者，正式转变为验收者和质量把关人。AI 负责执行 todo-list.md 中的每一项任务，你负责逐项验收、发现问题、记录问题、驱动修复。
整个阶段是一个循环：执行 → 验收 → 记录 → 修复 → 再验收。 通常需要 3-5 轮循环才能达到"可用"的状态。
执行阶段的工作流
每个 Step 的详细操作
Step 1 & 2：选取任务 + 构建上下文
不要指望 AI 记住之前所有的对话。 每次开始一个新任务（或者新的对话窗口），你都应该提供以下上下文：
我正在开发 [项目名称]。以下是项目的核心文档：
- claude.md（开发规范）：[粘贴或附件]
- 当前任务来自 todo-list.md 的任务 X.X：[粘贴任务描述]
- 相关架构设计：[粘贴 architecture.md 中相关章节]
- 当前已有代码：[粘贴相关文件]
请严格按照 claude.md 的规范执行该任务。完成后列出所有修改点。
"完成后列出所有修改点"——这句话非常重要。 它强制 AI 给你一份变更清单，你可以逐项检查，而不是大海捞针地 diff 代码。
Step 3：AI 执行
让 AI 生成代码。如果任务比较复杂，可以要求它先输出实现思路，确认后再写代码。这能避免它朝一个错误的方向写了一大堆代码之后再推倒重来。
经验法则：单个任务的代码修改量尽量控制在 200 行以内。 如果 AI 一次生成了 500+ 行代码，基本上验收时你一定会发现问题，而且你很难定位问题出在哪里。如果预计代码量较大，说明任务拆解的粒度不够细，应该回去拆分 todo-list.md。
Step 4：你来验收
验收不只是"跑起来没报错"。你应该对照 todo-list.md 中该任务的验收标准逐条检查：
- 功能是否正确：核心逻辑是否符合 PRD 描述？
- 边界情况：空输入、超长输入、并发请求……PRD 中标注的异常场景是否都处理了？
- 代码质量：是否符合
claude.md的规范？有没有 hardcode？有没有遗留的 TODO？ - 没有副作用：之前已经通过验收的功能是否仍然正常？（这一点极其容易被忽略）
Step 5：记录问题并循环
发现问题后，不要急于口头描述让 AI 修。先做两件事：
- 判断是 Bug 还是 Lesson
-
- 如果是代码写错了、逻辑有问题 → 记录到
buglist.md - 如果是 AI 的行为模式问题（比如又覆盖了不该碰的代码）→ 记录到
lessons.md，并更新claude.md
- 如果是代码写错了、逻辑有问题 → 记录到
- 结构化描述问题，然后再开始修复对话
验收轮次的典型节奏
根据我的经验，整个验收过程通常会呈现这样的节奏： 第 1-2 轮：Bug 高发期。主要是功能逻辑的问题，以及 AI 没有正确理解 PRD 中某些细节导致的偏差。这个阶段你会频繁更新 buglist.md。
第 2-3 轮：优化需求爆发期。基本功能跑通后，你开始实际使用，发现"这里加个提示更好"、"那里的交互不够顺畅"。这些优化点会被追加到 todo-list.md 中。
第 3-4 轮：收敛期。Bug 数量明显减少，优化点也趋于稳定。lessons.md 中积累了足够的经验规则，claude.md 也被打磨得越来越精准，AI 的输出质量显著提高。
第 4-5 轮：收尾期。只剩下零星的小问题和 UI 微调。此时你应该做一次全面的回归测试——按照 test-plan.md 中的用例，从头到尾跑一遍。
知道什么时候停下来
一个小工具不需要做到完美。我的判断标准是：
- 所有 P0 功能正常工作，经过至少 2 轮无 Bug 验证
- P1 功能基本可用，已知问题都已记录
- 没有数据丢失或安全风险
- 你自己愿意每天用它
满足以上条件，就可以宣布 v1.0 完成。那些遗留的 P2 优化点和 nice-to-have 功能，放到 todo-list.md 的 "Future" 章节里，留给下一个迭代。
完整流程全景图
几点核心感悟
1. 文档先行，杠杆很高
很多人觉得"写这么多文档，我自己都能把代码写完了"。但这个类比是错误的——你不是在给自己写文档，你是在给一个拥有超强执行力但缺乏主动判断力的"员工"写工作手册。 文档写得越精确，这个"员工"的表现就越好。
2. 角色扮演不是噱头，是认知框架
让 AI 扮演"前端架构师"和"后端架构师"分别输出文档，并不只是为了好玩。当你给 AI 一个明确的角色时，它会激活与该角色相关的知识权重，输出的内容会更加专业和聚焦。一个"全栈"的泛泛回答，永远不如两个"专家"的分别回答来得深入。
3. claude.md 是整个体系的灵魂
如果你只能保留一份文档，我建议保留 claude.md。它是你与 AI 之间的"契约"，是你对 AI 行为的所有期望的结晶。一个好的 claude.md 可以跨项目复用——你做完这个工具后，下一个工具可以直接在它的基础上迭代。它会变成你个人的"AI 协作操作系统"。
4. 验收能力比编码能力更重要
在这套工作流中，你几乎不需要自己写代码，但你必须能看懂代码在做什么、能判断它对不对。你的角色是"技术负责人"——不是你亲手盖房子，而是你检查每一面墙是否砌直了。 如果你完全不懂编程，我建议至少花几天时间学会阅读代码的基本能力。
5. 小步快跑优于一步到位
不要试图在一次对话里让 AI 完成所有功能。每次只做一件事，做完就验收，验收通过再做下一件。 这不仅让你更容易定位问题，也让 AI 在更小的范围内保持更高的准确率。
6. 谨慎用于复杂项目
不多解释啦
结语
这套方法论的本质是：把 AI 从"对话工具"升级为"项目协作者"，用文档驱动代替口头驱动，用角色分工代替笼统指令，用迭代验收代替一次性交付。
它不完美。它需要你花时间准备文档，需要你有耐心逐项验收，需要你在过程中不断反思和优化。但它有效——它让一个人可以用周末的时间，交付一个过去需要一个小团队花几周才能完成的工具。
这不是关于 AI 有多强大的故事。这是关于你如何组织和驾驭 AI 的能力的故事。
而这个能力，才是 AI 时代最值钱的技能。
这是"我的 AI 最佳实践"系列的第一篇。后续我还会分享更多关于如何高效利用 AI 的方法论，敬请期待。
