auto-parallel-dev

自动化并行开发管理 Skill - 严格边界版本。

核心理念：零外部脚本，完全基于 Claude Code 原生工具。

⚠️ 严格边界声明

本 Skill 遵循严格边界限制，确保可预测性、安全性和可控性。

边界 1: 文件操作边界

✅ 仅允许操作以下文件：

code

.claude/team/registry.json        # 读写
.claude/team/errors.log           # 仅追加
.parallel-team.yml               # 仅读取

❌ 绝对禁止：

•读写项目源代码（src/, frontend/, backend/ 等）
•修改任何配置文件（.env, package.json 等）
•创建新文件（除了追加日志）
•删除任何文件
•修改 Git 仓库文件

边界检查：

code

每次使用 Read/Edit 工具前，验证文件路径：
  - 必须以 .claude/team/ 开头
  - 或是 .parallel-team.yml

边界 2: 工具使用边界

✅ 允许使用的 Claude Code 工具：

工具	用途	限制
Read	读取文件	仅 registry.json, errors.log
Edit	编辑文件	仅 registry.json
Task	启动 Agent	仅 backend-dev, frontend-dev, qa
mcp__task-master-ai__*	Task-Master MCP	所有操作

❌ 绝对禁止使用：

•Write 工具（创建新文件）
•Bash 执行任何命令（包括只读命令）
•任何其他 MCP 工具（除了 Task-Master）
•NotebookEdit 工具

边界检查：

code

每次使用工具前，验证：
  - Read/Edit 的文件路径符合边界 1
  - Task 的 subagent_type 是开发类 Agent
  - MCP 是 task-master-ai 相关

边界 3: 时间边界

操作	时间限制	理由
监控循环间隔	≥ 30 秒	防止 CPU 占用过高
单次状态同步	≤ 60 秒	防止长时间阻塞
Agent 启动验证	≤ 5 秒	快速验证，不浪费时间
Task-Master 重试	总计 ≤ 30 秒	3 次，每次 10 秒

❌ 绝对禁止：

•频繁轮询（间隔 < 30 秒）
•长时间阻塞操作（> 60 秒）
•无限循环

边界检查：

code

监控循环实现：
  while not completed:
      # 执行检查（预计 < 10 秒）

      # 等待 30 秒
      sleep(30)  # 必须等待，不能提前检查

边界 4: 职责边界

✅ Skill 负责：

•监控后台 Agent 完成状态
•同步 Task-Master 和 registry.json 状态
•为空闲成员分配新任务
•记录无法自动恢复的错误

❌ Skill 不负责（由开发 Agent 负责）：

•实际开发工作（写代码、测试、重构）
•Git 操作（commit, push, merge）
•代码审查和质量检查
•创建 Git Worktree
•修改项目配置

边界检查：

code

当需要执行开发工作时：
  ❌ 不直接操作
  ✅ 通过 Task 工具启动相应的开发 Agent

边界 5: 错误处理边界

第 1 层：可自动恢复的错误

code

Task-Master 连接超时 → 重试 3 次（指数退避）
registry.json 并发冲突 → 等待 5 秒后重试

第 2 层：必须停止的致命错误

code

registry.json 文件损坏 → 停止监控，通知用户
.parallel-team.yml 格式错误 → 停止监控，通知用户
磁盘空间不足 → 停止监控，通知用户

第 3 层：仅记录的错误

code

Agent 启动失败 → 记录到 errors.log，继续运行
Gatekeeper 拒绝 → 记录到 errors.log，跳过任务
任务依赖不满足 → 记录到 errors.log，跳过任务

边界检查：

code

遇到错误时：
  1. 判断错误类型
  2. 按边界 5 处理
  3. 记录到 errors.log（如果需要）

🎯 核心功能

功能 1: 启动监控循环

code

用户命令：/auto-parallel-dev start

Skill 执行：
  1. 读取 .parallel-team.yml（Read 工具）
  2. 验证配置格式和必需字段
  3. 启动监控循环（无限循环，直到用户停止）

监控循环（每 30 秒）：
  步骤 1: 检查 Agent 完成状态
    - 检查是否有新的 task-notification
    - 读取 Agent 输出文件（Read 工具）

  步骤 2: 同步 Task-Master 状态
    - mcp__task-master-ai__set_task_status
    - 重试 3 次（如果失败）

  步骤 3: 更新 registry.json
    - 计算新状态
    - 原子更新（Edit 工具）

  步骤 4: 检测空闲成员
    - 读取 registry.json（Read 工具）
    - 查找 status=idle 的成员

  步骤 5: 分配新任务
    - 查询 Task-Master pending 任务
    - 使用 Task 工具启动新的开发 Agent
    - 更新 registry.json（Edit 工具）

  步骤 6: 等待 30 秒
    - 不执行任何操作
    - 仅等待定时器

功能 2: 停止监控循环

code

用户命令：/auto-parallel-dev stop

Skill 执行：
  1. 设置停止标志
  2. 退出监控循环
  3. 生成简要报告

功能 3: 查看状态

code

用户命令：/auto-parallel-dev status

Skill 执行：
  1. 读取 registry.json（Read 工具）
  2. 读取 Task-Master 状态（mcp__task-master-ai__get_tasks）
  3. 生成状态报告（仅输出，不写文件）

🔧 实现细节

监控循环实现

python

# 伪代码（实际在 Skill 中实现）

