我现在日常开发几乎所有代码都是 Claude Code 或者 Codex 生成的。偶尔回头看看 git log，已经分不清哪些是自己写的哪些是 AI 写的了。

问题也跟着来了。代码量上去了，人的审查跟不上。以前一个 PR 三五百行，认真看半小时能看完。现在动不动几千行改动，而且 AI 生成的代码往往结构正确、命名规范、注释齐全，看起来挑不出毛病，但跑起来就是有各种问题。

那能不能让 AI 来做代码审查？AI 写的代码再让 AI 审一遍，听起来很合理。但 AI 审 AI 的代码，怎么保证不是互相糊弄呢？今天就来分享一下我自己摸索出来的一套方法。

质量门控是底线

不管有没有 AI，基本的质量门控都得有。Lint、类型检查、单元测试、集成测试、端到端测试，这些是所有代码合并的前提。AI 时代这些东西反而更重要了，因为 AI 写代码特别擅长绕过人的直觉，但很难绕过一个覆盖全面的测试套件。

所以，如果你的项目连这些基本的门控都没搭好的话，那就不要让 AI 上来就开始做功能开发，AI 编程的第一步应该是补上这个短板，打好质量门控这个基础。

有这些基础之后，再来看如何用 AI 审 AI 的代码。

把 PR 拉到本地，给 AI 完整上下文

我现在的做法是让 Agent 把 PR 代码拉取到一个独立的工作树里，避免影响我正在进行的其他工作。然后拿整个代码库作为上下文来做整体审查。

之所以这么做，是因为我之前踩过不少坑。最典型的是 GitHub Copilot 的审查功能，特别容易产生大量评论，一个 PR 能标出十几个“严重问题”。看起来每条都头头是道，分析得很有道理。但你要是真跟着它改了，就有可能把原来好好的代码改坏。

为什么？因为 AI 在“想办法说服你它是对的”这件事上，比大部分人都厉害。它能给你编出一套完美的推理链，解释为什么这行代码有问题，为什么应该按它说的改。但这个推理链可能建立在一个错误的假设上，而你纯靠看代码很难发现这个假设是错的。

所以光“看”是不够的。

验证比审查重要得多

纯靠看代码做审查，不管是人看还是 AI 看，都有一个根本性的局限：你只能发现你能想到的问题。

解决方案是给 Agent 一个真实的运行环境，让它把修改后的代码构建起来、实际跑起来，做一些真实场景的验证。不是在脑子里模拟“这段代码会不会出问题”，而是实际跑一遍看看结果。

这个思路和 Claude Code 团队的 Boris Cherny 最近说的完全一致。他提到现在 LLM 产生的问题跟以前不一样了，不太会犯人容易犯的低级问题，更多是系统设计、UI 可用性、缺少更广泛的上下文这类问题。这种问题纯靠看代码几乎不可能发现，但跑一遍就很容易发现。

他给了一个很简单的例子：只需要一行提示词，让 Agent 用动态工作流在模拟器里对每个边界情况做对抗式测试，或者直接用 Claude Code 内置的 /code-review。对抗式的审查比单纯“帮我看看有没有问题”要有效得多。

跑真实环境的两个副作用

不过，给 AI 真实环境做验证也带来了新问题。

第一个是安全。Claude Code 有内置的 /security-review，Codex 也有类似的安全扫描能力，直接用就行。安全问题往往藏在代码的交互边界上，比如输入校验、权限检查、敏感数据处理这些地方。人看代码的时候注意力容易放在业务逻辑上，反而是这种模式匹配的活儿 AI 更擅长。

第二个坑我踩了好多次：AI 在验证过程中会跟你本地的各种服务交互，然后它写审查评论或者 PR 描述的时候，特别喜欢“展示证据”，顺便把你本地的环境信息也带出去了。我经常碰到的就是 PR 里出现我本地 Kubernetes 集群的名字、命名空间、用户名之类的信息。比如 AI 会写“在 xxx-cluster 的 dev 命名空间跑了验证，发现 xxx 问题”。这种私有信息一定要避免推到公开仓库。

最好的办法是在审查流程的最后加一个单独的清理步骤，专门扫描 PR 内容里有没有内部环境信息、凭据、IP 地址这些不该出现的东西。

那还需要人干嘛？

AI 编程之后再让 AI 来审核，是不是就不需要人了？是不是就应该把所有程序员都开掉？

完全不是的。随着大模型变的越来越强大，部分编程问题的确是已经解决了，但编程并非全部。

需求梳理、系统设计、用户体验、安全策略、技术路径选择等等，还有很多方面需要人来把关。AI 能写出正确的代码，但不一定能写出合适的代码。“正确”和“合适”之间的差距，就是人的判断力存在的空间。

其实现在已经能看到大量 AI 生成的小项目和工具，看起来功能齐全、代码规范，但真正用起来根本解决不了实际问题。代码能跑不等于产品能用，很多只是在浪费算力。没有人去判断“该不该做”和“做成什么样”，AI 再能写代码也只是在批量生产垃圾。

不过说实话，“人应该把关哪些东西”这件事我自己也还没完全想清楚。发现需求和设计产品显然需要人，但 UI 可用性呢？特定场景的边界情况呢？这些东西现在靠人，未来是不是也能靠更好的约束来覆盖？我不确定。目前的做法就是先把能自动化的自动化掉，剩下的再说。

怎么开始？

Claude Code 的 /code-review 和 Codex 的审查命令是不错的起点。

我建议你在本地开发的时候尽量把它们用起来，每次改完代码提 PR 前先让它们审一遍。不需要什么复杂配置，直接用就行。Claude Code 还支持不同级别的审查深度，/code-review low、/code-review medium 之类的，可以根据改动的风险程度选择。

对于自动化的 AI 代码审查流程，我的建议是参考这些工具的实现，在它们的基础上加上前面提到的几个核心点：

1. 完整的代码库上下文，别只看变更 diff
2. 真实环境验证，代码要能构建跑起来
3. 安全扫描
4. 本地信息清理
5. 对抗式审查测试，主动找茬而不是被动检查

不同项目的环境准备和验证步骤都不一样，不要试图造一个大而全的通用方案。为每个项目构建独立的审查配置，把项目特有的约束写进去，让 AI 生成的代码必须通过这些约束才能合入，通不过就打回去让它自己修。

这个做法跟我之前在《烧了 20 亿 token 总结的 Codex 使用指南》里说的一样，验证比生成重要，审查配置比审查本身重要。

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

Claude Code、Codex CLI 这些 AI 编程工具满打满算也就发布了不到一年半。但就这一年多时间，我们写代码的方式彻底变了。手搓代码快成“非遗”了，一行一行手敲反而成了需要特别标注的“传统编程”。变化快到有点不太真实。

不过工具用得越多，问题也暴露得越明显。其中最让我难受的不是模型能力，而是 TUI 本身。

比如早期的 Claude Code 在长会话时很容易出现终端疯狂刷屏、整个屏幕闪烁、所有历史消息全部重绘这样的问题。会话越长闪得越严重。这个问题被用户吐槽了好几个月，Anthropic 后来做了全屏渲染模式来缓解，但回滚查看历史消息也比之前慢多了。

闪烁还只是表面现象。真正让我烦的是：跑复杂任务的时候，想回头看看之前某一步 Agent 到底做了什么决策，在终端里翻消息简直是噩梦。对简单任务无所谓，但复杂任务往往需要反复审查 Agent 的中间决策，判断它有没有走偏，这就麻烦了。

你在用的时候是不是也有这个感觉？反正我经常碰到。我最近几个月一直在用一个叫 Paseo 的多 Agent 控制台，完美解决了这个问题。用下来感觉不错，分享给你。

克制是 Paseo 最大的优点

多 Agent 编排早就不是新鲜事了，开源闭源都冒出来很多项目，比如 Multica、Orca、Mission Control、Paperclip 等等，GitHub 上随便一搜几十上百个。但大部分都有个共同的毛病，都想做自己的 Agent Harness。

自己造 Harness 意味着什么？你的 CLAUDE.md 不生效了，Skills 读不了了，积累的配置和记忆也全部作废了。得在一个全新环境里从零开始教 Agent 干活。我之前试过几个类似的工具，对我用的 memory 格式支持都不好，老是要返工，甚至之前一两个小时的工作它能给我来来回回搞上一天，无奈最后还是回到了 Claude Code。

Paseo 则很克制，原生支持 Claude Code、Codex、OpenCode、Pi，再加上各种 ACP，主流的 Agent 它都可以接入。 Paseo 没有试图替代任何一个。你在 Paseo 里跑 Claude Code，底层就是 Claude Code 本身。CLAUDE.md、Skills、Hooks、MCP servers、memory 全都在，一个不少。说白了就是给 Agent 套了一层更直观易用的壳，灵魂还都原始保留着。

这种克制在当前这个赛道里反而成了最大的优点。切过来零成本，不喜欢随时切回去。

TUI 的问题它都解决了

Paseo 完美解决了 TUI 的两大问题：

第一个是消息过滤。Paseo 可以把 Agent 的输出分成不同视图：只看消息、只看关键输出、只看工具调用、或者全部展开。TUI 把所有东西混在一条流里往下刷，要么全看要么全不看。能分层看这件事听起来简单，用过之后就回不去了。

第二个是多 Agent 并行和跨 Provider 编排。你可以同时开几个 Agent，一个用 Claude Code 的 Opus 做架构设计，另一个用 Codex 跑实现。关键是 Paseo 的子 Agent 能跨 Provider 调度：Claude Code 可以把任务派给 Codex，Codex 也可以把任务派给 Grok，这在各家原生的多 Agent 方案里是做不到的。

它还有几个内置 Skills 挺实用。/paseo-handoff 在不同 Agent 之间交接任务，比如先用 Claude 做规划然后 handoff 给 Codex 去实现。/paseo-loop 循环跑一个 Agent 直到满足验收条件，还可以配一个 verifier。/paseo-committee 拉两个不同的 Agent 组成委员会做根因分析。另外还有 heartbeat 功能，可以让 Agent 定时检查 CI 状态，失败了自动修，通过了自动停。

手机不是用来写代码的

Paseo 支持 iOS、Android、桌面端和网页端，覆盖面在同类工具里算最全的。

不过手机端的价值不是让你在手机上写代码，而是监控和介入。Agent 跑长任务的时候不用一直盯着电脑，出门掏出手机看一眼进度，Agent 遇到需要确认的问题直接在手机上回复就行。它还有语音模式，可以直接用语音给 Agent 布置任务或者讨论问题，走路的时候不用掏手机打字。

其实 Paseo 这个名字就说明了设计意图。Paseo 是西班牙语里“散步”的意思。作者 Mo Boudra 之前遛弯的时候总是得 SSH 到 tmux 里查看 Agent 状态，太折腾了，于是做了这个工具。一个人从头写到尾，GitHub 上 12,000 多个 Star 全是他一个独立开发者撑起来的。

安全方面，设备之间通过端到端加密的 relay 配对。Agent 始终在你自己的机器上跑，没有遥测，没有追踪，也不需要登录。

部署在服务器上，随时随地连

Paseo 最实用的部署方式是跑在开发机或远程服务器上，然后从任何设备连过来操作。

桌面端最简单，从 paseo.sh/download 下载，打开之后 daemon 自动启动。手机配对在设置里扫个码就行。

远程服务器用 Docker：

docker run -d --name paseo\ -p 6767:6767\ -e PASEO_PASSWORD=your-password\ -v"$PWD/paseo-home:/home/paseo"\ -v"$PWD:/workspace"\ ghcr.io/getpaseo/paseo:latest

启动后访问http://your-server:6767 就是完整的 Web 界面。手机 App 连这个地址，就可以在任何地方操作服务器上的 Agent 了。服务器不在公网的话，可以用 Tailscale 或者 Paseo 自带的 relay 做穿透，relay 走端到端加密，不需要开端口。

前提是服务器上要装好对应的 Agent CLI。Paseo 是编排层，不包含 Agent 本身，Docker 镜像里自己加装就行。

写在最后

Paseo 还在 beta 阶段，有些粗糙的地方。移动端侧边栏滑动手势偶尔失灵，终端在手机上的输入体验还在打磨。WebSocket 连接在 Cloudflare relay 上大概 100 秒不活跃会断开，长时间挂着需要注意。

另外 Paseo 上手门槛不低，你得先有自己的 Agent CLI 环境，它也不帮你管理 Agent 环境。不过换个角度想，这恰恰是它克制的体现。不做自己不该做的事。

在一个所有人都想做 Agent Harness 的市场里，Paseo 选择不造引擎。它不跟 Claude Code 和 Codex 竞争，它让你同时用好它们。这种思路在我看来是对的。

当然，如果你不需要远程访问和多 Agent 跨 Provider 编排，只是单纯想在本机上有个比 TUI 更舒服的界面，Claude Desktop 和 Codex App 也都是不错的选择。它们各自对自家 Agent 的集成更深，开箱即用，不需要额外部署 daemon。Paseo 的优势在跨 Agent 和跨设备这两个场景上，如果你同时用多个 Agent 或者经常需要远程操作，它才是更合适的选择。

项目地址：https://github.com/getpaseo/paseo

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

题记：本文编译自 Anthropic 工程博客《Steering Claude Code: skills, hooks, subagents and more》，原文链接：https://www.anthropic.com/engineering/claude-code-best-practices。本文在翻译基础上做了整理和补充。

在使用 Claude Code 时，我的 CLAUDE.md 曾经写到几千行。项目规范、参考约定、编码风格、部署流程，还有日常开发中碰到的各种坑，全往里面塞。CLAUDE.md 的内容越来越丰富，Claude Code 也越来越好用。直到有一天我发现 Claude Code 开始选择性忽略某些指令，才反应过来，它的上下文太长了，它已经不能很好地遵循 CLAUDE.md 定义的各种规则了。

你是不是也碰到过类似的情况？明明写了“所有修改必须跑完整 e2e 测试”，结果只跑了一个单元测试就停了，需要你反复提示才执行。

我在这个问题上卡了很久，一度怀疑是 Claude 模型又降智了，后来才发现根本原因是上下文膨胀。把所有东西都塞进了 CLAUDE.md，这本身就是用错了 AI 工具。

Anthropic 最近发了一篇官方指南，系统梳理了提示 Claude Code 的 7 种方法和它们的实现原理。我之前踩过的很多坑，根因都是没搞清楚每种方法的加载时机和上下文成本。

下面是我对这篇指南的编译和解读，每一节加了自己的使用经验。

CLAUDE.md：写得越多，质量越差

