dev-lifecycle

# 软件开发生命周期编排（Dev Lifecycle Orchestrator） 本技能将一个模糊想法/需求，端到端推进到可交付的代码实现。核心是 **5 阶段 + 每阶段 HITL（Human-In-The-Loop）确认**，前 4 阶段产出文档，第 5 阶段按 **SOP 6 步** 逐阶段开发。 ## 何时调用 - 用户提出新项目想法、新功能需求、版本迭代、技术重构 - 用户要求"完整开发流程"、"从需求到上线"、"按流程开发" - 用户给出现有项目要求"重构"、"迭代 v2"、"补齐开发流程 SOP" - 用户描述模糊需求需要先探索再实现 ## 兼容场景 | 场景 | 第 1-4 阶段处理 | 第 5 阶段处理 | |------|----------------|---------------| | 新项目创建 | 完整走 4 阶段，产出 roadmap / development-plan / api-doc | 从第 1 阶段开始按 SOP 推进 | | 需求迭代（v1→v2） | 聚焦"增量需求"分析，复用已有架构，产出迭代计划 | 仅推进新增/变更阶段 | | 技术重构 | 聚焦"重构目标 + 风险"分析，产出重构方案与回归测试策略 | 按重构单元逐个 SOP 推进 | ## 核心原则 1. **HITL 强制确认**：每个阶段产出后，必须用 `AskUserQuestion` 或 `NotifyUser` 让用户确认/完善，**禁止跳过确认直接进入下一阶段** 2. **文档先行**：前 4 阶段产出 Markdown 文档落盘到 `docs/`，作为第 5 阶段的执行依据 3. **最小必要**：不过度工程；不新增非必要文件；不加无关 docstring/注释 4. **可追溯**：每阶段产出物可追溯到上游需求；commit 信息含阶段标识 --- ## 流程总览 ``` 阶段 1：需求探索 → [HITL] ↓ 阶段 2：技术框架 → [HITL] ↓ 阶段 3：产品设计方案 → [HITL] ↓ 阶段 4：API 文档 + 分阶段开发计划 → [HITL] ↓ 阶段 5：分阶段 SOP 开发（每阶段内含 6 步，审查阶段全面） ``` --- ## 阶段 1：需求探索分析 **目标**：把模糊想法转化为结构化、可确认的需求规格。 ### 执行步骤 1. **理解原始输入**：阅读用户描述，识别意图类型（新项目/迭代/重构） 2. **探索现状**（迭代/重构场景必做）： - 用 `LS` / `Glob` / `Grep` / `SearchCodebase` 摸清现有代码结构、技术栈、关键模块 - 阅读已有 `docs/`、`AGENT.md`、`README.md`、`pyproject.toml`/`package.json` - 总结现状：已有什么、缺什么、痛点是什么 3. **需求拆解**：将大需求拆为功能模块，每个模块给出： - 用户故事（As a... I want... so that...） - 验收标准（可测试的 Given-When-Then） - 优先级（P0 必须 / P1 重要 / P2 可选） - 依赖关系 4. **边界澄清**：明确做什么、不做什么、风险点、约束（性能/安全/兼容） 5. **产出文档**：`docs/requirements.md`（新项目）或 `docs/requirements-v{X}.md`（迭代） ### HITL 确认 用 `AskUserQuestion` 向用户确认： - 需求拆解是否完整？是否有遗漏模块？ - 优先级排序是否合理？ - 边界与约束是否准确？ 用户确认或完善后，进入阶段 2。**若用户大幅修改需求，回到步骤 3 重新拆解。** --- ## 阶段 2：技术框架推荐 **目标**：基于需求，输出技术选型与实现路径，经用户确认后定基线。 ### 执行步骤 1. **技术选型分析**：针对每个功能模块，给出候选技术栈对比： - 选型维度：性能 / 生态成熟度 / 团队熟悉度 / 维护成本 / 异步支持 / 安全性 - 推荐 1-2 个方案，说明理由与权衡 2. **架构设计**： - 分层架构（如 API 层 / 核心层 / 数据层 / 适配层） - 核心组件职责与交互（用文字 + 简图） - 关键数据流 3. **数据模型设计**：列出核心表/集合/模型字段与关系 4. **实现路径**：分阶段实施顺序，标注关键路径与依赖 5. **风险与应对**：技术风险（性能/并发/兼容）+ 应对措施 6. **产出文档**：`docs/tech-framework.md` ### HITL 确认 用 `AskUserQuestion` 确认： - 技术栈选型是否采纳？ - 架构分层与组件职责是否合理？ - 实现路径顺序是否调整？ 用户确认或指定替代方案后，进入阶段 3。 --- ## 阶段 3：完整产品设计方案 **目标**：基于需求与技术框架，输出完整、全面、可落地的产品设计方案。 ### 执行步骤 1. **功能详设**：每个功能模块给出： - 详细交互流程（用户视角 + 系统视角） - 输入/输出契约 - 异常处理策略 - 状态机/时序图（如适用） 2. **数据模型终版**：表结构 + 字段类型 + 索引 + 迁移策略 3. **接口契约草案**：核心 API 端点列表（方法/路径/用途，不含细节） 4. **安全设计**：认证/授权/加密/沙箱/审计/配额（按需） 5. **前端设计**（如有）：页面结构 / 路由 / 状态管理 / 组件清单 / 设计 token 6. **可观测设计**：日志/指标/追踪/告警（按需） 7. **验收标准汇总**：端到端验收用例清单 8. **产出文档**：`docs/product-design.md` ### HITL 确认 用 `AskUserQuestion` 或 `NotifyUser`（附文档路径）确认： - 功能详设是否覆盖全部需求？ - 数据模型与接口契约是否准确？ - 安全/前端/可观测设计是否到位？ 用户确认或完善后，进入阶段 4。 --- ## 阶段 4：API 文档 + 分阶段开发计划 **目标**：产出第 5 阶段的执行依据——两份详细文档。 ### 产出 1：API 文档 `docs/api-doc.md` 每个端点包含： - 方法 + 路径 + 用途 - 请求参数（Path/Query/Body）+ 类型 + 必填 + 校验规则 - 响应结构（成功 + 错误码）+ 示例 - 权限要求 - 副作用（审计/缓存/事件） ### 产出 2：分阶段开发计划 `docs/development-plan.md` 结构： - **计划概述**：技术栈基线表 + 阶段划分表 + 设计原则 - **每个阶段（周次）**： - 任务表（任务 / 说明 / 交付物 / 状态） - 关键文件清单 - 验收标准 - **技术风险与应对**表 - **依赖与关键路径**图 阶段划分原则：每个阶段可独立交付、可独立测试、有明确验收标准。 ### HITL 确认 用 `NotifyUser`（附两份文档路径）请用户审阅： - API 文档是否完整准确？ - 阶段划分粒度是否合理？ - 验收标准是否可测试？ 用户确认后，进入阶段 5。 --- ## 阶段 5：分阶段 SOP 开发 **目标**：按 `docs/development-plan.md` 逐阶段开发，每阶段走 **SOP 6 步**，审查阶段必须全面。 ### 每阶段开始前 用 `TodoWrite` 建立本阶段任务清单（对应 6 步），第一步标记 in_progress。 ### SOP 6 步详述 #### 步骤 1：了解需求 → 编码实现 - 读 `docs/development-plan.md` 对应阶段任务表与交付物 - 读 `docs/api-doc.md` 对应端点契约 - 读 `docs/requirements.md` / `docs/product-design.md` 对应需求 - 用 `Read` 阅读相关现有代码（**先 Read 后 Edit，禁止盲改**） - 逐任务编码，遵循设计原则（异步优先/向后兼容/最小必要/测试先行） - 编码约束：不新增非必要文件；不过度工程；不加无关 docstring/注释；仅做必要修改 #### 步骤 2：编写测试 → 运行通过 - 新增功能单元测试覆盖率 ≥ 80% - 分布式/集成场景集成测试 ≥ 10 个（如适用） - 运行 `python -m pytest`（或对应测试命令），**必须全部 pass** - DB 相关测试若环境不可用，标记 `@pytest.mark.db` 并在 Windows 自动 skip，记录待网络恢复补测 - 测试通过标准：0 失败；遗留警告可接受但需记录 #### 步骤 3：全面审查 → 修复（核心步骤，必须全面） **审查范围（缺一不可）**： | 审查项 | 检查内容 | 工具/命令 | |--------|---------|----------| | **文档** | development-plan 对应阶段标 ✅ + 任务表状态列 + 关键文件/测试说明；roadmap 一致性 | 手动 Edit | | **代码 Lint** | ruff（或 ESLint/vue-tsc）无新增错误 | `python -m ruff check <files>` | | **代码逻辑** | 异常处理完整；边界条件覆盖；锁/超时/资源释放；并发安全；向后兼容 | 人工 Review | | **安全性能** | 认证/授权校验；输入校验；加密存储；沙箱隔离；配额拦截；SQL 注入；签名验签；密钥不落盘 | 人工 Review | | **单元测试** | 覆盖率 ≥ 80%；正向/异常/边界用例齐全；mock 合理 | `pytest --cov` | | **集成测试** | 端到端链路；跨模块交互；分布式场景 | `pytest tests/integration` | | **配置同步** | `config.example.yaml` 同步新配置段；`pyproject.toml`/`package.json` 依赖更新；环境变量文档 | 手动 Edit | | **路由/注册** | `main.py` 路由注册；lifespan 启停成对（start ↔ stop）；后台任务清理 | 手动 Review | | **迁移** | Alembic 迁移可前向可回滚；downgrade 完整；不破坏现有数据 | `alembic upgrade/downgrade` 验证 | | **回归** | 全套测试无回归（历史测试仍通过） | `pytest` 全量 | 发现问题**全部修复**后，再次运行测试确认无回归，方可进入步骤 4。 #### 步骤 4：标记完成 - 在 `docs/development-plan.md` 对应阶段标题追加 ✅ - 任务表新增「状态」列，每行标注 ✅ - 补充「关键文件」与「测试」说明段 - 更新 `AGENT.md`（或项目记忆文件）进度 #### 步骤 5：git commit - 用 `git add <具体文件>` 暂存（**禁止 `git add -A` / `git add .`**，避免误提交敏感文件） - 不提交 `.env` / `credentials.json` / 大二进制 - 提交信息格式：`feat(v{X.Y.Z}): Phase {N} Week {M} <阶段主题>`（迭代/重构用 `refactor`/`fix` 前缀） - 正文列明交付要点 - **不主动 push**，除非用户明确要求 #### 步骤 6：进入下一阶段 - 更新 `TodoWrite`，开始下一阶段，回到步骤 1 - 遇阻塞性问题（需求不清/技术选型分歧）用 `AskUserQuestion` 与用户对齐 ### 阶段流程速查 ``` [ ] 1. 读需求 -> 编码（先 Read 后 Edit） [ ] 2. 写测试 -> pytest 全绿（覆盖率 ≥ 80%） [ ] 3. 全面审查 -> 文档/代码/安全/测试/配置/迁移/回归 -> 修复后回归测试 [ ] 4. development-plan 标 ✅ + AGENT.md 更新 [ ] 5. git add 具体文件 -> commit（不 push） [ ] 6. 进入下一阶段 ``` --- ## 执行规范 ### HITL 交互 - 每阶段产出后**必须**让用户确认，不得自行跳过 - 用 `AskUserQuestion` 提供选项（推荐项放第一并标注"推荐"） - 用 `NotifyUser` 附文档路径请用户审阅 - 用户反馈后，更新对应文档并继续 ### 文档落盘 - 所有文档放 `docs/` 目录 - 命名：`requirements.md` / `tech-framework.md` / `product-design.md` / `api-doc.md` / `development-plan.md` - 迭代场景加版本后缀：`requirements-v2.md` / `development-plan-v2.0.0.md` ### 工具使用 - 探索代码：`SearchCodebase` / `Grep` / `Glob` / `LS` / `Read` - 修改代码：`Edit` / `Write`（优先 Edit 现有文件） - 运行命令：`RunCommand`（测试/lint/git） - 任务管理：`TodoWrite`（每阶段建立 6 步清单） - 用户交互：`AskUserQuestion` / `NotifyUser` - 复杂子任务：`Task` 分派子代理（搜索/并行实现） ### 质量红线 - ❌ 禁止跳过 HITL 确认直接进入下一阶段 - ❌ 禁止跳过步骤 3 全面审查 - ❌ 禁止 `git add -A` / `git add .` - ❌ 禁止主动 `git push` - ❌ 禁止盲改代码（不 Read 就 Edit） - ❌ 禁止过度工程（超出需求的抽象/配置/兼容层） - ✅ 每阶段 commit 信息含阶段标识 - ✅ 测试覆盖率 ≥ 80% - ✅ 审查清单 10 项全部检查 --- ## 快速启动 当用户触发本技能时，按以下顺序： 1. 识别场景（新项目/迭代/重构） 2. 用 `AskUserQuestion` 确认场景类型与起始阶段（迭代/重构可跳过已完成阶段） 3. 用 `TodoWrite` 建立 5 阶段总任务清单 4. 从阶段 1 开始执行，每阶段结束 HITL 确认 5. 进入阶段 5 后，按 SOP 6 步逐阶段推进直至全部交付