LLM on 鬼哥的空间

Skill 越多，Agent 为什么越容易犯选择困难？

Wed, 19 Aug 2026 00:00:00 +0000

不知道大家Vibe Coding时间久了以后会不会碰到这样的问题: 学习和使用了不少有用的skill, 自己的skill库越来越丰富, 但 Skill 库越攒越多，Agent 反而偶尔开始犯一种很熟悉的病：选择困难症。 有些问题, 这个skill能处理, 那个也能搞定, 但又都不是完美匹配当前场景的. 导致同一个问题, 多次解决路径居然不一致, 带来的结果和周边影响也不一样.

AI跟人一样, 对一些问题有多条解决路径选择时。就跟鬼哥看到“干炒牛河、辣椒炒肉、小炒黄牛肉、湖南米粉”同时出现在菜单上，脑子就直接进入一个 Infinity Loop 循环, 这顿饭都没力气吃下去了。Agent 面前如果同时摆着几十份名字相近、边界暧昧的 Skill，情况大致相同，只是它不会叹气，而是更认真地读错几份文件。

鬼哥昨天读到一篇新论文 Demystifying Agent Skills: Why They Work—Until They Don’t 恰好把这个问题拆开了。它问的不是“Skill 有没有用”，而是更麻烦也更有价值的问题：它什么时候帮忙、为什么帮忙、又从哪里开始添乱？

论文的答案很克制：Skill 确实有效，但它最主要的作用不是给 Agent 多塞一点知识，而是把过去混乱的经验压缩成一根可执行的“程序锚点”。问题也在这里：锚点一旦抛错地方，船就会稳稳地停在错误的位置。

Skill 不是“经验文档”，而是经验的蒸馏

论文把同一批历史执行轨迹做成了三种版本：

给 Agent 的东西	它保留了什么	它容易带来的问题
Raw	什么都不注入，让 Agent 从头做	每次都要重新发现环境、命令和检查步骤
Workflow Memory	清洗过的历史流程	仍夹带失败分支、偶然细节和冗长探索
Skill	从同一批流程蒸馏出的 `SKILL.md`	需要判断是否适用、如何适配

这个对照很关键。Skill 和 Workflow Memory 来自同一批成功与失败轨迹，所以它们的差异不能简单归因于“前者知道得更多”。

在匹配比较里，Skill 的成功率为 61.9%，Raw 为 59.1%，Workflow Memory 为 55.9%；Skill 相比 Workflow Memory 的增益为 6.06 个百分点，95% bootstrap 置信区间为 +0.76 到 +11.36。

更有意思的是，研究者逐条分析 Agent 轨迹后发现：Skill 有效的案例里，65.7% 是因为它提供了程序锚点——步骤顺序、工具调用、检查点、验证方案、常见坑；只有 4.5% 是因为它补充了 Agent 原本不知道的事实。

这和很多人的直觉相反。我们写 Skill 时常想“把知识写全一点”，但真正有价值的，往往是让 Agent 在关键时刻不忘记：先启动什么、再检查什么、哪种输出不算完成、踩坑后怎样退回来。

Skill 最大的作用，不是替 Agent 多记一条知识，而是在关键步骤上少忘一件事。

它最擅长修的，是“会做但总忘”的问题

论文里的细分结果很像所有做过 Agent 工程的人见过的事故单：

环境或基础设施失败：从 Raw 的 5.3% 降到 Skill 的 0.2%；
输出格式或 schema 不匹配：从 7.4% 降到 3.2%；
后台服务生命周期失败：从 2.7% 降到 0.8%。

这些不是深奥推理题。它们更多是执行纪律问题：路径没记住、服务没确认、schema 没校验、命令没按正确顺序跑。

所以一个好的 Skill，应该像一位靠谱但不啰嗦的值班同事：它不替你决定产品要不要做，却会在你准备发布前提醒“配置读了吗？”“服务起来了吗？”“返回值真符合接口吗？”

但别因此高估它。算法逻辑错误在 Skill 条件下仍有 7.4%，只做静态检查、没有真正运行验证的失败仍有 11.7%。Skill 能稳住执行，不能替人重新定义一个理解错了的问题。

Skill 的反噬：它会让错误的假设更有执行力

Skill 不是自动执行的。Agent 必须先判断它是否相关，再决定跟到什么程度，还得在当前环境里修改它。

这一步一旦偷懒，Skill 就从经验变成了惯性。论文中，skill_guidance_misapplied_or_ignored 在 Skill 组里占 10.0%，而 Raw 是 0.8%、Workflow Memory 是 0.4%。

这不是说 Skill 内容一定不好。更常见的情况是：旧任务和新任务看起来像，但一个前提已经变了；Agent 拿着一份“通常正确”的流程，顺手把它套到“不再通常”的场景上。

一个没有退出条件的 Skill，是把经验固化成偏见的最快方式。

这也是为什么我现在更在意 Skill 里有没有下面四块，而不是它写了多少页：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


## 适用前提
- 什么输入、环境和权限下使用？

## 执行路径
- 关键步骤的顺序是什么？

## 验证标准
- 跑什么检查？什么结果才算完成？

## 退出与升级
- 哪些信号说明不适用？何时停止并转人工/换方案？

前面三项让它可执行，最后一项让它不会过度自信。

Skill 库越大，难的不是保存，而是选择和适配

论文专门测了这个问题。候选 Skill 池从 5 个增加到 100 个时，Agent 在真实执行里实际使用 ground-truth Skill 的精确率，平均从 29.6% 掉到 3.3%。

但下游任务成功率却没有同步崩掉，只从 36.4% 变到 39.3%。原因并不神秘：Agent 可能看了多份相近 Skill；其中某份并非标注的“唯一正确答案”，却依然给了有用的操作线索。反过来，即使它选中了 ground-truth Skill，也仍可能在执行、适配或验证环节失败。

论文由此给出一个很重要的结论：精确调用标注上的正确 Skill，既不是任务成功的充分条件，也不是必要条件。

这对个人开发者的含义是：别只用“检索命中了没有”衡量 Skill 库。更应该问：

这份 Skill 的触发条件是否能和相邻 Skill 区分开？
它能否解释自己为什么适用于当前任务？
它的关键步骤能否被当前环境的 verifier 验证？
当它与另一份 Skill 冲突时，Agent 知不知道该降级、组合还是停下来问？

Skill 库的瓶颈从来不是存储空间，而是选择和适配能力。菜单可以很长，但“都来一份”不是一个工程策略。

失败轨迹别急着扔，它们是 Skill 的边界说明书

研究者还做了一个很实用的消融：构建 Skill 时，保留或去掉历史轨迹的“成功/失败”标记。

只有成功轨迹时，是否保留标记影响不大；一旦混入失败轨迹，结果标签就开始发挥作用。以 Gemini 在 Terminal-Bench-2 的 3 成功 + 2 失败 轨迹组合为例：构建 Skill 时保留 outcome labels，成功率为 74.62%；拿掉标签后，只有 40.00%。

这说明失败轨迹并不是应当删掉的脏东西。它告诉我们：哪一步看似合理却不通、什么条件一变流程就失效、最终验证为什么没有通过。

当然，失败记录原封不动地塞回上下文也不行——Workflow Memory 的 timeout/budget exhaustion 达 10.6%，而 Skill 为 4.4%。正确做法不是保存更多过程，而是把失败蒸馏成可判断的边界：失败模式、触发条件、检查办法、替代路径。

给个人开发者的一条 Skill 维护规则

如果你正在维护自己的 Skill 库，我建议不要从“再写一份新的”开始，而是从每次真实任务结束后的四个问题开始：

这次 Agent 反复犯的，究竟是知识缺口，还是执行步骤遗漏？
哪一步可以写成稳定的前提、动作和 verifier？
哪个失败条件必须写进这份 Skill 的退出路径？
它和已有 Skill 的边界是否足够清楚，还是只是在菜单上多加了一道相似的菜？

若答案只是“我觉得这条 Prompt 很有用”，先别急着建库。让它在几个真实任务里活下来，再把它写成 Skill。

这篇论文仍是一篇预印本，实验主要集中在终端与工具调用任务，覆盖的 Agent 框架和模型数量也有限；它不等于已经证明了所有网页 Agent 或开放式协作场景的规律。但它至少把一个常被忽略的问题说清了：Skill 的效果不是一次注入，而是一条生命周期——蒸馏、检索、调用、适配、验证。

回到开头那张菜单。鬼哥并不需要把所有菜从菜单上划掉；我需要的是知道今天为什么点这道、吃到一半发现不对时能不能换，以及不要把“菜单很丰富”误当成“晚饭已经解决”。

对 Agent 也是一样。

参考资料

Zhiyuan Jiang et al., Demystifying Agent Skills: Why They Work—Until They Don’t, arXiv:2608.14036, 2026.

Claude-Cookbooks 全景导航：被 README 藏起来的另一半

Sat, 18 Apr 2026 00:00:00 +0000

最近 AI 的发展真的是日行千里。

每天打开手机开源社区、翻公众号、过一遍 GitHub Trending——新模型、新工具、新系统、新应用，再加上无数业内高人分享的实践经验，内容浩如烟海，百家争鸣，百家齐放。

说实话，我自己看着都眼花缭乱。有时候晚上躺下想到"今天又没来得及看那几篇论文、那几个新项目"，连睡觉都觉得是在浪费学习时间。

这种状态持续久了，人是会焦虑的。鬼哥每天拼命学习, 拼命实践, 都快忘了自己还是个吉他手, 也得花时间练琴了.

但前阵子我沉下心来，花了一段时间认真翻了一遍 Anthropic 官方的这份 claude-cookbooks——翻完之后我反倒松了一口气。

这份仓库里的内容，积累了 Anthropic 工程师过去三年对 AI 工程化的思考。覆盖面非常全：从 API 最基础的用法，到 Prompt Caching 的成本优化，到 Tool Use 的各种进阶模式，再到 Agent SDK、Managed Agents、Skills 这些最近才成型的产品形态——几乎把"怎么用好 Claude 做一个能上生产的 AI 应用"这件事，从头到尾挨个讲了一遍。