CLAUDE.md 是使用 Claude Code 所必需的第一步，所以也就成了大家最先接触、也是最容易写过头的配置方法。它在 Claude Code 会话启动时就加载，全程驻留在上下文空间中。

不过这里有个容易忽略的设计：CLAUDE.md 的写法其实分两种。

第一种，放在项目根目录的 CLAUDE.md 每次会话都加载，压缩后会被重新读取。适合放构建命令、目录结构、团队硬性约定这些 Claude 需要始终知道的信息。

第二种，子目录的 CLAUDE.md（比如app/api/CLAUDE.md）只在 Claude 读到该目录下的文件时才加载。离开这个目录，这些指令就不在上下文里了。

Anthropic 给的建议是：根 CLAUDE.md 控制在 200 行以内，给它一个 owner，像审查代码一样审查对它的修改。

这件事在团队协作的大仓库里尤其明显。CLAUDE.md 很容易变成一个没人维护的公共配置文件，每个组都往里加自己的规范，没人删旧的。

最终每个工程师的每次会话都要加载所有团队的规范，不管跟当前任务有没有关系。

要解决也很简单，在 monorepo 里给每个团队目录配置单独的 CLAUDE.md，让团队只加载自己的规范。还可以用claudeMdExcludes 跳过不相关团队的文件。

总结起来一句话，不要把 CLAUDE.md 当成垃圾桶，而是寸土寸金的黄金地段。能不放的，就别放。

Rules：按路径触发，不白占上下文

Rules 是.claude/rules/ 目录下的 Markdown 文件。

不带路径限定的 Rule 跟根 CLAUDE.md 行为一样：每次会话都会加载、会话压缩后也会重新注入。其实本质上就是换了个目录放的 CLAUDE.md 内容。

真正有意思的是带路径限定的 Rule。给 Rule 加一个paths 字段，它就只在 Claude 碰到匹配路径的文件时才加载：

---paths: -"src/api/**" -"**/*.handler.ts"---所有 API handler 必须用 Zod 校验输入参数.

这条规则在你改文档的时候完全不占上下文，只有碰到 API 相关代码才会出现。

所以，凡是只对特定目录或文件类型生效的约束，都应该用 path-scoped Rule，而不是写在 CLAUDE.md 里。这是控制上下文膨胀最直接的手段。

什么时候用 Rule 而不是子目录 CLAUDE.md？当一个约束是跨目录的。比如“所有.handler.ts 文件都要校验输入”，它可能散布在多个目录下，放某一个目录的 CLAUDE.md 里不合适。

Skills：按需加载，用完即走

Skills 住在.claude/skills/ 目录里，每个 Skill 是一个文件夹，核心是一个SKILL.md 文件，里面包含了名称、描述和正文。

Skills 最关键的一个设计时只有名称和描述在会话启动时加载，正文只有在被调用时才进入上下文。

它的调用方式有两种：通过斜杠命令（比如/code-review），或者 Claude 根据任务自动匹配。

在使用 Skills 的时候，也需要注意会话压缩的行为：压缩时，已调用的 Skills 会被重新注入，但所有 Skills 共享一个总 token 预算。一次会话里调用太多 Skills，最早调用的会被丢掉。

Anthropic 给的原则是：流程性的东西放 Skill，不要放 CLAUDE.md。部署流程、发布检查清单、代码审查规范，这些都应该是 Skill。CLAUDE.md 只放 Claude 需要始终知道的事实。

我自己的经历可也是如此。之前 CLAUDE.md 里写了一大段“发布+验证流程”，后来拆成 Skill，不发布的时候这些指令就不占空间了。省下来的上下文让 Claude 能记住更多真正相关的事情。

Subagents：不是多一个帮手，是多一块白板

Subagents 是.claude/agents/ 目录下的 Markdown 文件，用 YAML frontmatter 定义名称、描述和工具权限，正文是这个子 Agent 的系统提示词。

名称、描述和工具列表在会话启动时加载。但正文永远不会进入主会话的上下文，它在子 Agent 自己的独立上下文窗口里运行，只有最终的摘要消息回到主会话。

这个设计对上下文管理的意义挺大的。Subagent 可以嵌套最多 5 层，动态工作流可以编排几十甚至上百个后台 Agent。中间结果全在脚本变量里，不污染主上下文。

那 Skill 和 Subagent 怎么选？Anthropic 给的判断标准是这样的：

• 用 Skill：当你希望流程在主线程里执行，你能看到每一步、随时干预。
• 用 Subagent：当侧任务的中间结果你不需要再看（深度搜索、日志分析、依赖审计），只需要一个最终摘要。

说白了，Subagent 的核心价值不是“多一个 Agent”，而是上下文隔离。让主会话保持干净，不被旁支任务的中间过程淹没。

我自己用 Subagent 最多的场景有两个：一个是让它先 explore 整个代码库，写一份结构报告回来，主 Agent 拿着报告再动手改代码；另一个是设计和实现分离，设计时需要进行大量的调研工作，但实现的时候只需要设计文档就足够了。

Hooks：让 Claude Code 100% 执行

Hooks 是在 Claude Code 生命周期事件上触发的用户定义命令。注册在settings.json 里，在文件编辑、工具调用、会话启动等事件上自动触发。

Hook 有五种类型：command、HTTP、mcp_tool、prompt 和 agent。前三种确定性执行（跑脚本、发请求、调工具），后两种用模型判断来决定输出。

Hooks 的上下文成本极低，配置在主上下文窗口外面，harness 直接执行。只有少数 Hook 的输出会回到主上下文（比如阻断型 Hook 的错误信息，让 Claude Code 知道为什么被拒绝）。

Hooks 在整套 Claude Code 体系里最容易被忽略但最重要的一点是：

“每次 X 都必须做 Y” 如果放在 CLAUDE.md 里，本质上是在靠模型的遵从性来保证执行。模型大多数时候会遵守，但在长会话、上下文压力大、或者遇到 prompt injection 的时候，它可以不遵守。

想要确定性执行，必须用 Hook。比如“每次编辑后跑 prettier”，这不该是一条指令让 Claude Code 选择执行，而应该是一个PostToolUse Hook 在每次文件写入后自动触发。

同理，“绝对不能做 X” 这种约束也不该靠 CLAUDE.md。用PreToolUse Hook 检查调用，exit code 2 直接阻断。对企业来说，更严格的配置可以用 Managed Settings，管理员部署、用户不可覆盖。

所以，你要注意，凡是在 CLAUDE.md 里写了“必须”或“绝对不能”的规则，都别忘了问自己一句：这条规则失败了会怎样？如果后果严重，就赶紧改成 Hook。

Output Styles 和 append-system-prompt：慎用，杀伤力大

最后两种方法放在一起说，它们都作用在系统提示词层面，威力大但副作用也大。

Output Styles 是.claude/output-styles/ 目录下的文件，注入系统提示词，永不压缩。注意一个关键细节：自定义 Output Style 默认会替换 Claude Code 的默认系统提示词，除非在 frontmatter 里设置keep-coding-instructions: true。

换句话说，一旦用了自定义 Output Style，Claude Code 默认的那些行为指导（怎么控制变更范围、什么时候加注释、安全关注点、跑测试再报完工）全部会被覆盖。Claude Code 就从一个软件工程助手变成一个通用助手了。

所以 Anthropic 的建议是：先看看内置的 Proactive、Explanatory、Learning 三个样式够不够用，再考虑自定义。

append-system-prompt 是另一种用法，它是 CLI 启动时传入的 flag，只对当前会话生效，不会持久化。它是纯追加的，不会替换默认行为，一般适合临时加一些格式偏好或领域知识。

我觉得大多数人不需要碰 Output Styles。内置样式加上 CLAUDE.md 已经够用了，除非你真的要把 Claude Code 改造成一个完全不同的角色。

别踩这些坑

最后整理一下 Anthropic 给的“反模式”清单，基本都是我自己踩过或见过别人踩的：

第一个是把“每次 X 都必须做 Y” 这种强制性约束写在 CLAUDE.md 里。模型的指令遵循和代码自动执行是两回事。如果这个行为必须可靠发生，一定要用 Hook。同理，“绝对不能做 X” 也不该靠 CLAUDE.md，禁止性约束在 prompt injection 面前毫无抵抗力，要用 Hook 或 Managed Settings 做墙纸约束。

第二个是把流程放在 CLAUDE.md 里面。CLAUDE.md 应该只放 Claude Code 需要始终知道的事实以及它最常犯的一些错误的经验教训，而流程则放到 Skills 里面。

第三个是 Rule 不加 paths。一条只对src/api/ 生效的规则如果不加路径限定，效果等同于在 CLAUDE.md 里多了一行，每次都加载，每次都耗 token。个人偏好也是同样的道理，所有的配置方法都分为项目级和用户级，“永远用 semantic commit message” 这种个人习惯应该只放在本地，项目级只放团队共识。

速查表：7 种方法一览

这张表最有价值的一列是“上下文成本”。搞清楚哪些指令需要全程驻留、哪些只在触发时加载，是用好这套系统的关键。

写在最后

说实话，这篇官方指南没介绍什么新功能，这 7 种方法早就存在了。但它的价值在于第一次把每种方法的加载时机、压缩行为和上下文成本都讲清楚了。

这 7 种方法按 harness 设计的思路大致可以整理成为四层：

• 全局层（CLAUDE.md、unscoped Rules、Output Styles）：高成本、高权威，克制使用
• 触发层（path-scoped Rules、子目录 CLAUDE.md、Skills）：按需加载，中低成本
• 隔离层（Subagents）：零主上下文成本，只关注结果
• 确定性层（Hooks）：绕过模型，代码级保证

搞清楚这四层，大部分“Claude 为什么忽略我的指令”的问题就有了答案。不是模型不听话，是你把指令放在了错误的层级，或者上下文爆满之后它被忽略掉了。

我推荐的实践顺序是这样的：所有项目第一步先给根 CLAUDE.md 瘦身，拆出去的流程丢进 Skills，跨目录的约束用 path-scoped Rules，必须 100% 执行的规则用 Hooks 做约束。然后在日常使用中持续观察、持续迭代修改，如果发现有的指令被忽略了，那大概率是相关的指令放错了层级。

上下文窗口就那么大，每一行指令都有成本。把对的指令放在对的层级，比写更多指令管用得多。

原文：Steering Claude Code: skills, hooks, subagents and morehttps://www.anthropic.com/engineering/claude-code-best-practices

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

Codex 桌面版最近口碑爆了。我自己已经把很多工作都切到了 Codex 客户端的 Goal + GPT-5.5 上，一不小心就用了 20 多亿 token。

不过很多人第一次用 Codex，还是把它当一个更强的 coding agent，用来读仓库、改代码、跑测试、写 PR。这当然没错，Codex 的基本功能确实还是代码编程。但它的桌面客户端已经不只是编程工具了。Skills、Computer Use、浏览器操控、Gmail 和 Calendar 等等各种连接器和插件一路加上来，早就成了一个通用 Agent 客户端。甚至你还可以通过 ~/.codex/config.toml 配置文件给它接入 DeepSeek、Kimi 等第三方模型。

我让 Codex 扫了一下最近这个月的会话历史，总结了一些日常的使用方法，再加上自己的补充，整理成这篇分享给大家。如果你还不熟悉 Codex 桌面客户端的使用方法，可以参考 Jason Liu 最近写的 Getting the most out of Codex 文章（链接见文章最后），今天的文章假设你已经了解了 Codex 的基本用法。

1. 先给足上下文，再开始任务

AI Agent 最大的问题不是不会干活，而是太容易基于幻觉自信乱干。你不告诉它项目背景和规则，它就按自己的理解来，很容易过度自信，走向错误的方向。

要解决也很简单，写一个 AGENTS.md 放在项目根目录。Codex 每次打开项目会自动读这个文件，里面可以写项目背景、技术栈、代码规范、常见坑、测试方式，相当于给它一份新人上岗须知。如果任务涉及特定模块，还可以在 prompt 里直接指定“先读 docs/xxx.md 再动手”，让它从文档而不是从猜测开始。

Codex 桌面端有个置顶会话挺好用的，你可以把最常使用的会话固定在前面。不要把 Codex 的会话当成临时会话，而是一个持续的工作现场。Codex 已经能够自动帮你压缩会话上下文，再加上它的记忆功能，长时任务不需要新开会话，可以持续在同一个会话里持续下去。

这也是我觉得 Codex 最好用的一点，避免了很多上下文交接的问题，可以真正帮你干大活了。

2. 验证比生成重要得多

说实话，让 Codex 写代码，随便一个 coding agent 都能做个七八成。真正拉开差距的是验证，要拿真实的验证结果说话。

验证可以是很多东西：测试套件、benchmark、Web 界面截图、发布前 checklist 等等，也就是之前你自己手动做的所有操作应该都描述清楚，交给 Codex 让它去负责。

特别是在用 Goal 跑长任务的时候，这点更是必不可少。比如，“帮我把这个计划实现完” 看起来有目标，但其实病没有明确的停止条件。而好的 Goal 应该带上清晰的验证器：“完成后必须通过 xx 测试、浏览器检查和人工可审阅的变更摘要。如果验证失败，先修验证失败的问题，不要直接宣布完成。”

没有验证的 Goal，其实只是愿望。

3. 批量操作前加一道审查门

从我自己的使用历史来看，审查和清理类任务最容易翻车。Codex 默认倾向是搜到了就改，找到了就删。这时候，你需要主动在提示词里面拦一下。

具体做法是在 prompt 或 AGENTS.md 里加上审查规则。比如“批量修改前先列出所有命中并按类型分组（需要改 / 可能需要改 / 不该动），等我确认再执行”。清理旧分支也一样：“先输出 merged 和 unmerged 分支对比，标注哪些旧实现已被 main 覆盖，不要直接删”。

举个例子，代码库里搜到一堆旧 token 引用，不是所有命中都该删。有些是测试隔离需要的，有些是运行时继承的，真正有问题的可能只有几个。如果不加审查这道程序，Codex 可能会机械地全部清掉，然后测试挂一片（针对这个例子，加上上一步说的验证其实可以自动修复回来，但会浪费很多时间+token）。

这种不是高大上的 AI 能力，但特别体现人的判断，需要你把经常看到的坑告诉 AI，让它去主动规避。

4. 先配工具，再谈智能

模型当然重要，但真正决定 AI 能干什么的，是配置的工具、权限、上下文和验证方式。插件决定 Codex 能碰到哪些外部世界，Skills 决定它碰到这些世界时该怎么做。我自己常用的插件和 Skills 列在了文末附录里，这里只说一个最容易被忽略的点。

