clawteam-dev

ClawTeam 本地开发

此技能用于在 ClawTeam 仓库内开发和验证 ClawTeam。 当任务涉及修改 ClawTeam 本身、测试本地行为，或根据当前检出版本验证多 Agent 工作流时，请使用此技能。

开发环境初始化

使用初始化脚本统一本地开发环境：

bash scripts/bootstrap_clawteam_dev.sh

此脚本位于此技能文件夹中的 scripts/bootstrap_clawteam_dev.sh。

此脚本会执行以下所有操作：

• 在 ~/.clawteam-venv 创建固定的 uv 环境
• 将当前仓库及其开发依赖安装到该环境中
• 设置 ~/.local/bin/clawteam，使其指向此固定环境
• 在 ~/.bashrc 中添加 clawteam() shell 函数代码块

完成后：

source ~/.bashrc
clawteam --version

如果你希望在机器上的不同 Python 环境中使用相同的 clawteam 命令，请使用此初始化脚本。

项目技能配置

要配置另一个本地项目，使其 ./.agents 和 ./.claude 目录直接使用此仓库中的本地 ClawTeam 技能：

bash scripts/link_local_clawteam_skills.sh /path/to/project

此脚本位于此技能文件夹中的 scripts/link_local_clawteam_skills.sh。

此脚本会在目标项目中创建以下符号链接：

• ./.agents/skills/clawteam
• ./.claude/skills/clawteam

每当你想刷新或重新创建这些链接时，都可以再次运行此脚本。

典型用途

• 代码更改后运行有针对性的本地验证
• 重现 spawn / board / task / inbox / harness 相关问题
• 在 tmux 或 subprocess 模式下对真实 CLI 进行冒烟测试
• 基于当前仓库检出版本，端到端检查 ClawTeam 工作流

快速验证

优先选择能够验证更改的最小验证范围。

ruff check clawteam/ tests/
pytest tests/<target_file>.py -q

只有在更改涉及多个模块时，才进行更广泛的测试：

pytest tests/test_cli_commands.py -q
pytest tests/test_spawn_backends.py -q
pytest tests/test_harness.py tests/test_event_bus.py -q

先决条件

• 可用的 clawteam 命令
• 可用的 tmux
• 如果要启动真实工作进程，需要受支持的 CLI Agent，例如 claude 或 codex
• 测试 worktree 隔离或本地源代码更改时，当前目录必须是 ClawTeam git 仓库

本地冒烟测试

如果你需要检查真实的多 Agent 工作流，而非运行单元测试，请使用此项。

clawteam team spawn-team dev-smoke -d "Local ClawTeam smoke test" -n leader
clawteam task create dev-smoke "Smoke test worker" -o worker1 -p high
clawteam spawn --team dev-smoke --agent-name worker1 --task "Report your status to leader and mark the task completed when done."
clawteam board show dev-smoke
clawteam task wait dev-smoke --timeout 300 --poll-interval 5

如果你要专门验证 harness 行为：

clawteam harness conduct dev-harness \
  --goal "Create a small implementation plan and execute it with one worker" \
  --cli codex \
  --agents 1

清理

尽可能使用真实的 ClawTeam 命令，而不是随意假设目录结构：

clawteam team cleanup dev-smoke
clawteam team cleanup dev-harness

如果崩溃的 tmux 会话或 worktree 遗留了下来，请先检查，再明确清理。

开发规则

• 优先使用 clawteam 命令，而不是直接编辑状态文件。
• 优先运行有针对性的测试；只有在更改涉及 spawn/runtime/workflow 边界时，才进行广泛的端到端测试。
• 在认定问题出在 spawn 层之前，先使用 board、task wait 和 team status 观察行为。
• 测试 Agent 协作时，先保持团队规模较小：一位负责人和一到两名工作 Agent。
• 只有在较低层级的 task/spawn/inbox 流程已正常工作后，才升级到 harness 或完整 swarm 测试。