宝藏是真的多，内容也真的多。想用一两篇文章讲清楚根本不现实。

所以我决定先写这一篇——给这份指南做一个大致的梳理，整理出一份索引地图。 后面每个具体话题，再单独开长文展开。

也建议你把这份 cookbook 当作一份可以反复查、反复学的学习地图：不需要一次读完，但值得在接下来几个月里反复回来翻。

你打开 anthropics/claude-cookbooks 的 README，看到的大概是十几条链接——分类、RAG、摘要、几个 tool use 示例、一篇 prompt caching。

如果你只看 README，会以为这就是一份写了两年没人管的老项目。

但你往目录里翻一下就会发现——这份仓库里塞着接近一百篇 notebook，README 里能看到的，大概只占三分之一。

被 README 藏起来的另一半，恰恰是这两年 Anthropic 官方重点推进的东西：Claude Agent SDK 教程、Managed Agents 的 CMA 系列、Skills 技能包、Tool Use 的进阶玩法、Extended Thinking 和 Tool Search 的新模式……这些内容散落在 claude_agent_sdk/、managed_agents/、skills/、patterns/agents/ 这些 README 完全没提的目录下。

这篇文章做的事很简单：把这份 repo 按主题重新整理成一张可以反复查的索引地图。 每个模块一句话定位、列出具体 notebook 文件名、说清楚什么时候该看它——后面想逐篇深入的时候，翻这一页就知道从哪下手。

不做深度拆解，只做导航。真正的"为什么要这么设计"那种长文，留给后面每个主题单开一篇来写。

一、先把这份 repo 的定位搞清楚

在往下看之前，先明确一件事：claude-cookbooks 不是文档的补充，而是可跑的工程示例库。

Anthropic 官方的内容资源现在大致分成三层：

资源	角色	面向
docs.claude.com	权威文档	查 API 参数、模型特性
anthropics/courses	入门课程	第一次接触 API 的开发者
anthropics/claude-cookbooks	工程菜谱	已经会调 API、想把某个具体场景做好的人

Cookbook 是"可执行的最佳实践"：每个 notebook 就是一个最小可跑的场景，装完依赖、填上 API key 就能复现。它的价值不在于"教你 Claude 是什么"，而在于"别人做过这件事，代码给你抄走"。

换句话说，文档告诉你某个 API 参数是什么意思，cookbook 告诉你在真实场景里这个参数应该怎么配、还要和哪几件事配合用。这两者是互补的——文档适合查细节，cookbook 适合找套路。

这也解释了为什么它的更新节奏跟着 Anthropic 的产品线走——每出一个新产品或新能力，这里就会多一个目录。Claude Agent SDK 发布之后有了 claude_agent_sdk/，Managed Agents 发布之后有了 managed_agents/，Skills 功能上线之后有了 skills/。所以它也是观察 Anthropic 官方工程重点转向的一个风向标。

一个小提醒：README 里的链接还是旧的 anthropic-cookbook 仓库路径（目录名对，仓库名已改成 claude-cookbooks）。clone 的时候用新名字，跟着链接点进去会被 GitHub 自动重定向，不影响看内容，但会让你怀疑自己是不是 clone 错了库。

二、一张总览图：20 多个目录怎么归类

仓库里大大小小二十多个目录，我按"使用场景"把它们重新归了一下组：

大类	涉及目录	解决的问题
基础能力	`capabilities/` `multimodal/` `extended_thinking/`	Claude API 开箱即用能做的事
Tool Use	`tool_use/`	让模型调用外部工具
性能与成本	`misc/`（caching/batch 部分） `observability/`	Prompt caching、批处理、用量监控
Agent 三条路径	`patterns/agents/` `claude_agent_sdk/` `managed_agents/`	从模式→SDK→托管运行时的递进
Skills 技能包	`skills/`	打包专业能力给 Claude 调用
第三方集成	`third_party/`	Pinecone / Voyage / Mongo / Wolfram 等八家
评估与微调	`tool_evaluation/` `finetuning/` `misc/building_evals.ipynb`	Prompt eval、工具 eval、Bedrock 微调
工程实践（meta）	整个仓库的组织方式	uv / ruff / registry / slash commands

接下来按这个骨架一层层往里翻。

三、基础能力层：Claude API 开箱即用能做什么

3.1 `capabilities/` — 经典的 NLP 任务

这是整个 cookbook 里最"传统"的一块，也是大部分教程会从这里开始的原因——这些任务不依赖任何高级特性，一个 API key 就能跑：

classification/ — 文本分类。几个 prompt 模式对比，从 zero-shot 到 few-shot 到带 chain-of-thought 的长 prompt。
summarization/ — 摘要。包括长文分块摘要、多文档合并摘要、以及"按角色视角写摘要"这种进阶玩法。
retrieval_augmented_generation/ — RAG。从最基础的"向量检索 + 拼 prompt"到带 rerank、混合检索的几种设计。
contextual-embeddings/ — 这是比较新的一篇，讲 Anthropic 自己提出的"给每个 chunk 加一段上下文描述再 embed"的做法，在某些场景上能显著提升召回。
text_to_sql/ — 自然语言转 SQL，包括 schema 注入、错误恢复、结果校验。
knowledge_graph/ — 用 Claude 从文本抽取三元组、构建图谱。

如果你是刚开始用 Claude API 做项目，这块是"背景知识"——不是每篇都要精读，但至少扫一遍标题，知道什么场景能在这里找到参考实现。

contextual-embeddings/ 这篇值得单独提一下。传统 RAG 的 embedding 过程是直接把 chunk 扔进 embedding 模型，但很多 chunk 脱离上下文后其实没法检索——比如一段"它在第三季度增长了 12%"，没有"哪家公司 / 哪个产品"的上下文，embedding 向量就很泛。Anthropic 的做法是先用 Claude 给每个 chunk 生成一段上下文描述（“这段来自 XXX 公司 2024 Q3 财报的营收章节”），再和原文拼在一起去 embed。实测在有些场景上能把召回率提升 35% 以上，代价是 embedding 阶段的 prompt caching 必须做好，不然成本会飙。

3.2 `multimodal/` — 视觉能力

Claude 的 vision 能力现在已经是基础配置，这个目录把"怎么用好它"讲了一圈：

getting_started_with_vision.ipynb — 入门。base64 编码、URL 传图、多图一起传的几种姿势。
best_practices_for_vision.ipynb — 最佳实践。图片放在 prompt 的哪个位置、多图之间怎么编号、什么时候该先 OCR 再喂文字。
reading_charts_graphs_powerpoints.ipynb — 图表解读。财报柱状图、流程图、PPT 截图的实战。
how_to_transcribe_text.ipynb — 表单/手写稿 OCR。
crop_tool.ipynb — 让 Claude 自己决定"先裁图再看细节"的分步处理。
using_sub_agents.ipynb — 用 Haiku 做前置视觉处理，Opus 做最终决策的 sub-agent 模式。

3.3 `extended_thinking/` — 让模型"想得更久"

Extended Thinking 是 Claude 4 系列引入的能力，让模型在给出答案前先做一段内部推理：

extended_thinking.ipynb — 基础用法。怎么打开、thinking budget 怎么设、拿到的 thinking block 长什么样。
extended_thinking_with_tool_use.ipynb — 和 tool use 结合。这个组合比较微妙——model 在 tool call 之间保留 thinking context 的方式跟普通对话不一样，这一篇讲清楚了边界。

四、Tool Use 专题：整个 cookbook 最密的一块

tool_use/ 目录是更新最频繁、内容也最厚的一块。里面的 notebook 粗粗可以分成"基础用法"和"进阶玩法"两层：

基础几篇，先过一遍：

calculator_tool.ipynb — 第一次接触 tool use 必看，一个最简单的计算器示例。
tool_choice.ipynb — auto / any / tool（强制某个具体工具）三种模式的区别。
parallel_tools.ipynb — 一次响应里并发调多个工具。
extracting_structured_json.ipynb — 用 tool use 强制返回结构化 JSON，比裸 prompt 稳定得多。
tool_use_with_pydantic.ipynb — 直接用 Pydantic 模型定义 tool schema。
customer_service_agent.ipynb — 经典的客服机器人综合示例。

进阶部分，每篇都是一个独立课题：

memory_cookbook.ipynb + memory_tool.py — Claude 的 memory tool，让模型能读写自己的记忆文件。
programmatic_tool_calling_ptc.ipynb — PTC（Programmatic Tool Calling）。让 Claude 生成一段小代码来决定怎么调用一组工具，而不是一个个手动编排。
automatic-context-compaction.ipynb — 自动上下文压缩。长对话里如何在触发上限前让模型自己"总结前面然后丢掉"。这一篇和我之前写过的 Session 管理文章其实是同一套思路的底层实现。
tool_search_with_embeddings.ipynb + tool_search_alternate_approaches.ipynb — 工具太多塞不进 prompt 的时候怎么办。用 embedding 召回最相关的工具再喂给模型。
vision_with_tools.ipynb — 把 vision 输入和 tool use 混在一起用的注意事项。
threat_intel_enrichment_agent.ipynb — 威胁情报富化 Agent，一个比较完整的垂直场景实战。
context_engineering/ 子目录 — 专门讲上下文工程的一组 notebook，是相对独立的小专题。

这个目录是我个人会反复回来查的。基本上做任何一个需要"让模型调用外部能力"的项目，都能在这里找到至少一个相近的参考实现。

特别想点名 PTC 和 Tool Search 这两篇。 PTC（Programmatic Tool Calling）解决的是"工具编排逻辑比工具本身还复杂"的场景——比如你有 10 个工具需要按特定顺序调用并做中间结果处理，与其让模型一轮一轮 tool call，不如让它一次性生成一段编排代码，由你在沙箱里执行。这种做法在复杂工作流里能把 round-trip 次数从十几轮压到两三轮，延迟和成本都是数量级的改善。