大多数人写 Skill，会把它当成说明文档：告诉 Codex 该做什么、按什么顺序做。这当然有用，但 Skill 真正值钱的部分不是流程，而是 Gotchas，也就是每次 Codex 犯错之后补进去的“别踩这个坑”。

比如：

• 这个数据源经常不可用，不要猜。
• 这个任务结束前必须跑某个验证。
• 这个工具第一次会失败，失败后应该换另一种方式。
• 这个类型的 review 不能机械接受，要逐条验证。
• 这个工作流适合先搜宽一点，再只打开高价值候选。

一开始写个十几行骨架就够了，用一段时间后它自然会长成一个成熟 Skill。好用的 Skill 不可能一次写好的，都是拿实际经验养出来的。

5. 用 Side Panel 边看边改

以前用 AI 做文档、网页、PPT，最烦的是上下文切来切去。AI 在聊天框里生成，产物在另一个窗口打开，发现问题又要截图回来描述。来回几次，人和 AI 都开始丢上下文。

Codex 的 Side Panel 可以把产物留在工作流里直接改。具体做法是：让 Codex 生成一个 index.html 或者打开一个 localhost 页面，它会在侧边栏渲染出来。你一边看渲染结果，一边在同一个线程里说“这个按钮太大了”“表格第三列数据不对”，不用截图，不用切窗口。

有两类任务特别适合这个场景。一类是前端和网页，直接在旁边检查样式、交互和移动端适配。另一类是文档型产物，报告、表格、PPT、数据分析页面放在旁边边看边改，比导出再反馈高效得多。

6. 重要上下文写到文件里

会话会压缩，模型可能会切换，对话里的重要决策和验证方式如果不主动写到外部文件里，就很容易会被丢掉。

我自己在做长任务的时候（特别是那种跨天的任务），会特意让 Codex 总结记录下 summary、checkpoint、handoff 文档和下次接手的入口说明。下一个会话或者新任务可以接着这些文件继续，不用从零开始。

要实现也很容易，不需要搞复杂的记忆系统。一个 TODO.md 写待办事项，再加几个文件夹分类放踩坑记录和项目状态，就够了。关键是可检查、可编辑、可删除。Codex 内置的 Memory 和 Chronicle 可以当快速回忆层用，但替代不了外部文件。只有写进文件里的记忆，才有机会变成系统。

7. 随时在线，随处接管

长任务跑着的时候，你不需要一直坐在电脑前。在 ChatGPT 手机端连上你的 Mac 或远程机器，可以随时给远端的 Codex 下任务，或者回复 Codex 需要你介入的问题。

一般来说，当你把任务定义清楚之后，就可以通过 Goal 来启动长时任务，然后等着 Codex 的通知就可以了。你可以在手机上随时能看到它的输出、审批命令、中途纠偏。不用坐在电脑面前盯着，同时关键决策又可以随时介入。

如果你有 Linux 服务器，Remote SSH 更值得配一下。Codex 会自动读取本地 SSH config 里的主机列表，连上之后直接在远程服务器里跑任务。日常运维、配置管理、代码部署，SSH 连上就能让 Codex 干活，电脑端/手机端都可以随时跟进。配合前面说的 AGENTS.md 和文件记忆，远程接入的时候上下文还在，不用重新交代背景。

8. 定时自动化：让会话自己醒过来

前面说的远程接入是“你主动去给 AI 下发任务”，而定时自动化是“让 AI 主动来找你”。

具体做法是给置顶线程设一个 Thread Automation。跟普通定时任务不同，Thread Automation 每次触发会回到同一个线程，带着上次的上下文继续工作。它知道上次检查到了哪里，哪些事项已经处理过，哪些数据源接不上。

我自己用得比较多的是两类。一类是信息聚合：每天早上自动检查未读邮件和 IM 消息，按优先级整理好，等我打开的时候直接看结论。另一类是监控类：定期检查 PR 列表、问题反馈或者关注列表，有新内容就整理摘要，没有就不打扰。

这儿有一点需要注意的是不要让自动化假装全知。没有就是没有，不要编造虚假信息；依赖不可用就直接报不可用，不要自作聪明。

9. 不只是代码：邮件、调研、文档也能跑

文章到这里，其实大部分的场景还都是跟代码相关的。但 Codex 桌面客户端接上 Gmail、Browser、Documents 这些插件之后，很多非代码任务也都能跑的不错。

我自己用得比较多的几个场景：让 Codex 过一遍项目和相关邮件，做图文并茂的汇报 PPT；给一个调研主题，让它用 deep-research 搜多个来源，整理成带出处的摘要；会议前把相关文档和之前的讨论丢给它，让它准备一份简要；写完公众号文章后让它排版成微信公众号格式并生成封面图。

这些任务的共同点是：以前要在好几个工具之间切来切去，现在可以在一个会话里串起来，省掉了大量的不同工具和上下文切换。

10. 别追求全自动，要把主动权留在人的手里

Codex 好用，也可以自动化很多任务，但并不意味着你就要完全放手让它全自动去自己玩。

恰恰相反，你越把它接进真实工作流，越会看到很多边缘问题：权限、登录态、数据源缺口、工具失败、上下文压缩、验证不充分、自动化误触发等等。

所以更合理的用法是：让 Codex 做上下文收集、执行、验证和初步整理，人保留判断、授权和最终责任。Codex 的 Steering（中途纠偏）和 Queuing（排队追加下一步）就是为这个设计的。真实的工作往往都是边看边改、边发现边调整，不是“人给一个完美需求，让 AI 一次性完成”。

也就是说，人不应该退到系统外面，而是站在系统里面，负责纠偏、验收和更新规则。

Codex 的语音输入也是一个让人留在 loop 里很好的设计。它不是让你口述代码的，而是在想法还没成型的时候随时输入给 Codex，或者在 Codex 走偏的时候随时修正它。语音输入不需要很完整，有错别字啥的都没关系，模糊指令对一个已经掌握足够上下文的 AI 来说已经足够让它理解你的意图。

相关链接：

• Jason Liu Getting the most out of Codex：https://x.com/jxnlco/status/2057153744630890620
• Codex 功能文档：https://developers.openai.com/codex/app/features/
• Codex Skills 文档：https://developers.openai.com/codex/skills

附录：我常用的插件和 Skills

以下是文中第 4 条提到的工具清单，供参考。

常用插件：

• Browser：本地网页、localhost、侧边栏里的页面检查和截图。
• Chrome：需要登录态、真实 Chrome profile、远程网页操作时用。
• Computer Use：只能通过桌面 GUI 完成的工作。
• Gmail：搜索邮件、读取正文、筛选待办、草拟回复。
• Documents / Presentations / Spreadsheets：文档、PPT、表格类 artifact。
• Product Design：早期产品想法、原型、截图到交互稿。
• Build Web Apps：前端应用、组件、浏览器验证。
• HyperFrames / Remotion：视频、动画、程序化内容。
• Superpowers：计划、TDD、系统化调试、验证、代码 review、开发分支收尾。
• Codex Security：安全扫描、威胁建模、finding 修复。

常用 Skills：

• brainstorming（Superpowers 插件自带）：头脑风暴和 SPEC 设计。
• handoff：将当前对话整理成交接文档（用于新开会话接手）。
• deep-research：多源搜索调研。
• claude-skill：调用 Claude Code 写文档、做设计或者跟 Codex PK。
• twitter-cli / xfetch：读取和搜索 X/Twitter 内容。
• xiaohongshu-cli：搜小红书内容。
• youtube-transcribe-skill：解析下载 Youtube 视频字幕。

相关 Skills 的安装方法：

npx -y skills add mattpocock/skills -g -s handoffnpx -y skills add feiskyer/codex-settings -g -s claude-skillnpx -y skills add feiskyer/codex-settings -g -s deep-researchnpx -y skills add feiskyer/codex-settings -g -s youtube-transcribe-skill

几个 CLI 工具的安装方法：

uv tool install xiaohongshu-cli twitter-cli
npm install -g xfetch-cli

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

题记：本文编译自 Anthropic 工程团队官方博客《How Claude Code Works in Large Codebases: Best Practices and Where to Start》，原文链接：https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start。本文在翻译基础上做了整理和补充。

Claude Code 在小项目里用着真挺丝滑的，基本上你碰到的问题它都能帮你解决。

不过一旦搬到大代码库，体验就开始打折扣。让它查找一个函数，grep 出来上千条匹配，你的上下文空间直接就被淹没了；改一个子服务，它非要跑全项目的测试用例，跑就跑吧还动不动超时偷懒，有时甚至自作聪明顺手改了一堆不该改的代码。

你在大型代码库里使用 Claude Code 是不是也碰到过这些问题？反正我是经常碰到。

前两天 Anthropic 工程团队发了一篇官方博客 How Claude Code Works in Large Codebases: Best Practices and Where to Start），系统讲解了大型代码仓库中用好 Claude Code 的方法论，推荐所有 Claude Code 用户都读一读。

下面是逐节的翻译，每一节我加上了自己的注解。

一、Claude Code 是怎么浏览代码的

Anthropic 博客一开头就讲了一个容易被忽略的事实：Claude Code 在大代码库里搜代码的方式，跟我们一直理解的 RAG 方式是完全不同的思路。

RAG 的做法是把整个代码库做 embedding，查询时检索相关片段。听起来挺合理的，但在大代码库里有个死结：embedding 流程追不上工程团队的提交速度。等你查询的时候，索引反映的是几天甚至几周前的代码，搜出来的可能是已经被重命名的函数，或者已经被删掉的模块。

Claude Code 走的是另一条路，叫 agentic search。它就像一个工程师那样找代码：遍历文件系统、读文件、grep 关键字、跟着 reference 跳转。所有动作都是实时的，不依赖任何索引。

这个差异不是技术孰优孰劣，而是适用场景不同。小到中型、变化没那么频繁的代码库，RAG 可能更快。但大代码库、活跃项目、频繁重构这些场景，agentic 是唯一靠谱的方式。

要用好 agentic search 也有它的前提：你的代码库得让 Claude Code 快速定位到具体的位置。如果目录命名混乱、没有 README、没有任何线索告诉它从哪开始看，再聪明的模型也得绕远路遍历大量无关文件，导致上下文空间被白白浪费。后面 Anthropic 讲的所有最佳实践，本质都是在解决这个问题。

二、harness 比模型更重要

Anthropic 在原文里给了一个清单，列出了塑造 Claude Code 能力的 harness 七件套：

• CLAUDE.md
• Hooks
• Skills
• Plugins
• LSP
• MCP servers
• Subagents

这七件套加起来，决定了同样的模型在你手里跑出来是什么效果。

我自己的体验跟这个清单完全一致。同样是 Claude Opus 4.6 模型，裸装 Claude Code 写代码，跟调好 CLAUDE.md 、装备 subagent 、配上 skills 之后相比，效果不是一个量级的。

这跟之前 Anthropic 在 Harness 设计那篇文章（《为什么单 Agent 搞不定复杂应用》）里讲的逻辑是一致的：模型能力决定了天花板，harness 决定了你能走到天花板的多少。差的 harness 把模型能力浪费一大半都不夸张。

下面把这七件套一个一个聊聊。

三、CLAUDE.md：分层是最大的杠杆

CLAUDE.md 是每个会话启动时自动加载的上下文文件。Claude Code 会从当前目录往上一直走到根目录，把每一层的 CLAUDE.md 都读进来。

这个加载机制是叠加的，所以分层非常关键。Anthropic 给的原则是：根 CLAUDE.md 只放指针和关键注意事项。

Anthropic 还给了几条特实用的具体建议：

第一，给子目录创建 CLAUDE.md，而不是只是在根目录里。Claude 自动会往上走，所以你启动它的时候 cd 到任务相关的子目录，加载到的上下文最聚焦。

第二，lint 和 test 命令按子目录配置。改一个子服务却跑全项目的 test，是大代码库里最常见的浪费。耗时耗力不说，跑出来的输出信息还容易把 context 全淹了。子目录的 CLAUDE.md 应该写清楚“在这个目录下，跑测试用 X，跑 lint 用 Y”。

第三，用.ignore 文件（ripgrep 的标准 ignore 格式）排除生成目录、build 产物、第三方代码这些噪音，同时把permissions.deny 规则写到.claude/settings.json 里。后者会跟着 git 一起 commit 出去，团队每个人都自动生效，不用各自配。如果某些开发者就是要碰生成目录，可以在自己的本地 settings 里覆盖项目级规则，不影响其他人。

第四，如果你的代码库就是没有传统目录结构，那写一个 codebase map：根目录放一个简短的 markdown 文件，列出顶层目录每个是干嘛的，一句话描述，给 Claude Code 一个目录索引。

这一节是整篇文章里最值得反复读的。CLAUDE.md 调好，其他六件套的价值才能放出来。

四、Hooks：让你的 setup 自我进化

Hooks 是绑定在事件上的脚本。Stop hook 在 session 结束时跑，Start hook 在开始时跑，另外还有 PreToolUse、PostToolUse 这些。

Anthropic 给了三个典型用法：

第一个是 Stop hook 可以让 Claude 自己回顾这个 session，分析有什么经验值得沉淀，然后主动提议更新 CLAUDE.md。这其实是把 self-improvement 自动化了，让其越用越聪明。

第二个是 Start hook 可以根据当前路径或者当前用户动态加载团队特定的上下文。比如你今天在前端目录，自动加载 UI 团队的约定；明天切到后端目录，自动换成后端的那一套。每个开发者就不用手动维护自己模块的 setup 了。

第三个是强制规则用 hook 而不是 prompt。比如自动跑 lint、提交前必须过 typecheck、危险命令拦截，这些都很适合。Prompt 是建议，hook 是约束，能用 hook 就别只写在 prompt 里。这点跟我自己的体感完全一样：让模型自觉其实远不如代码里拦住它来得靠谱。

在我看来，Hooks 是 Claude Code 里最被低估的扩展点，配置门槛比 skill 低，杀伤力却大。建议先把基础 hook 配上，再去考虑其他扩展。

五、Skills 和 Plugins：把好东西散播开

Skills 解决的是“专业能力按需出现”的问题。

大代码库里任务类型几十上百种，每个 session 都把所有能力塞进上下文是不现实的。Skills 用的是 progressive disclosure 的思路：能力描述常驻 context，具体内容只有用到才加载。这次 Anthropic 还提了一个进阶用法，skill 可以按路径 scope，只在特定子目录激活，避免无关 skill 互相打架。

