mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-04 01:40:45 +08:00
60eab98782
- Implemented loop control tasks in JSON format for testing. - Created comprehensive test scripts for loop flow and standalone tests. - Developed a shell script to automate the testing of the entire loop system flow, including mock endpoints and state transitions. - Added error handling and execution history tests to ensure robustness. - Established variable substitution and success condition evaluations in tests. - Set up cleanup and workspace management for test environments.
5.0 KiB
5.0 KiB
Loop Requirements Specification
CCW Loop 的核心需求和约束定义。
Core Requirements
1. 无状态循环
Requirement: 每次执行从文件读取状态，执行后写回文件，不依赖内存状态。
Rationale: 支持随时中断和恢复，状态持久化。
Validation:
- 每个 action 开始时从文件读取状态
- 每个 action 结束时将状态写回文件
- 无全局变量或内存状态依赖
2. 文件驱动进度
Requirement: 所有进度、理解、验证结果都记录在专用 Markdown 文件中。
Rationale: 可审计、可回顾、团队可见。
Validation:
- develop/progress.md 记录开发进度
- debug/understanding.md 记录理解演变
- validate/validation.md 记录验证结果
- 所有文件使用 Markdown 格式，易读
3. CLI 工具集成
Requirement: 关键决策点使用 Gemini/CLI 进行深度分析。
Rationale: 利用 LLM 能力提高质量。
Validation:
- 任务分解使用 Gemini
- 假设生成使用 Gemini
- 证据分析使用 Gemini
- 质量评估使用 Gemini
4. 用户控制循环
Requirement: 支持交互式和自动循环两种模式，用户可随时介入。
Rationale: 灵活性，适应不同场景。
Validation:
- 交互模式：每步显示菜单
- 自动模式：按预设流程执行
- 用户可随时退出
- 状态可恢复
5. 可恢复性
Requirement: 任何时候中断后，可以从上次位置继续。
Rationale: 长时间任务支持，意外中断恢复。
Validation:
- 状态保存在 state.json
- 使用 --resume 可继续
- 历史记录完整保留
Quality Standards
Completeness
| Dimension | Threshold |
|---|---|
| 进度文档完整性 | 每个任务都有记录 |
| 理解文档演变 | 每次迭代都有更新 |
| 验证报告详尽 | 包含所有测试结果 |
Consistency
| Dimension | Threshold |
|---|---|
| 文件格式一致 | 所有 Markdown 文件使用相同模板 |
| 状态同步一致 | state.json 与文件内容匹配 |
| 时间戳格式 | 统一使用 ISO8601 格式 |
Usability
| Dimension | Threshold |
|---|---|
| 菜单易用性 | 选项清晰，描述准确 |
| 进度可见性 | 随时可查看当前状态 |
| 错误提示 | 错误消息清晰，提供恢复建议 |
Constraints
1. 文件结构约束
.workflow/.loop/{session-id}/
├── meta.json # 只写一次，不再修改
├── state.json # 每次 action 后更新
├── develop/
│ ├── progress.md # 只追加，不删除
│ ├── tasks.json # 任务状态更新
│ └── changes.log # NDJSON 格式，只追加
├── debug/
│ ├── understanding.md # 只追加，记录时间线
│ ├── hypotheses.json # 更新假设状态
│ └── debug.log # NDJSON 格式
└── validate/
├── validation.md # 每次验证追加
├── test-results.json # 累积测试结果
└── coverage.json # 最新覆盖率
2. 命名约束
- Session ID:
LOOP-{slug}-{YYYY-MM-DD} - Task ID:
task-{NNN}(三位数字) - Hypothesis ID:
H{N}(单字母+数字)
3. 状态转换约束
pending → running → completed
↓
user_exit
↓
failed
Only allow: pending→running, running→completed/user_exit/failed
4. 错误限制约束
- 最大错误次数: 3
- 超过 3 次错误 → 自动终止
- 每次错误 → 记录到 state.errors[]
5. 迭代限制约束
- 最大迭代次数: 10 (警告)
- 超过 10 次 → 警告用户，但不强制停止
- 建议拆分任务或休息
Integration Requirements
1. Dashboard 集成
Requirement: 与 CCW Dashboard Loop Monitor 无缝集成。
Specification:
- Dashboard 创建 Loop → 调用此 Skill
- state.json → Dashboard 实时显示
- 任务列表双向同步
- 状态控制按钮映射到 actions
2. Issue 系统集成
Requirement: 完成后可扩展为 Issue。
Specification:
- 支持维度: test, enhance, refactor, doc
- 调用
/issue:new "{summary} - {dimension}" - 自动填充上下文
3. CLI 工具集成
Requirement: 使用 CCW CLI 工具进行分析和实现。
Specification:
- 任务分解:
--rule planning-breakdown-task-steps - 代码实现:
--rule development-implement-feature - 根因分析:
--rule analysis-diagnose-bug-root-cause - 质量评估:
--rule analysis-review-code-quality
Non-Functional Requirements
Performance
- Session 初始化: < 5s
- Action 执行: < 30s (不含 CLI 调用)
- 状态读写: < 1s
Reliability
- 状态文件损坏恢复: 支持从其他文件重建
- CLI 工具失败降级: 回退到手动模式
- 错误重试: 支持一次自动重试
Maintainability
- 文档化: 所有 action 都有清晰说明
- 模块化: 每个 action 独立可测
- 可扩展: 易于添加新 action