ez-dev

EZ-DEV: 开发流程与原则

核心原则

完成粒度

• 谨慎决策什么样的功能记为「已完成」——是否构成独立可交付的功能点？
• 不要每个小的功能开发都记作一条 work_done 条目
• 按实际的大功能点来记录；小的更新/修复/优化应作为补丁附在所属大功能点下
• 判定标准（同时满足才算独立条目）：

  维度	独立条目	补丁
  业务边界	解决独立的用户场景/问题域	隶属于已有大功能点的局部优化
  文档载体	需要独立 .dev_doc/{feature}/	复用现有 feature 文档
  可独立验收	完整"输入→处理→输出"链路	只是大链路中的一环
  价值颗粒度	一次发布即可对外兑现价值	离开主条目无独立价值

• 反例：把"stdq 中范围重构""多日 TypeError 修复""duckdb 写 parquet"拆成 3 个独立 work_done 条目
• 正例：统一为 1 个「stdq 卫星遥测数据查询 Skill」条目 + 补丁记录

Worktree

• 所有代码开发在 worktree 中进行
• 各 Subagent 独立 worktree
• 合流必须保留分支历史

文档

• 开发文档存 .dev_doc/<feature>/
• 禁止根目录存 .md 开发文档
• 禁止 worktree 外存开发文档
• 禁止公共 .dev_doc/status.md（per-feature 允许）
• tests/ 和 .dev_doc/ 不入 git 仓库（需手动同步到本地分支）
• 文档路径：dev-handbook.md（手册）/ status.md（状态）/ test-report.md（测试报告）/ summary.md（总结）

Review

• 关键节点（Phase 1 / Phase 3）由独立 Subagent 审查
• Subagent 不加载前序对话，从"新开发者"视角审查
• 致命问题必须修复；非致命问题记录继续
• 闭环：失败 → 自纠 → 再 Review → 1 次机会 → 仍失败暂停

致命问题（必须修复）

• 核心功能无法正常工作
• 安全漏洞或数据泄露风险
• 资源泄露（连接、文件、内存）
• 破坏向后兼容性
• 严重性能问题

非致命问题（记录继续）

• 代码风格不一致
• 边界条件遗漏（有合理兜底）
• 文档不完整（代码本身可理解）
• 重复代码（不导致 bug）
• 未来优化建议

TDD

• red → green → refactor 循环
• 每循环提交
• 提交前自检

测试

• 0 failures 才能通过
• 每功能点至少 1 个测试
• 测试点分级：P0 核心业务逻辑 / P1 边界条件 / P2 异常处理
• 覆盖：新生成 + 现有关联 + 影响回归

合并

• 禁止 AI 主动合入本地分支
• merge 由用户执行
• squash 所有 commit 为 1 个

跨文件/共享依赖

• 多 Subagent 仅可并行无文件/数据依赖的模块
• 共享文件/数据依赖的模块必须串行

---

关键约定

Subagent 启动约定

• 不加载主对话历史，仅给定输入文件清单
• 必填返回结构：ok（是否通过）/ fatal（致命问题列表）/ non_fatal（非致命问题列表）/ suggestions（改进建议列表）
• 工具白名单：只读工具，不修改代码

文档必填字段

• dev-handbook.md：背景 / 目标 / 方案对比 / 接口设计 / 任务拆分 / 并发分析 / 风险 / 验收
• status.md（per-feature）：阶段 / 完成项 / 进行中 / 阻塞 / 下一步
• test-report.md：P0/P1/P2 测试点 / 覆盖率 / 0 failures 证据
• summary.md：变更摘要 / worktree 路径 / 合并命令预览

并发分组规则

• 共享依赖识别：共同 import 模块 / 共同读写的数据结构 / 共享全局状态
• 无共享依赖的模块可并行
• 共享依赖模块必须串行

squash 与合流的关系

• Phase 2 工作流内合流：worktree 间合并，保留分支分叉图
• Phase 4 最终落地：squash 为单 commit 入目标分支
• 二者不冲突：合流 ≠ squash，分属不同阶段

---

流程

Phase 1: 需求分析+设计+计划

• 通过 brainstorming 澄清需求
• 展示候选方案对比
• 写 dev-handbook.md（实现计划 + 并发可行性分析）
• 独立 Subagent 审查
• 用户批准

Phase 2: 并行开发

• 在 worktree 中开发
• 多 Subagent 并行（按并发分析）
• 各 Subagent 走 TDD 循环 + 频繁提交
• 各 Subagent 独立 commit 到自己的 worktree
• 合流（保留分支历史）
• 更新 status.md

Phase 3: 测试+Review

• 独立 Subagent 补全测试 + 执行（0 failures）
• 独立 Subagent 质量审计
• 致命问题 → 回 Phase 2 修复 → 重新 Phase 3
• worktree 提交

Phase 4: 完成

• squash 所有 commit
• 同步 tests/ 和 .dev_doc/ 到本地分支
• 调用 doc_integrate
• 调用 todo_list_manager
• 通知用户（merge 由用户执行）

---

异常处理

中断/放弃

• 立即停止
• 检查 worktree 状态（commit / untracked）
• 用户选择保留或删除 worktree
• 告知用户当前进度和恢复方式