Tool Search 解决的是另一类问题：工具数量多到塞不进 prompt。一个大型 Agent 系统可能挂了几百个 MCP 工具，全部塞进去既超 token 又污染模型判断。用 embedding 预先对工具做语义索引，按用户 query 召回 top-K 工具再喂给模型，是目前比较成熟的解法。这一篇讲清楚了实现细节和几种 trade-off。

五、性能与成本优化

做 Demo 的时候钱和速度都不敏感，但一旦到线上，成本和延迟立刻就会成为第一优先级问题。 这块内容散落在几个目录里，我挑出来单独放一节：

misc/prompt_caching.ipynb — Prompt caching 的基础用法。配合我之前那篇 Prompt Caching 深度拆解一起看效果最好：那篇讲"为什么要这么做"和底层 KV cache 原理，这篇告诉你"具体几行代码怎么写"。
misc/speculative_prompt_caching.ipynb — 推测式缓存。不等用户发消息，提前把可能的下一轮 prompt 预热进缓存。在某些低延迟场景下能把首 token 延迟打下去很多。
misc/batch_processing.ipynb — Message Batches API。离线批处理的价格是实时请求的 50%，跑评测、做回填数据时能省很多。
misc/session_memory_compaction.ipynb — 会话记忆压缩。和 tool use 里的 automatic-context-compaction 是配套关系，一个讲工具侧，一个讲消息侧。
observability/usage_cost_api.ipynb — Usage & Cost API。用来做团队用量看板、成本归因报表。
misc/using_citations.ipynb — Citations 功能。让 Claude 在回答里标注"这句话来自文档的哪一段"，做 RAG 产品时非常有用。
misc/sampling_past_max_tokens.ipynb — 当输出被 max_tokens 截断时怎么优雅续写。

这几篇单独看每一个都不长，但组合起来基本就是一个"线上项目优化清单"。上线前对着这张清单过一遍，能省下不少成本和踩坑时间。

有一个非常容易被忽略的组合用法：prompt caching + batch processing。Batch API 本身就打 5 折，再加上 caching 命中的部分又打 1 折左右，叠加下来做离线大规模推理时的成本可以比天真实现低 85% 以上。如果你在做评估、数据标注、回填历史数据这类离线任务，这个组合的经济性优势非常大，但大多数人做 MVP 时根本不会想到要用它。

六、Agent 的三条进阶路径

这是整个 cookbook 里我认为最值得花时间的一块，也是 README 最没讲清楚的一块。

Anthropic 把"怎么构建 Agent"拆成了三个层次递进的目录：

1
2
3


patterns/agents/ ← 模式层：概念和套路（轻量）
claude_agent_sdk/ ← SDK 层：用 Agent SDK 自己组装（中等）
managed_agents/ ← 托管层：用 Managed Agents 托管运行时（重型）

从左到右是"自由度递减、工程量递减"的关系。 哪一层适合你，取决于你要做的系统规模和运行需求。

6.1 模式层 `patterns/agents/` — 先把套路搞清楚

这个目录对应的是 Anthropic 那篇著名博客 Building Effective Agents 里提的几种基础模式的可运行版本：

basic_workflows.ipynb — Prompt chaining / Routing / Parallelization 三种基础工作流模式。
evaluator_optimizer.ipynb — 评估者-优化者模式。一个 Agent 输出、另一个 Agent 打分并反馈，循环到满足条件为止。
orchestrator_workers.ipynb — 编排者-工人模式。主 Agent 拆任务，子 Agent 并发执行。

这三篇是"概念打底"。哪怕你最后不用 Agent SDK，看一遍这三个模式，再去评估任何第三方 Agent 框架的设计，心里都会有一把尺子。

6.2 SDK 层 `claude_agent_sdk/` — 官方的 Agent 教程

这是 Anthropic 最近重点推进的一块，基于 claude-agent-sdk-python，六篇 notebook 是一条渐进式的教学路径：

#	文件	学到什么
00	`00_The_one_liner_research_agent.ipynb`	一行 `query()` 起一个研究 Agent，理解异步迭代和基础概念
01	`01_The_chief_of_staff_agent.ipynb`	CEO 助理 Agent——Memory、Output Styles、Plan Mode、Slash Commands、Hooks、子 Agent 编排全家桶
02	`02_The_observability_agent.ipynb`	可观测性 Agent，需要 GitHub Token + Docker
03	`03_The_site_reliability_agent.ipynb`	SRE Agent，处理告警和事故
04	`04_migrating_from_openai_agents_sdk.ipynb`	从 OpenAI Agents SDK 迁移过来的映射指南——有存量代码的团队重点看这篇
05	`05_Building_a_session_browser.ipynb`	Session 浏览器 demo，可视化 Agent 会话

这一条路径的隐含逻辑是：“你如果已经在用 Claude Code，那 Claude Code 背后的 Agent 内核就是 Agent SDK，你可以用同样的工具链做任何 Agent 应用，而不只是软件开发”。

01 这篇 Chief of Staff 我单独推荐——它是整个教程里最接近"生产级 Agent 到底长什么样"的那篇。里面把持久化记忆（CLAUDE.md 机制）、输出风格切换（给 CEO 发邮件 vs 给团队发内部备忘是两种语气）、Plan Mode（复杂任务先产出方案再执行）、Slash Commands（把高频操作做成可复用快捷方式）、Hooks（每次工具调用都自动写审计日志）、Subagent 编排（法务/财务/战略三个专项 Agent 分工协作）这一整套都串起来了。看完之后你会意识到，“Agent” 这个概念背后其实是一组工程约束的组合，单独拎出任何一个都不够，组合起来才是真正可以上生产的东西。

6.3 托管层 `managed_agents/` — Claude Managed Agents (CMA)

Managed Agents 是 Anthropic 相对较新的一个产品形态：服务端托管的 Agent 运行时，带沙箱、会话持久化、文件状态保留，你只要定义 Agent 和环境，剩下的交给托管服务。

这个目录分成两组：

三个应用型示例（适合先看，建立直觉）：

data_analyst_agent.ipynb — CSV 进、HTML 分析报告出的数据分析 Agent。
slack_data_bot.ipynb — 把上面那个分析 Agent 包成 Slack Bot。
sre_incident_responder.ipynb — 告警→调查→PR→人审→合并的完整 SRE 流程。

六个教程型 notebook（以 CMA_ 开头，建议按顺序读）：

Notebook	主题
`CMA_iterate_fix_failing_tests.ipynb`	入门。引入 agent / environment / session、文件挂载、流式事件循环
`CMA_orchestrate_issue_to_pr.ipynb`	issue → 修复 → PR → CI → 人审 → 合并的完整编排
`CMA_explore_unfamiliar_codebase.ipynb`	在陌生代码库里探索，含"过期文档陷阱"演示
`CMA_gate_human_in_the_loop.ipynb`	人类审批关卡，用自定义工具的 `decide()` / `escalate()` 模式
`CMA_prompt_versioning_and_rollback.ipynb`	提示词版本化与回滚——生产 Agent 的脆弱环节，中文圈讲得很少
`CMA_operate_in_production.ipynb`	生产部署：MCP 工具集、vault 存 per-user 凭证、webhook idle 模式

这一组是目前 cookbook 里最贴近"企业级 Agent 运营"的内容。如果你在做 B 端 Agent 产品，哪怕不用 Managed Agents，也强烈建议看一遍 prompt versioning 和 operate in production 这两篇——它们把"Agent 上线之后你还要做哪些事"讲得最清楚。

稍微展开一下 CMA_prompt_versioning_and_rollback.ipynb 为什么特别值得看：传统软件工程里代码改动有 Git、有 CI、有灰度发布，但 prompt 的改动目前很多团队还靠 Excel 或 Notion 维护。Prompt 不是代码但比代码更脆弱——同一个字改一下，模型行为可能完全变样。这篇 notebook 给出的答案是把 prompt 也纳入版本化体系：服务端存版本、每个 session 可以绑定到特定版本、用标注过的测试集做版本对比、发现回归可以按 session ID 批量回滚。这套工作流不依赖 Managed Agents 本身也能借鉴——核心思路是把 prompt 当成一等公民的配置来治理。

七、Skills 技能包

skills/ 目录对应的是 Claude 的 Skills 功能——打包好的"专业能力"，Claude 在需要的时候自动发现并加载。

核心理念是 Progressive Disclosure：技能定义不在每轮对话里都加载，只在模型判断"这个任务需要 Excel 能力"时才把 Excel skill 拉进来，从而节省 token。

这个目录下有三篇 notebook：

notebooks/01_skills_introduction.ipynb — 基础：加 beta header、创建第一个 Excel/PPT/PDF。
notebooks/02_skills_financial_applications.ipynb — 金融场景：投资组合报告、多格式工作流（CSV → Excel → PPT → PDF）。
notebooks/03_skills_custom_development.ipynb — 自定义 skill 开发：金融比率计算器、品牌指南 skill。

Skills 这个功能对应的是你在 Claude.ai 里看到的"Claude 帮你直接生成 Excel/PPT"那个能力。如果你想做类似的"让 Claude 产出真正可用的办公文档"的产品，这是唯一的官方路径。

Progressive Disclosure 这个机制值得单独理解一下。传统做法里，你要给模型扩展能力，通常是把所有工具定义、system prompt、知识都塞进每一轮对话——结果是你挂的能力越多，token 成本越高，而且大部分 token 根本用不上。Skills 的思路是把能力拆成有元数据的"技能包"，只在模型判断当前任务需要时才动态加载对应的代码和指令，本质上是一种 lazy loading + capability routing。这个设计思路在做大型 Agent 平台时非常关键，哪怕你不用 Skills 产品本身，理解它的机制对你设计自己的能力注入系统也有参考价值。

八、第三方集成一览

third_party/ 下有八家集成，都是最小可跑的对接示例：

