Reorganize workspace and archive skill artifacts
This commit is contained in:
zhuyongxin
@@ -0,0 +1,116 @@
|
||||
# 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 机制。
|
||||
@@ -0,0 +1,44 @@
|
||||
# Dev Flow Skill 改进 TODO
|
||||
|
||||
## P0：先修正执行稳定性
|
||||
|
||||
- [x] 重写 `description`，覆盖需求规划、feature 开发、openspec change、工程文档沉淀等触发场景。
|
||||
- [x] 将依赖表中的“✅ 已安装”改为“启动时检查”，区分 required、optional、fallback。
|
||||
- [x] 为子 skill 调用增加 fallback：优先调用 skill，不可调用时读取对应 `SKILL.md`，不存在时执行内置最小协议。
|
||||
- [x] 明确 `--quick` 模式：允许跳 Phase 1.5 和 Phase 2.5；禁止跳 Phase 2 最小澄清和 Phase 4 轻量归档。
|
||||
- [x] 增加 `devflow/` 初始化规则：创建 `projects/`、`glossary/`、`compound/`、`reference/`，并处理旧 `CONTEXT.md`。
|
||||
- [x] 增加 v3 OpenSpec-first 规则：devflow 辅助 OpenSpec，OpenSpec 指挥执行。
|
||||
- [x] 增加显式子 skill 调用规则：不能调用时必须标记 fallback 降级。
|
||||
- [x] 增加 devflow 产物分档：micro / standard / complex，避免默认产物过多。
|
||||
|
||||
## P1：补齐 Phase 契约和模板
|
||||
|
||||
- [x] 为 Phase 0 增加进入条件、退出条件、最小输入质量标准。
|
||||
- [x] 为 Phase 1 增加 openspec 产物检查：`proposal.md`、`design.md`、`specs/`、`tasks.md`。
|
||||
- [x] 为 Phase 1.5 增加 PRD/brief 最小模板和完成标准。
|
||||
- [x] 为 Phase 2 增加 `CONTEXT.md` 更新模板和 ADR 创建判断模板。
|
||||
- [x] 为 Phase 2.5 增加架构审计输出模板。
|
||||
- [x] 为 Phase 3 增加 diagnose 触发条件和 TDD 触发条件。
|
||||
- [x] 为 Phase 4 增加 acceptance report 模板和 openspec 提取规则。
|
||||
|
||||
## P2：重构 skill 文件结构
|
||||
|
||||
- [x] 将新版本迁移为 `.agents/skills/sm-flow/SKILL.md` 短执行协议。
|
||||
- [x] 新建 `.agents/skills/sm-flow/references/templates.md`，存放所有文档模板。
|
||||
- [x] 新建 `.agents/skills/sm-flow/references/phase-contracts.md`，存放 Phase 输入/动作/输出/退出条件。
|
||||
- [x] 新建 `.agents/skills/sm-flow/references/archive-rules.md`，存放 Phase 4 提取和归档规则。
|
||||
- [x] 新建 `.agents/skills/sm-flow/references/fallbacks.md`，存放子 skill 不可用时的最小协议。
|
||||
- [x] 删除或迁移 `SKILL.md` 中过长的理念说明，避免上下文膨胀。
|
||||
|
||||
## P3：完善展示和可移植性
|
||||
|
||||
- [ ] 评估是否需要 `agents/openai.yaml` 或其他技能展示元数据。
|
||||
- [ ] 增加一个最小示例项目，验证从 Phase 0 到 Phase 4 的完整流转。
|
||||
- [ ] 增加“复制到新项目后首次运行”的检查步骤。
|
||||
- [ ] 明确 Claude 版本与 Codex 版本的差异，避免工具名耦合。
|
||||
|
||||
## 建议执行顺序
|
||||
|
||||
1. 先改 `SKILL.md` 的触发描述、依赖检查、quick 模式和 fallback 规则。
|
||||
2. 再拆出 `references/` 模板与 Phase 契约。
|
||||
3. 最后用一个真实小需求跑通 Phase 0 到 Phase 4，回填发现的问题。
|
||||
Reference in New Issue
Block a user