def monitoring_loop():
    """主监控循环 - 严格遵循时间边界"""

    while not stop_flag:
        try:
            # 步骤 1: 检查 Agent 完成状态（预计 5 秒）
            completed_agents = check_agent_completions()

            # 步骤 2: 处理每个完成的 Agent（每个 10 秒）
            for agent in completed_agents:
                handle_agent_completion(agent)

            # 步骤 3: 检测空闲成员并分配（预计 10 秒）
            assign_pending_tasks()

            # 步骤 4: 检测项目完成（预计 5 秒）
            if is_project_completed():
                trigger_completion()
                break

            # 【关键】等待 30 秒（严格遵守时间边界）
            sleep(30)

        except Exception as e:
            # 错误处理（遵循边界 5）
            handle_error(e)
            sleep(30)

状态同步实现（原子操作）

python

def handle_agent_completion(agent_id, task_id, member_id, status):
    """处理 Agent 完成 - 使用 Edit 工具的原子性"""

    # 步骤 1: 读取 registry.json（Read 工具）
    registry = read_registry()

    # 步骤 2: 同步 Task-Master（MCP 工具）
    if status == "done":
        success = sync_taskmaster(task_id, "done")
        if not success:
            log_error("taskmaster_sync_failed", task_id)
            return  # 不更新 registry

    # 步骤 3: 计算新状态
    member = registry["members"][member_id]

    # 移除当前任务
    new_current_tasks = [
        t for t in member["current_tasks"]
        if t["task_id"] != task_id
    ]

    # 添加到完成任务
    new_completed_tasks = member["completed_tasks"].copy()
    new_completed_tasks.append({
        "task_id": task_id,
        "completed_at": now()
    })

    # 步骤 4: 原子更新 registry.json（Edit 工具）
    # Edit 工具提供原子性，不需要额外锁
    edit_registry(member_id, {
        "status": "idle",
        "current_tasks": new_current_tasks,
        "completed_tasks": new_completed_tasks
    })

错误处理实现

python

def handle_error(error):
    """分层错误处理"""

    # 第 1 层：可自动恢复
    if is_taskmaster_timeout(error):
        # 重试 3 次（在调用处处理）
        return

    if is_registry_conflict(error):
        # 等待 5 秒后重试
        sleep(5)
        return

    # 第 2 层：致命错误
    if is_registry_corrupted(error):
        stop_monitoring()
        notify_user("registry.json 损坏，请手动检查")
        return

    if is_config_error(error):
        stop_monitoring()
        notify_user("配置文件格式错误")
        return

    # 第 3 层：仅记录
    log_error(error)

📊 边界验证清单

使用 Skill 时，必须验证以下边界：

文件操作边界

• 仅读取 .claude/team/registry.json
• 仅读取 .claude/team/errors.log
• 仅读取 .parallel-team.yml
• 仅编辑 .claude/team/registry.json
• 仅追加 .claude/team/errors.log
• 不访问任何其他文件

工具使用边界

• 仅使用 Read 工具（上述文件）
• 仅使用 Edit 工具（registry.json）
• 仅使用 Task 工具（开发类 Agent）
• 仅使用 Task-Master MCP 工具
• 不使用 Write 工具
• 不使用 Bash 工具
• 不使用其他 MCP 工具

时间边界

• 监控循环间隔 ≥ 30 秒
• 单次状态同步 ≤ 60 秒
• Agent 验证 ≤ 5 秒
• Task-Master 重试 ≤ 30 秒

职责边界

错误处理边界

• 可恢复错误自动重试
• 严重错误停止并通知
• 其他错误仅记录

📖 使用示例

示例 1: 启动监控

code

用户: /auto-parallel-dev start

Skill: ✅ 监控循环已启动

📊 当前状态：
- 团队成员：5 人
- 待分配任务：87 个
- 监控间隔：30 秒

🔄 正在监控...

示例 2: Agent 完成后自动分配

code

（后台）Agent 完成：carol-frontend 完成 LWP-2-T079

Skill 自动执行：
  1. ✅ 同步 Task-Master 状态：T079 → done
  2. ✅ 更新 registry.json：carol → idle
  3. ✅ 检测空闲成员：carol
  4. ✅ 分配新任务：LWP-2-T081
  5. ✅ 启动后台 Agent：carol-frontend

🔄 新任务已分配给 carol

示例 3: 遇到错误

code

（后台）Task-Master 连接超时

Skill 自动执行：
  1. ⚠️  检测到 Task-Master 超时
  2. 🔄 重试 1/3（等待 1 秒）
  3. 🔄 重试 2/3（等待 2 秒）
  4. 🔄 重试 3/3（等待 4 秒）
  5. ❌ 仍然失败，记录到 errors.log
  6. ✅ 继续运行（不停止监控）

📝 错误已记录：taskmaster_sync_failed

🎓 设计原则

•最小权限原则 - 仅操作必要的文件
•原子操作原则 - 利用 Edit 工具的原子性
•时间可控原则 - 严格遵守时间限制
•职责单一原则 - 仅监控和协调，不开发
•错误隔离原则 - 分层处理，不同策略

⚠️ 重要提醒

本 Skill 不适合以下场景：

•❌ 需要创建/删除文件
•❌ 需要执行系统命令
•❌ 需要操作 Git 仓库
•❌ 需要修改项目配置

适合的场景：

•✅ 监控 Agent 状态
•✅ 同步 Task-Master 状态
•✅ 协调任务分配
•✅ 记录错误日志

🔜 后续增强（可选）

如果需要扩展功能，可以考虑：

•添加配置文件热重载
•支持自定义监控间隔
•添加性能监控（CPU、内存）
•支持多种 Task-Master MCP

但所有增强都必须遵守上述边界。