目录	角色	典型场景
`Pinecone/`	向量数据库	RAG 召回
`VoyageAI/`	Embedding 模型	RAG、语义搜索
`MongoDB/`	文档数据库 + 向量搜索	一体化 RAG 后端
`LlamaIndex/`	RAG 框架	和 Claude 一起用的完整 pipeline
`Wikipedia/`	知识源	实时查询百科做事实补充
`WolframAlpha/`	计算/数学	精确数值计算、公式求解
`Deepgram/`	语音转文字	音频输入场景
`ElevenLabs/`	文字转语音	语音输出场景

这块适合按需查阅——你项目里用到哪家就去看哪篇，不需要通读。

九、评估与微调

这两块相对偏"工程化"，但一旦你开始做严肃点的 AI 产品就绕不过去：

misc/building_evals.ipynb — 自动化评估。用 Claude 当 judge 给自己的 prompt 打分。
misc/generate_test_cases.ipynb — 用 Claude 生成测试用例来做对抗性评估。
tool_evaluation/tool_evaluation.ipynb — 工具级评估。Agent 系统里每个 tool 调用是否正确、参数是否合理的专项评估。
misc/metaprompt.ipynb — Metaprompt：让 Claude 帮你写/优化 prompt。
misc/building_moderation_filter.ipynb — 用 Claude 搭内容审核过滤器。
finetuning/finetuning_on_bedrock.ipynb — 在 AWS Bedrock 上微调 Claude，附 datasets/ 示例数据。

微调这块目前官方只出了 Bedrock 路径的教程，直接从 Anthropic API 做 fine-tuning 目前还不是公开能力。

十、仓库工程实践：这本身就是一份"怎么管理 Notebook 项目"的样板

这一节是给另一类读者的——那些在自己团队里也要维护大量 notebook / 示例代码的工程师。

claude-cookbooks 这个 repo 本身的组织方式，其实是一份挺成熟的范本：

用 uv 做包管理。有 uv.lock 和 uv.toml，uv sync --all-extras 一键把所有依赖装齐。相比 pip install -r requirements.txt，速度快一个数量级，也更容易复现。
ruff 做 lint 和 format。行长 100、双引号。Notebook 里放宽了 E402（中间 import）、F811（重定义）、N803/N806（变量命名），这几条放宽对 notebook 写作很实用——Jupyter 里本来就会有大量这种"不优雅但可读"的写法。
pre-commit + Makefile + tox。make check / make fix / make test 三条命令覆盖日常。
registry.yaml + authors.yaml。每篇 notebook 在 registry.yaml 里登记标题、路径、作者、分类，方便后续站点化检索。这是一个很聪明的做法——内容和元数据分离，让 notebook 集合可以被当成一个可查询的数据库来对待。
.claude/ 目录 + 自定义 slash commands。/notebook-review（检查 notebook 质量）、/model-check（校验模型 ID 是不是用了非推荐的日期版本）、/link-review（检查死链）。这几个 slash command 既给人用，也给 CI 用。
lychee.toml。专门的死链检查配置，比自己手写正则靠谱。
CLAUDE.md 里写死模型 ID 规范。明确规定永远用非日期别名（如 claude-sonnet-4-6）而不是 claude-sonnet-4-6-20250514。这种小约定写在 CLAUDE.md 里，让 Claude Code 或其他 Agent 在写示例代码时不会跑偏。

这些细节如果你自己维护过一个 notebook 集合，应该能立刻 get 到它们的价值。我之前维护过几套内部示例代码，最大的痛点就是时间一长没人管，示例里的 API 调用方式和模型名全都过时了。claude-cookbooks 用 CI + slash command + 自动化校验把这件事从"靠人自觉"变成"靠流程保证"，是很值得抄的做法。

另一个细节是 registry.yaml 里每篇 notebook 都登记了分类标签和作者。这看起来只是一个 meta 索引文件，但它背后其实是一个内容运营思路：让示例集合既能被人读，也能被机器查询。未来如果要做一个"按类目筛选的交互式站点"或者"根据用户目标推荐 notebook 的 Agent"，registry.yaml 就是现成的数据源。把内容和元数据分开，永远比把元数据硬编码进 README 要更灵活。

十一、我接下来会按什么顺序往里钻

最后给自己留一份阅读路线图，也供参考：

如果你是第一次用 Claude API：

misc/prompt_caching.ipynb — 先把成本大头的底子打好
tool_use/calculator_tool.ipynb + tool_choice.ipynb — Tool use 基础
capabilities/retrieval_augmented_generation/ — 如果你要做 RAG
multimodal/getting_started_with_vision.ipynb — 如果涉及图像

如果你已经在用 Claude Code，想扩展到自定义 Agent：

patterns/agents/ 三篇 — 先把概念过一遍
claude_agent_sdk/00 → 01 → 04 — 沿着教程走
tool_use/memory_cookbook.ipynb + automatic-context-compaction.ipynb — 长会话 Agent 必备
managed_agents/CMA_operate_in_production.ipynb — 想上线再看这篇

如果你在做 B 端 Agent 产品：

managed_agents/ 全套六篇 CMA 教程
tool_evaluation/tool_evaluation.ipynb + misc/building_evals.ipynb — 评估不能缺
observability/usage_cost_api.ipynb — 成本监控
managed_agents/CMA_prompt_versioning_and_rollback.ipynb — 运营侧

结尾：这只是起点

写到这里回头看，这份 cookbook 里随便挑一个模块展开，都够单独写一篇长文：

Agent SDK 的六篇 notebook 值得一篇一篇拆，特别是 Chief of Staff 那篇里塞了一整套生产级 Agent 该有的能力
Managed Agents 这个新产品形态本身就值得一篇"它和 Agent SDK 到底什么区别"的分析
Tool Use 里的 PTC、Tool Search with Embeddings、Memory Tool 每一个单拿出来都能写一篇技术拆解
Skills 的 Progressive Disclosure 机制和它对 token 经济的影响，是个完整的专题
patterns/agents/ 对应的那三种设计模式，配合实际项目经验聊一聊会很有意思

这些我都打算一篇一篇写。这份导航文章就当是书签——以后每完成一篇深度拆解，就回来把对应的链接加上，让这里慢慢长成一张真正可用的学习路线图。

如果你也在看这份 cookbook，欢迎告诉我你最关心哪个模块，我排序的时候可以参考一下。

参考资料

anthropics/claude-cookbooks — 本文索引的主体
anthropics/claude-agent-sdk-python — Agent SDK 本体
anthropics/courses — 如果你还在更早的阶段，先看这个
Building Effective Agents — Anthropic 官方 Agent 设计方法论
Equipping agents for the real world with Skills — Skills 的设计理念

Prompt Caching 深度拆解：Claude Code 是如何做到 92% 命中率的

Fri, 17 Apr 2026 00:00:00 +0000

你有没有想过这样一个问题：

当你跟 Claude Code 对话了 30 分钟，中间来回几十个 tool call 之后，每一次它要回复你，都会把前面所有的对话历史重新发一遍给模型。

System prompt、tool schema、CLAUDE.md 里的项目约定、三轮之前已经处理过的那些文件内容——全部重新读、重新算、重新计费。

这不是 bug，是 LLM API 的工作方式。对于长会话的 Agent 来说，这种"重复计算"往往是你 AI 基础设施账单里最贵的一项。

举个数：一个 2 万 token 的 system prompt，跑 50 轮对话，那就是 100 万 token 的纯冗余计算，全部按输入价格计费，产生零新价值。而这笔开销会在每个用户、每个 session 上复利叠加。

解决办法是 Prompt Caching。但要真正把它用好，你得先搞清楚底下到底发生了什么。

这篇文章来自 Avi Chawla 的一篇推文，作者把 Claude 如何做到 92% 缓存命中率这件事讲得非常透彻。我把它翻译整理出来，并加入了一些自己使用 Claude Code 过程中的观察。

一、静态上下文 vs 动态上下文

要优化一个 prompt，你得先理清楚：哪些是会变的，哪些是不变的。

每一次 Agent 的请求，其实都由两个本质上完全不同的部分组成：

	内容	特征
静态前缀	system 指令、tool 定义、项目上下文、行为规范	每轮都一样，永远不变
动态后缀	用户消息、模型回复、tool 输出、终端观察	每轮都在增长

这个划分，就是 prompt caching 能成立的前提。

推理基础设施会把静态前缀对应的数学状态（也就是 KV tensor）存下来，让后续发送完全相同前缀的请求可以直接跳过计算，从内存里读出来。

一旦你把这件事想通，后面所有的架构决策，都会变得非常显然。

二、KV Cache 到底在缓存什么

要理解为什么缓存这么有效，得先看 Transformer 处理你的 prompt 时到底做了什么。

LLM 推理有两个阶段：

Prefill 阶段：处理你输入的整个 prompt。在所有 token 上跑一轮密集矩阵乘法，构建模型的内部表示。这个阶段是 compute-bound（算力瓶颈），非常贵。
Decode 阶段：一个 token 一个 token 地生成。每次把新 token 追加到序列里，预测下一个。这个阶段是 memory-bound（显存瓶颈），因为大部分工作是在读历史状态。

在 prefill 阶段，Transformer 会为每一个 token 计算三个向量：Query、Key、Value。Attention 机制用它们来决定每个 token 跟其他 token 的关系。

关键在于：一个 token 的 Key 和 Value 只依赖于它前面的那些 token。一旦算出来，就永远不会变。

没有缓存的情况下，这些 Key 和 Value tensor 在每次请求结束后就被丢掉了，下次请求要从头再算一遍。对于 2 万 token 的前缀，那就是 2 万 token 的 attention 计算——完全没必要重复。

KV Cache 的做法是：把这些 tensor 持久化在推理服务器上，用 token 序列的加密哈希做索引。当新请求进来、前缀完全一致时，哈希命中，tensor 直接从内存里加载，这段 prefill 计算整个跳过。

