claude-code-controller（Claude 代码 controller）

Claude Code 控制器

专门用于控制 Claude Code 的技能，提供简化的命令接口和最佳实践。

📋 核心原则

1. 简单任务直接用 - 一行命令搞定
2. 复杂任务后台跑 - 后台模式 + 进度跟踪
3. 并行任务用 worktree - 多分支并行处理
4. 永远不要在家目录跑 - 只在项目目录或临时目录运行

🚀 快速开始

模式一：快速任务（Foreground）

适合：简单修改、代码审查、文件读取等 5 分钟内能完成的任务

# 在当前目录运行
claude --permission-mode bypassPermissions --print "你的任务描述"

# 在指定项目目录运行
cd /path/to/project && claude --permission-mode bypassPermissions --print "你的任务描述"

模式二：长时间任务（Background）

适合：功能开发、重构、测试编写等需要较长时间的任务

# 启动后台任务
bash workdir:/path/to/project background:true command:"claude --permission-mode bypassPermissions --print '你的任务描述'"
# 返回 sessionId 用于跟踪

# 查看进度
process action:log sessionId:XXX limit:50

# 检查是否完成
process action:poll sessionId:XXX

# 完成任务后清理
process action:kill sessionId:XXX

模式三：并行任务（Parallel）

适合：同时处理多个 issue、批量代码审查等

# 为每个任务创建独立 worktree
git worktree add /tmp/feature-a main
git worktree add /tmp/feature-b main

# 并行启动多个 Claude Code 实例
bash workdir:/tmp/feature-a background:true command:"claude --permission-mode bypassPermissions --print '开发功能 A'"
bash workdir:/tmp/feature-b background:true command:"claude --permission-mode bypassPermissions --print '开发功能 B'"

# 监控所有任务
process action:list

# 完成后清理
git worktree remove /tmp/feature-a
git worktree remove /tmp/feature-b

📝 常用命令模板

代码开发

# 开发新功能
claude --permission-mode bypassPermissions --print "
开发一个用户登录功能，要求：
1. 使用 JWT 认证
2. 包含密码加密
3. 添加速率限制
4. 编写单元测试

完成后运行：openclaw system event --text 'Done: 用户登录功能开发完成' --mode now
"

# 修复 bug
claude --permission-mode bypassPermissions --print "
修复 issue #123 中的空指针异常。
错误日志：[粘贴错误信息]
相关代码：[文件路径]

完成后运行：openclaw system event --text 'Done: Bug #123 已修复' --mode now
"

代码审查

# 审查 PR
claude --permission-mode bypassPermissions --print "
审查这个 PR 的改动：
1. 检查代码质量
2. 找出潜在 bug
3. 建议改进点
4. 确认是否符合项目规范

git diff origin/main...origin/pr/123
"

文件操作

# 批量重构
claude --permission-mode bypassPermissions --print "
将所有 .js 文件转换为 .ts：
1. 添加类型注解
2. 修复类型错误
3. 更新 import/export

完成后运行：openclaw system event --text 'Done: JS 转 TS 完成' --mode now
"

⚠️ 安全规则

1. 不要在家目录运行 - 只在项目目录或临时目录
2. 不要给完全权限 - 使用 --permission-mode bypassPermissions 而非 --yolo
3. 敏感操作要确认 - 删除、推送、发布等操作需要用户确认
4. 不要在 OpenClaw 目录运行 - 避免读取敏感配置文件

📊 进度跟踪

检查任务状态

# 列出所有运行中的任务
process action:list

# 查看特定任务输出
process action:log sessionId:XXX limit:100

# 检查任务是否还在运行
process action:poll sessionId:XXX timeout:5000

发送输入给 Claude

# 发送简单确认
process action:write sessionId:XXX data:"y"

# 发送带换行的输入
process action:submit sessionId:XXX data:"yes"

# 粘贴多行文本
process action:paste sessionId:XXX text:"多行内容"

🎯 最佳实践

任务描述技巧

1. 具体明确 - 不要说"改进代码"，要说"添加错误处理和日志记录"
2. 分步骤 - 复杂任务分解成清晰的步骤
3. 设定边界 - 说明哪些文件可以修改，哪些不能
4. 添加完成通知 - 让 Claude 完成后运行通知命令

示例好的任务描述

❌ 坏的："修复这个 bug"
✅ 好的："修复 src/auth/login.js 中的空指针异常，
         当用户名为 null 时抛出 ValidationError，
         添加单元测试覆盖这个场景"

❌ 坏的："改进性能"
✅ 好的："优化 src/api/users.js 中的数据库查询，
         使用批量查询替代 N+1 查询，
         目标是将响应时间从 500ms 降到 100ms 以下"

完成通知模板

在任务描述末尾添加：

当完全完成后，运行这个命令通知我：
openclaw system event --text "Done: [简要总结完成的工作]" --mode now

🔧 故障排除

Claude 卡住了

# 查看最后输出
process action:log sessionId:XXX limit:20

# 发送中断信号
process action:send-keys sessionId:XXX keys:["C-c"]

# 如果还不行，终止任务
process action:kill sessionId:XXX

权限问题

# 确保在项目目录运行
cd /path/to/project && claude --permission-mode bypassPermissions --print "任务"

# 如果需要写权限，确保目录可写
chmod -R u+w /path/to/project

输出太多

# 只看最新输出
process action:log sessionId:XXX offset:100 limit:50

# 搜索特定内容
process action:log sessionId:XXX | grep "ERROR"

📚 使用场景

💡 提示

• 保持任务专注 - 一个任务做一件事，不要试图一次性完成太多
• 善用完成通知 - 长时间任务一定要添加完成通知
• 定期检查进度 - 后台任务每 10-15 分钟检查一次进度
• 保留会话日志 - 重要任务的输出可以保存到文件供后续参考