说实话，写好一个 skill 门槛其实不低。Anthropic 之前专门写过一篇（《写好一个 Skill 有多难》），踩了几百个坑才总结出来一套规则。这次大代码库文档里强调的“按路径 scope”算是新增的进阶建议。

Plugins 解决的是“好配置散播开”的问题。

大代码库里最常见的一个现象是：少数几个老员工把 skill、hook、MCP 配置摸透了用得很爽，新人入职完全不知道有这些东西。这种 tribal knowledge 进不了生产力分布，对组织来说是很可惜的。

Plugin 把 skill、hook、MCP server 打包成一个安装包，新人一条命令装完就跟老员工同样的能力。我自己开源过两个仓库（claude-code-settings 和codex-settings），初衷就是这个：把自己折腾出来的配置整理出来，让别人不用再走一遍弯路。

升级路径也是 plugin 的优势。所有人都装同一个 plugin，你修了一个 skill 的 bug，下一次更新所有人都拿到。靠口口相传根本做不到这种分发。

六、LSP：从 grep 到 symbol

这一段可能是文档里最技术、但也最实用的一节。

Claude Code 默认搜代码靠 grep。grep 在小代码库还行，到了大代码库就是个灾难：你搜一个getUser，可能返回上千个匹配，分布在几百个文件里。Claude 为了搞清楚到底是哪个，得一个个打开看，context 瞬间被烧光。

LSP（Language Server Protocol）是编程 IDE 早就已经在用的东西。它知道你这个getUser 是哪个 class 的方法、有哪些 reference、定义在哪、被谁调用。把 LSP 的能力转给 Claude Code，搜索就从字符串变成了符号。

实际效果差距可能是几十倍。同一个查询，grep 返回的是上千条文本匹配，LSP 返回的可能只有几条，并且每一条都是真正引用这个符号的位置。Claude 不用再去打开一堆无关文件，context 也省下来了。

这个适用前提是你的语言有靠谱的 LSP，对 Go、TypeScript、Java、Python、Rust 这些主流语言都没问题。脚本类语言可能稍微弱一些。

七、MCP 和 Subagent：扩展和隔离

MCP server 主要是让 Claude 接入它本来够不到的那些东西：内部工具、私有 API、文档系统等等。我之前在《MCP 不只是开发工具》里聊过生产级 MCP 怎么搭，这里就不展开了。

这次有个新的角度挺值得提：专门写一个 MCP server，把代码库的结构化搜索包装成 Claude 可以直接调用的工具。比如“查找所有 implements 这个 interface 的 class”、“查找所有调用这个 deprecated API 的地方”。这类查询用 grep 做不到，用 LSP 部分能做，但用专用 MCP 是最干净的。

Subagent 这个我想专门聊一下，因为是我用得最多的一个。

简单来说，Subagent 就是一个独立的 Claude Code 实例，有自己的 context window，接到任务、做完工作、只把最终结果返回给主 agent。

我用 Subagent 用得最多的场景就是 explore/edit 拆分。让一个 read-only 的 Explore subagent 先去摸目录、读文件、画出系统结构，写到一个文件里。主 agent 拿到这份报告，再带着完整图景去改代码。

为什么不让主 agent 自己 explore 自己 edit？因为 explore 阶段会读几十个文件，每个文件成百上千行，主 context 很快就被这些读取结果污染了。等到要写代码的时候，模型注意力已经分散在大量无关的细节上。

把 explore 隔离到 subagent 里，主 agent 只拿到一份精炼的总结，相当于拿到一张地图开始施工，而不是边挖边迷路。这跟之前讲上下文管理那篇文章（《Claude Code 作者亲授：百万 token 上下文的正确用法》）里“Subagent 本质上是上下文管理工具”的说法完全一致。

八、配置随模型升级要瘦身

这是整篇文档里我觉得最容易被忽视的一节。

为旧模型写的指令，可能反过来限制新模型。

模型在不停升级。你为 Sonnet 4.5 写的 CLAUDE.md 提示、为修补当时模型缺陷加的 hook、为绕过当时上下文管理 bug 写的 skill，到了 Opus 4.7 可能不仅没用，反而成了限制。

我自己有个真实例子。早期我在根 CLAUDE.md 里加了一段“请先列出所有计划再执行”，那是因为当时模型容易跳步。等模型升级后，规划能力本来就有了，这条提示反而让 Claude 每次都先输出一段冗长的计划，效率反而降了。

Anthropic 的建议是每 3 到 6 个月，或者每次大版本发布后，专门 review 一次 harness 配置：哪些规则还有意义、哪些已经过时、哪些 hook 可以删、哪些 skill 可以合并。

这个习惯在传统工程里叫技术债清理，放到 harness 上同样适用。CLAUDE.md 跟代码注释一样会腐烂，你不主动清，它就慢慢变成噪音。

九、组织准备：DRI、agent manager、跨职能工作组

最后一节是组织层面的，大公司读者可能更关心。

Anthropic 观察到一个规律：Claude Code 推广最顺利的组织，都是在大规模铺开之前先做了一波基础设施建设。少数几个早期采用者负责把 plugin 库搭起来、把 MCP 接好、把 CLAUDE.md 模板写出来，然后才让全员上手。

新出现的一个角色叫 agent manager，是 PM + 工程师的混合角色，专门管理 Claude Code 生态。如果团队没这么奢侈，最起码也要有一个 DRI（Directly Responsible Individual），管 plugin marketplace、管 CLAUDE.md 约定、管 settings 决策。

问题是，光靠工程师自下而上的热情其实不够。热情会催生很多个人配置，但散乱、重复、互相冲突。这种时候需要有人来收口。

大公司还有一层是治理。安全、合规、代码审查流程要早立工作组。原文这点是比较国际化的语境，搬到中国团队还要再加上数据出境、审查留痕，以及敏感行业（金融、政务）的额外要求。这些事情早做比晚做要少很多痛苦。

哪怕你是个人开发者或者小团队，把配置维护这件事当成一个明确的责任分配下来，也比“大家都用一下吧”要有效得多。

写在最后

正如 Claude Code 一直在持续不停迭代一样，要用好 Claude Code 的 harness 配置也不是一次配好就一劳永逸的，也需要随着模型迭代一起进化。CLAUDE.md、Hooks、Skills、MCP、LSP、Subagent，每个配置存在的理由都要定期审视，不能因为它已经在那就让它一直在那。

我自己的实践顺序是这样的：所有项目第一步先创建 CLAUDE.md（包括核心子目录中的 CLAUDE.md），然后再根据需要在项目的 .claude 里面配置所需要的 Hook、MCP 和 Skills，然后就可以用 Claude Code 玩起来了。之后在根据实际需要调整优化，并提醒 Claude Code 把经常出错的地方存入它的 Memory。

相关资源：

• 原文：https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start
• Harness 设计前作：为什么单 Agent 搞不定复杂应用
• 上下文管理：Claude Code 作者亲授：百万 token 上下文的正确用法
• Skill 写作经验：写好一个 Skill 有多难
• 我的 Claude Code 配置：feiskyer/claude-code-settings

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

题记：本文基于 Claude Code 作者 Thariq 昨晚发布的长文《Using Claude Code: Session Management & 1M Context》编译整理，结合评论区的精华问答和个人使用经验，帮中文读者快速掌握上下文管理的核心策略。

Claude Code 升级到 100 万 token 上下文之后，我以为终于可以放飞自我了，一个 Session 从头用到尾，再也不用担心上下文不够用。

结果用了一段时间发现，情况没那么简单。上下文确实够大了，但有时候聊着聊着，Claude Code 的回答质量明显下滑，响应速度变慢不说，前面读过的文件细节开始记不清，甚至会重复做已经做过的事情。更让人困惑的是，有时候 compact 一下反而把关键信息给丢了。

这种体验应该不只我一个人有。昨晚 Claude Code 的作者 Thariq 专门写了一篇长文，系统讲了上下文管理这件事。

这里面有些东西是我之前没想清楚的，特别是 Rewind 和 Compact 的使用策略。再加上评论区 Thariq 亲自回复了不少细节，值得好好聊聊。

上下文腐烂：不是越多越好

上下文窗口越大，模型表现越好？不一定。

Thariq 用了一个很形象的说法叫上下文腐烂。随着上下文增长，模型的注意力被分散到更多 token 上，老旧的、跟当前任务无关的内容开始干扰判断。100 万 token 的窗口，实际上在 30 万到 40 万 token 左右就可能开始出现性能下降。当然，Thariq 也强调这个数字跟任务类型强相关，不是一条硬线。

评论区有人分享了一个挺有意思的观察：同一个 Session 里始终聚焦一个主题深挖，即使对话很长，质量下降也不明显。但频繁跳转不同主题，腐烂来得很快。

这跟我自己的体感也吻合。做一个功能从头做到尾，体验挺好。做完功能接着改 bug、写文档、调配置？Claude Code 就开始犯迷糊了。

100 万上下文不是让你往里塞 100 万 token。它给你的是更大的操作空间，让你能跑更长的自主任务，但上下文质量仍然需要主动管理。

每一轮对话都是一个决策点

Thariq 文章里最让我觉得有启发的，是这个框架：Claude Code 每完成一轮操作后，你面前其实有五条路可以走。

最自然的当然是继续对话，在当前 Session 里接着发下一条消息。大多数人都是这么用的，包括我自己。

但继续对话意味着什么？所有之前的工具调用结果、读过的文件内容、尝试过的方案，全都留在上下文里。有用的，没用的，一锅炖。积累到一定程度，上下文就开始腐烂了。

另外四条路各有各的用法，下面逐个拆开聊。

/rewind（或者连按两次 Esc）可以回退到之前的某条消息，从那个点重新开始。回退点之后的所有消息都会被丢弃。这适合“试了一条路发现走不通”的场景。

/clear 是彻底开一个新 Session。你需要自己把关键上下文写下来带到新会话里，比如“我们在重构 auth 中间件，约束是 X，相关文件是 A 和 B，已经排除了 Y 方案”。费点功夫，但新 Session 的上下文完全由你决定。

/compact 让 Claude Code 总结当前对话，然后用总结替换掉原始对话历史。你不用动手写任何东西，但总结的质量取决于 Claude Code 自己的判断。

还有 Subagent，也就是让 Claude Code 起一个子 Agent 来处理下一段工作。子 Agent 有自己独立的上下文窗口，做完之后只把最终结果返回给主 Session。中间产生的大量工具调用和文件读取不会污染主上下文。

这五个选项不是互斥的，更像是一个工具箱。关键在于判断什么时候该用哪个。

新 Session 还是继续？

Thariq 给了一条简单的判断原则：新任务，新 Session。

但实际操作中有灰色地带。比如你刚实现完一个功能，接下来要给它写文档。按说是不同任务，应该新开 Session。但如果新开，Claude Code 得重新读一遍你刚写的那些文件，既慢又费 token。

Thariq 的建议是，这种情况可以继续用当前 Session。写文档对上下文的“智力要求”没那么高，多一些历史上下文的干扰问题不大，换来的是不用重新读文件的效率提升。

所以这儿不是看任务是否相关，而是看新任务对上下文质量的敏感度。调试、重构，这类需要精确理解代码逻辑的活儿，上下文干净很重要，值得新开。写文档、加注释？继续用就行。

不过话说回来，什么时候该新开 Session 只是上下文管理的一部分。更关键的问题是：方案试错了怎么办？

Rewind：最被低估的上下文管理操作

如果只能从这篇文章里记住一个技巧，Thariq 说应该是 Rewind。

场景是这样的：Claude Code 读了五个文件，试了一个方案，结果不行。这时候很多人的本能反应是继续发消息说“那个方案不行，试试 X 吧”。

问题在于，这条纠正消息虽然给了新方向，但之前那次失败尝试的所有中间过程，读文件的结果、错误的代码、报错信息，全都还留在上下文里。Claude Code 的注意力不得不穿越这些无用信息来理解你的新指令。

更好的做法是 Rewind 到 Claude Code 读完文件之后、开始尝试方案之前的那个点，然后重新给指令：“不要用方案 A，foo 模块没有暴露那个接口，直接用方案 B。”

失败的尝试从上下文里彻底消失了。Claude Code 拿到的是一个干净的起点，加上你从失败中提炼出的经验。

Thariq 还提到一个配套功能叫“summarize from here”，可以让 Claude Code 在回退前先总结它学到了什么，生成一条交接消息。有点像给过去的自己写一封信：“方案 A 走不通，foo 模块的接口不对，直接走方案 B。”然后 Rewind，把这封信贴到新的起点。

这里有个大家比较关心的问题：Rewind 之后，会不会导致 prompt cache miss？毕竟上下文变了，缓存可能失效，那延迟和成本都会上去。Thariq 直接回复说不会，Rewind 之后仍然是 cache hit。

这意味着 Rewind 几乎没有额外代价。免费的上下文清理，不用白不用。

Compact 用不好，问题出在哪

很多人用/compact 的体验是玄学。有时候压缩完一切正常，有时候关键信息莫名其妙地丢了。

Thariq 解释了bad compact 的根本原因：模型无法预测你接下来要做什么。

举个例子，你花了很长时间在 debug 一个问题，中间偶然看到bar.ts 里有个 warning。debug 结束后自动触发了 compact，Claude Code 总结了整个 debug 过程，但那个顺带看到的 warning 被判定为不重要，从总结里丢掉了。然后你下一条消息说“修一下 bar.ts 里那个 warning”，Claude Code 就懵了，因为它的上下文里已经没有这个信息了。

更糟糕的是，compact 触发的时机往往是在上下文快满的时候，恰恰是上下文腐烂最严重、模型最不清醒的时刻。也就是说，模型在最笨的时候，被要求做一个关键的总结决策，能够稳定才怪。

不过 100 万上下文带来了一个好处：你有更多的时间窗口来主动 compact，不用等到快满了才被动触发。

这里有一个很多人不知道的技巧：/compact 可以带参数。比如/compact focus on the auth refactor, drop the test debugging，直接告诉 Claude Code 重点保留什么、可以丢掉什么。

总之，Compact 的正确用法不是等它自动触发，而是在阶段性工作完成后，带着明确的指令主动执行。

Compact 解决的是上下文太长怎么瘦身的问题。但还有一种情况：你明确知道接下来一段工作会产生大量中间输出，而你只要最终结论。这时候该怎么办？

用 Subagent 管理上下文

大多数教程把 Subagent 当并行执行或者任务委派来讲。Thariq 提了一个不同的角度：Subagent 本质上是一种上下文管理工具。