这把每生成一个 token 的计算复杂度从 O(n²) 降到 O(n)。对于一个重复使用 50 轮的 2 万 token 前缀，省下的算力是非常可观的。

三、经济账

定价结构才是让这个架构决策真正有分量的地方。

Cache Read：0.1x 的基础输入价格——也就是九折优惠，打完一折。
Cache Write：1.25x 的基础价格——存 KV tensor 要加收 25% 溢价。
Extended 1-hour Caching：2.0x 的价格。

下面是 Claude 各模型的具体价格：

但这笔账只有在缓存命中率够高的时候才划算。

生产环境里最好的例子，就是 Claude Code。

四、Claude Code 的 30 分钟实录

Claude Code 的整个架构设计，都围绕一个目标展开：让缓存一直保持热的（keep the cache hot）。

下面这段是一次真实的 30 分钟编码会话从计费视角看起来是什么样的：

第 0 分钟：Claude Code 加载 system prompt、tool 定义、项目 CLAUDE.md 文件。这个载荷超过 2 万 token，而且每个 token 都是新的，这是整场会话里最贵的一刻。但这笔钱你只付一次。

第 1-5 分钟：你开始下指令，Claude Code 派出 Explore Subagent 在代码库里游走，打开文件、跑 grep 命令。所有这些都被追加到动态后缀里。但那 2 万 token 的静态前缀现在是在以 $0.30/MTok 的缓存价读取，而不是 $3.00/MTok。

第 6-15 分钟：Plan Subagent 收到的是一份摘要版简报，而不是原始结果——因为把原始输出塞进来只会让动态后缀没必要地膨胀。它产出一份实现计划，你批准后，Claude Code 开始改代码。每一轮都在从缓存里读静态前缀，命中率飙过 90%，而且每次访问都会重置 TTL、让缓存保持温热。

第 16-25 分钟：你提出修改，意味着更多 tool call、更多终端输出、动态后缀里堆积更多上下文。到这时，整场会话已经处理了几十万 token，但每一轮都在从缓存读那 2 万 token 的地基。

第 28 分钟：你在终端敲 /cost。不带缓存的话，Sonnet 4.5 的定价下 200 万 token 要花 $6.00。带上 92% 效率的缓存，其中 184 万 token 是 cache read，总成本降到 $1.15——单次任务减少 81%。

这就是一个热缓存应该长的样子：为静态地基付一次钱，然后免费读取任意多次。动态尾部是唯一会被持续计费的部分。

鬼哥的使用体感：我平时重度用 Claude Code，每次敲 /cost 都会注意一下 cache_read_input_tokens 这一栏——动辄占到整个输入量的 90% 以上，这个数字非常直观地告诉你缓存是不是在工作。如果哪天命中率突然掉下去，基本就是提示你：你可能刚刚做了什么破坏缓存的事——比如中途换模型、或者手抖改了某个 subagent 的定义。

五、哈希缓存的脆弱性

关于 prompt caching，最反直觉的一点是：

“1 + 2 = 3” 可以命中缓存，但 “2 + 1” 就是一次 miss。

推理基础设施是从头开始对整个 token 序列做哈希。只要序列里任何东西变了，哪怕只是两个元素的顺序——哈希就变了，整个前缀都要按全价重算。

这不是什么实现细节，这是 Claude Code 所有工程决策背后最核心的约束。

下面是生产环境里真实出现过的、破坏缓存的几个例子：

在 system prompt 里注入了一个时间戳——每次请求都生成一个独一无二的哈希。
一个 JSON 序列化器对 tool schema 的 key 排序不稳定——前缀直接作废。
一个 AgentTool 的参数在会话中途被动态修改——2 万 token 的缓存全部报废。

从这里可以推出三条铁律：

不要在会话中途修改 tool。 Tool 定义是缓存前缀的一部分，加一个、删一个，都会让下游所有东西失效。
永远不要在会话中途切换模型。 缓存是按模型绑定的，意味着切到便宜模型继续对话，要重建整个缓存——省的钱可能还抵不上重建成本。
永远不要通过修改前缀来更新状态。 Claude Code 的做法是：把提醒标签追加到下一条用户消息里，而不是去编辑 system prompt——前缀永远不动。

鬼哥补充一条：你在写自定义 Agent 的时候，注意 Python dict 序列化成 JSON 时的 key 顺序。Python 3.7+ 的 dict 是有序的，但如果你的 tool schema 有一部分来自合并多个 dict 或者来自数据库查询，顺序可能每次都不一样。这种隐性的不确定性，是最容易让你整夜找不到原因的 cache miss 来源。

六、应用到你自己的 Agent

不管你是直接用 Claude Code，还是从头搭自己的 Agent，规则都是一样的。

按这个顺序组织你的 prompt：

System 指令和行为规范放在最上面。会话期间不要改。
**Tool 定义一次性全部加载完毕。**不要中途增减。
检索到的上下文和参考文档接下来。会话期间保持稳定。
对话历史和 tool 输出放最下面。这才是你的动态后缀。

如果你用的是 Anthropic API 的 auto-caching，缓存断点会随着对话增长自动推进。如果不用 auto-caching，你得手动管理 token 边界——边界错了一个位置，就意味着完全错过缓存。

对于上下文压缩（当你快接近上下文上限时），要用**“缓存安全的分叉”这种做法：保留同样的 system prompt、tool、对话历史，然后把压缩指令作为一条新消息追加**在后面。缓存前缀得以复用，真正要被计费的新 token 只有压缩指令本身。

验证缓存是否在工作，盯死 API 响应里这三个字段：

字段	含义
`cache_creation_input_tokens`	写入缓存的 token 数
`cache_read_input_tokens`	从缓存读取的 token 数
`input_tokens`	没走缓存、按全价计费的 token 数

缓存命中率 = cache_read_input_tokens / (cache_read_input_tokens + cache_creation_input_tokens)

把它当成你的可用率（uptime）指标来盯。命中率掉下去，就是警报。

七、Takeaways

Prompt Caching 不是一个你打开开关就能用的特性，而是一种必须贯穿到架构层面的纪律。

核心思想其实简单到一句话：把静态内容放最上面，动态内容从下面长。 基础设施会对前缀做哈希、存储 KV tensor、然后在你每一次读取时给你九折。

但纪律藏在所有细节里：

不要往 system prompt 里注入时间戳
不要打乱 tool 定义的顺序
不要在会话中途切换模型
不要在缓存断点上游去修改任何东西

Claude Code 在生产规模上演示了这套纪律的效果：92% 的缓存命中率，81% 的成本削减。

如果你正在搭 Agent 却没有围绕 prompt caching 做设计，你就是在把大部分利润留在桌上。

参考资料

原文推文：Prompt caching in LLMs, clearly explained - @_avichawla
Anthropic Prompt Caching 文档：Prompt caching - Anthropic Docs

Claude Code Session 管理指南：1M 上下文是把双刃剑

Thu, 16 Apr 2026 00:00:00 +0000

你用 Claude Code 的时候，是不是就一个终端窗口，一路发消息到底？

我之前也是这样。直到最近读到 Anthropic 的 Thariq 写的一篇关于 Session Management 的帖子，才意识到自己一直在用最笨的方式——把 100 万 token 的上下文窗口当成一个无限垃圾桶。

Thariq 说他最近跟很多 Claude Code 重度用户聊过，发现一个反复出现的主题：1M token 的上下文窗口是把双刃剑。 它让 Claude Code 能自主运行更久、处理更复杂的任务，但同时也打开了 context pollution（上下文污染）的大门——如果你不刻意管理 Session，模型的表现反而会越来越差。

Session 管理变得比以往更重要。要不要开两个终端？每次发 prompt 都新开一个 Session？什么时候该用 compact、rewind、还是 subagent？

这篇文章把这些问题讲清楚了。

Context、Compaction 和 Context Rot

先把基础概念对齐。

Context Window（上下文窗口） 是模型在生成下一条回复时能「看到」的全部内容——包括系统提示词、整段对话历史、每次工具调用的输入和输出、以及读过的每一个文件。Claude Code 的上下文窗口是 100 万 token。

但使用上下文是有代价的，这个代价叫 Context Rot（上下文衰退）。

Context Rot 指的是：随着上下文越来越长，模型性能会下降。因为注意力机制会被分散到更多的 token 上，老旧的、不相关的内容开始干扰当前任务。Anthropic 观察到的规律是，大约在 300-400k token 的时候，Context Rot 开始出现——但这高度依赖任务本身，不是一条硬规则。

上下文窗口是一个硬性截断。当你快用完的时候，需要把当前的工作总结成更精简的描述，在新的上下文窗口中继续——这个操作叫 Compaction（压缩）。你也可以手动触发它。

每一轮对话结束后，都是一个分叉点

假设你刚让 Claude 做完了一件事，上下文里现在有了一些东西（工具调用、输出结果、你的指令），接下来你有 5 个选项——但大多数人只用了第一个：

Continue —— 继续在同一个 Session 中发消息
/rewind（双击 Esc）—— 跳回到之前某条消息，从那里重新开始
/clear —— 新开一个 Session，通常带着你从上一轮蒸馏出来的 brief
/compact —— 压缩当前 Session 的历史，在摘要的基础上继续
Subagent —— 把接下来的工作委托给一个拥有独立干净上下文的子代理，只拿结果回来

最自然的反应当然是继续发消息。但另外四个选项的存在，就是为了帮你管理上下文。

什么时候该开新 Session？

1M 的上下文意味着你现在可以更可靠地完成更长的任务——比如让 Claude 从零搭建一个全栈应用。但 上下文没用完，不代表你不该开新 Session。

Anthropic 的经验法则：当你开始一个新任务时，也应该开始一个新 Session。

灰色地带在于：你可能想做一些相关的任务，上下文中的一部分内容仍然有用，但不是全部。

比如，你刚实现了一个功能，接下来要写它的文档。虽然可以新开 Session，但 Claude 得重新读一遍你刚实现的那些文件，更慢也更贵。写文档不是一个对「智能强度」要求特别高的任务，多余的上下文带来的效率增益可能值得保留。

