mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37: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.
193 lines
5.0 KiB
Markdown
193 lines
5.0 KiB
Markdown
# 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
|