fit-framework: Command for Claude Code

Block Task Command

功能说明

当任务遇到无法继续的问题时，使用此命令标记任务为阻塞状态，记录详细的阻塞原因，并将任务移动到 blocked 目录，等待问题解决。

⚠️ CRITICAL: 状态更新要求

执行此命令后，你必须立即更新任务状态并移动任务目录。参见规则 7。

使用场景

何时使用此命令

在以下情况下应该标记任务为阻塞：

技术问题：

• ❌ 编译失败且无法修复
• ❌ 测试失败且原因不明
• ❌ 依赖库存在 Bug
• ❌ 环境配置问题
• ❌ 工具链问题

需求问题：

• ❓ 需求不明确，需要澄清
• ❓ 发现需求冲突
• ❓ 缺少必要的需求信息
• ❓ 需要产品决策

资源问题：

• ⏳ 等待外部依赖
• ⏳ 等待第三方 API 或服务
• ⏳ 等待数据库迁移
• ⏳ 等待基础设施就绪

决策问题：

• 🤔 需要架构决策
• 🤔 需要安全审查
• 🤔 需要性能优化方案选择
• 🤔 需要人工审查和批准

何时不使用此命令

以下情况不应该标记为阻塞：

• ✅ 代码审查发现问题 → 使用 /refine-task 修复
• ✅ 实现遇到困难但可以解决 → 继续实施
• ✅ 测试失败但原因清楚 → 修复测试
• ✅ 文档不完整 → 完善文档

执行流程

1. 验证任务存在

检查任务文件是否存在：

ls -la .ai-workspace/active/{task-id}/task.md

如果任务不在 active 目录，检查是否已经在 blocked 或 completed 目录。

2. 分析阻塞原因

在标记阻塞前，必须仔细分析并记录以下信息：

问题描述：

• 遇到了什么具体问题？
• 问题出现在哪个步骤？
• 问题的表现形式是什么？

根本原因：

• 为什么会出现这个问题？
• 问题的根源是什么？
• 是否有错误日志或诊断信息？

尝试的解决方案：

• 已经尝试了哪些方法？
• 为什么这些方法没有解决问题？

需要的帮助：

• 需要谁来帮助解决？
• 需要什么资源或信息？
• 预计解决问题需要多长时间？

3. 更新任务状态 (CRITICAL)

必须更新 .ai-workspace/active/{task-id}/task.md：

status: blocked
current_step: {当前步骤，保持不变}
updated_at: {当前时间，格式: yyyy-MM-dd HH:mm:ss}
blocked_at: {当前时间，格式: yyyy-MM-dd HH:mm:ss}
blocked_by: {当前AI}
blocked_reason: {简短描述阻塞原因}

在 task.md 中添加"阻塞信息"章节（在 "注意事项" 之前插入）：

---

## ⚠️ 阻塞信息

### 阻塞概要

- **阻塞时间**: {当前时间}
- **阻塞步骤**: {current_step}
- **阻塞者**: {当前AI}
- **阻塞类型**: {技术问题/需求问题/资源问题/决策问题}
- **严重程度**: {高/中/低}
- **预计解决时间**: {预估}

### 问题描述

{详细描述遇到的问题，包括错误信息、日志、截图等}

### 根本原因

{分析问题的根本原因}

### 尝试的解决方案

1. **尝试方法 1**: {描述}
   - 结果: {失败/部分成功}
   - 原因: {为什么没有解决}

2. **尝试方法 2**: {描述}
   - 结果: {失败/部分成功}
   - 原因: {为什么没有解决}

### 需要的帮助

**需要谁**：{开发者/架构师/产品经理/运维/安全团队}

**需要什么**：
- 明确 XX 需求
- 解决 XX 技术问题
- 提供 XX 资源
- 做出 XX 决策

**附加信息**：
{任何有助于解决问题的额外信息}

### 解除阻塞条件

满足以下条件后可以解除阻塞并继续：
- [ ] 条件 1
- [ ] 条件 2
- [ ] 条件 3

### 备用方案

如果问题无法在合理时间内解决，可以考虑：
- 方案 1: {描述}
- 方案 2: {描述}

---

4. 移动到阻塞目录 (CRITICAL)

将任务从 active 目录移动到 blocked 目录：

# 确保 blocked 目录存在
mkdir -p .ai-workspace/blocked

# 移动任务目录
mv .ai-workspace/active/{task-id} .ai-workspace/blocked/