我自己的判断方式：下一个任务要是做错了会不会很麻烦？如果答案是"会"（比如重构核心逻辑），果断新开。如果答案是"还好"（比如写文档、加注释），继续旧 Session 省事。

最值得养成的习惯：用 Rewind 代替纠正

如果只能推荐一个习惯，Thariq 说他会选 rewind。

在 Claude Code 里，双击 Esc（或者运行 /rewind）可以跳回到之前任意一条消息，从那个点重新给 prompt。那条消息之后的所有内容会被从上下文中丢弃。

Rewind 往往比纠正更好。 举个例子：Claude 读了 5 个文件，尝试了一个方案，没成功。你的本能反应可能是说"那个不行，试试 X 方案吧"。但更好的做法是：rewind 到刚读完文件的那个点，然后带着你学到的信息重新给指令。

“别用方案 A，foo 模块没有暴露那个接口——直接走方案 B。”

你还可以用"summarize from here"让 Claude 总结它的发现，生成一份交接消息——有点像未来的 Claude 给过去的自己写了一封信：这条路走不通，原因是什么。

这件事我自己踩过很多坑。之前遇到 Claude 写的代码不对，我都是直接在下面追"不对，换个方式"、“还是不行，试试另一个”——结果上下文里全是失败的尝试，越到后面 Claude 表现越差。后来开始用 rewind，明显感觉"一次做对"的概率高了很多。

Compact vs 新开 Session

一旦 Session 变长，你有两种减重方式：/compact 或者 /clear（新开）。它们感觉很像，但行为完全不同。

/compact：让模型总结对话历史，用摘要替换完整记录。这是有损的——你在信任 Claude 来决定什么是重要的。好处是你不需要自己写任何东西，而且 Claude 可能在包含重要细节和文件方面比你更全面。你也可以引导它：/compact 聚焦 auth 重构部分，丢掉测试调试内容。

/clear：你自己写下重要的内容——“我们正在重构 auth 中间件，约束是 X，关键文件是 A 和 B，已经排除了方案 Y”——然后清空重开。工作量更大，但最终的上下文完全是你认为相关的内容。

简单说：/compact 是让 Claude 帮你做摘要，/clear 是你自己做摘要。 前者省事但有损，后者费力但精确。

什么导致了一次「坏 Compact」？

如果你经常跑长 Session，可能遇到过 compact 之后 Claude 突然变蠢的情况。

Anthropic 发现，坏 compact 通常发生在模型无法预测你接下来要做什么的时候。

举个例子：autocompact 在一段漫长的 debugging session 之后触发，它把调查过程总结了一遍。然后你的下一条消息是"现在去修 bar.ts 里那个 warning。"

但因为 Session 的主题一直是 debugging，那个 warning 可能已经被当作不重要的内容从摘要中丢掉了。

更麻烦的是：由于 Context Rot，模型在触发 compaction 的那个时刻恰恰处于最不聪明的状态。 它用最差的自己去总结整段历史，结果可想而知。

解法：利用 1M 上下文给你的时间余量，在 Context Rot 出现之前主动执行 /compact，并且告诉它你接下来打算做什么，作为总结的方向引导。

Subagent：独立上下文的子任务

Subagent 本质上是一种上下文管理手段。当你提前知道一块工作会产生大量中间输出、但你不再需要那些中间内容时，它特别有用。

当 Claude 通过 Agent 工具生成一个 subagent，这个 subagent 会获得自己独立的全新上下文窗口。它可以做任意多的工作，然后合成结果，只把最终报告返回给父 agent。

Anthropic 的心理测试：我还会需要这些工具输出吗？还是只需要结论？

虽然 Claude Code 会自动调用 subagent，但你也可以显式指定：

“启动一个 subagent，根据这个 spec 文件验证我刚才的实现是否正确”
“启动一个 subagent，读完另一个代码库，总结它的 auth 流程是怎么实现的，然后你自己按同样方式来”
“启动一个 subagent，根据 git 变更记录给这个功能写文档”

这个功能我现在用得越来越多。特别是让 subagent 去读别的项目的源码然后回来总结，效果非常好——因为读源码的过程会产生海量 token，留在主上下文里是纯粹的浪费。

最后

Session 管理这件事，说到底就一句话：每次 Claude 结束一轮工作、你准备发下一条消息的时候，那是一个决策点。

不要无脑继续。停下来想一想：上下文还干净吗？方向对吗？接下来的任务真的需要之前的全部内容吗？

Anthropic 说他们预计未来 Claude 会学会自己处理这些。但就现阶段而言，主动管理 Session 是你能做的、对 Claude Code 使用体验影响最大的一件事。

参考资料

原推文：Thariq (@trq212) on X
Claude 官方博客原文

Karpathy 的 LLM Wiki：用大模型编译知识，而不是检索知识

Mon, 06 Apr 2026 00:00:00 +0000

“我最近大部分的 token 消耗，不再是在操作代码，而是在操作知识。” —— Andrej Karpathy, 2026.04.03

2026 年 4 月 3 日，Karpathy 发了一条推文，描述了他最近用 LLM 构建个人知识库的工作流。第二天，他把这个想法整理成了一个 GitHub Gist，并提出了一个有趣的理念：在 LLM Agent 时代，分享 idea 比分享代码更有价值——你把 idea 交给自己的 Agent，它会为你定制和构建一切。

这条推文迅速引爆了技术社区。但在热度之下，Karpathy 真正提出的东西值得我们认真拆解：一种**用 LLM 编译知识（而非检索知识）**的全新范式。

本文将系统性地拆解这套思维体系——从它的历史渊源到技术架构，从与 RAG 的本质区别到社区的尖锐争论，最后给出可落地的实践路径。

一、从 1945 年说起：Bush 的 Memex 构想

要理解 Karpathy 在做什么，我们需要先回到 81 年前。

1945 年 7 月，Vannevar Bush 在《The Atlantic》发表了一篇名为 “As We May Think” 的文章，提出了 Memex（memory + index 的合成词）——一台桌面大小的设备，能存储一个人所有的书籍、记录和通信，并以"极快的速度和灵活性"供人检索。

Memex 最独特的设计是关联路径（Associative Trails）：用户可以在任意文档之间创建链式连接，模拟人类联想式思维，而非传统的层级索引。用户可以给这些路径加批注、创建分支，然后分享给同事。

这个构想直接影响了后来的一系列技术发明：

Douglas Engelbart（1945）读到这篇文章后开始研究，最终发明了鼠标、文字处理器和超链接
Ted Nelson（1965）明确引用 Memex，创造了"超文本"（Hypertext）这个概念
Tim Berners-Lee（1989）在此基础上构建了万维网
DARPA（2014）直接以 Memex 命名了一个研究项目

但 Bush 的构想有一个致命缺陷：维护成本。谁来持续更新这些关联路径？谁来在新文档加入时更新所有相关的交叉引用？谁来标注新旧信息之间的矛盾？

答案在 81 年后到来：LLM。

Bush 的 Memex 构想其实比万维网更接近 Karpathy 的方案——Web 是公开的、混乱的、弱链接的；Memex 是私人的、策展的、富链接的。

二、核心洞察：编译知识，而非检索知识

RAG 的根本问题

目前大多数人使用 LLM 处理文档的方式是 RAG（Retrieval-Augmented Generation）：上传文件 → 切块建索引 → 查询时检索相关片段 → 生成回答。

Karpathy 一针见血地指出了 RAG 的本质问题：

“LLM 每次查询都从零重新发现知识。什么都不积累。”

这就像一个图书管理员，每次有人来问问题，他都要从头翻阅所有的书，找到相关段落，拼凑出一个答案。下次同样的人来问相关的问题，他又从头来一遍——完全不记得上次的工作。

RAG 的具体局限：

维度	RAG 的问题
知识综合	只检索扁平文档，不在文档间创建关联和综合
复利效应	答案每次重新推导，知识不累积
检索噪声	基于嵌入的检索容易出现语义/词汇不匹配的静默失败
基础设施	需要向量数据库、嵌入模型、分块策略等一整套基建
上下文窗口	即使 2M token 也只能装约 300-400 页，一份财报就可能耗尽

知识编译：一种新范式

Karpathy 的替代方案是：不要只在查询时检索原始文档，而是让 LLM 增量地构建和维护一个持久的 Wiki。

当添加新资料时，LLM 不仅仅是索引它。它会：

阅读全文并提取关键信息
整合到现有的 wiki 知识体系中
更新相关的实体页面
修正已有的摘要
标注新旧信息之间的矛盾
强化跨文档的综合分析

知识编译一次，持续维护，而非每次查询都重新推导。

一个形象的比喻：

RAG = 一个有超快叉车的巨型仓库——什么都能找到，但不能解释货物之间的关系
LLM Wiki = 一个有专职图书管理员的策展图书馆——管理员不断写新的综述来描述和关联旧有的藏书

关键区别：Wiki 是一个持续复利的知识制品

交叉引用真实存在，矛盾被标注，综合分析反映了所有已读内容。Wiki 随着每一个新来源和每一次提问而变得更丰富。

三、三层架构

Karpathy 在 Gist 中明确定义了三层架构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


┌─────────────────────────────────────────┐
│ The Schema（配置层） │
│ CLAUDE.md / AGENTS.md │
│ 定义 wiki 结构、惯例、工作流 │
├─────────────────────────────────────────┤
│ The Wiki（知识层） │
│ LLM 生成和维护的 .md 文件 │
│ 摘要 / 实体页 / 概念页 / 综述 / 索引 │
├─────────────────────────────────────────┤
│ Raw Sources（原始资料层） │
│ 不可变的策展文档 │
│ 文章 / 论文 / 图片 / 数据集 / 代码库 │
└─────────────────────────────────────────┘

第一层：Raw Sources（原始资料）

这是不可变的事实来源。文章、论文、图片、数据文件——只进不改。所有的原始材料都保存在 raw/ 目录中。

