夜雨聆风文档先行、任务驱动、人机协同、持续收敛
AI原生研发范式 · 完整协作流程
这套工作流不仅严格遵循文档中的阶段划分，更将Spec、Design、issues三大核心文档载体与Agent in the loop、Human in the loop机制深度融合，旨在完整体现文档所倡导的"通过强约束上下文降低返工成本、提升交付确定性"的核心价值。
一、工作流全景视图
这套协作工作流的本质是一个"文档先行、任务驱动、人机协同、持续收敛"的闭环系统。其核心链路如下：
🎯 需求输入
PRD、原型、历史约束
↓
📋 Spec 收敛（定边界）
定边界、定US/FR、定EC/SC、定Q/CR
↓
🎨 Design 设计（定方案）
架构图、模块职责、数据流、接口契约
↓
📋 约束前置（定契约）
接口文档、部署文档、配置要求
↓
📝 任务拆解（定执行）
DAO层、Service层、API层按依赖顺序实现
↓
⚡ 分层实现（写代码）
代码生成 + 逻辑补全 + 人工Review
↓
✅ 多维验证（保质量）
自检 + Review + 接口测试 + 联调确认
↓
📦 资产交付（结成果）
代码 + 文档 + 接口文档 + 部署说明
↓
🔄 迭代反馈（促优化）
更新Spec → 更新Design → 更新Issues → 修改代码
整个过程由spec.md、design.md、issues.json三大文档串联，确保 AI 与工程师始终在同一语境下工作。
二、分阶段协作流程详解
阶段 1：需求澄清与 Spec 收敛（Scope Definition）
🎯 目标：将模糊的 PRD 或业务沟通记录转化为 AI 可精确执行的技术语义，确立"本期做什么、不做什么"。
⚙️ 核心动作：
输入整合：收集 PRD、原型、历史约束、外部依赖及非功能性要求。
人机协作（Human + Agent）：
Human（你）：提供业务背景，明确核心目标与禁忌（例如："只做计算引擎，不做基金池管理"）。
Agent（AI）：利用 spec-orchestrator Skill，协助整理需求，识别隐含假设，初步起草 spec.md。
📄 关键产出：
spec.md
• 明确范围边界（范围内/外）
• 定义用户故事（US）与功能需求（FR）
• 列出关键业务规则、全局边界情况（EC）及验收标准（SC）
• 沉淀开放问题（Q）与代码规范（CR），并使用统一编号（如 Q-1, FR-2）
💡 核心价值体现：在此阶段通过文档锁定需求口径，从源头上杜绝 AI 在后续实现中产生"想当然"的发散，大幅降低后期因需求误解导致的返工。
阶段 2：技术方案与 Design 设计（Solution Design）
🎯 目标：在 Spec 确定的边界内，将"做什么"转化为"怎么做"，为编码提供稳定蓝图。
⚙️ 核心动作：
方案草拟：基于 spec.md 中的 FR、Q、CR 等约束，进行技术选型。
人机协作：
Agent：根据项目已有的分层结构（如 api/application/domain/config），生成 design.md 草案，包括架构图、模块职责、数据流和关键接口定义。
Human：评审设计方案的合理性、扩展性及与现有系统的兼容性，重点确认 AI 是否准确回应了 spec.md 中的所有约束（例如检查 design.md 中是否有对应 D-1 的设计项来覆盖 FR-1）。
📄 关键产出：
design.md
• 确立分层架构与模块职责
• 定义接口契约与数据模型
• 建立映射关系：明确标注设计方案是针对 spec.md 中的哪条需求（如"对应 FR-1、Q-3"）
💡 核心价值体现：通过 Design 文档强制 AI 在编码前进行系统性思考，避免"边写边想"导致的代码风格不一、架构混乱问题。
阶段 3：交付约束前置与任务拆解（Constraint & Tasking）
🎯 目标：在写第一行代码前，确立对外契约与执行计划，让编码过程变成"填空题"。
⚙️ 核心动作：
约束前置：
• 根据 design.md 生成接口文档（如 Swagger/OpenAPI）
• 编写部署文档、联调说明与配置要求（config.yaml）
任务拆解：
• Agent：依据 design.md 的结构，自动生成 issues.json
• Human：确认任务粒度和依赖关系
📄 关键产出：
• 接口/部署文档：作为实现的硬性约束
• issues.json：将方案拆解为可执行任务列表，包含 id、title、acceptance_criteria、status、depends_on，并引用 spec 和 design 中的编号（如 "参考 spec.md Q-1"）
💡 核心价值体现：实现了"设计即任务，任务即约束"。AI 不再是自由发挥，而是严格按照 issues.json 中的待办事项和验收标准进行增量开发，确保每一次提交都有据可依。
阶段 4：分层实现与 Code 生成（Implementation）
🎯 目标：在既定约束下，高效、准确地完成代码落地。
⚙️ 核心动作：
按层推进：遵循 issues.json 的依赖顺序，依次实现：
• DAO 层：封装数据访问（如 fund_data_dao.py）
• Service 层：编排业务逻辑（如 fund_return_service.py）
• API 层：暴露接口与参数校验（如 routes_fund_returns.py）
人机协作：
Agent：应用 karpathy-guidelines Skill，遵循"显式假设、简单优先、精准修改"的原则生成代码骨架与逻辑补全。
Human：对关键业务逻辑、边界处理和算法口径进行人工 Review。
📄 关键产出：符合分层设计与代码规范的源代码。
💡 核心价值体现：利用 AI 强大的代码生成能力，配合严格的工程约束（分层、命名规范、注释要求），将工程师从重复性编码中解放，专注于高价值的逻辑校验与架构看护。
阶段 5：验证、交付与联调（Verification & Delivery）
🎯 目标：确保实现结果不仅"能跑"，而且"正确、可交付"。
⚙️ 核心动作：
多维验证：
• AI 自检：代码层面的静态分析与基础逻辑检查
• 人工 Review：重点检查业务口径（如文档中提到的"起始日是否归一化为 0%"、"非交易日是否剔除"）
• 接口测试：使用 Postman 或自动化脚本验证接口响应
联调确认：与前端或其他服务方基于已生成的接口文档进行联调。
资产交付：
• 交付物包括：代码、spec.md、design.md、接口文档、部署说明、progress-log.md
📄 关键产出：通过验收的可运行服务与完整的工程资产。
💡 核心价值体现：将验证环节从单纯的"找 Bug"升级为对前置文档有效性的反向验证。如果验证不通过，通常不是直接改代码，而是回到文档层修正 Spec 或 Design。
阶段 6：迭代维护与 Bug 修复（Iteration & Bug Fixing）
🎯 目标：建立可持续演进的维护机制，将每一次变更转化为资产沉淀。
⚙️ 核心动作：
变更驱动：
• 需求迭代：更新 spec.md（调整范围）→ 更新 design.md（调整方案）→ 更新 issues.json（调整任务）→ 修改代码
• Bug 修复：定位根因 → 更新 design_bug.md 或 issues_bug.json → 修复代码 → 更新 bug-register.md
持续对话：通过 Trae Chat 持续对话，推动文档与代码同步演进。
日志留痕：在 progress-log.md 中记录关键决策、变更文件和阻塞问题。
📄 关键产出：持续更新的文档体系与稳定的系统版本。
💡 核心价值体现：文档不仅是起点的规划，更是终点的归宿。通过"先修文档，再修实现"的模式，确保系统的每一次改动都可追溯、可解释，避免了知识流失。
三、工作流的核心价值总结
基于文档定义的这套工作流，其核心价值在于将 AI 从"代码补全工具"重塑为"工程协作者"，具体体现在：
1. 极致的确定性
通过 Spec 锁定需求、Design 锁定方案、issues 锁定执行，将软件开发中的不确定性大幅前置消解。
2. 资产化沉淀
代码只是冰山一角，背后的 Spec、Design、规则与日志才是核心资产。新人接手或需求变更时，无需重头沟通，直接阅读文档即可接续。
3. 人机效能最大化
AI 负责整理、生成、补全和自检；工程师负责决策、把关和验收。两者各司其职，通过 Human in the loop 与 Agent in the loop 实现 1+1 > 2 的协同效应。
4. 低成本演进
无论是需求变更还是 Bug 修复，都遵循统一的文档迭代路径，避免了碎片化修改带来的技术债务累积。
这套工作流不仅适用于 calculation_engine 这样的计算模块，更是一套可复用于各类后端服务的 AI 原生研发范式。
