前两周我做了一次挺上头的实验：把一个多模块 Node 项目里积压的 20 个测试补齐任务，从 Claude Code 的对话窗口里拿出来，改成了一堆独立的 Markdown 任务文件，再交给它在非交互模式下自动跑。跑完那天下班前，我盯着调度日志里一个任务失败、自动重试、另一个任务正常完成的过程，突然意识到：我把 Claude Code 用成任务调度器之后，真正值得看的不是它又完成了多少功能，而是背后那套任务拆分、状态回写、安全限制和失败恢复的设计。
这篇文章专门聊聊这个改造过程和设计心得，适合两类人：一是被 AI 编程助手“上下文不够用”折磨的人，想把它从单次问答变成可批量执行的流水线；二是对 Agent 系统设计感兴趣的人，想看看一个实际落地的调度框架长什么样。我会把可复现的步骤、提示词模板、外层调度脚本、常见坑都写出来，你照着搭一套就能用。
1. 为什么把 Claude Code 当任务调度器用？
1.1 从“一问一答”到“任务队列”
很多人用 Claude Code 的方式还是传统的聊天式：打开终端，敲一句“帮我修一下这个函数”，看完结果，再敲下一句。这种用法本身没问题，但一旦任务量上来，就立刻暴露两个痛点。
第一个痛点是上下文累积。一个稍大的需求稍微聊深一点，对话里就堆满了历史内容。模型不是记不住，而是容易把注意力分散到无关的旧讨论上，改着改着突然开始“回忆”前面说过的边角料，非常影响输出质量。第二个痛点是任务之间没有边界。你让它改完 A 再改 B，中间一旦发生意外中断，要么从头再来，要么得费力解释“刚才进行到哪一步了”。
我当时的做法很直接：把 20 个测试补齐任务拆成 20 个独立的任务文件，每个文件只描述一个模块的目标、路径、约束和验收条件。然后写了一个外层 Python 脚本，循环调用claude -p非交互模式去执行每个任务。跑完一个记一个状态，失败就把错误信息写回状态文件，外层下次启动时能看到哪些完成了、哪些没完成。
这就是任务调度器的核心思维：把一个大而模糊的目标，拆成多个小且明确的原子任务，排队执行，记录状态，失败隔离。Claude Code 在这里变成了一个“执行引擎”，而我定义的 Markdown 任务文件和状态文件，才是真正的控制中枢。
1.2 调度器设计的三层职责
用了一周之后，我总结出这套调度架构其实可以拆成三层，每一层的职责都很清楚。
第一层是调度层，也就是外层脚本。它负责读取任务列表、决定串行还是并发、设置超时时间、捕获异常、更新状态文件。这层不关心“怎么写代码”，只关心“哪个任务该跑了”“跑失败了要不要重试”“日志写到哪”。
第二层是执行层，也就是 Claude Code 本身。它拿到一个独立任务描述之后，在自己的上下文窗口里规划步骤、读写文件、执行命令、验证结果。每个任务之间互不干扰，上一个任务的失败不会污染下一个任务的上下文。
第三层是反馈层，也就是状态文件和日志。Claude Code 跑完一个任务之后，会把结果摘要、剩余事项、错误信息写到一个约定好的 JSON 文件里。外层脚本靠这个文件来判断下一步动作，而不是靠“猜”。
这个三层模型，和很多团队里的项目经理、工程师、看板工具之间的关系很像。项目经理不写代码，但负责派活和验收；工程师只专注手头的一张卡；看板展示了所有人的进度和阻塞项。Claude Code 调度器本质上就是把这套协作流程搬到了本地。
2. 值得细看的设计细节：Claude Code 调度器思路拆解
2.1 刻意的小粒度任务与上下文预算
Claude Code 的上下文窗口并不小，但在调度体系里，我刻意把所有任务都控制在一个“刚好够用”的范围内。这不需要精确计算 token，而是靠经验判断：一个任务涉及的文件数量、改动范围、验证步骤，尽量限制在一个人 20 分钟内能手工完成的量级。
为什么要这么做？道理很简单：上下文窗口再大，也是有限的。更重要的是，任务描述越短、越聚焦，模型的注意力就越集中在真正需要修改的代码上。我见过有人把 10 个模块的需求写进同一个提示词，结果就是模型前面分析得很起劲，后面改到第三个模块时已经开始漏改。
实际操作时，我每个任务描述都遵循固定格式，用【目标】【相关文件】【约束】【验收标准】四段式。比如一个测试补齐任务的描述长这样：
【目标】 为 src/utils/dateParser.ts 补充单元测试，覆盖 parseDate 的正常输入、非法输入和边界时间。 【相关文件】 - src/utils/dateParser.ts - tests/utils/dateParser.test.ts 【约束】 - 使用 vitest，不引入新的测试框架 - 不要修改 src/utils/dateParser.ts 的导出接口 - 如果已有测试文件，先读取原有内容再补充，不要直接覆盖 【验收标准】 - 运行 npm test -- tests/utils/dateParser.test.ts 全部通过 - 新增用例至少 6 个这个格式看起来简单，但非常关键。“相关文件”让模型知道该读什么；“约束”限制了它的自由发挥空间；“验收标准”告诉它如何自我检查。我尝试过只写“给这个文件补几个测试”，效果远不如这种格式。模型会把上下文预算浪费在扫描整个项目上，而不是聚焦到指定文件。
2.2 状态回写与失败恢复
调度器最怕的不是任务失败，而是失败之后不知道从哪继续。我在设计状态文件时只保留了最小必要字段，避免自己也被信息淹没。
{ "task_id": "14_fix_auth_middleware", "status": "failed", "error": "未找到 router 中间件声明位置，尝试修改了错误文件", "remaining": "重新定位中间件引用位置，确认修改前先 grep 找出所有使用点" }这个文件由 Claude Code 自己维护。我在任务提示词最后都会加上一句：“完成或失败后，请更新 /path/to/status.json 对应字段，不要直接退出。”这句话看起来像废话，实际作用很大。因为 Claude Code 有很强的自我记录意识，你明确要求它写状态，它就会在结束前检查自己是否真的完成了，而不是只回复一句“我已经改好了”。
失败恢复时，外层脚本会把上次的错误信息和 remaining 字段拼进新的任务提示词，然后再次调用。我在 20 个任务里遇到过两次失败，一次是模型把文件路径看错了，一次是测试命令写错。第二次重试时，我直接把错误信息原样塞给它，它很快意识到了问题，换了个思路搞定。这种“记录错误、带着错误重试”的机制，和人类排障时的复盘节奏很像。
2.3 权限边界：可执行命令白名单与危险操作拦截
把 Claude Code 当调度器用，最大的风险来自它能直接执行终端命令。写文件是好事，执行npm test也是好事，但绝对不能让它顺手干出git push --force或者rm -rf node_modules这种事。
我的做法是在用户级配置文件~/.claude/settings.json里设置权限白名单。一个简单的配置示例：
{ "permissions": { "allow": [ "Read", "Write", "Bash(npm test)", "Bash(git status)", "Bash(git diff)" ], "deny": [ "Bash(git push)", "Bash(git commit)", "Bash(rm -rf *)" ] } }这里的关键思路是“最小权限”：默认情况下，它只能读文件、写文件，以及跑极少数的安全命令。凡是可能对外产生不可逆影响的操作，直接 deny。更进一步，我把调度脚本放在一个独立的临时目录里跑，或者用 Docker 容器隔离。容器里只有项目代码和依赖，没有 git 远程权限，就算 Claude Code 真的想执行危险命令，也找不到目标。
这个设计比“功能多不多”更值得琢磨。一个能自己写代码、跑命令的 Agent，如果没有边界，就像请了一个能力很强但手里永远拿着钥匙的临时工。你需要的不是他什么都能干，而是他在你画好的圈子里把活干漂亮。
3. 实操：把 Claude Code 改造成任务调度器
3.1 环境准备：安装与跨平台配置
开始之前，先确保 Claude Code 本体是可用的。安装方式官方推荐两种，我用的是 npm 全局安装：
npm install -g @anthropic-ai/claude-code安装完之后执行claude --version验证。如果没有输出，检查一下 npm 全局 bin 目录是否在 PATH 里。Windows 上我一般用 WSL 或者原生终端跑，原生终端需要确认 Node.js 版本在 18 以上；Ubuntu 等 Linux 发行版通常没有额外问题，但要注意权限：如果当前用户无法写项目目录，后续任务里的文件读写会失败。
安装好之后，先在交互模式登录一次。直接在终端敲claude，按提示走一遍登录流程。调度脚本是借用你本机的登录凭证来调用模型的，所以这一步必须提前完成。
如果你在 VS Code 里工作，可以安装官方扩展“Claude Code for VS Code”，它会读取同一个登录状态，体验上等于把命令行的能力搬到了编辑器侧边栏。不过调度器脚本本身不依赖 VS Code，纯终端环境就够。跨平台配置方面，唯一要注意的是路径分隔符：在 Windows 原生终端里，所有 Python 脚本中的文件路径建议用pathlib，不要手写带反斜杠的字符串，否则换到 Linux 或 WSL 上很容易炸。
3.2 定义任务清单与提示词模板
调度器的“输入”就是任务文件。我在项目根目录下建了一个tasks/文件夹，每个任务是一个独立的.md文件，文件名即任务 ID，比如01_fix_date_parser.md、02_refactor_auth.md。
提示词模板我固定成下面这个结构：
你是一个任务调度器中的执行引擎。请完成以下任务。 【任务ID】 {task_id} 【目标】 {goal} 【相关文件】 {files} 【约束】 {constraints} 【验收标准】 {acceptance_criteria} 完成后，请将执行结果写入状态文件 /path/to/status.json，更新对应 task_id 的 status、summary、remaining 字段。不要直接退出。为什么要写“你是一个任务调度器中的执行引擎”？因为这样能让模型快速进入批处理状态，减少它“聊天式”的废话。我实测下来，加了这句之后，输出更简洁，也更少出现“好的，我来帮你……”这类寒暄。它还更容易接受“更新状态文件”这种看起来像程序指令的要求。
任务清单的粒度判断标准很简单：如果一个任务需要同时改动超过 5 个文件，或者涉及两个以上不相关的模块，我就继续拆。宁可多拆几个任务，也不要在一个小任务里塞太多意图。
3.3 外层调度脚本：串行版与并发版
调度层的核心是一个 Python 脚本，我先把最简单的串行版本放出来，你自己跑一遍就知道这套机制怎么运转了。
import json import subprocess import pathlib import sys ROOT = pathlib.Path("/path/to/project") TASK_DIR = ROOT / "tasks" STATUS_FILE = ROOT / "status.json" def load_status(): if STATUS_FILE.exists(): return json.loads(STATUS_FILE.read_text(encoding="utf-8")) return {"tasks": {}} def run_claude(prompt: str) -> str: cmd = [ "claude", "-p", prompt, "--output-format", "json", "--permission-mode", "acceptEdits", "--allowedTools", "Read Write Bash(npm test) Bash(git status) Bash(git diff)", "--disallowedTools", "Bash(git push) Bash(git commit) Bash(rm -rf *)", ] proc = subprocess.run( cmd, cwd=ROOT, capture_output=True, text=True, timeout=900, ) return proc.stdout def run_all(max_retry: int = 1): status = load_status() for task_file in sorted(TASK_DIR.glob("*.md")): task_id = task_file.stem if status["tasks"].get(task_id, {}).get("status") == "done": continue prompt = task_file.read_text(encoding="utf-8") print(f"[scheduler] start {task_id}") last_error = "" for attempt in range(max_retry + 1): if last_error: prompt += f"\n【上次错误】\n{last_error}\n请参考这个错误调整方案后重试。" try: output = run_claude(prompt) status["tasks"][task_id] = { "status": "done", "attempt": attempt, "output_preview": output[:300], } print(f"[scheduler] done {task_id}") break except Exception as exc: last_error = str(exc) status["tasks"][task_id] = { "status": "failed", "attempt": attempt, "error": last_error, } print(f"[scheduler] failed {task_id}: {last_error}") STATUS_FILE.write_text(json.dumps(status, ensure_ascii=False, indent=2)) if __name__ == "__main__": sys.exit(run_all())这个脚本有几个地方值得说明。第一，--permission-mode acceptEdits表示自动接受文件编辑类操作，减少交互卡住；读和写文件在大多数任务里都是刚需。第二，--allowedTools和--disallowedTools是双保险，在配置文件和命令行同时限制。第三，timeout=900是硬超时，单个任务跑超过 15 分钟就强制中断，避免周而复始的循环。
如果你想让互不依赖的任务并发跑，可以用 Python 的concurrent.futures.ThreadPoolExecutor，把run_claude封装成可并行调用的函数。但我必须提醒一点：并发会显著增加 API 调用频率，容易撞上速率限制。更重要的是，如果两个任务改到同一个文件，会产生难以排查的冲突。我的经验是，优先串行，除非你对文件间的依赖关系非常有把握。
3.4 定时触发与结果通知
调度器搭好之后，我把它挂到了系统定时任务里，让它在每天凌晨自动清理“低优先级但必须做”的技术债。Linux 和 macOS 直接写 cron 就行：
0 2 * * * cd /path/to/project && /usr/bin/python3 scheduler.py >> logs/scheduler.log 2>&1Windows 上用“任务计划程序”，触发器选“每天”，操作里填python scheduler.py，起始目录填项目路径，也可以达到同样效果。这里的关键是日志一定要重定向到文件，否则 cron 环境里输出丢失，出了问题你完全不知道发生过什么。
结果通知我用的最简单方案：日志尾部追加一行[scheduler] done task_id，然后用grep查看失败率。如果你希望更主动，可以在脚本里加一个 webhook 调用，比如把失败任务列表POST到一个内部接口。不过对于个人项目来说，早晨起来cat logs/scheduler.log | tail -50已经够用。
4. 本地模型与订阅限制：两类环境的调度配置实践
4.1 使用 LM Studio 等本地模型作为执行引擎
不少人问过我：用 Claude Code 跑调度，是不是一定要联网订阅？如果不是重度使用，其实可以把它指向本地模型。Claude Code 支持通过环境变量ANTHROPIC_BASE_URL来覆盖 API 地址，所以你可以把下面的配置写进启动脚本：
export ANTHROPIC_BASE_URL="http://127.0.0.1:1234" export ANTHROPIC_MODEL="你的本地模型名"我在本地试过用 LM Studio 起一个线程跑“批量给注释补中文说明”这类低难度任务。为什么说低难度？因为本地模型在复杂代码重构、跨文件追踪上的能力，和云端模型差距还是挺明显的。但本地模型的一个巨大优势是免费、离线、没有接口速率限制，你把一堆格式化、写文档、重命名的小任务丢给它，完全没问题。
需要注意一点：Claude Code 走的是 Anthropic 兼容接口，而 LM Studio 默认提供的是 OpenAI 兼容接口。如果你手头的工具只支持 OpenAI 格式，中间需要再套一层转换服务。我的建议是优先选那些直接声明支持 Anthropic 兼容端点的本地推理服务，省掉转换层的维护成本。这个配置只影响“执行层”，调度层脚本完全不用改，因为外层脚本调用的始终是claude命令。
4.2 organization 禁用订阅访问的排查路线
如果你在公司电脑上跑，可能会遇到一个很经典的报错，提示大意是“your organization has disabled claude subscription access for claude code”。这个报错说明当前使用的账号权限不足，通常是企业管理员在 Claude 系统后台限制了订阅访问。
碰到这种情况，我推荐的排查顺序是：先确认你是否在用个人订阅账号。如果登录的是公司统一分配的账号，那权限策略由管理员控制，个人无法绕过，直接找 IT 或管理员了解开通方式是正路。如果你确实在使用自己的账号，再看环境变量。有时候脚本里设置了ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN，会覆盖本机登录状态，导致系统认为你是某个被限制的账户。可以执行env | grep ANTHROPIC检查，把可疑的环境变量临时去掉再试。
这个问题的本质是身份边界。Claude Code 在本机存了登录态，但一旦存在环境变量，它的优先级会更高。调度脚本里如果为了其他用途设置了这类变量，记得在调用claude之前清理干净，否则你会看到一系列和订阅完全无关的诡异报错。
5. 常见问题与排查技巧实录
5.1 任务卡住或重复执行
调度跑了一个月，我遇到最多的问题是任务卡住，表现为明明某个文件已经改好了，但任务迟迟不结束，或者不断尝试同一个命令。原因通常有两个：一个是模型在“自我怀疑”，反复验证结果是否达标；另一个是执行命令回显太长，把上下文塞满了。
解决手段是双管齐下。第一，在任务描述里写明失败策略：“如果某个命令连续失败两次，不要继续尝试，直接记录失败原因并跳转到状态文件更新。”第二，外层脚本设置硬超时，也就是前面代码里的timeout=900。500 行代码能超过 15 分钟？大概率不是正常执行，而是在空转。超时中断不可怕，Status 文件里记一个 failed，下次调度带着错误重试就行。
5.2 命令白名单不生效
有时候你在settings.json里限制了命令，但 Claude Code 还是在“请求权限”或者直接拒绝。首先要确认配置文件的层级。用户级配置在~/.claude/settings.json，项目级配置在项目根目录的.claude/settings.json，两个文件会合并，但项目级优先。如果你把白名单写在用户级，项目级里一旦有旧的deny规则，仍然可能踩中。
另外，命令匹配规则是精确匹配的。Bash(npm test)只能允许npm test，如果你希望允许npm run test:unit，就得再写一条。我建议尽量精确到个别命令，不要写宽泛的Bash来省事。安全这件事，宁可多花一分钟加规则，也不要等出了问题再后悔。
5.3 文件被并发修改冲突
我一开始图快，让 4 个任务并行跑，结果两个任务同时改了同一个入口文件，其中一个把另一个的改动覆盖了。排查了半天才发现是文件锁缺失。如果你的任务之间没有任何共享文件，并发是安全的；一旦有共享文件，最简单的方式就是回退到串行。
更细一点的做法是给共享文件加“改动人”标记，比如让 Claude Code 在执行任务前先读取一个LOCK文件，发现被占用就跳过。但说实话，对我来说串行已经够快了。20 个任务全串行，一个任务平均 3 分钟，一个小时内跑完。与其花时间设计复杂锁机制，不如把任务拆得更独立。
5.4 如何解析输出并提取有效信息
claude -p默认输出比较啰嗦，里面可能混入模型思考过程、命令回显、最终结果。我在调度脚本里加了--output-format json，让输出变成结构化数据。即使这样，偶尔也会夹杂一些警告信息到 stderr，所以捕获时要同时处理stdout和stderr。
更稳的方案不是解析 stdout，而是让 Claude Code 把结果写进状态文件。你可以在提示词里明确要求“不要输出任何解释文字，只更新状态文件”。模型在指令清晰的情况下会照做。外层脚本只需要在命令执行完成后，重新读取status.json，判断对应任务的status字段是不是done，完全不用跟模型输出较劲。
5.5 上下文窗口超限的进一步思路
如果你已经按小任务来拆，仍然频繁遇到上下文超限，那可能是单个任务本身太重，比如要你重构一个 5000 行的模块。这时候我会开启 Claude Code 的 subagent 能力，在CLAUDE.md里定义一个更专项的子代理，让它只负责某个子问题。语义上有点像“把一个任务再下放给一个专职同事”。
不过在调度器场景下，我的优先级排序是：能拆任务就不开 subagent，因为外层脚本天然就是“任务分解器”。subagent 适合的是单个任务内部太复杂，而不是调度层的任务数量太多。把握住这个边界，你的调度系统就不会乱。
最后分享一个我最近养成的习惯：给每个任务文件都写“验收标准”。很多时候任务失败不是因为模型不行，而是因为我自己没想清楚“什么叫完成”。Claude Code 真正教会我的，不是写代码，而是把需求拆到可以验证的程度。现在我自己动手写代码之前，也会先给自己列一个带验收标注的任务清单，一条一条执行，效率比以前高很多。这大概就是好的工具设计的价值：功能帮你省时间，设计帮你改习惯。