判断标准就一句话：你需要的是中间过程，还是最终结论？

如果你让 Claude Code 在另一个代码库里调研 auth 的实现方式，中间它可能读了二十个文件、试了好几种搜索，产生了大量的工具调用输出。但你真正需要的只是一份总结：“他们用了 JWT + refresh token，关键逻辑在 auth/middleware.ts 里，token 过期时间是 24 小时。”

如果这些中间过程留在主 Session 里，就是纯粹的上下文污染。用 Subagent 来做，中间过程封装在子 Agent 的独立上下文里，主 Session 只拿到最终的总结。

Thariq 给了几个典型场景。比如让 Subagent 根据 spec 文件验证你的实现是否符合要求，只返回“通过/不通过”和问题列表。或者让 Subagent 去读另一个代码库，总结 auth 是怎么实现的，然后你在主 Session 里按总结来写自己的。还有让 Subagent 根据 git 变更写文档，写完直接交付，中间读了多少文件、改了几版，主 Session 完全不需要知道。

共同特点就一个：中间过程产出量大，最终需要的信息量小。

Subagent 默认继承主 Agent 的模型，但你可以在 Agent tool 参数里用model 字段覆盖，比如主任务跑 Opus，Subagent 用 Haiku 来省钱。不过实际用下来我发现一个有点尴尬的地方：Claude Code 自己就很爱起 Explore agent 来搜索代码，然后又提示你 subagent 使用量过高。自己制造开销自己报警，这个体验还有优化空间。

写在最后

看完 Thariq 这篇文章，最大的感受是：上下文管理这件事，其实跟程序员管理内存没什么本质区别。

100 万 token 像是一台内存超大的工作站。内存大了，能同时打开更多文件、跑更长的任务，但不管内存多大，working set 永远应该保持精简。

从 Claude Code 目前的工具链来看，Rewind 处理回退，Compact 处理压缩，Subagent 处理隔离，Auto Memory 处理跨 Session 的持久化，四件套基本覆盖了上下文管理的主要场景。Thariq 在文章最后也说了，未来 Claude Code 会更主动地帮你管理上下文，但现在这个阶段，理解这些机制比等待自动化更实际。

一个表格总结：

养成 Rewind 的习惯，主动/compact 带参数，中间过程多的任务扔给 Subagent。这三个动作做到位，大多数上下文问题就解决了。

相关资源

• Thariq 原文（X Article）：https://x.com/trq212/status/2044548257058328723
• Claude 官方博客版本：https://claude.com/blog/using-claude-code-session-management-and-1m-context
• Claude Code 文档：https://docs.anthropic.com/en/docs/claude-code

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

最近用 Claude Code 写代码，总觉得哪里不对。

我的 CLAUDE.md 里写得很清楚：每次开发完成后，先跑单元测试,再跑 e2e 测试。这个要求跟了我好几个月，之前一直好好的。但最近两三周，e2e 测试愣是不跑。单元测试做完，它就活干完开始总结了。

我以为是提示词不够明确，又在每个任务最后都加了一行“e2e 测试必须执行，不能跳过”这样的提示词。结果还是没用。最后变成每次单元测试跑完，手动再输一句“跑 e2e”，它才肯动。

一开始以为是自己的问题。直到前几天 Hacker News 上炸了一个帖子，才知道不止我一个人。

有人分析了 Claude Code 的 thinking 深度，发现从 2 月底开始下降了 67% 。Claude Code 的作者 Boris Cherny 在 HN 上亲自回复了。他把问题拆成了两个原因。

第一个是 adaptive thinking。Opus 4.6 上线后默认启用了自适应思考，模型自己决定每一轮想多久。听起来更高效，但它经常判断失误。觉得这个任务简单，少想一点就行，该深入的地方直接跳过。

Boris 后来进一步确认：有用户已经设了 effort=high，但 adaptive thinking 仍然在某些轮次分配了零思考 token。零思考，直接出现幻觉了。

第二个是 effort 默认值。3 月 3 号开始，Claude Code 把默认 effort 从 high 降到了 medium。Boris 说这是成本-延迟曲线上的最佳点。但对需要深度推理的任务，这就不够了。

知道原因，解决起来不复杂。

最简单的办法是输入 /effort high，想更激进可以 /effort max。

但光调 effort 不够，核心问题是 adaptive thinking 会自作主张降低思考量。关掉它需要设环境变量：CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1。

你可以在 ~/.claude/settings.json 里一次性配好这两个配置:

{"env": {"CLAUDE_CODE_EFFORT_LEVEL":"max","CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING":"1" }}

这样每次启动自动生效。

顺便提一个反直觉的坑：ULTRATHINK 触发的是 high effort，不是 max。如果你已经设了 /effort max，加 ULTRATHINK 反而会降低那一轮的 effort。

我自己设完这套配置后，e2e 被跳过的情况少了不少。从每次都跳变成偶尔还会跳。不能说完全解决，但至少不用每次手动催了。

如果你也觉得最近 Claude Code 不太对劲，先试试上面那几个配置。

相关资源

• Boris 在 HN 的回复:https://news.ycombinator.com/item?id=47664442
• 原始 issue 讨论:https://news.ycombinator.com/item?id=47660925
• Claude Code 设置文档:https://code.claude.com/docs/en/settings

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

用 Claude Code 跑过长会话的人，应该都经历过这种场景：在 Claude Code 长会话中输入新消息后，终端在那疯狂刷屏，屏幕不停闪烁，你想看一眼前面的上下文，得等所有历史会话消息全部都刷一遍屏。

我自己平时在 tmux 里跑 Claude Code，会话长了之后这个闪烁就很明显，但还能忍。真正让我受不了的是在 VSCode 集成终端或者 SSH 连接到服务器的时候，终端渲染本来就慢，再加上 Claude Code 每次输出都要刷新整个屏幕，长会话到后面很长时间都在等刷屏了。网络延迟再叠上渲染延迟，这体验简直了。

这个痛点社区里吐槽很久了，现在终于等来了修复。愚人节当天， Claude Code 负责人 Boris Cherny 宣布了全屏渲染模式，通过环境变量CLAUDE_CODE_NO_FLICKER=1 开启。

一行配置，立竿见影

开启方式很简单，启动时加个环境变量：

CLAUDE_CODE_NO_FLICKER=1 claude

不想每次都敲这一串的话，扔到 shell 配置文件里：

# 加到 ~/.zshrc 或 ~/.bashrcexport CLAUDE_CODE_NO_FLICKER=1

也可以写进 Claude Code 的settings.json：

{"env": {"CLAUDE_CODE_NO_FLICKER":"1" }}

我加上之后第一感觉就是终于安静了。输入框固定在屏幕底部，Claude Code 的输出在上方平滑滚动，不再有那种整屏闪一下的刷新。整个体验和 vim、htop 这类全屏终端程序一样，Claude Code 接管了整个终端画面。

为什么终端会闪

不闪了当然好，但我比较好奇的是：为什么以前一定会闪？这到底是 Claude Code 的 bug，还是终端本身的限制？翻了 Boris 的推文线程，发现答案是后者。

终端不是浏览器。浏览器有 DOM、有 CSS、有 GPU 加速的合成器，想更新页面某个区域，直接改那个区域就行。终端能用的只有 ANSI 转义码，一套上世纪 70 年代设计的指令集：移动光标到 (x, y)、在当前位置写一段文字、清除一行、清除整个屏幕。

关键问题在于，ANSI 转义码没有移动光标到屏幕外某一行的指令。也就是说，当 Claude Code 的输出已经超出屏幕之后，你没办法只更新那一行。想要重新渲染，唯一的办法就是清空整个屏幕然后重画。

这就是闪烁的根源。每次 Claude Code 输出新内容，传统渲染器都要：清屏 → 重绘所有可见内容 → 把光标移到正确位置。会话越长，需要重绘的内容越多，闪烁越严重，CPU 和内存占用也跟着线性增长。

全屏模式怎么解决的

那 Claude Code 团队是怎么绕过这个限制的呢？

思路其实不复杂，也就是换成了虚拟滚动。就像在前端设计中，一个长列表有一万条数据，你不会把一万个 DOM 节点全渲染出来，只需要渲染可见的那几十条。Claude Code 的全屏模式做的是同样的事，只不过对象从 DOM 节点变成了终端字符行。

具体来说，传统模式下 Claude Code 把所有内容都写到终端的主滚动缓冲区里，让终端自己处理滚动。新模式切换到终端的备用屏幕缓冲区，然后自己接管所有的滚动、鼠标和键盘事件。

这样做的好处是，渲染器只需要画当前终端可见的内容。一个 2 小时的长会话，可能积累了几百条消息，但屏幕上一次最多显示几十行。只渲染这几十行，CPU 和内存占用就变成了常量，不会随着会话长度增长。

这对慢速终端环境来说改善特别明显。VSCode 的集成终端、tmux、iTerm2 这些渲染吞吐量本来就是瓶颈的场景，以前长会话到后面明显卡顿。现在每帧需要发送给终端的数据大幅减少，这些环境下的体验提升是最大的。

不只是不闪了

全屏模式顺带解锁了一些之前终端里做不到的交互。

鼠标支持是让我比较意外的。开启后可以直接用鼠标点击输入框来移动光标，以前想在输入框里改个词，得按方向键一个字一个字挪过去，现在直接点一下就到位了。折叠的工具调用结果也可以点击展开，URL 和文件路径点了直接打开。

选择文字的体验也有改善。以前在终端里选 ClaudeCode 的输出，会连带选上行号和 UI 边框，粘贴出来会带上这些多余的字符。现在选择是在应用层处理的，只选到实际内容，松开鼠标直接复制到剪贴板。双击选词时文件路径会被当作一个完整单元选中。

滚动方面，用鼠标滚轮或者键盘快捷键都行：

MacBook 没有 PgUp/PgDn 键的话，用Fn+↑ 和Fn+↓ 代替。

往上滚动查看历史时，自动跟随会暂停，新输出不会把你拽回底部。想回去接着看最新进展，按Ctrl+End 或者滚到底部就行。以前最烦的就是想回头看看上面的代码，Claude Code 一输出新内容就把你弹回底部了，现在不会了。

搜索怎么办

全屏模式有一个变化需要适应：因为内容在备用屏幕缓冲区里，终端自带的Cmd+F 搜索和 tmux 的搜索功能都用不了了。不过全屏模式提供了替代方案。

按Ctrl+O 进入转录模式，支持一套 vim 风格的导航：