采集工具：

Obsidian Web Clipper 浏览器扩展：一键将网页文章转为 markdown
配合 Obsidian 快捷键将相关图片下载到本地，方便 LLM 直接引用
手动放入的论文 PDF、数据集等

第二层：The Wiki（知识层）

这是 LLM 生成和维护的核心层——一组结构化的、互相链接的 markdown 文件。包括：

摘要页：每个原始资料的关键要点提炼
实体页：人物、组织、技术的专属页面
概念页：抽象概念的解释和关联
综述页：跨多个来源的主题综合分析
索引文件：全局目录和导航

关键原则：人类几乎不直接编辑 wiki，这是 LLM 的领地。 你负责策展来源、提出问题、引导方向；LLM 负责所有的簿记工作。

第三层：The Schema（配置层）

一个配置文档（如 CLAUDE.md 或 AGENTS.md），定义：

Wiki 的目录结构和命名规范
页面的模板格式
摄入新资料时的工作流程
质检的标准和流程

这个配置层将 LLM 从通用聊天机器人转变为结构化的知识维护者。

四、三大核心操作

操作一：Ingest（摄入）

当你往 raw/ 目录放入新资料时：

LLM 阅读原始资料
与你讨论关键要点
写摘要页，放入 wiki
更新 index.md（全局目录）
遍历已有的 wiki 页面，更新所有相关的实体页和概念页
在 log.md 中追加操作记录

一次摄入可能会触及 10-15 个 wiki 页面——这正是 LLM 维护的核心价值：人类不可能每加入一份资料就手动更新十几个页面，但 LLM 可以。

操作二：Query（查询）

当你向 LLM 提问时：

LLM 首先读取 index.md 了解知识库全局结构
根据问题定位相关的 wiki 页面
阅读相关页面，综合回答，附上引用来源
如果答案质量足够好，将其作为新页面归档到 wiki 中

最后一点至关重要——你的探索和提问不是一次性的消耗，而是持续增值的投资。每一次高质量的问答都会回流到知识库中，让它在下一次查询时更加丰富。

Karpathy 的研究 wiki 在单个主题上已经增长到 ~100 篇文章、~40 万词。令人惊讶的是，在这个规模下，他发现不需要花哨的 RAG——LLM 自动维护的索引文件和简要摘要，已经足够让它找到所有重要的相关数据。

操作三：Lint（质检）

定期对 wiki 进行"健康检查"：

矛盾检测：不同页面之间的数据冲突
过时标注：可能已经不准确的断言
孤立页面：没有任何入链的页面
缺失引用：应该存在但缺失的交叉引用
数据空白：知识库中缺失的重要概念
新文章建议：基于已有数据，发现值得深入探索的新方向

LLM 擅长的不只是回答问题，还包括提出问题。Lint 操作让知识库自我进化。

五、关键基础设施：索引与日志

index.md —— 知识的目录

这是 LLM 回答问题时首先读取的文件：

以类别组织的全局目录
每个页面附有链接、简要摘要和元数据
每次 Ingest 后自动更新

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


## 机器学习

- [Transformer 架构](concepts/transformer.md) — 自注意力机制的核心原理及变体
- [LoRA 微调](concepts/lora.md) — 低秩适应的参数高效微调方法
- [MoE 架构](concepts/moe.md) — 混合专家模型的路由策略和效率权衡

## 论文摘要

- [Attention Is All You Need](summaries/attention-paper.md) — Transformer 原始论文要点
- [LoRA Paper](summaries/lora-paper.md) — 低秩适应方法的理论基础

log.md —— 操作的时间线

一个**只追加（append-only）**的时间记录：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


## [2026-04-01] ingest | Attention Is All You Need
添加 Transformer 原始论文。新建概念页：transformer.md, self-attention.md。
更新：index.md, nlp-overview.md

## [2026-04-02] query | MoE vs Dense 的效率权衡
回答了关于 MoE 架构的查询，综合了 3 篇论文的观点。
输出归档为：analysis/moe-vs-dense.md

## [2026-04-03] lint | 健康检查
发现 2 个矛盾（transformer.md 与 attention-paper.md 的参数数量不一致），
标注 3 个孤立页面，建议新文章：positional-encoding.md

这个日志有两个作用：一是让你追踪知识库的演化历程，二是其一致的格式使得程序化解析成为可能。

六、工具生态

Obsidian：知识的可视化前端

Karpathy 使用 Obsidian 作为阅读和导航界面——不是用来写（写是 LLM 的事），而是用来看：

Graph View：以图谱形式展示所有文章的互链关系，一眼看到知识结构
实时渲染：LLM 在后台编辑 markdown 文件时，Obsidian 实时更新显示
反向链接面板：查看哪些页面引用了当前页面
Dataview 插件：查询 YAML frontmatter，生成动态表格

Marp：从知识到演示

Marp 是一个基于 markdown 的幻灯片工具。你可以让 LLM 从 wiki 中提取内容，直接生成演示文稿——知识到输出的转化链路极短。

QMD：本地搜索引擎

当知识库规模增大时，需要更精确的搜索。QMD 是 Shopify 创始人 Tobi Lutke 开发的本地 markdown 搜索引擎：

qmd search：BM25 全文关键词搜索（快速，无需模型）
qmd vsearch：语义向量搜索（找概念相关但无关键词重叠的内容）
qmd query：混合搜索 + LLM 重排序（最高质量）

所有处理在本地运行，支持 MCP Server 协议，可直接被 Claude Code 等 Agent 调用。

号称能实现 95%+ 的 token 节省——哲学是：与其把整个知识库塞进上下文窗口，不如精确搜索后只传递相关内容。

Git：时间机器

整个 wiki 就是一个 git 仓库。每一次 Ingest、Query、Lint 都产生可追踪的 diff。你可以：

用 git log 追踪知识的演化
用 git blame 追溯每一行的来源
用 git diff 查看每次操作的具体变更
随时回滚到任意历史状态

纯文本 + Git = 可移植、有版本控制、工具无关、面向未来。文件比应用活得更久。

七、为什么这套方法真的有效

Karpathy 给出了一个简洁有力的解释：

“维护知识库的枯燥部分不是阅读或思考——而是簿记。”

更新交叉引用、保持摘要最新、标注矛盾、维护一致性——这些工作是人类放弃维护 wiki 的根本原因。企业内部的 Confluence 为什么总是过时？个人的 Notion 笔记为什么半年后就成了废墟？因为维护成本太高。

LLM 解决了这个问题：

不会厌倦：更新 15 个页面的交叉引用对 LLM 来说和更新 1 个一样轻松
不会遗忘：每次 Ingest 都会检查所有相关页面
成本趋近于零：维护的边际成本几乎可以忽略
无限耐心：Lint 操作需要 N×N 的比较？没问题

人类负责有创造力的部分：选择什么值得读、提出什么问题、决定往什么方向深入。 LLM 负责一切机械性的簿记工作。

八、社区的尖锐争论

这条推文引发了激烈的讨论。支持者和批评者都提出了有价值的观点。

支持方

“每家企业都有一个 raw/ 目录，但没人编译过它。这就是产品。” —— 创业者 Vamshi Reddy 一语道破了商业潜力。

“这样你拥有记忆；在现有的平台部署中，拥有记忆的是平台。” —— TeMPOraL 指出了数据主权的关键优势。所有数据都是本地 markdown 文件，不依赖任何平台。

批评方：思考的摩擦力

最有哲学深度的批评来自知识管理社区。

Extended Brain 的一篇分析文章直接指出了**“思考的摩擦力”问题：Niklas Luhmann 的 Zettelkasten（卡片盒笔记法）之所以有效，是因为手动用自己的话重写想法这个动作本身就是思考的机制。当你写到一半写不下去的时候，那个卡壳的瞬间恰恰暴露了你理解上的空白——这种有价值的阻力**，是 LLM 生成的综合分析无法替代的。

Hacker News 的 qaadika 也提出了类似观点：

“正是在做这些事情的过程中，新想法才会涌现……我的许多洞见都来自于偶然看到一条笔记紧接着另一条笔记。”

批评方：幻觉污染

另一个实际的担忧：LLM 在生成 wiki 内容时可能引入幻觉，而这些幻觉会被后续的查询当作事实引用，形成幻觉的复利效应——不是知识在复利增长，而是错误在复利增长。

jdthedisciple 在 HN 上说：“我宁愿每次都引用原始文档，而不是一个我可能没时间去核实的 LLM 生成的 wiki。”

我的看法：两者不矛盾

这两种批评都有道理，但并不意味着 LLM Wiki 模式无价值。关键是找到正确的分工：

LLM 负责基础设施和地图：索引、交叉引用、摘要、矛盾标注
人类负责综合和思考：基于 LLM 的地图，做出自己的判断和创造
溯源机制不可省略：每一个 wiki 断言都应该能追溯到 raw/ 中的原始来源

社区中一些成熟的实现已经在解决这些问题：基于内容 hash 的新鲜度验证、propositions 级别的来源追踪、AI 生成内容和人类编写内容的明确标记等。

九、社区实践中沉淀的高级模式

Gist 的评论区和 HN 讨论中，实践者们贡献了不少有价值的改进模式：

1. 分类后再提取

不同类型的文档需要不同的处理策略——报告和信件的提取方式完全不同。先分类，再用对应的模板提取。

2. Token 预算分级

为索引设计四级上下文策略：

级别	内容	用途
L0	页面标题列表	快速概览
L1	标题 + 一句话摘要	定位相关页面
L2	完整摘要	深入了解
L3	全文	精确引用

LLM 根据查询复杂度选择合适的级别，避免要么读太少要么烧光上下文。

3. 类型化模板

使用基于实体类型的页面结构（人物模板、技术模板、论文模板），而非通用模板。这比自由格式能更好地维护一致性。

4. 决策记录

不只记录"知识变了什么"，还记录"为什么变"。当 wiki 页面被修改时，同时生成 decision record 记录推理过程和被否决的替代方案。

