Avoid unnecessary sleep commands: Do not sleep between commands that can run immediately — just run them. Use the Monitor tool to stream events… For one-shot “wait until done,” use Bash with run_in_background instead.
Monitor description 里反复强调”strong filter is first-class citizen”、”never pipe raw logs”、”monitors that produce too many events are automatically stopped”。这是在告诉 Claude:background 事件流的成本是对话上下文 · 不选择性输出会被系统截断。这条约束比”能不能跑”更微妙 —— 能跑但会被限流。
Cron 的 session-only 声明
CronCreate description 明确:job 只活在 session 里 · Claude 退出即失效。这一条把 background 机制的边界写进单个工具的描述里 —— 让 Claude 每次考虑 CronCreate 都会读到”这不是系统级 cron”。跟 AskUserQuestion 把「和 plan mode 的时序关系」写进自己描述是同一种思路:跨工具契约写进单个工具。
Bash 的字段描述里写:”Only use this if you don’t need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away — you’ll be notified when it finishes. You do not need to use ‘&’ at the end of the command when using this parameter.”
Agent 的字段描述里写:”Foreground vs background: Pass run_in_background: false to run an agent in the foreground when you need its results before you can proceed… Otherwise let it run in the background (the default) so you can keep working in parallel.”
Monitor 的描述围绕五件事:通知选型 / 事件流建模 / 完备性(silence is not success)/ 输出音量 / 数据源偏好。挑最有意思的看:
开篇一句,奠定基调
Start a background monitor that streams events from a long-running script. Each stdout line is an event — you keep working and notifications arrive in the chat.
“streams events” + “each stdout line is an event” 两个短语就把 Monitor 的语义钉死:**这不是”命令完成时返回全部输出”的工具,是”事件流工具”**。stdout 的每一行 = 一个 notification 流入对话,这条设计让 Monitor 完全对齐 unix 哲学 —— 任何能产生 line-buffered 输出的命令 / 脚本(tail -f / inotifywait -m / while 轮询 / 自定义 Python)都能变成事件源。
三选一场景分类 —— 从「通知次数」选工具
Pick by how many notifications you need:
One (“tell me when the server is ready / the build finishes”) → use Bash with run_in_background
One per occurrence, indefinitely (“tell me every time an ERROR line appears”) → Monitor with an unbounded command
One per occurrence, until a known end (“emit each CI step result, stop when the run completes”) → Monitor with a command that emits lines and then exits
开篇就把「怎么选工具」讲清楚。三种通知需求 → 三种工具选择。这条 prompt 训练 Claude 从「通知次数」的角度思考等待原语,而不是「等多久」或「等什么」。
反轮询原则 —— 单次通知不该用 Monitor
Don’t use an unbounded command for a single notification. tail -f, inotifywait -m, and while true never exit on their own
如果只想「build 完了通知我一次」· 用 Bash run_in_background + until grep -q "Ready" dev.log; do sleep 0.5; done —— 因为这个循环会 exit · 一次性通知。
Every pipe stage must flush per line or matches sit in its buffer unseen: grep needs --line-buffered, awk needs fflush(). head cannot flush at all — | head -N delivers nothing until N matches accumulate, then ends the stream.
Coverage — silence is not success. When watching a job or process for an outcome, your filter must match every terminal state, not just the happy path. A monitor that greps only for the success marker stays silent through a crashloop, a hung process, or an unexpected exit — and silence looks identical to “still running.” Before arming, ask: if this process crashed right now, would my filter emit anything? If not, widen it.
Recurring tasks auto-expire after 7 days — they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the 7-day limit when scheduling recurring jobs.
要求 Claude 主动告知用户 7 天上限。不是被动回答问题,是主动预告约束。这是「诚实的默契」—— Claude 帮用户设时不能藏着掖着。7 天上限本身是防遗忘设计:用户可能建了个「每小时监控」然后忘了,这个上限保证不会永久占资源。一次性任务不受此限(反正只 fire 一次)。
「负载分散」意识写进 prompt · 避开 :00 和 :30
Every user who asks for “9am” gets 0 9, and every user who asks for “hourly” gets 0 * — which means requests from across the planet land on the API at the same instant. When the user’s request is approximate, pick a minute that is NOT 0 or 30
这是把「系统级负载分散」写进 tool prompt 的稀有设计 —— 一般 tool 只关心 Claude 使用行为,不管服务器压力。Cron 例外,因为它是唯一一个可能造成用户不察觉的定期请求的 tool。所有用户对「9 点」的直觉都是「9:00」,所有请求都会挤在同一秒,Anthropic 后端会同时被打(负载尖峰)。让 Claude 自动挑一个偏移分钟(如 :57 或 :03),请求分散,后端稳定。
明确解释理由 · 不只是「按这规则来」—— Claude 理解规则背后的意图,才能在边界情况下自行判断。
何时反而应该用 :00 / :30 · 给出反例
Only use minute 0 or 30 when the user names that exact time and clearly means it (“at 9:00 sharp”, “at half past”, coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.
给出反例 —— 明确什么时候用 :00 是对的(用户明确要求或有会议对齐)。避免 Claude 教条化:规则有例外,exception 也写清楚。
不用 Cron 的场景 · 指路 Monitor
Not for live watching. CronCreate re-runs a prompt at fixed wall-clock intervals. To watch a log file, process, or command output and be notified the moment something changes, use the Monitor tool instead — Monitor streams events as they happen; cron polls on a schedule.
明确告诉 Claude 别拿 Cron 当 Monitor 用。tool description 里直接指路兄弟 tool,而不是指望模型自己去比对多个工具。这也是「工具间协作契约写进单个工具描述里」的又一个例子。
一次性任务的判断 · 从用户语言反推
For “remind me at X” or “at
给出 recurring: false 的具体触发信号 —— 「remind me at X」/「at
本地时区语义 · 避免 UTC 换算
Uses standard 5-field cron in the user’s local timezone: minute hour day-of-month month day-of-week. “0 9 * * *” means 9am local — no timezone conversion needed.
明确本地时区语义,避免 Claude 手动做 UTC 转换。这类「习惯误区」写进 prompt 是从血泪教训里长出来的 —— 老一辈 sysadmin 都遇过时区搞错的坑。用起来跟用户在自己终端里写 crontab 一样直觉。
抖动机制透明
The scheduler adds a small deterministic jitter on top of whatever you pick
告诉 Claude 有 jitter —— 让 Claude 别以为「我写了 :57 结果 :58 fire,是不是有 bug」。透明化让 Claude 建立合理预期。Jitter 具体规则:周期性任务实际触发最多延迟 10%(上限 15 分钟);一次性任务写在 :00 或 :30 时,自动提前最多 90 秒 fire。又是负载分散 —— 就算 Claude 教条化选了 0 9 * * *,runtime 也会加抖动让请求分散。
REPL idle 才触发 · 保护 Claude 不被打断
Jobs only fire while the REPL is idle (not mid-query).
如果 cron 到期时 Claude 正在处理另一个用户 prompt,触发会延迟到当前处理完。这防止 cron 和用户 prompt 撞车打断 Claude 思路。
Claude 依次 WebFetch 三个 URL · 每次带一个具体的 prompt告诉 WebFetch 要提取什么:
1 2 3 4
WebFetch( url: "https://www.anthropic.com/news/claude-4-5-sonnet", prompt: "Extract: model release date · main improvements over Claude 4 · benchmark numbers · API model ID" )
IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, look for a specialized MCP tool that provides authenticated access.
整个 WebFetch 描述里最重的一句。用 IMPORTANT + 全大写 WILL FAIL 双重强调:别浪费一次调用去撞 401。同时给了替代路径 —— 找专用的 MCP tool。这条 prompt 在训练 Claude 建立「先看工具集再动手」的直觉:每一次「no」都带一次「yes」 —— 不是简单说不行,而是「不行、但你可以走这条」。
MCP 优先让位
IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
不自动跟跨域重定向 —— 把决定权交给 Claude。防止一类攻击:诱导 WebFetch 通过跳转到你没意识到的域。让 Claude 显式确认再抓,是安全边界。同域跟随、跨域上报 —— 是一个既方便又不失控的默认。
15 分钟缓存透明
Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
告诉 Claude 有缓存 · 短时间内重复抓同 URL 会更快 · 鼓励在同一会话里放心重复调用(有些设计里 Claude 会因为”怕浪费”而不重复调 · 明确 cache 存在能消除这个顾虑)。
HTTP 自动升级 HTTPS
HTTP URLs will be automatically upgraded to HTTPS
隐藏行为透明化 —— Claude 写 http:// 会自动升级,不用手动改。降低出错概率,不做静默魔法。
Prefer working on tasks in ID order (lowest ID first) when multiple tasks are available
默认按 ID 顺序做任务。因为「早建的任务通常是后面任务的前置」 —— 这个约束让 Claude 的调度符合任务被建出来的直觉顺序,不东挑西拣。
TaskUpdate 前的 staleness 提醒
Make sure to read a task’s latest state using TaskGet before updating it.
任务状态可能被别的 agent 改过 —— 尤其在多 Claude 协作时。TaskUpdate 之前先 TaskGet 拿最新状态,防止 stale write 覆盖别人的更新。这本质上是乐观并发控制的直觉版本 —— 「先读再写」而不是「盲目更新」。
TaskOutput 的废弃告示
DEPRECATED: Background tasks return their output file path in the tool result, and you receive a <task-notification> with the same path when the task completes.
For bash tasks: prefer using the Read tool on that output file path
Task 家族有一个内置提醒机制 —— 如果 Claude 长时间没用 Task 相关工具,系统会插入一条 system reminder:
The task tools haven’t been used recently. If you’re working on tasks that would benefit from tracking progress, consider using TaskCreate to add new tasks and TaskUpdate to update task status.
这条 reminder 是 harness 层帮 Claude 建立「用 Task 家族追踪进度」的习惯。就算 Claude 一时忘了,系统会提醒 —— 但结尾一句「Only use these if relevant to the current work」也说明不是强制,是提示。这个 hook 是 Task 家族独有的 —— 前 9 个工具都不需要 reminder,因为它们的用途在当下就用了;Task 家族要追踪进度,需要跨时间的 nudge。
If the target is already known, use the direct tool: Read for a known path, grep via the Bash tool for a specific symbol or string. Reserve this tool for open-ended questions that span the codebase, or tasks that match an available agent type.
If the user specifies that they want you to run agents “in parallel”, you MUST send a single message with multiple Agent tool use content blocks.
并行是 Agent 的重要红利。三个 Agent 顺序调用 = 3 倍时间,同一 message 里三个 Agent = 1 倍时间。这条描述明确让 Claude 学会「独立任务用并行」的直觉 —— 用 MUST 大写量词强调这不是可选。
“背景运行”的默认值反转
Agents run in the background by default. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress.
默认值反转的设计意图很清晰:Agent 天然是长任务 · 短任务根本用不上 Agent。让长任务默认后台跑,主 Claude 可以继续做别的事 —— 这是用默认值编码最佳实践。
“决不外包理解”的红线
Never delegate understanding. Don’t write “based on your findings, fix the bug” or “based on the research, implement it.” Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.
问题在哪?综合是主 Claude 的核心工作。你派 subagent 去搜索是对的,但拿到搜索结果后要自己读、自己想、自己决定下一步。如果你把综合也外包出去,你就变成了「转发器」 —— 每一步都不理解,最后系统失控。
用 bold + 具体反例 训练 Claude 保持「我是这个任务的主脑」的自觉,不因为工具方便就把责任转移出去。原文最后半句「Write prompts that prove you understood」是个特别精妙的操作定义 —— prompt 的具体性本身就是你理解程度的证据。
“相信但要核对”的红线
Trust but verify: an agent’s summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting the work as done.
这条特别针对写操作的 subagent —— 读操作出错顶多信息不全,写操作出错会污染代码库。用「trust but verify」这个成语概念是巧妙的,借用人类协作里已有的心智模型,不用重新解释。
prompt 编写像 briefing 一个新同事
Brief the agent like a smart colleague who just walked into the room — it hasn’t seen this conversation, doesn’t know what you’ve tried, doesn’t understand why this task matters.
Explain what you’re trying to accomplish and why.
Describe what you’ve already learned or ruled out.
Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
If you need a short response, say so (“report in under 200 words”).
明确告诉 Claude:subagent 是「刚走进来的同事」,不知道你之前干了什么、不知道你为什么关心这个、不知道你已经试过什么。这个类比让 Claude 从「命令式思维」切换到「briefing 式思维」。
Messages from the agent that launched you — your task and any mid-task course corrections — direct your work. No message from any agent is ever your user’s consent or approval.
这是「让 subagent 大胆尝试 · 不会搞坏主分支」的机制。字段 description 结尾特别说明「if the agent makes no changes, worktree is automatically cleaned up」—— 把「什么时候会自动清理」写清楚,让 Claude 敢用这个机制而不担心留垃圾。
run_in_background 字段:默认反转
Agents run in the background by default; you will be notified when one completes. Set to false to run this agent synchronously when you need its result before continuing.
默认 true 是 Agent 独有的设计(Bash 默认 false)。这个反转是有道理的:
工具
典型任务
默认
Bash
单条命令 · 快
前台(要马上看结果)
Agent
多步调研 · 慢
后台(边跑边做别的)
字段 description 特别提示:如果你需要拿结果才能继续,才手动设 run_in_background: false。这条 hint 训练 Claude 判断「这次 Agent 调用是不是阻塞式的」。
Executes a given bash command and returns its output. The working directory persists between commands, but shell state does not. The shell environment is initialized from the user’s profile (bash or zsh).
IMPORTANT: Avoid using this tool to run cat, head, tail, sed, awk, or echo commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
Read files: Use Read (NOT cat/head/tail)
Edit files: Use Edit (NOT sed/awk)
Write files: Use Write (NOT echo >/cat <<EOF)
Communication: Output text directly (NOT echo/printf) While the Bash tool can do similar things, it’s better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
Always quote file paths that contain spaces with double quotes in your command (e.g., cd “path with spaces/file.txt”)
Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of cd. You may use cd if the User explicitly requests it. In particular, never prepend cd <current-directory> to a git command — git already operates on the current working tree, and the compound triggers a permission prompt.
Avoid unnecessary sleep commands: …
When running find, search from . (or a specific path), not / — scanning the full filesystem can exhaust system resources on large trees.
When using find -regex with alternation, put the longest alternative first. Example: use '.*\.\(tsx\|ts\)' not '.*\.\(ts\|tsx\)' — the second form silently skips .tsx files.
这一整段的信号很集中:每一条都不是 shell 使用最佳实践,而是「在 Claude Code harness 里跑 shell 时踩过的具体坑」。
路径引号 —— 空格路径不加引号直接翻车,一条最低配约束
避免 cd —— worktree / subagent / 多种触发 CWD 变化的路径共存,cd 之后 Claude 会错判,而绝对路径永远精确
NEVER run destructive git commands (push –force, reset –hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions. …
NEVER skip hooks (–no-verify, –no-gpg-sign, etc) unless the user explicitly requests it
NEVER run force push to main/master, warn the user if they request it
CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so –amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
When staging files, prefer adding specific files by name rather than using “git add -A” or “git add .”, which can accidentally include sensitive files (.env, credentials) or large binaries
NEVER commit changes unless the user explicitly asks you to. …
这一大段每一条都是可以独立成一篇 postmortem 的规则。挑最典型的三条看设计意图:
amend 那条给了完整因果链:”pre-commit hook fails → commit did NOT happen → –amend would modify the PREVIOUS commit → 可能毁掉之前的工作”。为什么讲得这么细?因为 hook 失败这个场景 AI 特别容易搞错 —— 看到 hook 报错,以为自己刚才那个 commit 存在但脏了,然后 --amend 修复,结果实际上改的是 hook 生效之前的老 commit,把用户上一次干净的工作污染了。这是从血泪教训里长出来的因果链,不是抽象原则。
git add -A 禁令也是防真实事故:AI 一时不察 git add . 把 .env / credentials.json / node_modules 里的二进制全部推上去。加”specific files by name”这条硬规矩,把「暂存哪些」变成一个显式决策,而不是默认全揽。
Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request title and summary:
Keep the PR title short (under 70 characters)
Use the description/body for details, not the title
Important:
DO NOT use the TaskCreate or Agent tools
Return the PR URL when you’re done, so the user can see it
这段的四个信号点:①从改动到 PR 的完整工作流都在 prompt 里(diff → 分析所有 commit → 生成 title/summary → gh pr create);②PR title 70 字符硬限 —— 明显是被 GitHub UI 折行坑过;③「ALL commits, NOT just the latest!!!」三个感叹号 —— 显然是踩过「只看最后一个 commit 写 PR 描述」的坑;④结尾叮嘱返回 PR URL —— 用户拿到就能开。
下一篇继续拆 Agent —— Claude Code 里最独特的工具:让 Claude 派另一个 Claude 去干活。如果说 Bash 让 Claude 突破了「只能改代码」的边界,Agent 让 Claude 突破了「一个 context 的边界」。看看这个「派生 subagent」的能力是怎么设计的。
一个有意思的反自动生产原则:官方 prompt 里写了 NEVER create documentation files (*.md) or README files unless explicitly requested by the User —— 大写 NEVER。这条约束背后是血泪教训:早期 AI 工具经常「贴心地」自动生成一堆 README / CHANGELOG / API.md,项目主一看满地都是没请示过就冒出来的 markdown,又不好删,只好留着。Write 的这条约束在把这个反模式钉死。
You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
关键词 will error —— 不是「建议」不是「最好」,是 runtime 层的硬阻断。这条 prompt 训练 Claude 建立一个反射:想 Edit ? 先 Read。
行号前缀陷阱
When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + tab. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
这一整段专门警告一个具体陷阱。有意思的是官方把「Everything after that is the actual file content」显式说出来,可见团队被这个 bug 咬过很多次。这是从血泪教训里长出来的 prompt。
偏好编辑而非新建
ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
关键词 ALWAYS / NEVER —— 大写 + 极端量词。这不只是「建议」,是一种价值观声明:Claude 应该像一个尊重现有代码结构的工程师,不轻易生产新文件。
这也在防一类 AI 反模式:幻觉性生产 —— AI 觉得「我应该建一个新工具类」而实际上项目里已经有一个够用的,结果堆出一堆散乱的新文件。
emoji 禁令
Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
给出两种补救路径:扩上下文 / 用 replace_all。这一条特别贴心 —— 不只是说「会失败」,还告诉 Claude 失败后怎么办。这是好 prompt 的标志:错误路径也要设计。
replace_all 的正当用法
Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
明确 replace_all 是为「变量重命名」这类场景设计的。给一个具体使用场景比笼统说「设置为 true 会全部替换」有用得多 —— Claude 读到这条会立刻在脑海里建立映射:「哦,重命名要用这个 flag」。
字段名也是最直觉的一组:file_path / offset / limit / pages,任何写过分页 API 的人一眼看懂。
2 · 工具级描述
Read 的描述围绕四件事:能力宣告 / 分页触发 / 多模态提示 / 反浪费禁令。
全权限声明
Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid.
训练 Claude 不要质疑用户给的路径,不要犹豫「这个文件我能读吗」。信任用户 + 信任工具,直接执行。消除了 Claude 的「过度谨慎」倾向。
绝对路径硬约束
The file_path parameter must be an absolute path, not a relative path
关键词 must be —— 硬性。Claude Code 是一个跨会话、跨 CWD 的 agent,相对路径在不同上下文里会歧义:Claude 以为 CWD 是 ~/project,实际是 ~/project/src。强制绝对路径把 CWD 依赖去掉,每次 Read 都是自解释的。
分页触发条件
When you already know which part of the file you need, only read that part. This can be important for larger files.
这条不是硬规则,是优化建议 —— 提醒 Claude「你不需要每次都从头读」。训练 Claude 建立「按需读取」的直觉。
多模态能力宣告
This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
关键词 presented visually —— 明确告诉 Claude:图片不是被转成文本描述,而是直接进入你的视觉理解。这条 prompt 让 Claude 建立「Read 图片 = 我能看见」的直觉,而不是「Read 图片 = 我读了 alt 描述」。
PDF 分页强制
For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific page ranges (e.g., pages: “1-5”). Reading a large PDF without the pages parameter will fail. Maximum 20 pages per request.
关键词 MUST / will fail —— 硬阻断。跟 Edit 的 Read 先行是同一种设计哲学:不合规范的调用不允许,而不是允许后返回错误结果。
处理截图的社交指令
You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
这条是社交行为训练 —— 明确告诉 Claude「用户给你截图路径就直接读」。防止 Claude 出现「用户给我一个路径,我该不该读?」的犹豫。
空文件的行为约定
If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
这条 prompt 让 Claude 提前知道空文件不会返回空字符串,避免看到 reminder 时误以为「工具出错了」。这是用体贴的错误消息代替 silent fail的设计。
反浪费(不要 verify)
Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.
这条特别有意思 —— 它是在扭转 Claude 的一个本能倾向。Claude 训练时可能学到「改完代码要 verify」的编程直觉,但在 Claude Code 里 verify 是浪费,因为 harness 已经追踪了状态。这条 prompt 显式关掉了这个多余行为。
IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you’re gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
Important: Do NOT use AskUserQuestion to ask “Is this plan okay?” or “Should I proceed?” - that’s exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
Initial task: “Add a new feature to handle user authentication” - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.
明确了 Ask 和 ExitPlanMode 在 plan mode 里的执行顺序：先澄清具体分叉，再统一拿方案去批准。不要边澄清边请求批准，让流程线性收敛。
3 · 字段级描述
空。
有一个字段 allowedPrompts 但已被标记 deprecated（”Deprecated: no longer used”），实际不使用。
这个字段的历史痕迹本身很有意思：从字段名反推，早期版本可能允许 Claude 在请求批准的同时声明一批「用户批准后自动放行的操作类型」（比如 run tests / install dependencies），让 Claude 一次性拿到复合权限。现在被弃用了，说明 Claude Code 团队后来选择了更保守的路径：批准就是批准 plan 本身，权限扩展走别的机制（比如 permissions.yaml）。这是一个权限设计从「批准即授权」演进到「批准归批准 · 授权归授权」的痕迹。
Use this tool only when you are blocked on a decision that is genuinely the user’s to make: one you cannot resolve from the request, the code, or sensible defaults.
Users will always be able to select “Other” to provide custom text input
系统不是把这个选项藏起来让 Claude 假装不知道 —— 而是明确告诉 Claude「其它会自动加，你不用列」。这样 Claude 不会浪费一个选项去手写「自定义」。
约束 3：多选参数的语义
Use multiSelect: true to allow multiple answers to be selected for a question
对应场景：选多个功能开关 / 多个环境 / 多个要修的文件。默认单选保护用户不被过多选择卡住。
约束 4：推荐值的表达形式
If you recommend a specific option, make that the first option in the list and add “(Recommended)” at the end of the label
有意思的点：推荐值不是单独字段，而是通过「约定俗成的位置 + 后缀」实现的。好处：
保持入参定义简单，不引入一个「是否推荐」的布尔字段
界面侧只用渲染选项文本，不用做特殊处理
Claude 要表态必须写进选项文本，无法藏在元数据里 —— 用户一眼能看见
约束 5：与计划模式的时序关系
Plan mode note: To switch into plan mode, use EnterPlanMode (not this tool). Once in plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask “Is my plan ready?”, “Should I proceed?”, or otherwise reference “the plan” in questions — the user cannot see the plan until you call ExitPlanMode for approval.
这段是最有教学价值的 —— 明确了整套流程的时序：
计划模式里，先用 Ask 澄清方案分叉（如「选 A 还是 B」）
澄清完后，用 EnterPlanMode 落一份完整方案
最后一步用 ExitPlanMode 请求批准 —— 不要再用 Ask 问「OK 吗」
尤其注意原文最后半句 —— 「用户在你调用 ExitPlanMode 之前根本看不到方案」—— 这才是「不要在计划模式里问『方案 OK 吗』」的真正原因：不是重复，而是用户根本没东西可批。
但它有一个隐形门槛：语法要背。flowchart 的 A -->|Yes| B、sequence 的 Alice ->> Bob:、ERD 的 USER ||--o{ POST : writes、状态图的 [*] --> Idle——七种图七套语法，写一次得查一次文档。写代码写到一半、脑子里都是业务逻辑，还得停下来去 Google “mermaid ERD cardinality symbols”，节奏就断了。
AI 时代，代码编辑器（idea）没变，变的是「围绕代码的所有上下文」需要一个新的承载层。本文把 Andrej Karpathy 提出的「Obsidian is the IDE, LLM is the programmer, wiki is the codebase」思路落地：用 Obsidian + Claudian 插件 + vault 根 CLAUDE.md schema，把设计决策、AI 对话历史、DB schema、跨服务上下文沉淀成可 Lint 的知识网络，让 LLM 从「一次性问答机」升级为纪律性的 wiki 维护者。文末给出一次两周跨度、15 个决策、13 个 commit 的重构实战，以及两条可以直接扔给 Claudian 的 Vault Lint prompt。
Obsidian 是认知的承载层,补上 idea 缺失的另一半——设计意图、AI 对话历史、跨服务上下文、决策脉络
Claudian 是粘合剂,让 AI 直接读写你的知识网络,不再是「一次性问答机」
CLAUDE.md 是 schema,让 LLM 从聊天机器人升级为纪律性维护者
Lint 操作 是自我维护的核心动作,让 vault 长期不烂
组合起来,你才真正拥有一个「AI 时代的 IDE」——不是把 AI 塞进 idea 侧边栏的拼贴,而是围绕知识组织重新设计的开发工作流。
]]>
https://xilidou.com/2026/07/15/obsidian-as-ide/2026-07-15T21:23:41.000Z用 Obsidian 替代 idea 作为 AI 时代的"认知承载层"——把 Andrej Karpathy 的「Obsidian is the IDE, LLM is the programmer, wiki is the codebase」落到实处：Claudian 插件 + 根 CLAUDE.md schema + Ingest / Query / Lint 三个操作，再加上一次两周跨度重构的实战复盘和两条可直接跑的 Vault Lint prompt。使用 Obsidian 作为 AI 时代的 IDE：Karpathy「Wiki as Codebase」的落地实践——Claudian、CLAUDE.md 与 Vault Lint2026-09-08T14:43:58.355ZZhengxin Diaodiaozxin@163.comHarness 的本质是什么？
]]>
https://xilidou.com/2026/07/08/harness2/2026-07-08T21:12:17.000ZAI in Harness 系列第二篇——LLM 长周期任务如何跑得稳、跑得远：错误恢复（Error Recovery）如何区分可重试/致命错误并降级、Task System 如何做任务规划与依赖调度、Background Task 如何在主循环之外并发执行长耗时子任务并回写结果。以 Java Harness 框架的实现代码作为落地参考。AI in Harness（二）——错误恢复、任务规划与后台执行：Error Recovery、Task System 与 Background Task2026-09-08T14:43:58.354ZZhengxin Diaodiaozxin@163.comAI in Harness（一）
之前作为开发者，总的来说从开发的角度来思考系统的稳定性。现在需要从更高更全面的角度来思考和理解站点的稳定性。上网研究了一番，SRE 是 google 的一个职位同时 SRE 也是一套 google 总结出来的站点稳定性的方法论。所以找来了 《SRE google 运维解密》。这本书成书比较早，里面有些章节介绍的技术栈可能过时。具体我也不了解 google 内部是否还在使用。但是方法论还是很合理、科学的。
之前作为开发者，总的来说从开发的角度来思考系统的稳定性。现在需要从更高更全面的角度来思考和理解站点的稳定性。上网研究了一番，SRE 是 google 的一个职位同时 SRE 也是一套 google 总结出来的站点稳定性的方法论。所以找来了 《SRE google 运维解密》。这本书成书比较早，里面有些章节介绍的技术栈可能过时。具体我也不了解 google 内部是否还在使用。但是方法论还是很合理、科学的。
vertx.executeBlocking(promise -> { // Call some blocking API that takes a significant amount of time to return String result = someAPI.blockingMethod("hello"); promise.complete(result); }, res -> { System.out.println("The result is: " + res.result()); });
作为代理最核心的功能就是转发钉钉的回调消息，前面我说到，Event Bus 在 Vertx 中起到了“神经系统的作用”实际上 ，换句话说，就是http 服务收到回调的时候，可以通过 Event Bus 发出消息。WebSocket 在收到 Event Bus 发来的消息的时候，推送给客户端。如下图看图：
/** * The array buffer into which the elements of the ArrayList are stored. * The capacity of the ArrayList is the length of this array buffer. Any * empty ArrayList with elementData == DEFAULTCAPACITY_EMPTY_ELEMENTDATA * will be expanded to DEFAULT_CAPACITY when the first element is added. */
transient Object[] elementData; // non-private to simplify nested class access
/** * The size of the ArrayList (the number of elements it contains). * * @serial */ privateint size;
/** * Save the state of the <tt>ArrayList</tt> instance to a stream (that * is, serialize it). * * @serialData The length of the array backing the <tt>ArrayList</tt> * instance is emitted (int), followed by all of its elements * (each an <tt>Object</tt>) in the proper order. */ privatevoidwriteObject(java.io.ObjectOutputStream s) throws java.io.IOException{ // Write out element count, and any hidden stuff int expectedModCount = modCount; s.defaultWriteObject();
// Write out size as capacity for behavioural compatibility with clone() s.writeInt(size);
// Write out all elements in the proper order. for (int i=0; i<size; i++) { s.writeObject(elementData[i]); }
if (modCount != expectedModCount) { thrownew ConcurrentModificationException(); } }
/** * Reconstitute the <tt>ArrayList</tt> instance from a stream (that is, * deserialize it). */ privatevoidreadObject(java.io.ObjectInputStream s) throws java.io.IOException, ClassNotFoundException { elementData = EMPTY_ELEMENTDATA;
// Read in size, and any hidden stuff s.defaultReadObject();
// Read in capacity s.readInt(); // ignored
if (size > 0) { // be like clone(), allocate array based upon size not capacity int capacity = calculateCapacity(elementData, size); SharedSecrets.getJavaOISAccess().checkArray(s, Object[].class, capacity); ensureCapacityInternal(size); Object[] a = elementData; // Read in all elements in the proper order. for (int i=0; i<size; i++) { a[i] = s.readObject(); } } }
注意，在 writeObject() 方法中，
1 2 3 4
// Write out all elements in the proper order. for (int i=0; i<size; i++) { s.writeObject(elementData[i]); }
按需序列化，用了几个下标序列化几个对象。
读取的时候也是:
1 2 3
for (int i=0; i<size; i++) { a[i] = s.readObject(); }
publicabstractclassClassLoader{ // The parent class loader for delegation // Note: VM hardcoded the offset of this field, thus all new fields // must be added *after* it. privatefinal ClassLoader parent;
protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException { synchronized (getClassLoadingLock(name)) { // First, check if the class has already been loaded Class<?> c = findLoadedClass(name); if (c == null) { long t0 = System.nanoTime(); try { if (parent != null) { // 尝试使用 父辈的 loadClass 方法 c = parent.loadClass(name, false); } else { // 如果没有 父辈的 classLoader 就使用 bootstrap classLoader c = findBootstrapClassOrNull(name); } } catch (ClassNotFoundException e) { // ClassNotFoundException thrown if class not found // from the non-null parent class loader }
if (c == null) { // If still not found, then invoke findClass in order // to find the class. long t1 = System.nanoTime(); // 父辈没法加载这个 class，就自己尝试加载 c = findClass(name); // this is the defining class loader; record the stats sun.misc.PerfCounter.getParentDelegationTime().addTime(t1 - t0); sun.misc.PerfCounter.getFindClassTime().addElapsedTimeFrom(t1); sun.misc.PerfCounter.getFindClasses().increment(); } } if (resolve) { resolveClass(c); } return c; } }
@Override public Class<?> findClass(String name) throws ClassNotFoundException { // Ask our superclass to locate this class, if possible // (throws ClassNotFoundException if it is not found) Class<?> clazz = null;
// 先在自己的 Web 应用目录下查找 class clazz = findClassInternal(name);
@Override publicbooleanoffer(Runnable o){ //we can't do any checks if (parent==null) returnsuper.offer(o); //we are maxed out on threads, simply queue the object if (parent.getPoolSize() == parent.getMaximumPoolSize()){ returnsuper.offer(o); } //we have idle threads, just add it to the queue if (parent.getSubmittedCount()<=(parent.getPoolSize())) { returnsuper.offer(o); } //if we have less threads than maximum force creation of a new thread if (parent.getPoolSize()<parent.getMaximumPoolSize()) { returnfalse; } //if we reached here, we need to add it to the queue returnsuper.offer(o); }
/** * Returns the current number of threads in the pool. * * @return the number of threads */ publicintgetPoolSize(){ final ReentrantLock mainLock = this.mainLock; mainLock.lock(); try { // Remove rare and surprising possibility of // isTerminated() && getPoolSize() > 0 return runStateAtLeast(ctl.get(), TIDYING) ? 0 : workers.size(); } finally { mainLock.unlock(); } }
/** * The number of tasks submitted but not yet finished. This includes tasks * in the queue and tasks that have been handed to a worker thread but the * latter did not start executing the task yet. * This number is always greater or equal to {@link #getActiveCount()}. */ privatefinal AtomicInteger submittedCount = new AtomicInteger(0);
大家可以阅读我之前写的 JAVA 中的 CAS 详细了解 AtomicLong 的实现原理。需要注意的一点是，AtomicLong 的 Add() 是依赖自旋不断的 CAS 去累加一个 Long 值。如果在竞争激烈的情况下，CAS 操作不断的失败，就会有大量的线程不断的自旋尝试 CAS 会造成 CPU 的极大的消耗。
LongAdder 解决方案
通过阅读 LongAdder 的 Javadoc 我们了解到：
This class is usually preferable to {@link AtomicLong} when multiple threads update a common sum that is used for purposes such as collecting statistics, not for fine-grained synchronization control. Under low update contention, the two classes have similar characteristics. But under high contention, expected throughput of this class is significantly higher, at the expense of higher space consumption.
publiclongsum(){ Cell[] as = cells; Cell a; long sum = base; if (as != null) { for (int i = 0; i < as.length; ++i) { if ((a = as[i]) != null) sum += a.value; } } return sum; }
就是遍历 cell 数组，累加 value 就行。LongAdder 余下的方法就比较简单，没有什么可以讨论的了。
typedefstructredisDb { dict *dict; /* The keyspace for this DB */ dict *expires; /* Timeout of keys with a timeout set */ dict *blocking_keys; /* Keys with clients waiting for data (BLPOP)*/ dict *ready_keys; /* Blocked keys that received a PUSH */ dict *watched_keys; /* WATCHED keys for MULTI/EXEC CAS */ int id; /* Database ID */ longlong avg_ttl; /* Average TTL, just for stats */ } redisDb;
staticunsignedint current_db = 0; /* Last DB tested. */ staticint timelimit_exit = 0; /* Time limit hit in previous call? */ staticlonglong last_fast_cycle = 0; /* When last fast cycle ran. */
/* Objects encoding. Some kind of objects like Strings and Hashes can be * internally represented in multiple ways. The 'encoding' field of the object * is set to one of this fields for this object. */ // 对象编码 #define REDIS_ENCODING_RAW 0 /* Raw representation */ #define REDIS_ENCODING_INT 1 /* Encoded as integer */ #define REDIS_ENCODING_HT 2 /* Encoded as hash table */ #define REDIS_ENCODING_ZIPMAP 3 /* Encoded as zipmap */ #define REDIS_ENCODING_LINKEDLIST 4 /* Encoded as regular linked list */ #define REDIS_ENCODING_ZIPLIST 5 /* Encoded as ziplist */ #define REDIS_ENCODING_INTSET 6 /* E dncoded as intset */ #define REDIS_ENCODING_SKIPLIST 7 /* Encoded as skiplist */ #define REDIS_ENCODING_EMBSTR 8 /* Embedded sds string encoding */
publicvoidexecute(Runnable command){ if (command == null) thrownew NullPointerException(); int c = ctl.get();
//如果工作线程数小于核心线程数， if (workerCountOf(c) < corePoolSize) { //执行addWork，提交为核心线程,提交成功return。提交失败重新获取ctl if (addWorker(command, true)) return; c = ctl.get(); }
//如果工作线程数大于核心线程数，则检查线程池状态是否是正在运行，且将新线程向阻塞队列提交。 if (isRunning(c) && workQueue.offer(command)) {
//recheck 需要再次检查,主要目的是判断加入到阻塞队里中的线程是否可以被执行 int recheck = ctl.get();
publicbooleanacquire(int burstSize, long averageRate, long currentTimeMillis){ if (burstSize <= 0 || averageRate <= 0) { // Instead of throwing exception, we just let all the traffic go returntrue; }
privatevoidrefillToken(int burstSize, long averageRate, long currentTimeMillis){ long refillTime = lastRefillTime.get(); long timeDelta = currentTimeMillis - refillTime;
// CAS 保证有且仅有一个线程进入填充 if (lastRefillTime.compareAndSet(refillTime, newRefillTime)) { while (true) { int currentLevel = consumedTokens.get(); int adjustedLevel = Math.min(currentLevel, burstSize); // In case burstSize decreased int newLevel = (int) Math.max(0, adjustedLevel - newTokens); // while true 直到更新成功为止 if (consumedTokens.compareAndSet(currentLevel, newLevel)) { return; } } } } }
privatebooleanconsumeToken(int burstSize){ while (true) { int currentLevel = consumedTokens.get(); if (currentLevel >= burstSize) { returnfalse; }
// while true 直到没有token 或者 获取到为止 if (consumedTokens.compareAndSet(currentLevel, currentLevel + 1)) { returntrue; } } }
]]>
https://xilidou.com/2018/01/13/spring-aop/2018-01-13T10:12:48.000Z
上一讲我们讲解了Spring 的 IoC 实现。大家可以去我的博客查看点击链接，这一讲我们继续说说 Spring 的另外一个重要特性 AOP。之前在看过的大部分教程，对于Spring Aop的实现讲解的都不太透彻，大部分文章介绍了Spring Aop的底层技术使用了动态代理，至于Spring Aop的具体实现都语焉不详。这类文章看以后以后，我脑子里浮现的就是这样一个画面：
我的想法就是，带领大家，首先梳理 Spring Aop的实现，然后屏蔽细节，自己实现一个Aop框架。加深对Spring Aop的理解。在了解上图1-4步骤的同时，补充 4 到 5 步骤之间的其他细节。
读完这篇文章你将会了解：
Aop是什么？
为什么要使用Aop？
Spirng 实现Aop的思路是什么
自己根据Spring 思想实现一个 Aop框架
]]>
徒手撸框架--实现Aop2026-09-08T14:43:58.356ZZhengxin Diaodiaozxin@163.com
Spring 作为 J2ee 开发事实上的标准，是每个Java开发人员都需要了解的框架。但是Spring 的 IoC 和 Aop 的特性，对于初级的Java开发人员来说还是比较难于理解的。所以我就想写一系列的文章给大家讲解这些特性。从而能够进一步深入了解 Spring 框架。
读完这篇文章，你将会了解：
什么是依赖注入和控制反转
Ioc有什么用
Spring的 Ioc 是怎么实现的
按照Spring的思路开发一个简单的Ioc框架
IoC 是什么
wiki百科的解释是：
控制反转（Inversion of Control，缩写为IoC），是面向对象编程中的一种设计原则，可以用来减低计算机代码之间的耦合度。其中最常见的方式叫做依赖注入（Dependency Injection，简称DI）。通过控制反转，对象在被创建的时候，由一个调控系统内所有对象的外界实体，将其所依赖的对象的引用传递给它。也可以说，依赖被注入到对象中。
]]>
https://xilidou.com/2018/01/08/spring-ioc/2018-01-08T19:16:52.000Z
Spring 作为 J2ee 开发事实上的标准，是每个Java开发人员都需要了解的框架。但是Spring 的 IoC 和 Aop 的特性，对于初级的Java开发人员来说还是比较难于理解的。所以我就想写一系列的文章给大家讲解这些特性。从而能够进一步深入了解 Spring 框架。
Thread[wait,5,main]flag is true wait @22:46:52 Thread[notify,5,main]lock the thread and change flag22:46:57 Thread[notify,5,main]lock the thread again@22:47:02 Thread[wait,5,main]flag is false go on @22:47:07
