117 lines
5.8 KiB
Markdown
117 lines
5.8 KiB
Markdown
# Dev Flow Skill 评估报告
|
||
|
||
**日期**：2026-05-19
|
||
**对象**：`.claude/skills/dev-flow/SKILL.md`
|
||
**背景**：该 skill 基于 openspec 工作流，并融合 `to-prd`、`grill-with-docs`、`zoom-out`、`diagnose`、`tdd` 等开源 skill 思路，目标是形成一套从需求到实现再到知识沉淀的工程开发闭环。
|
||
|
||
## 总体评价
|
||
|
||
这套 `dev-flow` 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。
|
||
|
||
最有价值的设计是 `devflow/` 产物聚合层：
|
||
|
||
- `openspec/changes/` 负责机器可执行的变更工作区。
|
||
- `devflow/projects/` 负责人类可回溯的项目档案。
|
||
- `devflow/glossary/CONTEXT.md` 负责跨项目领域词汇。
|
||
- `devflow/compound/` 负责沉淀可复用工程知识。
|
||
|
||
目前最大的问题是：`SKILL.md` 更像一份设计说明书，而不是一份代理可以稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。
|
||
|
||
## 亮点
|
||
|
||
1. **产物聚合层设计清晰**
|
||
- `devflow/projects/YYYY-MM-DD-{slug}/` 解决了 openspec archive 后上下文难以回溯的问题。
|
||
- 工具工作区和人类档案层分离，职责边界明确。
|
||
|
||
2. **阶段顺序合理**
|
||
- Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。
|
||
|
||
3. **Phase 4 很有价值**
|
||
- 明确要求从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。
|
||
- 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。
|
||
|
||
4. **grill-with-docs 融合方式正确**
|
||
- Phase 2 要求一次只问一个问题，并即时更新 `CONTEXT.md` / ADR。
|
||
- 这符合“边澄清边沉淀”的工作方式。
|
||
|
||
5. **质量闭环意识强**
|
||
- Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。
|
||
- TDD 被设计为可选增强，避免对所有任务强制套用重流程。
|
||
|
||
## 主要问题
|
||
|
||
1. **触发描述不够完整**
|
||
- 当前 `description` 说明了流程构成，但没有覆盖足够多的用户触发场景。
|
||
- 建议明确写入：当用户要从需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程时使用。
|
||
|
||
2. **Claude 工具耦合较强**
|
||
- `allowed-tools` 使用 Claude Code 风格工具名。
|
||
- 如果未来迁移到 Codex skill，这些工具名可能不适用。
|
||
- 建议把工具白名单保留给 Claude 版本，同时在正文中描述环境无关的 fallback 行为。
|
||
|
||
3. **依赖安装状态不应写死**
|
||
- 依赖表中写了“✅ 已安装”，这对当前仓库成立，但复制到其他项目会误导。
|
||
- 应改成“启动时检查是否存在”，并区分 required、optional、fallback。
|
||
|
||
4. **子 skill 调用方式不稳**
|
||
- 文档写“调用 Skill 工具启动 openspec-propose / openspec-apply-change”。
|
||
- 但不同代理环境未必支持直接调用 Skill 工具。
|
||
- 建议增加 fallback：如果不能直接调用，就读取对应 `SKILL.md` 并按其协议执行。
|
||
|
||
5. **缺少初始化算法**
|
||
- 文档要求写入 `devflow/projects/YYYY-MM-DD-{slug}/`，但没有说明如何生成 slug、如何处理重名、如何创建目录骨架。
|
||
|
||
6. **缺少模板**
|
||
- PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 都有路径要求，但没有最小模板。
|
||
- 这会导致代理每次输出格式不稳定。
|
||
|
||
7. **quick 模式与约束存在冲突**
|
||
- `--quick` 说可以跳 Phase 1.5 和 2.5，仅 grill + apply。
|
||
- 约束又说严禁跳过 Phase 2。
|
||
- 需要明确 quick 模式只能跳哪些阶段，不能跳哪些阶段。
|
||
|
||
8. **Phase 退出条件不足**
|
||
- 每个 Phase 有目标，但没有明确“什么时候可以进入下一阶段”。
|
||
- 建议增加进入条件、退出条件和必需产物。
|
||
|
||
## 改进建议
|
||
|
||
1. **将 `SKILL.md` 改成执行协议**
|
||
- 保留角色、触发场景、阶段总览、硬性约束和关键分支规则。
|
||
- 把长解释、模板、示例迁移到 `references/`。
|
||
|
||
2. **增加启动前检查清单**
|
||
- 检查 `openspec/` 是否存在。
|
||
- 检查 `.claude/skills/openspec-*` 是否存在。
|
||
- 检查 `devflow/` 是否已初始化。
|
||
- 检查是否存在旧的根目录 `CONTEXT.md`，必要时迁移或合并到 `devflow/glossary/CONTEXT.md`。
|
||
|
||
3. **增加 Phase 契约**
|
||
- 每个 Phase 明确：输入、动作、输出、退出条件、失败时回退路径。
|
||
|
||
4. **补齐模板**
|
||
- 新增 `references/templates.md`，收纳 PRD、research、design、tasks、acceptance、ADR、compound knowledge 的最小模板。
|
||
|
||
5. **补齐归档规则**
|
||
- 新增 `references/archive-rules.md`，明确如何从 openspec 文件提取信息到 `devflow/projects/`。
|
||
|
||
6. **统一 quick 模式语义**
|
||
- quick 模式可以跳过 Phase 1.5 和 Phase 2.5。
|
||
- quick 模式不能跳过 Phase 2 的最小澄清，也不能跳过 Phase 4 的轻量归档。
|
||
|
||
7. **增加 fallback 策略**
|
||
- 优先调用子 skill。
|
||
- 如果不可调用，则读取该 skill 的 `SKILL.md`。
|
||
- 如果 skill 文件不存在，则执行 dev-flow 内置的最小协议。
|
||
|
||
## 优先级
|
||
|
||
- **P0**：修正工具/环境耦合、依赖检查、quick 模式冲突。
|
||
- **P1**：补模板和 Phase 退出条件。
|
||
- **P2**：把长理念迁移到 `references/`，保持 `SKILL.md` 更短更可执行。
|
||
- **P3**：增加 `agents/openai.yaml` 或等价元数据，方便技能列表展示。
|
||
|
||
## 结论
|
||
|
||
`dev-flow` 已经具备成为高价值工程元技能的基础：流程完整、沉淀意识强、质量闭环明确。下一步不应继续增加理念，而应把它产品化为“代理稳定执行协议”：更短的 `SKILL.md`、更明确的 Phase 契约、更标准的模板、更稳的 fallback 机制。
|