如果你就是想用终端原生的搜索功能，也有办法。在转录模式下按[，会把整个会话内容写回终端的主滚动缓冲区，这时候Cmd+F 和 tmux 的复制模式就都能用了。

几个需要注意的地方

这个模式目前还是 Research Preview 状态，我用下来碰到几个需要适应的地方。

复制粘贴的行为变了。选中文字后松开鼠标就自动复制到剪贴板，不需要再Cmd+C。如果你更喜欢手动控制，可以在/config 里关掉 Copy on select，改用Ctrl+Shift+C。

鼠标滚轮的速度在不同终端上差异挺大。VSCode 终端里滚轮每次只走一行，太慢了。调一下这个环境变量：

export CLAUDE_CODE_SCROLL_SPEED=3

值域 1 到 20，3 大概相当于 vim 的默认滚动速度。

在 tmux 里使用需要开启鼠标模式。如果你的~/.tmux.conf 里还没有这行，加一下：

set -g mouse on

不过要注意，iTerm2 的 tmux 集成模式（tmux -CC）和全屏渲染不兼容（普通的 tmux 没问题）。

如果你通过 SSH 使用，或者在 tmux 里选文字时遇到剪贴板的问题，可以关掉鼠标捕获，只保留无闪烁渲染：

CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_MOUSE=1 claude

这样键盘滚动、固定输入框、常量内存这些核心好处都还在，只是鼠标相关的功能回到了终端原生行为。

写在最后

解决终端渲染性能问题有不同的思路。Warp 当年选择从底层重写终端模拟器，用 GPU 渲染。Claude Code 走的是另一条路：不改终端，在应用层做虚拟滚动，只渲染可见区域。Claude Code 的做法有个明显优势，它适用于任何终端，不管你是在 iTerm2、Ghostty 还是 WSL 默认的那个终端里，加个环境变量就都能用。

这个模式目前还是 Research Preview，滚动物理效果和选文字的边界判断偶尔还有点问题。但和以前的闪烁比起来这些都是小问题。如果你也在 VSCode 终端或者 SSH 环境里被刷屏折磨过，加个CLAUDE_CODE_NO_FLICKER=1 试试。

相关资源：

• Claude Code Fullscreen 官方文档：https://code.claude.com/docs/en/fullscreen
• Boris Cherny 发布推文：https://x.com/bcherny/status/2039421575422980329

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

题记：本文编译自 Anthropic 工程师 Thariq（@trq212）发表的长文。上次他的文章分享了《像 Agent 一样思考：Claude Code 工具设计的进化史》，这次聊的是 Skill 怎么写才好用。原文链接：https://x.com/trq212/status/2033949937936085378。

写过 Claude Code Skill 的人应该都有一个体会：写出来容易，写好很难。

之前我推荐过不少好用的 Skill（《十个顶级 Claude Code Skills，装上就不想卸》《OpenClaw 必备 Skill 清单》），但“好用的 Skill 到底是怎么写出来的”这个问题一直没怎么聊过。市面上的教程大都停在”创建一个 SKILL.md 文件”这一步，至于写什么、怎么组织、哪些信息该放哪些不该放，基本没人系统讲过。

Anthropic 内部现在有几百个 Skill 在日常使用，Thariq 最近把他们踩过的坑整理成了一篇长文。我读完觉得信息密度挺高的，很多坑自己也踩过，但一直没想清楚为什么。这篇就把里面最有价值的部分整理出来。

先纠正一个常见误解

很多人觉得 Skill 就是一个 Markdown 文件。能跑，但没用好。

Skill 的本质是一个文件夹，里面可以放脚本、数据、模板、配置，Claude 能发现、探索和操作这些文件。另外，Skill 还支持很多配置选项（详见官方文档的 frontmatter 参考），包括动态注册 Hook。

Anthropic 内部用得最好的那些 Skill，恰恰是充分利用了文件夹结构和配置选项的。后面会具体聊到。

9 类 Skill：你的团队还缺哪些？

Thariq 把 Anthropic 内部所有的 Skill 做了一次盘点，发现它们大致可以归为 9 类。他说最好的 Skill 通常干净利落地属于某一类，而那些让人困惑的 Skill 往往横跨好几类。

这个分类不是什么权威定义，但作为一个自查清单挺实用的，可以看看你的团队还缺哪几类。

库和 API 参考

教 Claude 怎么正确使用某个库、CLI 或 SDK。可以是内部库，也可以是 Claude 经常用错的外部库。这类 Skill 通常会带一个代码片段文件夹和一份“踩坑清单”。

比如你内部的计费库有一堆边界情况，或者你的 CLI 工具有一些 Claude 不知道的子命令和用法。

产品验证

描述怎么测试和验证代码是否正确。通常会配合 Playwright、tmux 之类的外部工具来做验证。

这类 Skill 的价值在于确保 Claude 的输出是对的，而不是“它说对了就信它”。Thariq 的原话是：让一个工程师花一周时间专门打磨验证类 Skill，是值得的。

可以考虑的技巧包括让 Claude 录制测试视频方便回看，或者在每一步强制做断言。这些通常通过在 Skill 中放脚本来实现。

数据获取与分析

连接到你的数据和监控系统。这类 Skill 可能会包含带凭据的数据获取脚本、Dashboard ID、常见查询工作流。

比如“哪些事件表能看到注册→激活→付费的转化漏斗”，或者“Grafana 里哪个 dashboard 对应哪个问题”。

业务流程自动化

把重复性工作流一键化。比如自动聚合 ticket tracker、GitHub 活动和 Slack 消息来生成 standup，或者自动创建 ticket 并触发后续的 review 和通知流程。

这类 Skill 指令通常比较简单，但依赖其他 Skill 或 MCP。一个有用的技巧是把每次执行的结果保存到日志文件里，Claude 下次执行时可以参考上次的结果，保持一致性。

代码脚手架

为代码库中的特定功能生成框架代码。当你的脚手架有一些无法纯粹用代码覆盖的自然语言需求时，Skill 的优势就体现出来了。比如新建一个带你们标准认证、日志和部署配置的内部应用。

代码质量与审查

在团队内部强制执行代码质量标准。可以包含确定性脚本来保证鲁棒性。你可能想通过 Hook 自动触发这些 Skill，或者放到 GitHub Action 里跑。

比如启动一个全新视角的子 Agent 来挑刺，迭代到只剩 nitpick 级别的问题为止。

CI/CD 与部署

帮你拉代码、推代码和部署的 Skill。比如监控 PR 状态，自动重试 flaky CI，解决合并冲突，开启 auto-merge。或者做灰度发布时自动对比错误率，有回归就自动回滚。

Runbook

拿到一个症状（Slack 线程、告警或错误签名），走一遍多工具调查流程，输出结构化报告。这就是把 on-call 经验沉淀成了可执行的标准流程。

基础设施运维

执行日常维护和运维操作，有些涉及破坏性操作，所以 Skill 里可以内置安全护栏。比如查找孤立的 Pod/Volume，先发到 Slack 等一段时间确认，用户同意后再级联清理。

这 9 类基本覆盖了一个工程团队日常工作的方方面面。如果你的团队刚开始用 Skill，可以从这个清单出发，看看哪几类能最快产生价值。我自己的体感是验证类和业务流程自动化类最容易见效，因为它们解决的是每天都在重复的痛点。

知道了该做什么类型的 Skill，接下来的问题就是怎么写了。

怎么把 Skill 写好？

这部分是我觉得全文最有价值的，因为很多坑不踩一遍真想不到。

Anthropic 最近也发布了Skill Creator 来简化 Skill 的创建过程，但即使有工具辅助，下面这些原则还是得自己把握。

别写 Claude 已经知道的

Claude 本身就懂很多编程知识，对你的代码库也有不少了解。如果你的 Skill 主要是知识类的，重点放在那些能把 Claude 推出它默认思维模式的信息上。

frontend-design Skill 是个好例子。它是 Anthropic 的工程师跟客户反复迭代出来的，核心就是教 Claude 避免那些经典的 AI 审美，比如 Inter 字体配紫色渐变。这些才是 Claude 需要被纠正的地方，而不是告诉它“请写出高质量代码”。

好好写 Gotchas 部分

任何 Skill 里信息量最高的部分就是 Gotchas（踩坑清单）。把 Claude 使用你的 Skill 时经常犯的错记下来，随着使用不断补充。

我自己写 Skill 的经验也是这样。一开始写的 Skill 可能只有二三十行，用了一个月之后 Gotchas 部分比正文还长。因为每次 Claude 犯一个新错，你就加一条，这些积累才是 Skill 真正的价值所在。

用好文件系统和渐进式披露

前面说了，Skill 是文件夹，不只是 Markdown。你应该把整个文件系统当作上下文工程和渐进式披露（Progressive Disclosure）的手段。在 SKILL.md 里告诉 Claude 这个 Skill 里有哪些文件，它会在合适的时候去读。

最简单的做法是把详细的函数签名和用法示例拆到references/api.md 里。如果你的最终输出是 Markdown 文件，可以在assets/ 里放一个模板让 Claude 复制使用。

脚本、示例、参考文档，这些都可以分门别类放进 Skill 文件夹。Claude 知道它们在那儿，需要的时候自己会去找。

这个思路在上一篇《像 Agent 一样思考》里也聊过。从被动接收上下文到主动探索上下文，渐进式披露是 Claude Code 工具设计的核心理念之一。

别把 Claude 钉死

Claude 会尽量遵守你的指令，但 Skill 是会被反复使用的，如果指令太具体，它在某些场景下就会变得很死板。给 Claude 它需要的信息，但也给它根据具体情况灵活调整的空间。

比如不要写“必须按 A→B→C→D 四个步骤执行”，而是写“通常的流程是 A→B→C→D，但可以根据实际情况调整顺序或跳过某些步骤”。

想清楚初始化流程

有些 Skill 需要用户先提供一些上下文才能用。比如一个发 standup 到 Slack 的 Skill，需要知道发到哪个频道。

一个好的做法是把这些配置信息存到 Skill 目录下的config.json 里。第一次运行时，如果配置不存在，Claude 就问用户；配置好了以后就直接用，不再重复问。

如果你想让 Claude 给用户提结构化的选择题而不是开放式提问，可以让它调用AskUserQuestion 工具。

description 字段是写给模型看的

Claude Code 启动时会构建一个所有可用 Skill 的清单，每个 Skill 带上它的 description。Claude 扫这个清单来决定“当前这个请求有没有对应的 Skill”。

所以 description 不是给人看的摘要，而是给模型看的触发条件。你应该写清楚“什么时候应该触发这个 Skill”，而不是“这个 Skill 做了什么”。

这个细节我之前也没太注意，但仔细想想确实重要。如果 description 写的是“用于格式化代码”，Claude 可能在很多场景下都不确定要不要用。但如果写的是“当用户要求格式化代码、或代码风格不一致时触发”，触发率会准确得多。

给 Skill 加记忆

有些 Skill 可以通过存储数据来实现记忆功能。可以简单到往一个文本日志里追加内容，也可以复杂到用 SQLite 数据库。

比如前面提到的 standup Skill，如果每次执行都把内容追加到standups.log 里，下次运行时 Claude 读一遍历史，就能知道哪些是新变化，不需要从头分析。

需要注意的是，Skill 目录下的数据在升级 Skill 时可能被删掉。所以应该把数据存到稳定的位置。目前 Claude Code 提供了${CLAUDE_PLUGIN_DATA} 作为每个 Plugin 的稳定存储目录。

放脚本，让 Claude 组合

给 Claude 代码是你能做的最有力的事之一。把辅助脚本和库函数放到 Skill 里，Claude 就可以把精力花在组合和决策上，而不是从头写重复的样板代码。

比如在数据分析 Skill 里放一组从数据源拉数据的辅助函数，Claude 就可以按需组合这些函数来回答“周二发生了什么”这类问题。

按需 Hook

Skill 可以包含只在被调用时才激活的 Hook，持续到会话结束。适合那些比较“有态度”的 Hook，平时开着太烦，但某些场景下非常有用。

比如/careful，通过PreToolUse 拦截 Bash 里的rm -rf、DROP TABLE、force-push、kubectl delete。你只在碰生产环境时才想开它，平时开着只会让人抓狂。再比如/freeze，阻止 Claude 编辑特定目录之外的文件。调试的时候特别有用，你只想加日志，不想 Claude 顺手把不相关的代码也修了。

别忘了统计

顺便提一下分发和统计。Anthropic 内部用一个PreToolUse Hook 来记录 Skill 的使用情况（示例代码），这样就能发现哪些 Skill 被高频使用、哪些触发率低于预期。

分发方面，小团队直接把 Skill 提交到仓库的.claude/skills 目录就行。规模大了以后，可以搭建内部的 Plugin Marketplace，让团队成员自己选择安装哪些。Anthropic 内部没有一个集中的团队来决定哪些 Skill 上架。有人做了一个好用的 Skill，先放到一个 sandbox 目录让人试用，有了口碑再提 PR 进入正式市场。

还有一个需要注意的问题：Skill 之间的组合和依赖。比如你的 CSV 生成 Skill 依赖一个文件上传 Skill。目前 Marketplace 还没有原生的依赖管理，但你可以在 Skill 里直接引用其他 Skill 的名字，Claude 会自动调用已安装的。

写在最后

回头看这篇文章，最让我有感触的是 Gotchas 部分。我自己写 Skill 的经历也验证了这一点，Skill 的价值不在初始版本写得多完整，而在于使用过程中不断补充 Claude 犯过的错。一开始写个十几行的骨架，用一段时间后自然会长成一个成熟的 Skill。

另一个让我重新审视的是“别写 Claude 已经知道的”。我之前写过一些 Skill，里面有大段的编码规范和最佳实践，这些其实 Claude 本来就会。真正该写进 Skill 的是那些 Claude 不知道的、你的团队特有的知识，比如内部约定、踩过的坑、用什么工具查什么问题。

如果你已经在用 Skills 但觉得效果一般，不妨回去对照一下上面的原则，看看有哪些地方可以调整。如果你还没开始，从一个小的 Gotchas 清单开始就行，不需要一上来就做得很复杂。

相关资源：

• 原文链接：https://x.com/trq212/status/2033949937936085378
• Claude Code Skills 文档：https://code.claude.com/docs/en/skills
• Agent Skills 课程：https://anthropic.skilljar.com/introduction-to-agent-skills
• Skill Creator 博客：https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills
• Anthropic 官方 Skills 仓库：https://github.com/anthropics/skills
• Skill 使用日志 Hook 示例：https://gist.github.com/ThariqS/24defad423d701746e23dc19aace4de5

话题标签：#ClaudeCode #Skills #Anthropic #AI 编程

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

用 Claude Code 大半年了，Skills 和 Plugin 装了几十个，删了一半，留下来的都是真正改变了我工作方式的。这篇就挑十个我用得最多、也觉得最值得推荐的，每个都附安装命令，拿去直接用。

先简单说下 Skill 和 Plugin 的区别。Skill 是一个包含 SKILL.md 的文件夹，教 Claude 怎么做某类任务；Plugin 更完整，可以打包命令、SubAgent、Hook 和 MCP 服务器。不过对使用者来说差不多，下面就不区分了。

Superpowers

如果只能装一个，我选这个。

Superpowers 打包了 20 多个可组合的 Skill，覆盖软件开发的完整流程。brainstorming、TDD、代码审查、Git 提交，每个环节都有对应的 Skill 来约束 Claude 的行为。

我用得最多的是 brainstorming。装了之后，Claude 不会拿到需求就直接开写，而是先问你一轮问题，探索不同方案，把设计决策摊开讨论，最后生成一份设计文档存到本地。看似慢了，实际上能省掉后面大量返工。你会发现很多问题在讨论阶段就暴露了，而不是写了三百行代码之后才发现方向不对。

另一个常用的是 TDD 工作流。它会强制 Claude 先写测试再写实现，跑不过就继续改，直到全绿。Claude 的默认行为是直接写代码然后告诉你“应该没问题”，有了这个约束差别非常大。

当然，20 多个 Skill 全开可能有点重。我一般只启用 brainstorming 和 TDD 两个，其他的按需打开。

claude plugin install superpowers

GitHub:https://github.com/obra/superpowers

Planning with Files

Claude Code 自带的 Plan Mode 有个让人头疼的问题：规划存在对话上下文里，上下文一压缩就丢了。长任务做到一半，Claude 忘了自己在干嘛。又从头开始。

Planning with Files 把规划、进度和知识都写进 Markdown 文件。Claude 开始干活前先创建计划文件，每完成一步就更新进度，遇到有用的信息就记到知识文件里。文件在磁盘上就不会丢，即使上下文被压缩了也能恢复状态。

这个思路其实来自 Manus。Manus 在复杂任务上表现好，核心原因之一就是中间状态都持久化了。Planning with Files 算是社区版的实现。

claude plugin marketplace add OthmanAdi/planning-with-filesclaude plugin install planning-with-files

GitHub:https://github.com/OthmanAdi/planning-with-files

UI UX Pro Max

让 Claude 写前端页面，出来的东西大都长一个样。紫色渐变背景，圆角卡片，居中布局，也就是典型的 “AI 审美”。

Anthropic 官方有个 frontend-design Skill 能改善一些，但 UI UX Pro Max 做得更彻底。它内置了 67 种 UI 风格和 161 套行业配色方案，根据你的项目类型自动推荐设计系统，从配色到排版到交互模式，一步到位。我试着让它做一个 SaaS 后台的 dashboard，选了 Bento Grid 风格，出来的效果比 Claude 默认的好太多，至少看起来不像 AI 做的了。

技术栈方面，React、Vue、Svelte、SwiftUI、Flutter 这些都支持，不只是 Web。

claude plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skillclaude plugin install ui-ux-pro-max@ui-ux-pro-max-skill

GitHub:https://github.com/nextlevelbuilder/ui-ux-pro-max-skill

聊完前端设计，下一个自然要聊的就是代码质量了。

Code Review

这是官方 Plugin 里我觉得设计最精巧的一个。

它不是让一个 Claude 从头到尾看代码，而是启动多个 Agent 并行审查同一个 PR。有的看逻辑正确性，有的看安全漏洞，有的看代码风格。每个 Agent 给出的问题都带置信度分数，最后按分数过滤，只保留高置信度的反馈。

为什么要搞这么复杂？因为 AI 代码审查最大的问题是假阳性太多。以前让 Claude 审代码，它总能挑出一堆潜在问题，看着很认真，但大部分都是过度谨慎的废话。有了置信度过滤之后，留下来的基本都值得看一看。

不过使用时要注意，大 PR 跑起来 token 消耗挺猛的，好几个 Agent 同时跑，一次 review 吃掉的 token 可能比写代码本身还多。小 PR 用着挺舒服，大 PR 建议先拆再审。

claude plugin install code-review

GitHub:https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-review

Code Simplifier

写代码的时候容易堆逻辑，写完跑通了就不想再碰了。Code Simplifier 帮你做那个“写完再看一遍”的事情。

它聚焦最近修改过的代码，检查重复逻辑、多余的中间变量、可以合并的条件分支。不改功能，只做简化。上次我写了一段数据处理的逻辑，里面有三段几乎一样的错误处理，跑完 Code Simplifier 它给合并成了一个通用函数，代码量少了三分之一。

claude plugin install code-simplifier

GitHub:https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier

Webapp Testing

前端写完了，测试怎么办？手动点来点去太慢，写 Playwright 脚本又太繁琐。这个 Skill 把过程自动化了：你告诉 Claude 要测什么场景，它自己用 Playwright 写脚本、启动浏览器、跑测试、截屏，有问题还会自己调试。跟前面的 UI UX Pro Max 搭配起来特别顺手。

claude plugin marketplace add anthropics/skillsclaude plugin install example-skills@anthropic-agent-skills

GitHub:https://github.com/anthropics/skills/tree/main/skills/webapp-testing

Ralph Loop

名字来自辛普森动画里的 Ralph Wiggum，Anthropic 工程师 Daisy Hollman 做的。通过 Stop Hook 拦截 Claude 的退出，把同一个任务重新喂给它。

Claude Code 有个习惯：做到一半觉得差不多了就停下来说“我已经完成了基础框架，你可以在此基础上继续”。Ralph Loop 不让它停。Claude 试图退出，Hook 拦截，检查完成条件，没满足就塞回去。循环往复，直到真正做完。

简单粗暴，但真的管用。

用这个有个关键技巧：完成条件要写得越具体越好。做完这个功能不行，Claude 会自己说服自己已经完成了。要写“所有 CRUD 端点可用，测试覆盖率超过 80% ，README 包含 API 文档，完成后输出 COMPLETE”。条件越模糊，它越会找理由提前收工。

claude plugin install ralph-loop# 使用示例/ralph-loop:ralph-loop"实现用户认证模块。完成标准：JWT 登录注册、测试通过、README 更新。完成后输出 COMPLETE" --max-iterations20 --completion-promise"COMPLETE"

更好详细例子可以参考:https://awesomeclaude.ai/ralph-wiggum

MCP Builder

MCP 这个协议最近讨论度挺高，但真要从零写一个 MCP Server，门槛还是不低。MCP Builder 把构建过程拆成了四个阶段，引导 Claude 一步步完成：理解 API、设计工具接口、实现、测试。

用它的体验比直接让 Claude “帮我写一个 MCP Server”好很多。直接写的话 Claude 经常漏掉 rate limiting 和 token 过期处理等等之类边界情况，用了 MCP Builder 之后这些它都会主动考虑。

claude plugin marketplace add anthropics/skillsclaude plugin install example-skills@anthropic-agent-skills

GitHub:https://github.com/anthropics/skills/tree/main/skills/mcp-builder

PPTX

做 PPT 大概是程序员最不想做的事。

这个 Skill 让 Claude 直接生成.pptx 文件，支持母版、图表、动画。说实话，生成的 PPT 不可能直接拿去做重要汇报，内容、排版和配色都还需要适当调整。但用它生成初稿已经完全够用了，可以大大节省 PPT 得创作时间。

它解决的是“从零开始太痛苦”的问题。起点有了，后面就快了。

claude plugin marketplace add anthropics/skillsclaude plugin install document-skills@anthropic-agent-skills

GitHub:https://github.com/anthropics/skills/tree/main/skills/pptx

Skill Creator

最后一个放 meta 的。Skill Creator 是 Anthropic 官方出的，用来帮你创建新的 Skill 的技能。

之前我写过一篇文章聊它的更新（《写 Claude Skill 最大的盲区，Anthropic 终于帮你补上了》），核心变化是加了 eval 测试框架。现在你可以给 Skill 写测试用例，验证它到底有没有在起作用，还能做 A/B 对比，有 Skill 和没 Skill 的效果差多少，看数据说话而不是凭感觉。

上面九个用完了觉得不够？那就自己造。

claude plugin install skill-creator

GitHub:https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator

选 Skill 跟选工具一样，不在多，在合适。装太多互相打架，反而会影响整体的性能，并且上下文也吃不消，所以精选几个足够用即可。

另外，对不同功能的 Skills，特别是仅跟项目相关的 Skills，推荐放到项目中，提交到 Git，即方便了管理和团队共享，还节省了其他项目的上下文空间。

相关资源：

• Anthropic 官方 Skills 仓库：https://github.com/anthropics/skills
• Anthropic 官方 Plugins 仓库：https://github.com/anthropics/claude-plugins-official
• Awesome Claude Skills 社区列表：https://github.com/travisvn/awesome-claude-skills
• Claude Code Skills 文档：https://code.claude.com/docs/en/skills
• Skills 市场：https://skillsmp.com/

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

用 Claude Code 做过稍微复杂点的项目的人，应该都有一个共同的经验：新开 Session 后，第一件事不是写代码，而是提供 Context：这个项目是什么，用的什么架构，测试环境有哪些坑，之前约定的命名规范是什么等等。

这些背景情况交代完，快的也要五分钟，慢的可能要十几分钟。然后 Claude Code 说“好的，我理解了”，才终于能开始干活。

这个问题确实让人有点烦。开源社区也有很多人试图通过外挂记忆的方式来解决这个问题，但实际体验都不太好。比如 claude-mem 试图通过捕捉工具使用情况自动生成语义摘要，并把相关信息带到未来会话中。看起来很美好，但实际用起来问题一大堆，安装/依赖复杂不说，内存占用高，查询巨慢，稳定性还极差。

这样的痛点 Claude Code 作者自然也早就看到了。刚刚，Anthropic 工程师 Thariq 发了条公告：Claude Code 正式推出了 auto-memory 功能。简单说，Claude Code 现在能跨 session 记住东西了。你的项目上下文、调试习惯、偏好的解决方案，下次开新会话时自动调取，不需要你手动写任何东西。

Auto Memory 是怎么工作的

机制不复杂。

Claude Code 在你编程过程中，会自动把它认为值得记住的东西写进一个本地文件：

~/.claude/projects/<project-hash>/memory/MEMORY.md

记什么、怎么记？我扒了一下它的系统提示词，完整内容如下：

# auto memoryYou have a persistent auto memory directory at`~/.claude/projects/<project-hash>/memory/`.Its contents persist across conversations.As you work, consult your memory files to build on previous experience.## How to save memories:- Organize memory semantically by topic, not chronologically- Use the Write and Edit tools to update your memory files- MEMORY.md is always loaded into your conversation context — lines after 200 will be truncated, so keep it concise- Create separate topic files (e.g., debugging.md, patterns.md) for detailed notes and link to them from MEMORY.md- Update or remove memories that turn out to be wrong or outdated- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.## What to save:- Stable patterns and conventions confirmed across multiple interactions- Key architectural decisions, important file paths, and project structure- User preferences for workflow, tools, and communication style- Solutions to recurring problems and debugging insights## What NOT to save:- Session-specific context (current task details, in-progress work)- Information that might be incomplete — verify against project docs before writing- Anything that duplicates or contradicts existing CLAUDE.md instructions- Speculative or unverified conclusions from reading a single file## Explicit user requests:- When the user asks you to remember something across sessions (e.g., “always use bun”, “never auto-commit”), save it — no need to wait for multiple interactions- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files

这里有几个值得注意的设计：

memory 不只是一个文件。MEMORY.md 是主文件，前 200 行自动加载到 prompt 里。但 Claude code 还可以创建debugging.md、patterns.md 这样的主题文件，从 MEMORY.md 链接过去，需要的时候再读取。这有点像一本带着索引页的笔记本，翻到某个主题再看详细内容。

“What NOT to save”这段我觉得挺克制的。大多数人做记忆功能，恨不得什么都往里塞。Anthropic 反过来，先画了条线说哪些东西别碰：临时状态不记、没验证的不记、CLAUDE.md 里已有的不重复记、只看了一个文件就猜的结论不记。

还有”Explicit user requests”那段也挺实用：你可以直接告诉 Claude 以后都用 bun 装依赖或者永远不要自动 commit，它会立刻写进 memory，不需要等多次交互才总结。反过来你说别再记这个了，它也会去找到对应条目删掉。

另外，内存文件存在本地，按项目哈希值隔离。不会上传到云端，不同项目之间也完全独立。

/memory 命令

内存功能的控制中心是/memory 命令。

打开它，你能看到 Claude Code 自己记录的所有内容，可以编辑某一条，可以删掉觉得没用的，也可以整个关掉这个功能。

这个设计我觉得也挺实用的。Claude Code 的判断不一定都准确，它可能觉得某个临时的 debug 方案很重要。但那只是你一次性的权宜之计，没必要永久保留。透明可控，比黑盒记忆要放心得多。

当然，如果你实在不想开启自动记忆，也可以一行命令搞定：

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

跟 CLAUDE.md 什么关系

用 Claude Code 一段时间的人，大概都写过 CLAUDE.md。你把项目规范、禁止行为、常用命令写在里面，所有会话都生效。

Auto Memory 和 CLAUDE.md 是两件不同的事，完全互补，互不覆盖。

CLAUDE.md 是你主动写给 Claude Code 的规则，记录那些你希望它每次都记住的、不变的约定。Auto Memory 不一样，它是 Claude Code 自己在工作过程中积累的观察，比如项目模式、你的习惯、踩过的坑等等。

两个配合起来的效果最好。可以这样理解：CLAUDE.md 是你写的入职手册，Auto Memory 是它自己记的工作笔记。新员工到岗，先读手册，再翻笔记，然后才真正上手。

几个需要提前知道的问题

说实话，功能本身的设计我觉得没什么可挑的，零配置、透明可控、跟 CLAUDE.md 互补。不过用的时候有几个地方需要注意。

200 行的限制，大项目用久了会碰到天花板。目前的实现是简单的前缀加载，也就是取文件开头 200 行塞进 prompt。不像向量数据库那样能按相关性检索，它就是按顺序读。所以如果 memory 文件积累得多了，靠后的内容实际上不会被加载。

需要养成用/memory 定期整理的习惯，留重要的，删过时的。就像清理浏览器书签，不主动管理就会越来越乱。

另一个问题是过期的记忆。不是所有记下来的东西都应该永久保留。比如你两个月前用了某个临时方案处理一个 bug，现在早就改了。但 Claude 还惦记着旧方案，下次遇到类似问题，再优先往那个方向想就不对了。陈旧的记忆有时候比没有记忆更麻烦。

官方还没给出自动过期或 decay 机制，所以现在还得完全靠手动管理。

不过换个角度想，Anthropic 的选择挺有意思。不用向量数据库，不做复杂的检索增强，就是本地的 Markdown 文件。这跟 Claude Code 一贯的设计哲学一脉相承，能用简单方案解决的，就别上复杂架构。先跑起来，不够再迭代。

说说我自己的感受

功能发布之前，我处理这个问题的方式是：在 CLAUDE.md 里手动把关键的项目背景写进去，然后还要在每次新 session 的第一条消息里补充这次的具体任务背景。

两件事加起来，我其实是在替 Claude Code 充当记忆介质。

比如，有次跑一个长任务，Claude Code 花了大半个小时梳理项目的测试文件。找出了几个有问题的查询接口，还整理出一套处理边界情况的思路。然后上下文窗口到了临界点，触发了自动压缩。下一个 session 接手时，那一套思路就不见了，从头开始分析，之前做的工作重复做了一大半。那半个小时基本白费了。

Auto Memory 解决的就是这类问题。Claude Code 在工作过程中发现的有价值的东西，不应该在 session 结束时消失。

多 Agent 协作的场景里，这个功能的价值可能会更明显一些。一个 Agent 发现了某种边界情况的处理方式，把它写进 memory。下一个 Agent 一开始就能读到，不需要上一个专门提醒。

写在最后

看到 Claude Code 的 Auto Memory，我第一时间想到的是 OpenClaw 的内存设计。

OpenClaw 能两周冲到 10 万星，原因很多，但持久记忆绝对是核心卖点之一。它不只是一个聊聊天就忘的机器人，而是能记住你说过的每一件事，下次提起来直接就知道上下文。这个体验差异太大了，用过的人都回不去。OpenClaw 甚至在 Markdown 记忆之上还加了向量搜索，做成了混合检索，相当于给 Agent 内置了一套 RAG 系统。

Claude Code 的 Auto Memory 走的是更简单的路线：纯本地 Markdown 文件，前 200 行前缀加载，没有向量检索。从功能完备度来说，跟 OpenClaw 的记忆系统还有很大差距。但 Anthropic 的做法一贯如此。先用最简单的方案把核心体验跑通，不够再迭代。

我比较期待的是下一步。200 行的前缀加载很快会碰到天花板，到时候大概率会引入某种形式的语义检索。如果再加上自动过期和记忆质量评估，Claude Code 的记忆系统就真的能跟 OpenClaw 掰手腕了。

相关链接：

• Auto Memory 官方文档：https://code.claude.com/docs/en/memory
• Thariq 的公告：https://x.com/trq212

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

题记：本文编译自 Andrej Karpathy 在 X 上的一篇长推文，发表于 2026 年 1 月 26 日。这篇推文发布后迅速获得上万转发，在开发者社区引发了广泛讨论。本文在翻译基础上做了整理和补充。

Andrej Karpathy 最近发了一条长推，聊了聊他过去几周用 Claude Code 编程的感受。

如果你不熟悉 Karpathy，简单介绍一下。他是斯坦福博士，师从李飞飞，做计算机视觉出身。2015 年加入 OpenAI 成为创始团队成员，后来去了特斯拉担任 AI 总监，负责 Autopilot 自动驾驶系统。2022 年短暂回归 OpenAI，之后离开开始独立研究和创业。他在 YouTube 上的深度学习教程系列，是很多人入门 AI 的启蒙课程。

这样一个在 AI 领域摸爬滚打了十几年的人，说他经历了“近二十年编程生涯中最大的工作流变革”，这话还是有分量的。

我自己用 Claude Code 也有大半年了，从最早写教程、研究系统提示词，到后来自己造了个 Koder，对 AI 编程工具的演进一直在跟进。Karpathy 这篇推文里说的很多问题，我也都遇到过，但他的一些观察角度确实给了我新的启发。

工作流的剧变

Karpathy 说，他的编程方式在 2025 年 11 月到 12 月之间发生了剧烈变化。11 月的时候，大概 80% 还是手写代码加自动补全，只有 20% 用 Agent。到了 12 月，这个比例彻底反过来了，80% 靠 Agent 编程，自己只做 20% 的修改和润色。

他说这感觉有点尴尬，毕竟现在主要是用英语告诉 LLM 该写什么代码，而不是自己写。不过用大规模代码操作的方式来操作软件，实在是太有用了。一旦你适应了这种模式、学会了怎么配置和使用它、搞清楚它能做什么不能做什么，效率提升是非常明显的。

这是他近二十年编程生涯中最大的工作流变化，而且是在几周内发生的。

他估计，类似的变化正在发生在“两位数百分比”的工程师身上，但大众对这件事的认知可能还停留在“个位数百分比”。

IDE 还不能扔，Agent 集群也别太激动

关于不再需要 IDE 和 Agent 集群的炒作，Karpathy 认为现在还言之过早。

模型确实还会犯错。如果你在乎代码质量，就需要在旁边开一个大屏 IDE，像鹰一样盯着它。

模型犯的错也变了。不再是简单的语法错误，而是微妙的概念性错误，就像一个有点马虎、有点着急的初级开发者会犯的那种错。

最常见的问题是什么？模型会替你做假设，一路狂奔，不跟你确认。它们不会主动管理自己的困惑，不会寻求澄清，不会指出矛盾，不会呈现权衡，不会在该推回来的时候推回来，还是有点太讨好人了。

在 Plan Mode 下会好一些，但确实需要一种更轻量的内联规划模式。

模型还有个毛病，喜欢把代码写复杂。它们会膨胀抽象层，不清理死代码，用 1000 行写一个低效、臃肿、脆弱的实现。直到你说“你不能就这样做吗？”，它会说“当然可以！”，然后立刻把代码缩减到 100 行。

它们有时还会顺手改掉或删掉一些它们不喜欢或不理解的注释和代码，即使这些跟当前任务毫无关系。

这些问题在CLAUDE.md 里写了明确的指令要求也解决不了。但即便如此，整体来说还是巨大的改进，很难想象再回到手写代码的时代。

他现在的工作流是这样的，左边开几个 Ghostty 窗口放着 Claude Code 会话，右边开着 IDE 看代码和做手动编辑。

不知疲倦的韧性

Karpathy 说，看着 Agent 不知疲倦地工作，是一件很有意思的事。

它们从不累，从不泄气，就是一直尝试。换做人类，早就放弃改天再战了。但 Agent 可以挣扎 30 分钟，最后还是把问题解决了。

这是一种感受 AGI 的时刻。你会意识到，耐力是工作的核心瓶颈之一，而有了 LLM，这个瓶颈被大大突破了。

速度提升还是能力扩展？

怎么衡量 LLM 辅助编程的加速效果？这个问题并不简单。

Karpathy 说，他确实感觉做事快了很多。但主要的效果不是更快地做完原来要做的事，而是能做更多事，更能做原来做不了的事了：

1）以前觉得不值得写代码去做的事情，现在可以顺手做了；

2）以前因为知识或技能限制做不了的事情，现在页可以做了。

这不仅仅是加速，更可能是一种能力的扩展。

杠杆效应

LLM 特别擅长循环直到达成目标，这也是最能感受 AGI 的地方。

Karpathy 的建议是，不要告诉它怎么做，而是给它成功标准，看它自己去实现。

具体做法包括，让它先写测试，再让它通过测试；让它配合浏览器 MCP 在循环中工作；先写一个很可能正确的朴素算法，再让它优化同时保持正确性；把你的方法从命令式改成声明式，让 Agent 循环得更久，获得更大的杠杆效应。

更有趣了

Karpathy 说，他没想到 Agent 编程会让编程变得更有趣。

因为大量填空式的苦力活被移除了，剩下的是创造性的部分。他感觉更少被卡住了，也更有勇气了，因为几乎总能找到一种方式跟 AI 协作推进。

不过他也提到，有些人可能会有相反的感受。AI 编程可能会让工程师分化成两类，一类是喜欢编程本身的，一类是喜欢构建的。

能力退化

Karpathy 承认，他已经注意到自己手写代码的能力在慢慢退化了。

生成代码和判别代码是大脑里两种不同的能力。这主要是因为编程涉及大量语法细节，即使写起来费劲，读代码还是没问题的。

2026 年会发生什么？

Karpathy 说，他已经在为 2026 年做心理准备了，这将是 Slopacolypse 之年，也就是低质量内容大爆发。

GitHub、Substack、arXiv、X/Instagram，以及所有数字媒体，都会充斥着 AI 生成的低质量内容。我们还会看到更多 AI 炒作式的生产力表演，当然也会有真正的实质性改进。

他还抛出了几个开放性问题。10 倍工程师会怎样？普通工程师跟顶尖工程师之间的生产力差距会怎么变？很可能会拉大很多。通才会不会开始碾压专才？LLM 更擅长填空，也就是微观层面，而不是宏观战略。装备了 LLM 的通才，会不会越来越强过专才？未来的 AI 编程会是什么感觉？像玩星际争霸？玩异星工厂？还是像演奏音乐？社会有多少部分是被数字知识工作卡住的？

写在最后

Karpathy 的结论是，LLM Agent 的能力，尤其是 Claude 和 Codex，在 2025 年 12 月左右跨过了某种“连贯性阈值”，引发了软件工程及相关领域的相变。

AI 的智能部分突然跑得太快，工具集成、组织流程、技术普及这些配套都还没跟上。

2026 年将是高能量的一年，整个行业都在消化这种新能力。

Karpathy 说的这些问题我也都遇到过，模型喜欢过度设计、不清理死代码、有时候会顺手改掉不该改的东西。这半年多用下来，我的感受是：AI 编程工具确实在快速进化，但人的监督短期内还省不掉。

这场变化来得比大多数人想的要快。

相关资源

• Karpathy 原推文：https://x.com/karpathy/status/2015883857489522876
• Karpathy 的 2025 LLM 年度回顾：https://karpathy.bearblog.dev/year-in-review-2025/

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

题记：本文编译自 Cursor 官方博客《Scaling long-running autonomous coding》，作者是 Cursor 研究团队的 Wilson Lin。原文分享了他们让数百个编程智能体连续自主运行数周的实验经验。本文在翻译基础上做了整理和补充。

前几天社交媒体上被 Cursor 的多智能体实验刷屏了。Cursor 的 CEO Michael Truell 发了一个 AI 狂造浏览器的帖子直接炸锅，浏览量突破 600 万：他们用 GPT-5.2 驱动数百个智能体，连续跑了一周，吐出 300 多万行代码，从零撸了一个浏览器渲染引擎。

结果呢？很多人跑去验证，瞬间被打脸。bug 一堆不说，功能上离 Chrome/WebKit 还差十万八千里。但即便如此，也有很多人给出很高的评价。比如 Stripe CEO Patrick Collison 评价说：

This work by @cursor_ai is, I think, the coolest AI breakthrough since GPT-4. (And there are plenty of candidates!)

Django 联合创始人 Simon Willison 也亲自验证了这个浏览器项目。他在 macOS 上成功编译运行，google.com 和他自己的博客都能渲染出来。虽然还有明显的渲染问题，但页面可读、大体正确。他的评价是“Honestly those are very impressive!”。有意思的是，Simon 在年初预测“到 2029 年会有人用 AI 辅助编程构建完整浏览器”，结果可能预测错了三年。

抛开浏览器项目本身的争议不谈，Cursor 在博客里分享的多智能体协作设计和踩坑经验，对大型代码仓库的 AI 协作开发还是很有参考价值的。我仔细读了原文，整理翻译出来分享给大家。

单个智能体的局限

现在的编程智能体处理聚焦性任务已经没什么问题了，但面对复杂项目时速度还是太慢。为了解决速度问题，自然的想法是并行跑多个智能体，但怎么协调它们的工作是个难题。

Cursor 团队最初的直觉是，提前做详细规划太死板了。大项目的路径本身就是模糊的，一开始很难知道怎么分工最合理。所以他们选择了动态协调的方式，即让智能体根据其他智能体当前在做什么，自己决定接下来要做的事。

协调有多难

Cursor 最早的方案是给所有智能体平等的地位，让它们通过一个共享文件来自我协调。每个智能体会检查其他智能体在做什么，认领一个任务，更新自己的状态。为了防止两个智能体抢同一个任务，加了锁机制。

这个方案不出意外地失败了，失败的方式还挺有意思：

• 智能体经常把锁拿着不放，或者干脆忘了释放。即便锁机制工作正常，它也会变成瓶颈。20 个智能体跑起来，实际吞吐量可能只相当于两三个，大部分时间都在等锁。

• 整个系统还特别脆弱，智能体可能在持有锁的时候崩溃，可能尝试获取自己已经持有的锁，或者干脆不拿锁就直接更新协调文件。

之后，他们又尝试用乐观并发控制来替代锁。智能体可以随意读取状态，写入时如果发现状态已经变了就会失败。这种方式更简单、更健壮，但还有更深层的问题。

没有层级结构的情况下，智能体变得更倾向于规避风险。它们会回避困难任务，只做小的、安全的改动。没有哪个智能体愿意承担难题或者端到端的实现。结果就是工作在原地打转，长时间没有实质进展。

规划者与执行者

既然协调方案走不通，Cursor 有继续尝试了其他方案。下一个尝试的是角色分离，即 Agent 不再是扁平结构，而是建立一个有明确分工的流水线：

• 规划者（Planner） 负责持续探索代码库、创建任务、生成子规划者来负责特定区域，并让规划本身也变成并行和递归的。

• 执行者（Worker） 负责领取任务，专注于完成任务。执行者不需要和其他执行者协调，也不用操心全局。就是埋头干活，干完了就提交代码，领下一个任务。

每个周期结束时，有一个裁判智能体（Judge Agent） 来判断是否继续，下一轮迭代重新开始。这个方案解决了大部分协调问题，让他们能够扩展到非常大的项目，而不会让单个智能体陷入局部视野。

实战：狂跑一周造了个浏览器

为了测试这套系统，他们设了一个很有野心的目标：从零开始构建一个网页浏览器。

智能体跑了将近一周，写出了分布在 1000 多个文件的 100 万行代码，并把它开源了，源码可以在 GitHub 上看到：fastrender。

尽管代码库规模很大，新加入的智能体仍然能理解它并做出有意义的贡献。数百个执行者同时运行，向同一个分支提交代码，冲突却很少。

另一个实验是在 Cursor 自己的代码库里做框架迁移，把 Solid 原地迁移到 React。这个任务跑了三周多，改动量是 +266K/-193K 行。虽然最终代码还需要仔细审查，但已经通过了 CI 和早期检查。

第三个实验是改进一个即将发布的产品。Cursor 利用一个长期运行的 Agent 使用 Rust 重写了视频渲染模块，性能提升了 25 倍，还加上了平滑缩放和平移功能，带有自然的弹簧过渡和运动模糊效果。这段代码已经合并，很快会上线生产环境。

除此之外，Cursor 还有几个正在持续运行的项目，规模也都不小：

• Java LSP：7400 次提交，55 万行代码
• Windows 7 模拟器：14600 次提交，120 万行代码
• Excel：12000 次提交，160 万行代码

他们学到了什么

这些实验消耗了数万亿个 token，系统效率还谈不上完美，但效果远超预期。Cursor 团队从中得到了一些有意思的发现。

1. 模型选择对长时间任务影响很大。他们发现 GPT-5.2 明显更适合自主工作，更能遵循指令、保持专注、避免偏离、实现得更精确完整。而 Opus 4.5 则倾向于更早停下来，在方便的时候走捷径，很快就把控制权交回去。GPT-5.2 做规划比 GPT-5.1-Codex 更好，尽管后者是专门为编程训练的。所以他们现在针对不同角色选用最合适的模型，而不是一个模型打天下。

2. 有意思的是，很多改进来自移除复杂性，而不是增加复杂性。他们最初设计了一个整合者角色来做质量控制和冲突解决，结果发现它制造的瓶颈比解决的问题更多。执行者本身就有能力处理冲突，多加一层反而添乱。

3. 他们最初试图照搬分布式计算和组织设计的模式，但发现并不是所有模式都适用于智能体。合适的结构介于两者之间：太少会导致冲突、重复劳动和偏离；太多则会带来脆弱性。最好的系统往往比预期的更简单。

4. 还有一点值得注意：提示词比架构和模型更重要。系统行为很大程度上取决于如何给智能体写提示词。让它们协调好、避免病态行为、在长时间内保持专注，需要大量实验。框架和模型当然重要，但提示词才是关键。

当然，多智能体协调的问题并未完全解决，在整个业界仍然是个难题。当前的设计基本能用，但离最优还差得远。比如规划者应该在任务完成时被唤醒来规划下一步，而不是干等着；智能体偶尔会跑太久；为了对抗偏离和局部视野，仍然需要定期重新开始。

不过核心问题的答案已经比你想象的乐观得多：能不能通过投入更多智能体来扩展自主编程？能。数百个智能体可以在同一个代码库上协作数周，在超大规模的项目上取得真正的进展。Cursor 表示，这里开发的技术最终会融入 Cursor 的智能体功能。

写在最后

Cursor 这篇文章里有几个点挺有意思的。

角色分离这件事，其实和人类团队管理的道理相通。扁平结构看起来很民主，但在智能体协作中反而会导致风险规避和内耗。有明确的规划者和执行者分工，系统的潜力反而能释放出来。

另一个印象深刻的是“简单比复杂好”。他们移除整合者角色反而效果更好，这提醒我们不要过度设计。很多时候加一层抽象不是解决问题，而是制造新问题。

还有提示词工程的重要性。即便有了好的架构和模型，如果提示词写得不好，智能体还是会出各种问题。Anthropic 之前在《Building effective agents》里也强调过类似观点，工具定义和提示词规范需要投入大量工程关注，这往往比架构设计更影响最终效果。

当然，文章也有一些没展开的地方，比如具体的提示词是怎么写的？规划者和执行者之间的任务粒度怎么划分？裁判智能体的判断标准是什么？这些细节还需要更多实践来验证。

相关资源

• 原文链接：https://cursor.com/blog/scaling-agents
• 浏览器项目源码：https://github.com/wilsonzlin/fastrender
• Building effective agents：https://www.anthropic.com/engineering/building-effective-agents

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。