5. 隐私分层

敏感内容用本地模型（如 Ollama）处理，通用内容用云端模型（如 Claude）。这让机构级部署成为可能。

6. 规模瓶颈感知

纯 markdown 方案在 ~500 个文档 以内表现良好。超过这个规模，考虑引入 SQLite 存储元数据，或使用 QMD 等搜索工具辅助定位。

十、未来方向：从上下文到权重

Karpathy 在推文中提到了一个意味深长的方向：

“当知识库足够大时，自然会想到合成数据生成 + 微调，让 LLM 把数据’知道’在权重里，而非仅靠上下文窗口。”

这描述了一条完整的知识管道：

1

原始资料 → LLM 编译为 wiki → wiki 作为高质量训练数据 → 微调领域专用模型

一个维护良好的 wiki 本身就是高质量的合成训练数据——它结构化、有引用、有交叉验证、不断被 lint。这可能是通往个人化、领域化 LLM 的最自然路径。

加上上下文窗口的指数级增长（GPT-3 的 2K → Gemini 2.0 Pro 的 2M，1000 倍增长），“把整个 wiki 加载到单次上下文"的方式在当前规模下完全可行，无需向量数据库。

十一、动手实践：从零构建你的 LLM Wiki

理论说完了，下面是可执行、可落地、可见成效的实践路径。

阶段一：最小可行 Wiki（第 1-2 天）

目标：跑通完整的 Ingest → Query 循环，感受知识编译的效果。

具体步骤：

1
2
3


mkdir -p my-wiki/{raw,wiki,wiki/summaries,wiki/concepts}
cd my-wiki
git init

编写 Schema 文件

创建 CLAUDE.md（如果用 Claude Code）或等效的系统提示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# Wiki Schema

## 结构
- raw/: 原始资料，只读
- wiki/index.md: 全局目录，按类别组织
- wiki/log.md: 操作日志，只追加
- wiki/summaries/: 每个原始资料的摘要
- wiki/concepts/: 概念页面

## Ingest 工作流
当我说"ingest <文件>"时：
1. 阅读 raw/ 中的指定文件
2. 在 wiki/summaries/ 创建摘要页
3. 识别关键概念，创建或更新 wiki/concepts/ 中的概念页
4. 更新 wiki/index.md
5. 在 wiki/log.md 追加记录

## 页面格式
每个 .md 文件开头包含 YAML frontmatter：
- title, date, sources, related

采集 3-5 篇你感兴趣领域的文章到 raw/

可以用 Obsidian Web Clipper，也可以手动复制粘贴为 markdown。

逐个 Ingest

在 Claude Code（或你选择的 LLM Agent）中：

1

ingest raw/article-1.md

观察 LLM 如何创建摘要、识别概念、更新索引。

提一个需要跨文档综合的问题

1

这几篇文章在 XX 主题上有什么共识和分歧？

预期成果：3-5 篇原始资料 → 3-5 个摘要页 + 若干概念页 + 1 个索引 + 1 个日志。你会直观感受到"编译"和"检索"的区别。

阶段二：建立 Obsidian 工作流（第 3-5 天）

目标：让知识库可视化，建立高效的采集通道。

具体步骤：

用 Obsidian 打开 wiki 目录

安装 Obsidian，将 my-wiki/ 作为 Vault 打开
打开 Graph View，观察页面互链的图谱

安装关键插件

插件	用途
Obsidian Web Clipper	一键采集网页到 `raw/`
Dataview	动态查询 frontmatter 数据
Marp Slides	将 wiki 内容转为幻灯片

建立采集习惯

浏览到有价值的文章 → Web Clipper 保存到 raw/
下载相关图片到本地（Obsidian 快捷键）
定期（每天或每周）批量 Ingest

开始提问和归档

每次查询后评估答案质量
好的答案让 LLM 归档为新 wiki 页面

预期成果：原始资料增长到 10-20 篇，wiki 开始呈现有意义的图谱结构。

阶段三：引入 Lint 和工具链（第 2-3 周）

目标：让知识库自我进化，提升数据完整性。

具体步骤：

运行第一次 Lint

1
2
3
4
5


对整个 wiki 做一次健康检查：
- 找出页面之间的矛盾
- 标注可能过时的断言
- 列出缺失交叉引用的孤立页面
- 建议值得新增的概念页

安装 QMD（可选，当规模超过 50 篇时建议引入）

1
2
3


npm install -g @tobilu/qmd
qmd index wiki/
qmd search "你的查询"

建立定期维护节奏

每周一次 Lint
每次 Lint 后根据建议执行 2-3 个改进
追踪 log.md 的增长趋势

预期成果：wiki 开始自我修复和自我增强。你会发现 LLM 建议的新方向经常出乎意料地有价值。

阶段四：输出和复用（第 4 周+）

目标：让知识库产出实际价值。

具体场景：

写报告：让 LLM 基于 wiki 生成特定主题的分析报告
做演示：用 Marp 格式输出幻灯片
生成可视化：让 LLM 用 matplotlib 生成数据图表
回答复杂问题：wiki 越大，能回答的问题越复杂
发现盲区：通过 Lint 发现你知识体系中的空白

每一次输出都可以考虑归档回 wiki，形成正向循环。

进阶方向

当你的 wiki 稳定运行一个月以上，可以考虑：

多主题 Wiki：为不同研究方向建立独立的 wiki
MCP 集成：将 wiki 搜索暴露为 MCP Server，让其他 Agent 也能查询
自定义 CLI 工具：基于你的特定需求开发辅助脚本
微调实验：将 wiki 内容转化为 QA 对，微调一个领域专用的小模型

十二、总结

Karpathy 提出的不是一个工具，而是一个设计模式：

人类策展，LLM 编译——人负责选择、提问、思考；LLM 负责簿记、索引、维护
编译优于检索——知识编译一次、持续更新，而非每次查询都从零推导
复利效应——每一次 Ingest 和 Query 都让知识库变得更丰富
维护成本趋零——LLM 解决了 Bush 1945 年就发现的维护问题
纯文本哲学——Markdown + Git，可移植、有版本、面向未来

从 1945 年 Vannevar Bush 的 Memex 构想，到 2026 年 Karpathy 的 LLM Wiki 实践，人类花了 81 年找到了解决个人知识管理维护难题的方案。答案是：把维护交给不会厌倦的 LLM，把思考留给自己。

LLM on 鬼哥的空间

Skill 越多，Agent 为什么越容易犯选择困难？

Skill 不是“经验文档”，而是经验的蒸馏

它最擅长修的，是“会做但总忘”的问题

Skill 的反噬：它会让错误的假设更有执行力

Skill 库越大，难的不是保存，而是选择和适配

失败轨迹别急着扔，它们是 Skill 的边界说明书

给个人开发者的一条 Skill 维护规则

参考资料

Claude-Cookbooks 全景导航：被 README 藏起来的另一半

一、先把这份 repo 的定位搞清楚

二、一张总览图：20 多个目录怎么归类

三、基础能力层：Claude API 开箱即用能做什么

3.1 capabilities/ — 经典的 NLP 任务

3.2 multimodal/ — 视觉能力

3.3 extended_thinking/ — 让模型"想得更久"

四、Tool Use 专题：整个 cookbook 最密的一块

五、性能与成本优化

六、Agent 的三条进阶路径

6.1 模式层 patterns/agents/ — 先把套路搞清楚

6.2 SDK 层 claude_agent_sdk/ — 官方的 Agent 教程

6.3 托管层 managed_agents/ — Claude Managed Agents (CMA)

七、Skills 技能包

八、第三方集成一览

九、评估与微调

十、仓库工程实践：这本身就是一份"怎么管理 Notebook 项目"的样板

十一、我接下来会按什么顺序往里钻

结尾：这只是起点

参考资料

Prompt Caching 深度拆解：Claude Code 是如何做到 92% 命中率的

一、静态上下文 vs 动态上下文

二、KV Cache 到底在缓存什么

三、经济账

四、Claude Code 的 30 分钟实录

五、哈希缓存的脆弱性

六、应用到你自己的 Agent

七、Takeaways

参考资料

Claude Code Session 管理指南：1M 上下文是把双刃剑

Context、Compaction 和 Context Rot

每一轮对话结束后，都是一个分叉点

什么时候该开新 Session？

最值得养成的习惯：用 Rewind 代替纠正

Compact vs 新开 Session

什么导致了一次「坏 Compact」？

Subagent：独立上下文的子任务

最后

参考资料

Karpathy 的 LLM Wiki：用大模型编译知识，而不是检索知识

一、从 1945 年说起：Bush 的 Memex 构想

二、核心洞察：编译知识，而非检索知识

RAG 的根本问题

知识编译：一种新范式

关键区别：Wiki 是一个持续复利的知识制品

三、三层架构

第一层：Raw Sources（原始资料）

第二层：The Wiki（知识层）

第三层：The Schema（配置层）

四、三大核心操作

操作一：Ingest（摄入）

操作二：Query（查询）

操作三：Lint（质检）

五、关键基础设施：索引与日志

index.md —— 知识的目录

log.md —— 操作的时间线

六、工具生态

Obsidian：知识的可视化前端

Marp：从知识到演示

QMD：本地搜索引擎

Git：时间机器

七、为什么这套方法真的有效

八、社区的尖锐争论

支持方

批评方：思考的摩擦力

批评方：幻觉污染

我的看法：两者不矛盾

九、社区实践中沉淀的高级模式

1. 分类后再提取

2. Token 预算分级

3. 类型化模板

3.1 `capabilities/` — 经典的 NLP 任务

3.2 `multimodal/` — 视觉能力

3.3 `extended_thinking/` — 让模型"想得更久"

6.1 模式层 `patterns/agents/` — 先把套路搞清楚

6.2 SDK 层 `claude_agent_sdk/` — 官方的 Agent 教程

6.3 托管层 `managed_agents/` — Claude Managed Agents (CMA)