文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载本篇技术指南以开源仓库claude-code-system-prompts中的 Agent Prompt: Background agent state classifier约 6237 tokens对应 Claude Code v2.1.205为核心完整讲解 Claude Code 如何读取后台 Agent 转录文本的结尾tail将其判定为 working、blocked、done、failed 四种状态并输出可供手机通知与任务列表直接消费的紧凑状态 JSON。读完本篇你将掌握四态定义的判别逻辑、六大硬边界与显式标记、API/认证/基础设施错误的兜底规则、detail / tempo / needs / output 字段的写作规范以及它与后台作业 Agent 指令、Project 线程状态卡分类器之间的配套关系可直接用于理解或复刻 Claude Code 的后台任务状态跟踪机制。一、背景为什么后台 Agent 需要一个状态分类器在 Claude Code 中用户可以启动一个后台 Agentbackground job / background agent去执行编码任务然后离开电脑。系统需要知道这个 Agent 此刻处于什么状态以便决定是否通知用户。核心判定问题只有两个用户现在需不需要回来如果不需要工作是已经完成还是仍在进行这份 状态分类器提示词 就是干这件事的它读取 Agent 转录文本的尾部在四态中做出判定输出一段紧凑的状态 JSON供系统消费。分类结果直接驱动手机推送通知blocked会 ping 用户回来处理其他状态不会打扰用户。因此误判的代价是双向的假 blocked一次毫无意义的打扰假 done / 假 workingAgent 其实卡在等用户回复而任务一直闲置到用户偶然查看为止。分类器的输入与读取范围关键约束来自配套的 后台作业 Agent 指令分类器只能读取 Agent 的文本消息——它看不到工具输出、子 Agent 报告也看不到人类的回复。因此后台 Agent 被要求叙述Narrate行动前先写一行方案每完成一段说明发生了什么、接下来做什么复述Restate即使工具已经打印了结果也要在文本中用自己的话重述因为提取器看不到工具输出发出显式状态信号完成时输出独立的result:行、卡住时输出needs input:行、失败时输出failed:行。这些显式信号正是下文显式标记EXPLICIT MARKERS一节的 ground truth 来源——分类器把它们当作无可争议的事实。二、四种状态的精确定义1. done已完成Agent 已回答了请求、交付了成果并且不打算在没有用户进一步指示的情况下再做任何事。这是交互式会话中最常见的回合结束状态。需要注意done 不要求一定有 PR、commit 或文件产出。如果用户只是问了一个问题而结尾就是答案本身而非去找答案的计划那就是 done。以下类型的收尾都属于 done解释explanations、分析analyses、建议recommendationsheres what I found、the cause is X、no change needed以 files at 形式给出的文件路径收尾。2. working工作中Agent打算在无人指示的情况下继续推进。典型信号明确的向前意图now let me…、next Ill…、running…、checking…或正在等待它自己发起的外部事件CI、构建、子 Agent、部署、定时器named external wait。判定要点寻找显式的向前意图或具名的外部等待。3. blocked阻塞需要用户Agent 在没有用户介入的情况下无法继续。收尾表现为一个 Agent 必须得到答案才能继续的直接问题请求提供某样东西文件、凭据、决策、OTP要求用户执行某个动作replygo、approve the PR、run /login用户可修复的认证/API 错误。判据测试用户回复或行动是否能让它解阻塞能 → blocked。4. failed失败Agent 放弃因为任务在给定框架下结构上不可能完成仓库搞错了、功能不存在、前提为假、所有途径都试尽且没有任何用户能提供的东西可以解阻塞。此状态很罕见。关键区分如果 Agent点名了某个具体缺失的资源那是 blocked 而不是 failed——因为用户可以提供它来解阻塞。三、六大硬边界THE HARD BOUNDARIES文档明确给出了四条最常出错的边界判定规则。边界一Done vs Working一个收尾只要在解释、总结、汇报发现、展示改动——且没有说接下来还要做更多——就是 done。不要从以下情况推断 working警告性备注caveats后续建议follow-up suggestions只是没出现 done 这个词。只有出现显式向前意图now let me、next Ill、running或 Agent自己发起的具名外部等待waiting on CI、build in progress、fork still running时才判 working。边界二Done vs Blocked——可选提议 vs 硬性关卡交付完成后Agent 经常以追加提议收尾例如let me know if you want Xif youd like, I can also Yping me and Ill Zsay the word and Ill updatewant me to dig into that?tell me the IDs and Ill re-homehappy to do the latter if you wantshall I also…?这些都是done——交付物已经发出提议只是额外项。判别测试如果用户无视这个收尾问题原始请求是否仍然得到满足是 → done否 → blocked。唯一的例外是当问题涉及是否/如何交付用户请求的工作时——放进哪个 PR、要不要应用、推还是暂缓、采用哪种方案——此时交付物在没有答案的情况下不算落地所以是blocked。原文给出的成对示例Found the fix. Want me to add it to this PR or open a new one? →blocked交付方式尚未决定Fixed it in this PR. Want me to also clean up the old helper while Im here? →done交付已完成额外项是离题的。边界三Working vs Done vs Blocked——收尾提到等待时判别器是AGENT 自己是否还会做更多。Agent 的表述判定理由Ill report when X lands、next check in 5 min、shepherding CI、will re-poll、checking back、N agents in flight — Ill consolidateworkingAgent 拥有下一步无论它在等什么replygoto merge、awaiting your approval、which approach do you want?无 re-pollblocked只有用户能推动它前进auto-merge armed, awaiting stamp、posted to #stamps、CI will rundoneAgent 的部分已结束之后发生的事情无需它参与同时出现两者时Awaiting yourgo. Next check in 20m →working——Agent 会自行重新检查go只是可选的加速器不是硬性关卡。边界四粘性规则Stickiness分类器会被告知上一个状态不要从 done→working 或 failed→working除非 Agent显式重新开始working→done 是正常的回合结束路径当收尾是陈述性的、没有将来时计划时倾向于判 done。四、显式标记当作 ground truth 对待以下是无歧义的标记分类器必须当作事实依据标记文本判定No response requested. / No action needed. / Nothing needed from you.done单独一行的 result: textdone且 text 就是output.resultNext check in time / Shepherding CI / Ill report when X lands / checking backworkingReplygoto verb / Awaiting yourgo且未提及 re-pollblockedGiving up. / The task is not actionable.failed单独一行的 blocked: reason / Im blocked: reasonblocked其中result:与blocked:这两种独立成行的信号正是后台作业 Agent 指令中要求 Agent 主动发出的完成/阻塞信号对应result:与needs input:/failed:二者在协议层面是严格对齐的。五、API / 认证 / 基础设施错误一律 blocked绝不 failed凡是瞬时性的或用户可修复的API/认证/基础设施错误一律判 blocked绝不判 failed并在needs字段里给出修复动作。覆盖范围如下。Anthropic API401Invalid API keyPlease run /loginrate limitedoverloaded529credit balance too lowusage limit reachedMCP 服务器OAuth token expired/revokedvault credential missingMCP authentication failedMCP unauthorized外部服务gh auth logingcloud auth loginaws sso loginbad credentialstoken expiredGitLab/GitHub PAT 错误Stripe/Slack 401兜底条款任何点名了具体 re-auth / re-login 步骤的叙述性文本同样视为 blocked。六、其他消歧规则OTHER DISAMBIGUATION场景判定理由Agent 遇到错误但在重试/排查let me try again、checking the logsworking仍有向前意图Agent 停下并点名了某个用户能提供的具体缺失项文件、环境变量、凭据、OTP、路径、决策即使措辞是 cant proceed 或 stopping hereblocked用户可解阻塞不是 failed交付发现后的范围备注、caveats、FYInote: Y is untested、out of scope but worth flaggingdone交付已完成无问题的选项总结或建议B is the right call、Id take option 1done建议本身就是交付物对用户的祈使句但属于建议而非关卡Ship the seek scale.、Run the migration when ready.doneAgent 并未在等它七、完整示例集tail → classification以下示例全部继承自原文档可直接当作判定规则的可执行训练数据。working 示例Reading config files to understand the setup. → {state:working,detail:reading config files to map the setup,tempo:active,output:{}} Found it in auth.ts:88. Now let me check if the same pattern appears elsewhere. → {state:working,detail:found pattern at auth.ts:88; scanning for other occurrences,tempo:active,output:{}} Waiting for CI to finish (~8 min). → {state:working,detail:waiting on CI (~8 min),tempo:idle,output:{}} Awaiting your go. Next check in 20m. → {state:working,detail:PR awaiting go-ahead; agent re-checking in 20m,tempo:idle,output:{}} Agent 会自行重新轮询go 只是可选的加速器 → working Babysit tick — PR #40689. All CI green, threads resolved. Awaiting human approval. Next check via cron in ~5 min. → {state:working,detail:PR #40689 green, awaiting approval; next cron check ~5 min,tempo:idle,output:{}} next check via cron Agent 会重新轮询 → working Both subagents updated to use ack_seq. Theyre still running — Ill report PR URLs when each completes. → {state:working,detail:2 subagents running with ack_seq rename; will report PR URLs,tempo:idle,output:{}} Ill report when each completes Agent 会针对结果行动 → working Searching internal knowledge for the org ID — Ill report back when the search completes. → {state:working,detail:searching internal KB for org ID,tempo:active,output:{}}blocked 示例CI green on PR #31030. Reply go to merge. → {state:blocked,detail:PR #31030 CI green; awaiting user go-ahead to merge,tempo:blocked,needs:reply go to merge,output:{}} 无 Agent 重轮询只有用户的 go 能推动 → blocked I found the bug in auth.ts:42. Want me to fix it or just report? → {state:blocked,detail:found null-check bug at auth.ts:42; awaiting fix-vs-report,tempo:blocked,needs:fix it or just report?,output:{}} Agent 尚未交付修复没有答案就无法继续 → blocked Found the fix — its a 3-line change to the retry handler. Want me to add it to this PR or open a new one? → {state:blocked,detail:3-line retry-handler fix ready; awaiting which PR,tempo:blocked,needs:add to this PR or open a new one?,output:{}} 问题关乎如何交付被请求的工作 → blocked I cant proceed — the repo requires GITHUB_TOKEN and its not set. → {state:blocked,detail:missing GITHUB_TOKEN; cannot clone,tempo:blocked,needs:set GITHUB_TOKEN env var,output:{}} Cant run the tests — needs the openapi.yaml file which isnt in this checkout. Stopping here. → {state:blocked,detail:missing openapi.yaml; cannot run tests,tempo:blocked,needs:provide config/openapi.yaml,output:{}} stopping 点名具体缺失资源 → blocked不是 failed API Error: 401 Invalid API key · Please run /login → {state:blocked,detail:API auth failed (401),tempo:blocked,needs:run /login,output:{}}done 示例Auto-merge armed on PR #4821. Posted to #stamps. Awaiting stamp. → {state:done,detail:PR #4821 auto-merge armed; posted to #stamps,tempo:idle,output:{result:PR #4821 ready, auto-merge armed}} 由 GitHub 合并而非 AgentAgent 的部分已结束 → done Heres how the auth flow works: the token is validated in middleware.ts:42 before each request. → {state:done,detail:auth flow: token validated in middleware.ts:42 per request,tempo:idle,output:{result:token validated in middleware.ts:42}} 回答了问题——done 不需要 PR/commit/文件 Indentation is now consistent at all four call sites (RepoPicker, both EnvironmentPicker sites, BranchPicker, SessionView). CIs swift-format should find nothing left to reflow. → {state:done,detail:indentation fixed at 4 call sites; swift-format clean,tempo:idle,output:{result:indentation consistent across RepoPicker/EnvironmentPicker/BranchPicker/SessionView}} At 30-40k rows theres no hint that gets you there without a new index — and at that point the column is strictly cheaper than a (session_uuid, source, sequence_num DESC) index. → {state:done,detail:dedicated column beats a composite index at 30-40k rows,tempo:idle,output:{result:recommend dedicated column over composite index}} 纯分析收尾无问题、无向前意图 → done No response requested. → {state:done,detail:completed; no response requested,tempo:idle,output:{}} Both PRs remain bot-clean. Continue your e2e test on the restarted localhost:4000 (now pointed at local CCR). → {state:done,detail:both PRs bot-clean; localhost:4000 restarted on local CCR,tempo:idle,output:{}} Continue your test 是对用户的建议不是 Agent 的计划 → done Wrote the chart to plots/venn.png; script is at scripts/venn.R. → {state:done,detail:venn chart written to plots/venn.png scripts/venn.R,tempo:idle,output:{result:plots/venn.png scripts/venn.R}} Fixed the regex; tests pass. If you want, I can also open a follow-up PR to clean up the old helper. → {state:done,detail:regex fixed in parser.ts, all tests green,tempo:idle,output:{result:regex fixed, tests pass}} 交付物已发出提议是离题的额外项 → done Throughput drop confirmed — ~16K/min notifications being dropped from pod capacity. Ship the seek scale. Want me to dig into the upstream volume change too? → {state:done,detail:~16K/min notif drop confirmed; recommend seekscale,tempo:idle,output:{result:~16K/min drop, pod capacity — ship seekscale}} 发现 建议已交付尾部问题只是可选项 → done Not applied — say the word and Ill update both widgets. → {state:done,detail:widget query change drafted; not applied pending go-ahead,tempo:idle,output:{}} say the word and Ill 可选提议 → done B is the right call — it lands in the table the chart already reads, and avoids the migration. → {state:done,detail:recommend option B: reuses the table, avoids the migration,tempo:idle,output:{result:recommendation: option B}} PR opened: https://github.com/acme/repo/pull/123\nresult: fixed auth race in auth.ts, PR #123 → {state:done,detail:opened PR #123: fixed auth race,tempo:idle,output:{result:fixed auth race in auth.ts, PR #123}} result: 独立成行 → done且该行内容即 output.result Added the analytics enum conditional at the .withScreenAnalyticsLogging call site. Want me to also add the missing screen tag for the empty-state view while Im here? Its a ~5-line change. → {state:done,detail:analytics enum conditional added at the logging call site,tempo:idle,output:{result:analytics logging wired at SessionView}} 被请求的工作已交付while Im here 的额外项是离题的 → donefailed 示例The build is broken on main and I cant reproduce locally. Giving up. → {state:failed,detail:cannot reproduce build failure; logs uninformative,tempo:idle,output:{}} 没有任何具体资源可解阻塞途径已试尽 → failed八、对比对CONTRASTIVE PAIRS表象相同、状态不同原文档专门给出四组表面句式几乎一样、判定截然相反的对照是理解边界规则的最佳速查表述 A状态表述 B状态区分要点Tests pass. Let me know if you also want the docs updated.doneTests written but I havent run them. Let me know which env to use.blockedA交付物已发出提议是额外项B交付物未经验证需要 env 才能继续Waiting for CI (~8 min).workingCI green. Awaiting yourgoto merge.blockedA只是外部等待B用户关卡Want me to also clean up the old helper?doneWant me to apply this fix or just report it?blockedA交付后的离题额外项B被请求工作的交付方式Ill re-pull metrics when the timer fires and confirm it drained.workingIll re-pull metrics once you confirm the timer fired.blockedAAgent 拥有下一步B用户拥有下一步九、输出协议状态 JSON 与字段写作规范分类器必须只输出下面的 JSON不加任何代码围栏{state:working|blocked|done|failed,detail:one line, ≤64 chars,tempo:active|idle|blocked,needs:when blocked: the exact ask; omit otherwise,output:{result:one-sentence deliverable headline, ≤180 chars; omit when working}}detail锁屏头条≤64 字符约十个词detail会显示在用户的手机锁屏和会话列表的单行状态列上所以要写得像同事发的 Slack 消息点出具体事物文件、函数、错误、数字、发现以及它发生了什么。✅ fixed auth race in middleware.ts, tests green而不是 completed task✅ waiting on CI for #4821而不是 working✅ confirmed 16K/min drop from pod capacity而不是 investigated issue硬性预算约 64 字符 / 十个词。它是标题HEADLINE不是报告——具体名词 它发生了什么不要括号、不要 URL、不要第二从句的解释。其余内容放进可以更长的output.result✅ PR #4821 merged; auto-merge disarmed❌ PR #4821 was failing because the retry helper double-counted (see #4790); fixed and now green on rebase and mergedtempo三种节奏active 正在计算idle 在等外部事物CI、定时器、评审者blocked 在等用户。needsblocked 时的精确行动仅在 blocked 时出现用户应当执行的确切动作尽量逐字照抄转录尾部——用户会直接照此行动不会去读转录。其他状态下省略该字段。output.result已完成交付物的一句话头条一句话点名一个已完成的交付物直接答案、Agent 产出的 URL/路径、用户应运行的命令。如果转录尾部有独立成行的result:该行就是 result。仍在工作时省略{}或者当它只会重复状态时也省略。十、配套机制与后台作业 Agent 指令的闭环状态分类器并不是孤立存在的它与 Claude Code 的后台作业体系构成闭环后台作业 Agent 指令告诉后台 Agent叙述进度、复述工具结果、并在完成/卡住/失败时分别输出独立成行的result:、needs input:、failed:信号。该指令明确说明result:行是唯一的完成信号像 done 或 finished 这样的散文不会被检测到——这与分类器把result:视为 ground truth、把 Giving up. 判为 failed 完全对应。后台会话指令规定了后台作业的运行环境临时文件放在$CLAUDE_JOB_DIR/tmp避免并行后台作业共用/tmp互相覆盖并要求以用户可直接行动的报告收尾做了什么、成果在哪、下一步命令。后台会话 worktree 持久化指引补充了后台作业的 git 行为在 worktree 中改动后应提交并推送保证工作不随会话删除而丢失。也就是说分类器的判定质量取决于后台 Agent 是否遵守叙述与信号约定Agent 发好result:/needs input:/failed:信号分类器就能稳定产出正确的四态 JSON。十一、横向对比Project 线程状态卡分类器仓库中还收录了结构高度相似的 Project 线程状态卡分类器约 4299 tokens。两者可以互为参考维度后台 Agent 状态分类器Project 线程状态卡分类器输入Agent 转录尾部 上一状态线程上一状态 调用的工具 最近的人类消息 线程最后消息尾部状态集4 态working / blocked / done / failed5 态needs_reply / needs_approval / done / failed / working用途决定是否推送手机通知为 Project 所有者生成状态卡两行 建议回复输出字段state / detail / tempo / needs / output.resultstate / headline / needs / happened / needs_you / reply核心判据用户回复/行动能否解阻塞同样以所有者是否必须行动为核心值得注意的差异在线程场景中401 / rate limited / overloaded / token expired这类错误被划入failed所有者无法在线程内修复只能 Retry later 或 Reconnect GitHub in settings, then retry而网络策略/出口代理拦截blocked by network policy、domain not allowed被划入needs_approval所有者放行域名即可继续——这与后台 Agent 场景API/认证错误一律 blocked的口径不同反映了用户能否就近修复在不同场景下的不同答案。阅读两个文档时务必注意这一差异。十二、仓库中的阅读路径主文档system-prompts/agent-prompt-background-agent-state-classifier.md配套一system-prompts/agent-prompt-background-job-agent-instructions.md后台 Agent 的信号约定配套二system-prompts/system-prompt-background-session-instructions.md后台会话运行环境配套三system-prompts/system-prompt-background-session-worktree-persistence-guidance.md后台会话 git 持久化横向参考system-prompts/agent-prompt-project-thread-status-card-classifier.md五态线程状态卡分类器仓库总览与提取说明README.md提示词直接提取自 Claude Code 的 npm 包与线上安装版本逐字一致如需定制本地安装中的提示词片段仓库提到可使用 tweakcc 工具对同一字符串做补丁从源码结构看这些提示词都是作为独立字符串嵌入 Claude Code 主程序一个大型压缩 JS 文件中、按环境与配置条件性注入的因此本仓库中的分类器文档即是线上后台任务状态跟踪链路的权威实现文本。赞分享文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载相关推荐Ralph for Claude Code实时状态检查JSON格式输出解析终极指南Ralph for Claude Code实时状态检查JSON格式输出解析终极指南 Ralph for Claude Code是一个强大的自主AI开发循环系统人工智能AI 应用自主智能体CLI开发工具agent-core-v2 目标阻塞提醒注入Goal Blocked Reminder深度解析Kimi Code 的 blocked 状态上下文机制agent core v2 目标阻塞提醒注入Goal Blocked Reminder深度解析Kimi Code 的 blocked 状态上下文机制 本文AI Agent代码智能体人工智能大模型CLIAX状态机深入剖析PENDING、FAILED、COMPLETED、CANCELED五态流转AX状态机深入剖析PENDING、FAILED、COMPLETED、CANCELED五态流转 AX Agent Executor是 Google 开源的分人工智能AI AgentAgent 框架自主智能体上一篇斯坦福CS 229机器学习速查手册7份PDF装下整门课的知识点下一篇终极指南如何用Next AI Draw.io版本历史功能跟踪和恢复图表修改记录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考