面向 AI 协作开发的完整工作流
总体原则
整个流程遵循几个默认原则：
-
先澄清问题，再设计方案，再写代码。
-
先调研已有实现，再决定是否自研。
-
优先复用成熟生态、成熟库、成熟代码库，减少重复造轮子。
-
技术选型优先低复杂度、低维护成本、易交付方案。
-
如无必要，不引入更高工程复杂度的语言和框架。
- 例如：能用 Python 完成，就优先不选 Rust。
-
聊天记录用于探索，文档用于定稿，执行以文档为准。
Phase 0 — Idea Capture：捕获模糊想法
这一阶段的输入可以非常不完整：
- 几个关键词
- 一个模糊场景
- 一个问题感受
- 一个想做的东西
- 一个别人家的产品印象
例如：
- “想做一个研究笔记整理工具”
- “想把大模型接到 Obsidian”
- “希望自动整理证券账户里的现金管理”
- “想做一个轻量级 agent 平台”
这时候不要直接进入实现，也不要急着定技术栈。
这一阶段的目标只有一个：
把模糊意图变成可讨论的问题陈述。
AI 在这一阶段主要做：
- 帮你把模糊想法转成一句较清楚的问题定义
- 区分“目标”“约束”“猜测”“偏好”
- 提出明显缺失的信息
- 识别这是产品问题、工程问题、自动化问题，还是研究问题
这一阶段的产物建议是：
brief.md
内容可以很轻，主要包括：
- 初始想法
- 目标场景
- 已知约束
- 未知问题
- 暂不确定事项
结束条件：
- 已经能说清楚“想解决什么问题”
- 已经知道下一步该围绕什么去讨论
Phase 1 — Clarification：需求澄清与问题收敛
这一阶段通过和 AI 对话，把需求越辩越明。
重点不是让 AI 直接给答案，而是让 AI 帮你把这些东西逐渐说准：
- 真实目标是什么
- 为什么要做这个
- 谁来用
- 在什么场景下用
- 现有痛点是什么
- 成功标准是什么
- 有哪些硬约束
- 哪些内容不在范围内
- 哪些只是“想要”，不是“必须”
这一阶段还要特别区分两类东西：
1. 必须满足的约束
比如：
- 必须本地运行
- 必须离线
- 必须兼容已有仓库
- 必须低开发成本
- 必须可由单人维护
2. 可以权衡的偏好
比如：
- 最好有 GUI
- 最好跨平台
- 最好性能高一点
- 最好语言优雅一点
这一步非常重要，因为很多项目会把“偏好”误当成“硬约束”，然后导致过度设计。
这一阶段的产物可以继续写进 brief.md，也可以升级成：
requirements.md
建议内容包括：
- 问题定义
- 目标
- 非目标
- 用户与场景
- 约束
- 验收标准雏形
- 尚未回答的问题
结束条件：
- 核心需求已经比较清楚
- 主要歧义已经暴露出来
- 可以进入调研，而不是闭门造车
Phase 2 — Research：调研已有实现、现有生态与可复用资源
这一阶段的核心问题不是“我能不能做”，而是：
这个问题别人是否已经做过？做到了什么程度？哪些东西可以直接复用？哪些地方才值得自己做？
这里要调研四类东西：
2.1 现有产品 / 现有项目
查有没有现成工具、开源项目、SaaS、插件、框架已经覆盖了大部分需求。
关注点：
- 是否已经存在成熟方案
- 功能做到哪一步
- 是否满足核心需求
- 是否还差关键能力
- 是否可以通过二次开发满足需求
2.2 可复用的代码库 / SDK / 库
查生态里有没有成熟库能直接解决关键子问题。
例如：
- Web 框架
- LLM SDK
- 文档解析
- 向量检索
- GUI 框架
- 数据处理
- 调度系统
- 权限与认证
- 配置管理
关注点：
- 成熟度
- 社区活跃度
- 维护状态
- 文档质量
- 学习成本
- 与现有技术栈兼容性
2.3 技术选型与复杂度评估
不是只看“能不能做”，而是看“值不值得这样做”。
例如：
- Python 能否满足性能与交付要求
- 是否真的需要 Rust / Go / C++
- 是否真的需要微服务
- 是否真的需要数据库
- 是否真的需要前后端分离
- 是否真的需要 agent 框架
默认原则是：
如果 Python + 现有成熟库足以满足需求，就不要为了性能想象或语言偏好引入 Rust。
只有在这些情况才考虑更高复杂度技术栈：
- 性能瓶颈是核心问题且已被证明
- 安全/系统级控制有硬需求
- 部署环境明确要求
- 团队已有成熟能力和维护基础
- 低复杂度方案确实无法满足目标
2.4 复用 vs 自研边界
这一阶段要明确划线：
- 哪些部分直接采用现有方案
- 哪些部分基于现有方案扩展
- 哪些部分必须自己做
- 哪些部分暂时不做
这是避免重复造轮子的关键。
这一阶段的产物建议单独保存为：
research.md
建议结构：
# Research
## 1. Problem Summary
本次要解决的问题概述
## 2. Existing Solutions
已有产品 / 开源实现 / 同类项目
## 3. Reusable Libraries / Frameworks
可复用库、框架、SDK、工具链
## 4. Comparison
各候选方案对比：成熟度、复杂度、成本、限制
## 5. Reuse Strategy
哪些直接复用，哪些扩展，哪些自研
## 6. Tech Stack Recommendation
推荐技术栈，以及为什么
## 7. Rejected Options
放弃的方案及原因
## 8. Open Questions
仍待确认的问题结束条件：
- 已知是否存在成熟实现
- 已知哪些部分应复用
- 已知技术选型的大方向
- 已知哪些地方才值得自己写
Phase 3 — Solution Design：在调研基础上形成完整方案
这个阶段才开始真正写方案。
注意，这里的方案不应该是“凭空设计”，而应该是：
在需求澄清 + 调研复用 + 技术取舍之后，形成的一版完整、可审阅、可落地的设计。
这一阶段的目标是产出 proposal.md 草稿。
proposal.md 应回答这些问题：
- 背景是什么
- 目标是什么
- 为什么这样做
- 为什么不选其他方案
- 哪些东西复用了现有生态
- 哪些地方自己实现
- 系统边界在哪里
- 风险与边界条件是什么
- 如何验收
建议结构：
# Proposal
## 1. Background
## 2. Goal
## 3. Non-goals
## 4. Constraints
## 5. Research Summary
## 6. Reuse Strategy
## 7. Proposed Architecture / Approach
## 8. Tech Stack
## 9. Alternatives Considered
## 10. Risks / Edge Cases
## 11. Acceptance Criteria
## 12. Open Questions这里特别建议把两节写清楚：
Research Summary
把 research.md 的核心结论压缩进来，不必重写全部细节，但要说明：
- 市面上/社区里已有实现到哪一步
- 为什么不直接用它们
- 为什么选择当前路径
Reuse Strategy
明确写：
- 直接复用什么
- 在什么基础上扩展
- 哪些模块自己实现
- 为什么这样划分
结束条件：
proposal.md已经完整、自洽- 不依赖聊天记录也能被人读懂
- 方案体现了调研结果，而不是闭门造车
Phase 4 — Human Review：人类审阅方案并提出修改意见
这一步仍然非常关键，因为 AI 能帮你补细节、补结构、补逻辑，但最终取舍仍然要由人来定。
人类审阅时重点关注：
- 目标有没有说准
- 有没有范围膨胀
- 调研结论是否充分
- 是否真的最大化复用了成熟生态
- 是否存在重复造轮子
- 技术选型是否过重
- 是否为了“工程感”引入了不必要复杂度
- 是否忽略了真实交付成本
- 验收标准是否清楚
尤其要审这两个问题：
1. 是否过度自研
很多方案的问题不是“做不到”，而是“没必要自己做”。
2. 是否过度选型
很多方案的问题不是“语言不够强”，而是“复杂度远超需求”。
所以这一阶段的审阅重点可以概括为一句话：
这个方案是不是已经足够复用、足够简单、足够可交付。
AI 在这一阶段负责：
- 根据人类反馈修订
proposal.md - 不重写已确认部分
- 只针对争议点和缺漏点迭代
结束条件：
- 核心设计、复用策略、技术选型、范围边界都已确认
Phase 5 — Freeze：冻结最终方案，生成正式 proposal.md
到这一步，方案进入冻结状态。
核心原则：
后续执行默认以 proposal.md 为唯一方案依据。
也就是说：
- 聊天记录只作为背景参考
- 真正的执行标准是
proposal.md - 如果后面发现重大偏差，应先更新
proposal.md，再继续
冻结前建议再过一遍这几个检查项：
- 目标是否明确
- 非目标是否明确
- 调研结论是否已吸收
- 复用策略是否明确
- 技术选型是否合理
- 风险与边界是否明确
- 验收标准是否明确
产物：
- 最终版
proposal.md
Phase 6 — Planning：根据 proposal.md 生成执行文档 todo.md
这一步是把“设计文档”转换成“执行文档”。
两者分工要非常明确：
proposal.md负责说明：做什么、为什么这么做todo.md负责说明：先做什么、后做什么、每步做到什么程度
todo.md 不应该只是普通 checklist，而应当是能直接指导 AI 编码工作的任务计划。
建议包含：
# TODO
## 0. Execution Rules
- proposal.md 是唯一方案依据
- 若执行中发现方案冲突，先更新 proposal.md
- 不擅自扩展范围
- 优先复用已有依赖与现有项目结构
## 1. Setup
- [ ] 确认项目结构
- [ ] 确认已有依赖和可复用模块
- [ ] 确认入口、配置、测试方式
## 2. Tasks
### Task 2.1
- Status:
- Goal:
- Based on proposal:
- Reuse:
- Files:
- Changes:
- Done when:
- Risks:
### Task 2.2
...我建议每个任务都加一个字段：
Reuse
明确这一步是：
- 直接使用现有组件
- 基于现有模块扩展
- 新写少量 glue code
- 必须自研
这个字段非常有用，因为它能持续提醒 AI：
不是每一步都从零写。
结束条件：
proposal.md已被拆成一组可执行、可验证、可跟踪的任务- 每项任务都知道应该复用什么，而不是盲目自写
Phase 7 — Execution：按 todo.md 执行并持续同步文档
到这里才进入真正编码阶段。
执行时遵循三个原则：
7.1 先按 proposal，再按 todo
- 设计看
proposal.md - 执行看
todo.md
7.2 如果发现现实与方案冲突，不要硬写
应该：
- 发现冲突
- 回到
proposal.md修正方案 - 更新
todo.md - 再继续执行
7.3 继续坚持“优先复用、优先简单”
执行中很容易又掉回“顺手多写一点”的习惯，所以要持续约束：
- 能调用成熟库就不要重写
- 能扩展现有模块就不要再造一套
- 能用 Python 实现就不要因为偏好切到更高复杂度语言
- 能用单体清楚表达就不要提前拆复杂架构
执行阶段的产物包括：
- 代码变更
- 更新后的
todo.md - 如有必要，更新后的
proposal.md
最终闭环
所以更完整的闭环应该是：
模糊想法 → 需求澄清 → 调研已有实现与生态 → 形成方案 → 人类审阅 → 冻结 proposal.md → 拆成 todo.md → 执行 → 发现冲突时回写 proposal 和 todo → 继续执行
这套流程中建议固定存在的文档
建议至少保留这四个文件：
1. brief.md
用于记录最初的想法、场景、约束和未知问题。
偏探索，不要求完整。
2. research.md
用于记录已有实现、生态、可复用资源、技术选型比较、复用策略。
这是“避免重复造轮子”的核心文档。
3. proposal.md
用于记录最终方案与设计决策。
这是后续执行的单一事实来源。
4. todo.md
用于记录实际执行任务。
这是直接指导 AI 干活的文档。
补充:用于限制编码风格的prompt
请仅将以下内容作为编码行为约束来执行；无需额外说明、总结或汇报，直接按这些原则编写或修改代码。
你生成的代码必须同时满足 “Human-friendly（人类友好）” 和 “AI-friendly（AI 友好）” 两个目标。
一、总体原则
- 以正确性为最高优先级。
- 在满足需求的前提下，优先选择简单、稳定、可验证、可维护的实现。
- 不要为了“显得高级”而引入不必要的抽象、设计模式、包装层、技巧性写法或第三方依赖。
- 不要擅自改变未被明确要求的接口、行为、输入输出格式、目录结构、配置方式或技术栈。
- 对已有代码进行修改时，优先采用“最小充分改动”原则：只修改解决问题所必需的部分，不重写无关代码，不做无关重构，不制造大面积 diff 噪声。
- 所有新增或修改的代码都应当服务于当前任务，不引入与任务无关的“顺手优化”。
二、Human-friendly（人类友好）的具体含义
生成的代码应便于人类工程师阅读、理解、调试、审查和长期维护。具体要求如下：
1. 命名
- 变量、函数、类、模块名必须准确、稳定、可理解。
- 命名应直接反映语义，不使用晦涩缩写，除非该缩写在上下文中是行业或项目内的标准术语。
- 同类概念使用统一命名风格，避免同义不同名或同名不同义。
2. 结构
- 保持代码结构自然、线性、清晰；优先使用容易跟踪的控制流。
- 避免不必要的深层嵌套、链式技巧、过短但难懂的写法、过度函数式化或过度元编程。
- 每个函数/模块应承担单一而清晰的职责；避免一个函数同时处理多种不相关任务。
- 新增逻辑应放在最合理、最容易被维护者找到的位置。
3. 可维护性
- 显式处理边界条件、异常情况、空值、失败路径和资源清理。
- 不依赖隐式副作用、脆弱顺序、魔法默认值或隐藏状态。
- 能写清楚的逻辑不要藏在技巧里；能显式表达的约束不要依赖调用者“默认知道”。
4. 注释
- 在代码文件开头加入简要说明，说明该文件/模块的用途、核心思路、主要输入输出或使用方式。
- 在关键逻辑、边界处理、容易误解的分支、重要设计选择处加入必要注释。
- 注释应解释“意图、原因、约束、边界”，而不是逐行翻译代码表面行为。
- 不要写冗余注释、噪声注释、显而易见的注释。
三、AI-friendly（AI 友好）的具体含义
生成的代码应便于后续模型继续定位、理解、补丁、扩展和重构，并尽可能降低未来自动修改时的失控风险。具体要求如下：
1. 可定位性
- 代码组织应让后续修改点容易定位：相关逻辑尽量集中，避免把同一功能拆得过碎、散落在多个不明显位置。
- 新增逻辑尽量局部化，不把无关改动混入同一次修改中。
- 保持模块边界清楚，让后续工具容易判断“哪里该改、哪里不该改”。
2. 可预测性
- 接口、参数、返回值、异常行为应清晰一致，减少模糊约定和隐式契约。
- 避免“聪明但脆弱”的代码写法，避免高度依赖上下文猜测的实现。
- 尽量减少隐式耦合、跨层副作用、魔法注册、动态注入、非必要反射、过度元编程等会降低后续修改稳定性的机制。
3. 可增量修改
- 修改已有代码时，尽量保持原有结构、命名体系和代码风格稳定，除非当前任务明确要求调整。
- 不随意大规模重排代码、批量改名、混入无关格式化，避免后续 diff 难以理解。
- 优先做局部、可回滚、可验证的改动，使未来继续补丁时能建立在当前改动之上。
4. 可恢复上下文
- 通过清晰命名、合理函数边界、必要注释和显式错误处理，让后续模型即使只读取局部代码，也能较快恢复上下文。
- 重要假设、边界约束、非直观行为应体现在代码结构或注释中，而不是只依赖外部说明。
- 不把关键规则藏在难以察觉的常量、隐式状态或调用顺序里。
四、实现细则
- 新代码必须完整、可运行、可集成，不省略必要的导入、辅助函数、类型定义、初始化或清理逻辑。
- 若是对现有代码补丁，优先保持原有接口和调用方式不变；如确需改变，应仅在任务明确要求或技术上不可避免时才这样做。
- 除非任务明确要求，否则不要主动引入新依赖、新框架、新配置文件、新目录层级。
- 优先使用项目现有约定、现有风格、现有工具链。
- 若存在多种可行实现，优先选择最直接、最清晰、最稳健、最容易被人类和后续 AI 继续维护的一种。
- 对性能、资源管理、并发、安全、输入校验等问题，在任务相关时必须显式考虑，而不是默认忽略。
- 对潜在错误输入或不合法状态，优先选择显式防御而不是静默失败。
- 不保留占位实现、伪代码、TODO 式空壳，除非任务明确允许。
- 不为了“统一风格”而重写无关旧代码；仅让新增和修改部分与周围代码自然一致。
五、在不同任务类型下的补充约束
1. 新文件 / 新模块
- 文件开头必须有简要头部说明。
- 先建立清晰骨架，再填入实现；模块职责不要模糊。
- 公共接口优先稳定、明确、低耦合。
2. 修改已有代码
- 先遵循最小充分改动原则。
- 优先修复根因，而不是在表面叠加补丁。
- 不改动与当前问题无关的旧逻辑、旧命名、旧结构。
- 保持与现有项目风格、目录、调用方式一致。
3. 重构
- 只有在任务明确要求重构，或不重构就无法正确实现任务时，才进行结构性调整。
- 重构必须保留原有行为，减少一次性引入的变化面。
- 重构后的结构要比原来更易读、更易维护、更易继续被 AI 修改，而不是更“炫”。
六、最终编码风格目标
你的代码应当表现出以下特征：
- 对人类：一眼能看懂用途，顺着读能理解逻辑，出问题时容易排查，半年后回来还能维护。
- 对 AI：局部上下文足够清楚，修改点容易定位，行为边界明确，后续继续补丁时不需要大面积重新推断结构。