06｜16 小时 Claude Code：图片、多模态、CLAUDE.md 与上下文管理

17 · 图片与多模态：贴张截图，它就懂了

比如要把一张设计师给的页面截图还原成网页。搁以前，咱们得对着图一个像素一个像素量——这块间距多少、字号几号、按钮圆角几度，光抠数值就得磨一上午。

这时候只要把那张 PNG 直接拖进 Claude Code 的窗口，敲一句「照着这张设计稿生成对应的 CSS」。

几分钟后，它吐出来一整段 CSS——布局、配色、圆角、阴影全对上了，贴进项目里，浏览器一刷新，和设计稿几乎一模一样。效率差距一下就出来了：给它看比跟它讲快得多。

说白了，一图胜千言这句话，在 Claude Code 这儿是字面意义上成立的。今天就把「怎么喂图 + 喂图能干嘛」讲透。

看完这一篇，你会拿到：

• 三种把图片塞进 Claude Code 的方法，照着做就行（含一个 Mac 用户必踩的快捷键坑）
• 图片的三大正经用途：贴报错截图、还原设计稿、读图表 / 架构图
• 一个判断标准：什么时候该上图、什么时候打字就够
• 多图怎么用、Claude 怎么引用图片、怎么一键点开它说的那张

01 为什么要给它看图，而不是只打字

先说结论：当一件事「描述起来比截图还费劲」的时候，就该上图了。

这是官方文档里白纸黑字的判断标准——「当文本描述不清楚或繁琐时使用图像」。

类比：一图胜千言。 你跟朋友形容一个红绿报错弹窗长啥样，说半天「左上角有个红叉，下面一行小字，右边还有个按钮……」对方还是云里雾里；但你截个图甩过去，他「哦」一声就全明白了。给 Claude 看图，是同一个道理——省下你组织语言的力气，也省下它猜的力气。

哪些场景特别适合上图？用下来主要是这三类：

这里有个关键区别得拎清楚：Claude Code 看的是「图里的内容」，不是帮你截图。截图这一步还得你自己来（系统自带的截图工具就行），它负责的是「看懂你给的图」。

💡 一句话总结：判断标准就一句——描述起来比截图还累，就上图；官方原话叫「文本不清楚或繁琐时用图像」。

02 三种喂图方式：拖、贴、给路径

怎么把图塞进去？官方文档给了三种方法，任选一种，效果一样。我按「上手难度从低到高」排一下。

这张图把三条加图路径并到一处：拖拽进窗口、复制后 ctrl+v 粘贴（Mac 也是 ctrl+v）、或直接给文件路径——三种方式殊途同归，都是把图喂给 Claude 让它「看着干活」。

方法一：直接拖进窗口（最直觉）

把图片文件从访达 / 文件管理器里拖进正在运行 Claude Code 的终端窗口，松手，它就进去了。

这是最不用动脑的方式——跟你往微信聊天框拖文件发图一个感觉。新手一般先从这个上手，零学习成本。

方法二：复制图片，ctrl+v 粘贴（最高频，但有个坑）

很多时候图根本没存成文件——你刚截了个屏，或者从网页上右键「复制图片」，这时候直接粘贴最爽。

但这里有全篇最大的一个坑，官方文档专门强调了：

复制图像并使用 ctrl+v 将其粘贴到 CLI 中（不要使用 cmd+v）。

注意：Mac 上粘贴图片也用 ctrl+v，不是你习惯的 cmd+v。

这点反直觉到什么程度？Mac 用户复制粘贴文字十年了都是 cmd+v，肌肉记忆根深蒂固。第一次贴截图，很容易习惯性按 cmd+v，结果终端里冒出来一长串乱码路径，图根本没进去，还以为是不支持。翻一翻文档就明白了——很多终端里 cmd+v 粘的是文件路径文本，只有 ctrl+v 才稳稳把图片本身喂给 Claude。

（补一句：个别终端比如 iTerm2 也认 cmd+v 粘图，但各终端行为不一致，ctrl+v 是哪儿都好使的那条路，记它就不踩坑。）

记死这一条：

一个小细节：粘贴成功后，输入框里会出现一个 [Image #1] 的占位标记（官方叫「芯片（chip）」），表示图已经挂上了，你可以在这条提示里接着打字。

方法三：直接给图片路径（最适合脚本 / 已存好的图）

如果图已经存成文件了，路径你也知道，那最干脆的办法是在提示里直接把路径打出来，让它自己去读：

Analyze this image: /path/to/your/image.png

把 /path/to/your/image.png 换成你那张图的真实路径就行（相对路径、绝对路径都认）。这种方式不依赖鼠标拖拽，写在脚本里、或者图片藏在项目某个目录深处时，最好用。

💡 一句话总结：拖进窗口 / ctrl+v 粘贴 / 直接给路径，三选一；Mac 用户死记 ctrl+v，别按 cmd+v。

03 用途一：贴报错和 UI 截图，给它「现场」

第一个最实用的场景——把出问题的截图甩给它，让它看着现场断案。

为什么这招好用？因为很多报错和样式问题，文字根本传达不全。一个报错弹窗里有图标、有颜色、有排版，你手敲只能描述个大概；UI 错位更是如此，差几个像素肉眼能看出来，嘴说不清。

类比：去医院别光靠嘴描述「这儿疼」，拍张片子给医生。 你说「肚子右下角隐隐作痛」，医生只能猜；一张 CT 片摆上去，问题在哪一目了然。截图就是给 Claude 的那张「片子」。

具体怎么做？把截图喂进去（三种方法任选），然后配一句话点出你的诉求。官方给的示范提示就很到位：

Here's a screenshot of the error. What's causing it?

或者，UI 上的问题：

Describe the UI elements in this screenshot

比如调一个 React 页面，有个按钮死活偏右，CSS 翻来覆去看不出毛病。这时候直接截了张错位的图丢进去，配一句「这个按钮为什么往右挤了」，Claude 一看就说「你父容器有个 padding-right，加上按钮自己的 margin，叠一块了」——一句话点破，对着改一行就好了。要是靠打字描述这个错位，怕是得来回拉扯好几轮。

💡 一句话总结：报错和 UI 问题，截图就是「现场照片」——给它看比给它讲，断案快得多。

04 用途二：还原设计稿，截图直接出代码

这就是开头那个「效率差距一下拉开」的场景，单独拎出来讲——给它一张设计稿，让它吐出能跑的代码。

为什么这招最惊艳？因为它把「设计→代码」这段最磨人的体力活给省了。对着图量数值、调间距、试配色，原本是前端最枯燥的一环，现在丢给它先出个八九不离十的版本，你再微调。

类比：拿张照片让裁缝照着做衣服。 你不用把每条尺寸都报给裁缝，把样衣照片往他面前一放，他自己就能量出版型、用料、走线。设计稿截图之于 Claude，就是那张「样衣照片」。

官方给的示范提示，记住这两句就够开工：

照着这张设计稿生成对应的 CSS

What HTML structure would recreate this component?

第一句让它照着设计稿生成 CSS，第二句让它推断出能复刻这个组件的 HTML 结构。两句连用，一个静态组件的骨架就出来了。

说句实话，得有个合理预期：它不是像素级复刻，是给你一个高完成度的起点。像开头那段 CSS，整体布局和配色全对，但有两个地方的内边距差了几像素，手动调一下就行。可这已经省了至少一小时——从零写 CSS，和改它给的八成稿，完全是两个工作量。

💡 一句话总结：设计稿截图 +「照着这张设计稿生成对应的 CSS」，它给你八成稿，你补最后两成，省下的全是体力活。

05 用途三：读图表和架构图，让它「看懂结构」

第三个用途，图表、数据库 schema、架构图——这些「结构性」的图，它也能看懂。

为什么单列一类？因为前两类（报错、设计稿）图里是「界面」，这类图里是「关系」——谁连谁、数据怎么流、模块怎么分层。这种关系用文字串起来特别绕，用图一目了然，正好是 Claude 的菜。

类比：给新同事讲系统，白板上画个框图比讲半天管用。 你跟新人口述「用户服务调订单服务，订单服务又依赖库存和支付……」，他听得云里雾里；白板上几个框一连，箭头一画，他立马懂了。把这张框图截给 Claude，效果一样。

官方给的示范提示，覆盖了「读」和「改」两个方向：

This is our current database schema. How should we modify it for the new feature?

Are there any problematic elements in this diagram?

第一句是拿着现有的数据库结构图，问它新功能该怎么改表；第二句是让它审一审这张图里有没有不合理的地方。

一个很常见的用法：接手一个陌生项目，对方甩来一张架构图 PNG，直接喂给 Claude，让它先讲讲这套系统大概怎么跑。它能从图里读出模块和调用关系，给你一段概览——比自己对着图干瞪眼快多了，相当于有人先带你把图捋了一遍。

💡 一句话总结：图表、schema、架构图这类「讲关系」的图，喂给它当背景，让它读懂结构再帮你改或审。

06 多图、引用、一键点开：几个好用的小操作

最后补几个让你用得更顺的细节，都是官方文档里提到的。

一次可以喂多张图

不用一张张来——同一条提示里可以塞多张图。比如「这是旧设计稿、这是新设计稿，告诉我改了哪些地方」，两张一起给，让它对比。设计稿改版时常这么干，省得来回切换描述。

Claude 怎么引用图片：[Image #1]

当 Claude 在回复里提到你给的某张图时，它会用 [Image #1]、[Image #2] 这样的编号来指代——第几张图就是几号。多图的时候，这个编号让你一眼对上「它说的是哪张」。

一键点开它说的那张图

它回复里出现的 [Image #N] 是可以点开的，按官方说法：

当 Claude 引用图像时（例如 [Image #1]），Cmd+Click（Mac）或 Ctrl+Click（Windows/Linux）链接以在默认查看器中打开图像。

也就是说，想确认它指的到底是哪张，Mac 上 Cmd+Click、Windows/Linux 上 Ctrl+Click 那个编号，系统默认看图工具就帮你把图打开了。

注意这俩快捷键的「分工」是反的：粘贴图片用 ctrl，点开图片链接 Mac 上却用 Cmd。别记混了。

💡 一句话总结：一条提示能塞多张图，Claude 用 [Image #N] 指代，点那个编号（Mac 是 Cmd+Click）就能把图打开核对。

07 动手：拖一张图让它读，三步跑通

光说不练假把式。下面用一张你电脑上随便一张图，三步跑通「喂图 → 它读懂」的完整流程。不需要任何项目，桌面上有张图就行。

第一步：随便找一张图，记住它的位置

截个屏，或者随便找张已有的 PNG / JPG。Mac 截屏默认存桌面，文件名形如 截屏2026-06-10 下午3.20.15.png。把它拖到一个好打的路径，比如直接放桌面就行。

第二步：在任意目录启动 Claude Code

claude

预期：出现欢迎屏幕，底部有输入框。（读图不挑目录，随便在哪启动都行。）

第三步：把图喂进去，让它描述

三种方式任选，新手推荐直接拖：把那张图从桌面拖进终端窗口，松手，输入框里会出现 [Image #1] 标记。然后接着打字：

这张图里是什么？用中文描述一下你看到的内容

回车。

预期：Claude 读取这张图，用中文告诉你图里有啥——是张截图就说界面元素，是张照片就描述画面内容。看到它准确说出了图里的东西 = 喂图成功，全流程跑通。

⚠️ Mac 用户想试「复制粘贴」那条路：先在预览 / 浏览器里复制图片，回到终端按 ctrl+v（不是 cmd+v）。要是按完冒出来一串文件路径文本而不是 [Image #N] 标记，八成是手贱按成 cmd+v 了，删掉重来。

💡 一句话总结：拖进去 / ctrl+v / 给路径，三步喂图，看到 Claude 准确描述图里内容即为跑通。

08 小结

这一篇你学会了给 Claude Code 开「视觉」这一路——从只能打字，到能直接给它看图。

把要点串一遍：

你现在应该能： 把任意一张截图、设计稿或架构图喂给 Claude Code，让它看着图帮你断报错、出代码、捋结构；并且记住了 Mac 上那个最反直觉的 ctrl+v。这套「给它看」的能力，会让你之后描述问题的成本直线下降——很多以前要打半天字的需求，现在一张图加一句话就解决了。

下一篇 18「CLAUDE.md 使用指南」——前面咱们一直在喂图、喂需求，但每次都得重复交代项目背景。有没有办法让 Claude 一进项目就自动知道这是个啥、该守哪些规矩？下一篇就讲那个给它的「入职手册」——CLAUDE.md，配好了它就再也不用你反复念叨了。

18 · CLAUDE.md 使用指南：把项目规矩写进它的记忆

都说 CLAUDE.md 写得越详细越好，但说句实话，最没用的 CLAUDE.md，恰恰是那种写了三百行、Claude 一条都没听的。

设想一份接手项目里前任留下的 CLAUDE.md，洋洋洒洒：公司背景、产品愿景、团队介绍、技术选型的来龙去脉……翻到第二屏才看到一句有用的「用 pnpm 不用 npm」。结果呢？Claude 照样动不动给你 npm install。

问题不在它不听话，在那条规矩被埋在两百行废话里，注意力早被稀释没了。

CLAUDE.md（Claude 的项目记忆文件）这东西，写好了是神器，写砸了是负担——它每次会话都占你的上下文窗口，写得越臃肿，留给真正干活的空间越小。今天咱们就把这件事掰开：它分几层、该写什么、不该写什么、怎么引用别的文件、怎么维护精简。

看完这一篇，你会拿到：

• CLAUDE.md 三个层级（用户级 / 项目级 / 子目录级）各管什么、加载顺序怎么排
• 一张「该写 vs 不该写」的清单，避开 90% 新手往里塞废话的坑
• 用 @ 语法引用其他文件的正确姿势，以及它对上下文的真实代价
• 会话里临时补一条记忆的官方做法，加一套「好 vs 烂」对照表当模板

ℹ️ 本篇只聚焦 CLAUDE.md 这一个文件怎么写好、怎么维护。/init 一键生成的玩法在 12「项目初始化」 讲过了，更广的自动记忆（auto-memory）机制留给 25「记忆系统」 专门聊。

01 先搞懂：CLAUDE.md 到底是什么

先给结论：CLAUDE.md 是你写给 Claude 的一份「持久指令」，每次开会话它都先读一遍，当成项目背景装进脑子。

为什么需要它？因为每个 Claude Code 会话都从一张白纸开始——上次你苦口婆心交代的「用 pnpm、别碰 legacy 目录、测试这么跑」，这次它一概不记得。没有 CLAUDE.md，你就得每次重新解释一遍，烦不烦？

类比：给新员工的入职手册。 新人第一天来，你不会站他旁边全天候口述规矩。你给他一份手册：项目是干嘛的、代码怎么提交、哪几个雷区别踩。他自己看一遍就上手了。CLAUDE.md 就是 Claude 的入职手册——而且是每天上班前都会重读一遍的那种。

但这里有个关键认知，官方文档说得很直白：

CLAUDE.md 内容作为用户消息在系统提示之后传递，而不是系统提示本身的一部分。Claude 读取它并尝试遵循它，但没有严格遵守的保证。

翻译成人话：CLAUDE.md 是「强烈建议」，不是「铁律」。 它塑造 Claude 的行为，但不是硬性强制层。所以你写得越具体、越简洁，它遵守得越稳。指望靠它 100% 卡住某个危险操作？那是 Hook（钩子）的活儿，不是 CLAUDE.md 的活儿——这俩的分工后面篇章会讲。

什么时候该往里加内容？官方给了几个特别实在的信号：

• Claude 第二次犯同一个错 —— 说明这条得写进去固化下来
• 你这次会话又敲了一遍上次会话敲过的那句更正
• 代码审查时发现，它应该早就知道这个代码库的某个约定
• 新队友需要同样的背景才能快速上手

💡 一句话总结：CLAUDE.md 是 Claude 每次开工必读的入职手册，「强烈建议」级而非「铁律」级，写得越具体越管用。

02 三个层级：谁管全局，谁管单项目

CLAUDE.md 不止一份，它能放在好几个地方，作用范围从大到小。新手最容易在这儿犯迷糊，咱们一次理清。

按官方文档，常用的是这三层（外加一个本地变体）：

还有一层「托管策略层」，由 IT 管理员部署到系统目录（macOS 为 /Library/Application Support/ClaudeCode/CLAUDE.md），在用户级之前加载、不可被个人排除。个人用户通常碰不到，本篇略去；企业场景可查官方文档。

怎么分工？记一句话：个人习惯放用户级，团队规矩放项目级。

• 用户级（~/.claude/CLAUDE.md）：放跨项目通用的个人偏好。比如「回复用中文」「改代码前先说思路别直接上手」「提交信息用英文」。这些跟具体项目无关，是「你这个人」的习惯，所以对所有项目生效、不进任何项目的 git。
• 项目级（./CLAUDE.md）：放这个项目专属、且全队都该守的规矩。技术栈、构建命令、目录约定、禁改清单。它跟着代码进版本控制，新同事 clone 下来就自带这套规范。
• 子目录级：大仓库才用得上。比如前端目录放一份前端专属的，后端目录放一份后端专属的。它平时不加载，只有当 Claude 真去读那个目录里的文件时，才顺手把那份 CLAUDE.md 带进来——省上下文。

类比还是入职手册： 用户级 = 你个人的工作习惯本（换公司也带着）；项目级 = 这家公司发的员工手册（离职就还回去）；子目录级 = 某个部门内部的额外细则（只有调到那个部门才发给你）。

举个常见的用户级配置：在 ~/.claude/CLAUDE.md 里放一句「遇到多种实现方案时，列出选项让我选，而不是默默替我决定」。这条对你每个项目都成立，所以放用户级最省事——一次配上之后，再不用在某个新项目里重新交代这句话。

💡 一句话总结：个人习惯写用户级（~/.claude/CLAUDE.md），团队规矩写项目级（./CLAUDE.md 进 git），大仓库再用子目录级按模块拆。

03 加载顺序：项目级为什么「后说话更管用」

上一节列了三层，那它们同时存在时，谁说了算？这是另一个高频误区，得讲准。

官方的规则：从最广的范围到最具体的范围依次加载，越靠近你启动目录的指令，越晚被读到。

具体怎么排？Claude Code 从你当前所在的目录一路往上走，沿途每一层有 CLAUDE.md 就收进来，最后拼成一整块上下文。顺序大致是：

用户级 ~/.claude/CLAUDE.md
        ↓（先读）
（目录树里更靠上的）父目录 CLAUDE.md
        ↓
项目根 ./CLAUDE.md
        ↓（后读，离你最近）
子目录 CLAUDE.md（只有 Claude 读那个目录的文件时才加进来）

注意两个要点，都来自官方文档：

第一，所有找到的文件是「拼接」不是「覆盖」。 它们全都进上下文，不是后面的把前面的顶掉。所以用户级和项目级同时生效，不存在「设了项目级，用户级就失效」。

第二，更靠近工作目录的指令「最后被读到」。 当两条规矩打架时——比如用户级说「字符串用单引号」、项目级说「用双引号」——离得近的项目级因为后说话，通常更占优。说白了，项目规矩能盖过你的个人习惯，这正是团队协作想要的效果。

这张图把三层从上到下叠在一起：用户级（管所有项目、最先读）、项目级（当前项目、进 git）、子目录级（离代码最近、冲突时占优）；右侧箭头标出「从上往下」的加载顺序，底部那条铁律点明——三层是拼接、不是覆盖，越靠近代码的越晚读、说了算。

这里还得纠一个常见的错误说法。网上不少教程把优先级写成「项目本地 → 项目根 → 子目录 → 全局」，这跟官方描述的加载方向是反的。很容易被这种说法带偏，但翻官方文档就清楚了：官方明确说是「从最广泛的范围到最具体的范围」加载，项目指令出现在用户指令之后。以官方为准，别记反了。

还有个贴心细节：项目根的 CLAUDE.md 在 /compact（压缩对话）之后会自动从磁盘重新读回来，不会丢。但子目录里那些嵌套的 CLAUDE.md 不会自动重注入，得等 Claude 下次读那个目录的文件才回来。所以重要规矩尽量放项目根，别埋太深。

💡 一句话总结：多层 CLAUDE.md 是拼接不是覆盖，越靠近工作目录的越晚读、冲突时越占优，所以项目规矩能盖过个人习惯——别把官方的加载方向记反了。

04 该写什么 vs 不该写什么

这一节是全篇的命门。CLAUDE.md 写不好，九成是栽在「该写的没写清，不该写的塞一堆」。

先说该写的——官方一句话点透：写「Claude 应该在每个会话中都保持的事实」。 翻成清单就是这五类：

其中常用命令是被参考最频繁的——Claude 跑测试、构建前会先来这儿翻命令，省得它瞎猜或者用错。禁止清单则是防它「聪明但闯祸」的护栏：哪些目录是遗留代码只读不改、哪个文件改之前必须先告诉你、哪些密钥文件禁止输出内容。

再说不该写的，这才是新手翻车重灾区：

• ❌ 长篇大论的背景：公司介绍、产品愿景、技术选型的历史渊源——Claude 写代码用不上，纯占上下文。
• ❌ 过时信息：换了包管理器却没更新 CLAUDE.md，里面还写着 npm，结果误导它。
• ❌ 看代码就知道的东西：别去复述目录结构里每个文件干啥、别把 ESLint 配置已经定义的代码风格再抄一遍。Claude 自己会读代码，复述等于白占空间。

官方对这事的态度很明确，专门给了大小红线：

每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度。

为什么 200 行这么要紧？因为 CLAUDE.md 跟你的对话抢同一个上下文窗口。你塞进去三百行废话，等于一开局就占掉一大块工作台，留给真正任务的空间反而缩水——而且重要规矩淹在废话里，注意力被稀释，遵守度不升反降。这就是开头那个「三百行没人听」的病根。

有个好用的土办法：写每一条之前先自问一句「这条 Claude 看代码能不能自己推出来？能，就删」。 就靠这一刀，能把一份接手项目的 CLAUDE.md 从三百多行砍到八十行，留下的全是它推不出来的硬约束——砍完之后，它用错包管理器的次数肉眼可见地降下去。

💡 一句话总结：写「每个会话都该记住的事实」（概述 / 技术栈 / 命令 / 约定 / 禁区），删一切 Claude 看代码能自己推出来的东西，全文压在 200 行以内。

05 引用其他文件：@ 语法与它的代价

有时候你项目里已经有现成的规范文档了——一份 API 设计指南、一份数据库约定。没必要把内容复制进 CLAUDE.md，用 @ 语法引用就行。

写法很简单，在 CLAUDE.md 里任意位置写 @ 加路径：

有关项目概述，请参阅 @README，可用命令见 @package.json。

# 其他指令
- git 工作流 @docs/git-instructions.md

Claude 读 CLAUDE.md 时，会把这些引用的文件内容展开、一起加载进上下文。几个官方明确的细节，记牢了别踩坑：

• 相对路径相对于「包含引用的那个文件」解析，不是相对于你的工作目录。这点容易搞错。
• 绝对路径也行；引用的文件还能再引用别的文件，最多递归四跳。
• 第一次遇到项目外的引用，Claude Code 会弹个批准框列出这些文件让你确认；你拒了，这个引用就一直禁用，框也不再弹。

但这里有个最关键的认知，官方反复强调，也是最容易踩的坑：

导入的文件在启动时展开并加载到上下文中。分割到 @path 导入有助于组织，但不会减少上下文，因为导入的文件在启动时加载。

说白了：@ 引用是「整理」，不是「省钱」。 很多人以为把内容拆到外部文件、CLAUDE.md 本体变短了，上下文就省了——错。 被引用的文件照样在开局全量加载进窗口，该占的上下文一点没少。设想把一份五百行的规范拆出去用 @ 引，以为瘦身了，结果 /context（查看上下文占用）一看，该吃的 token 一个没落下。

所以原则是：@ 引用用来让结构更清爽、便于人类维护，但要省上下文，得靠「精简内容」或「路径范围规则」，不是靠拆文件。 引用的单个文件也别太大，太大照样拖累。

顺带提一个相关的：如果你有些纯个人、不想进 git 的项目偏好（比如你本地的沙箱 URL、爱用的测试数据），别写进 ./CLAUDE.md，写进 ./CLAUDE.local.md，再把它加进 .gitignore。它跟 CLAUDE.md 一起加载、处理方式完全一样，只是不会被提交、不影响队友。

💡 一句话总结：@路径 把外部文档引进来是为了「结构清爽」，但被引用的内容照样全量进上下文、不省 token；想省得真删内容；私人偏好放 CLAUDE.local.md 并 gitignore。

06 维护：会话里随手补、定期精简

CLAUDE.md 不是写完一次就供起来的，它得跟着项目长。这节讲两个维护动作：怎么随手补一条、怎么定期瘦身。

会话里临时想补一条怎么办

经常是这样：聊着聊着你纠正了 Claude 一句，心想「这条以后每次都该守，得记下来」。最省事的官方做法——直接在对话里跟它说：

把「数据库操作必须走 Service 层，别在路由里直接写 SQL」这条加进 CLAUDE.md

Claude 会帮你把这条写进 CLAUDE.md 文件。你也可以随时敲 /memory 命令，它会列出当前会话加载的所有 CLAUDE.md、CLAUDE.local.md 和规则文件，点一下就在编辑器里打开，手动改也行。想让 Claude 自己决定怎么措辞就用第一种；想精确控制措辞就用 /memory 自己编辑。

ℹ️ 一个版本差异提醒：早期 Claude Code 里，在输入框用 # 开头打一句话能快速追加记忆。新版本里这套交互已经变了——以官方现在的做法为准：要么直接让 Claude「加进 CLAUDE.md」，要么用 /memory 自己编辑。你敲一句「记住 xxx」，Claude 默认多半存进它自己的自动记忆（auto-memory，那是 25「记忆系统」 的话题）；想明确进 CLAUDE.md，就把「加进 CLAUDE.md」这句话说全。

定期精简，删掉过时和打架的

官方点名的一个隐患：两条规矩互相矛盾时，Claude 可能随便挑一条听。 所以得定期回头审视，把过时的、冲突的清掉。该触发精简的时机：

• 换了包管理器 / 构建工具（旧命令必须删，留着就是误导）
• 加了或去了重要依赖
• 定了新的编程约定（顺手检查跟老规矩冲不冲突）
• 发现 CLAUDE.md 又悄悄涨过 200 行

判断一条规矩好不好，就看它像不像「规则」而非「散文」。官方给的对照特别实用，我整理成表：

左边那种话等于没说——「整洁」「尽量」「注意」全是主观词，Claude 没法验证、自然没法稳定执行。右边每一条都具体到能验证：50 行、必须有测试、必须过某函数。官方的原话就是「编写具体到足以验证的指令」。

写 CLAUDE.md 不妨养成一个硬习惯：每条规矩写完，自己当裁判判一下「这条能不能用一眼看出有没有违反」。判不了的，就是写虚了，回去改具体。

💡 一句话总结：随手补一条就让 Claude「加进 CLAUDE.md」或用 /memory 编辑；定期删过时和打架的规矩；好规矩长得像「能一眼验证的规则」，不是「整洁、尽量」这种散文。

07 动手：给玩具项目配一份合格的 CLAUDE.md

光说不练没用。下面用一个最小项目，走一遍「建文件 → 写规矩 → 验证加载」的完整流程。跟着敲，五分钟搞定。

第一步：建个玩具项目并初始化 git（Mac / Linux）

mkdir claude-md-demo
cd claude-md-demo
git init
echo 'def add(a, b):
    return a + b' > main.py

预期：claude-md-demo 目录里有一个 main.py 和一个 .git 目录。git 初始化是为了让这份 CLAUDE.md 能进版本控制（团队共享的前提）。

第二步：手写一份精简的项目级 CLAUDE.md

用你顺手的编辑器，在项目根目录新建 CLAUDE.md，贴入下面这份（注意它一共没几行——这就是好 CLAUDE.md 该有的样子）：

# add-demo — 一个演示用的最小 Python 项目

只有一个 `add` 函数，用来演示 CLAUDE.md 怎么写。

## 常用命令
- `python -m pytest` —— 运行测试

## 编程约定
- 所有函数必须有类型注解
- 字符串一律用双引号

## 注意事项
- 不要修改 `main.py` 里 `add` 的函数签名，只能在内部加逻辑

预期：项目根目录下出现 CLAUDE.md，内容就是上面这几节。全文不到 15 行——记住这个篇幅感，真实项目也别失控膨胀。

第三步：启动 Claude，验证它真读到了

在项目目录里启动：

claude

启动后，敲这个命令确认加载情况：

/memory

预期：列表里能看到你刚写的 ./CLAUDE.md。只要它在列表里，就说明 Claude 这次会话确实把它装进上下文了。 这一步是官方推荐的排查手段——要是某条规矩没被遵守，第一件事就是 /memory 看文件到底加载了没。

第四步：让它干一件「踩约定」的活，看它守不守规矩

退出 /memory 回到输入框，敲：

给 add 函数加上类型注解

预期：Claude 给出的 diff 里，类型注解用的是项目约定的写法，而且不会去动函数签名以外它被禁止改的部分。如果它老老实实按你 CLAUDE.md 里「函数必须有类型注解」来改——恭喜，这份入职手册生效了。

⚠️ 万一发现它没按 CLAUDE.md 来：先 /memory 确认文件加载了；再检查那条规矩是不是写得太模糊（「整洁」这种）；最后看有没有两条规矩在打架。这三步是官方给的标准排查顺序，照着走基本能定位。

💡 一句话总结：走一遍「建文件 → 写不到 15 行的精简规矩 → /memory 确认加载 → 让它干活验证守不守规矩」，没生效就按 /memory → 查模糊 → 查冲突这套官方顺序排查。

08 小结

这一篇你把 CLAUDE.md 这个「Claude 的项目记忆」从头到尾摸清了：

你现在应该能： 判断一条信息该不该进 CLAUDE.md、放哪一层；写出具体到能验证的规矩而不是空话；用 @ 引用外部文档同时清楚它的上下文代价；项目跑久了知道怎么随手补、定期瘦身。一句话——你能写出一份 Claude 真愿意听、而不是写了三百行没人理的 CLAUDE.md 了。

下一篇 19「上下文管理」——这篇里反复提到「CLAUDE.md 会占上下文窗口」「@ 引用照样全量加载」，那这个上下文窗口到底是什么、满了会怎样、/context 和 /compact 又怎么用？下一篇就专门把这块工作台讲透。留个小思考：你觉得一份 CLAUDE.md 占掉的 token，和你一整段对话比，哪个更耗？

19 · 上下文管理：别让它「失忆」也别烧爆 token

刚上手 Claude Code 那阵子，很容易干一件挺蠢的事。

接手一个不熟的中型项目，想着「让它先把整个仓库读一遍再动手，这样它最懂全局」，于是甩了一句：「把这个项目所有文件都读一遍，然后告诉我架构。」

结果呢？它真就一个文件接一个文件地读，终端哗哗滚屏，读了二十几个文件之后明显变慢、变迟钝。等你开始让它改一个登录的 bug，它居然反问「你说的 auth 模块在哪个文件」——那文件它十分钟前刚读过。活没干完，它先「失忆」了，token 也烧了一大把。

搞明白之后才知道：上下文窗口不是越满越好，它满了反而会变蠢。今天就把这块「工作台」讲透——它是什么、塞满了会怎样、怎么用 /compact 和 /clear 收拾、怎么实时看用量，以及怎么从源头省 token。

看完这一篇，你会拿到：

• 一个能让你彻底想明白「上下文窗口」的类比，以及它满了之后到底会发生什么
• /compact（压缩）、/clear（清空）、直接新开会话，三者分别什么时候用，一张表说清
• 用 /context、/usage 实时盯住占用的具体动作 + 预期输出
• 五个天天用得上的省 token 习惯，每个都来自真实踩坑
• 搞懂「自动压缩」（auto-compact）到底在背后干了啥，别再被它突然打断吓一跳

01 上下文窗口：Claude 的「工作台」有多大

先把这个最核心的概念立住。

上下文窗口（context window） —— 是 Claude 在这一次会话里能同时「看到」的全部内容的总容量，按 token（模型处理文本的最小计费单位）计。

它装的不只是你打的字，而是一整摊东西。官方 context-window.md 把它拆得很清楚，我给你翻成人话：

看到没？你以为对话主要是「你说的话」，其实大头是它读的文件和命令输出。前面那次让它读二十几个文件，等于把工作台一下子堆满了别的工程图纸，留给「干活」的空地就没多少了。

类比：工作台大小。 把 Claude 想成一个在工作台上干活的木匠。台子就这么大，图纸、工具、半成品、你递给他的便签，全得摊在这张台子上。台子大，他能同时照顾的东西多；台子塞满了，他就得把早先的图纸推到一边——那张图纸上的信息，他就「忘」了。

这块台子有多大？取决于你用的模型。多数模型在 20 万 token 量级，部分模型（比如带 [1m] 标识的）能到 100 万。但记住一句话比记数字更有用：

台子再大也有边界，塞得越满，它越笨。

💡 一句话总结：上下文窗口就是 Claude 的工作台，装的大头是它读的文件而不是你说的话；台子有边界，塞满了它就开始往外「掉」早期信息。

02 工作台塞满了会怎样：它会变慢、变蠢、甚至「失忆」

这是本篇最该记住的判断：上下文不是越满越好，满到一定程度，Claude 的表现会肉眼可见地下滑。

为什么？台子上的东西越多，模型的「注意力」就被摊得越薄，早先那些不相关的内容开始干扰当前任务。业内管这个现象叫「上下文衰退」（context rot）。

你怎么知道它「衰退」了？我总结了几个一线症状，命中任意一条就该警觉：

• 它开始前后矛盾，忘了你俩之前明明已经定好的方案
• 回答变得又模糊又笼统，细节越来越少，开始说正确的废话
• 反复问你已经回答过的东西（就像开头那句「auth 在哪个文件」）
• 同一个问题，你纠正它两遍以上还在原地打转

比如写数据迁移脚本，聊了一个多小时反复调试，到后面它把前半段我们一起否决掉的错误方案又端了上来。不是它能力退化了，是上下文被一小时的调试垃圾污染了。

那台子真满了 Claude 会怎么办？它会自动压缩（auto-compact）——第 05 节细讲。这里先知道：它是个被动保命动作，时机不由你定，还可能在关键任务的当口突然打断你。

所以正确姿势是：别等它自动压缩，你主动管。怎么管？接着往下。

💡 一句话总结：上下文塞满会触发「上下文衰退」——前后矛盾、变笼统、反复问；与其在污染的台子上反复纠正，不如主动清理。

03 两把扫帚：/compact 压缩 vs /clear 清空

收拾工作台，Claude Code 给了你两把扫帚，用途完全不同，千万别用混。

/compact：把台子上的东西「打包压扁」，但留着

/compact（压缩）干的事是：把当前这一长串对话历史，总结成一份精简摘要，然后用摘要替换掉原来的逐字记录，继续在同一个任务上往下干。

类比：把摊了一桌的草稿纸整理成一页要点。 你跟同事讨论了俩小时，桌上堆满了画废的草图。/compact 就是把这堆草图归纳成一页「我们最终定了 A、否了 B、下一步做 C」的要点，腾出桌面，但结论还在。

关键一点，它支持带指令告诉它重点保留什么：

/compact 保留认证流程的架构决策和已确认的 API 格式，丢掉调试中的无效尝试

官方 costs.md 给的英文例子是 /compact Focus on code samples and API usage（重点保留代码示例和 API 用法），一个意思。

什么时候用 /compact：任务还没干完、上下文却快满了，但前面聊的东西后面还要用。比如一个功能做到一半，前期定的架构决策不能丢，但中间一堆试错的命令输出可以扔。

/clear：直接清空，从头再来

/clear（清空）更狠：把整个对话历史全清掉，等于开了一个全新的会话。

但别怕——/clear 不会动你的 CLAUDE.md 和自动记忆，它俩在新会话里照样自动加载。你丢的只是「这次对话聊过的内容」，项目规范和长期记忆都还在。

类比：换个全新的任务，干脆收拾干净台面再开工。 上一个活儿干完了，下一个活儿跟它八竿子打不着，那把台子整个清空，比留着上一摊干扰更利索。

官方 costs.md 原话就建议：切换到不相关的工作时，用 /clear 重新开始，因为「陈旧的上下文会在随后的每条消息上浪费 token」。

这里有条值得定下来的铁规矩：同一个问题纠正两遍它还不对，就别在这个会话里耗了，直接 /clear，带着这两遍学到的教训，重写一个更精准的提示词从头问。干净的台子 + 更好的提示，几乎总是赢过在污染的上下文里继续掰扯——这是实测下来最值钱的一条经验。

💡 一句话总结：/compact 是「打包压扁、留着接着用」，/clear 是「整个清空、换活儿重开」；纠正两遍还不对，别犹豫，/clear。

04 监控用量：用 /context 和 /usage 看清台子还剩多少

凭感觉判断「是不是快满了」太玄学。Claude Code 给了两个命令让你看实数，这俩名字别记混。

/context：看台子被什么占满了

/context

/context 会用彩色格子图可视化当前上下文的实时占用，并按类别列出——系统提示占多少、CLAUDE.md 占多少、各个 MCP 服务占多少、对话历史占多少，还会给优化建议。官方 context-window.md 明确：想知道任意时刻你的真实上下文用量，就跑 /context。

一个值得养成的习惯是：开始一个大任务之前先 /context 看一眼底子。要是发现某个 MCP 服务白占了一大块、或者 CLAUDE.md 臃肿得离谱，先收拾了再干活。

配套还有个 /memory 命令，用来检查启动时到底加载了哪些 CLAUDE.md 和自动记忆文件——怀疑它「记错了」什么的时候用它查。

/usage：看这次会话烧了多少 token / 多少钱

/usage

/usage 顶部的 Session 块给的是当前会话的 token 使用统计，还会按本地估算折算成美元。官方 costs.md 给的样子大致是这样：

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

预期输出说明：Total cost 是这次会话的预估花费（本地算的，可能和真实账单有出入，权威数字以 Claude Console 为准）；Total duration (API) 是真正调用模型的耗时；Total duration (wall) 是你开着这个会话的总时长。

⚠️ 提醒：Pro / Max 订阅用户的会话成本是包含在订阅里的，这个美元数跟你的账单没直接关系，看个相对量级就行。具体的套餐和计费咱们在第 06 篇讲过了，这篇只从「上下文」的角度看 token。

嫌每次手动敲麻烦？官方还支持把上下文用量常驻显示在状态栏（statusline），让它一直挂在屏幕上。具体配置方法见官方 statusline 文档，本篇不展开。

💡 一句话总结：/context 看「台子被什么占了」，/usage 看「这次烧了多少 token / 多少钱」；大任务开干前先 /context 看一眼底子。

05 自动压缩（auto-compact）：它会自己保命，但你别指望它

前面几次提到「自动压缩」，这节说清它到底是个啥。

auto-compact（自动压缩） —— 是 Claude Code 内置的保命机制：当上下文快要顶到窗口上限时，它会自动把对话历史总结成摘要，腾出空间继续干，省得你直接撞墙报错。官方 costs.md 把它和 prompt caching 并列，作为 Claude Code「自动优化成本」的两个手段之一。

类比：流水线上的自动卸料。 传送带快堆满了，系统自己把旧料归拢压实，免得整条线卡死。你不用管，它自动触发。

听起来挺贴心，但我劝你别依赖它，原因有两个：

第一，它的触发时机不由你。很可能你正让它干一个关键步骤，台子刚好满了，它「啪」地停下来先去压缩——节奏全被打断。

第二，自动压缩是「无指令」压缩。它触发的那一刻，恰恰是上下文最满、模型最迟钝的时候。这时候它自己决定丢什么、留什么，很可能把你认为重要的东西给压没了。

所以正确做法是主动出手：在你感觉对话变长、/context 显示占用偏高的时候，自己先 /compact 一下，并且带上指令告诉它保留重点。主动压缩有两个好处——时机你说了算，保留什么你也说了算。

还有一招更省心：把压缩偏好直接写进 CLAUDE.md。官方 costs.md 给的写法是在 CLAUDE.md 里加一段：

# Compact instructions

When you are using compact, please focus on test output and code changes

这样每次压缩（不管手动还是自动）它都会优先保留你指定的内容，相当于给自动压缩上了个保险。比如在常用项目的 CLAUDE.md 里写一句「压缩时保留已确认的方案决策和接口约定」，就省得每次手动叮嘱了。

💡 一句话总结：自动压缩是保命用的，但它打断你、还可能压没重要信息；与其等它，不如自己主动 /compact 带指令，或在 CLAUDE.md 里把保留偏好写死。

06 省 token 五招：从源头别让台子那么快满

收拾台子是补救，不让它那么快堆满才是上策。下面五招天天用得上，每招都从「上下文」角度出发，跟套餐价格无关。

第一招：练手别拿大项目。 跟第 07 篇说的一样——学习和试验阶段，建个三五个文件的玩具项目。文件少，它读得少，台子干净，你也看得清它干了啥。开头那个「读二十几个文件失忆」的坑，根子就是一上来拿了个不熟的中型仓库。

第二招：用 @ 精准指文件，别让它满仓库找。 与其说「修一下登录的 bug」让它一个个文件去翻，不如直接 @src/api/auth.ts 修复 401 的问题。官方 costs.md 说得很直白：模糊请求触发广泛扫描，具体请求让它以最少的文件读取高效工作。@ 就是把它的目光直接钉在那个文件上。

第三招：别一次塞太多需求。 一口气甩五个不相关的任务，它读的文件、产生的输出会把台子撑爆。拆成五次小提问，每次干完一件，台子始终清爽。

第四招：长任务拆分，干完一段就清。 一个大功能别指望一个会话从头扛到尾。做完一个相对独立的阶段，/compact 收一次；切到完全无关的部分，/clear 重开。

第五招：把冗长操作丢给子代理（subagent）。 跑测试、翻大量日志、查文档这种会产出海量输出的活儿，交给子代理去做——它在自己独立的工作台上折腾，只把结论摘要带回你的主对话。官方 context-window.md 举的例子里，子代理读了 6100 token 的文件，回到主上下文只占 420 token。子代理后面有专篇，这里先知道它是省上下文的利器。（链接届时补充）

把「补救」和「预防」放一起对比，你就知道该往哪使劲：

💡 一句话总结：收拾台子是补救，少读文件、拆小任务、丢给子代理才是预防；最该养成的肌肉记忆是——提需求时用 @ 把文件指准。

07 动手：三步把上下文管理走一遍

光看不练记不住。下面用一个最小流程，让你亲眼看到上下文怎么涨、/compact 怎么把它压下去。在任意一个项目目录里启动 claude，跟着走。

第一步：开局先看底子

启动 Claude 后，第一件事先敲：

/context

预期：终端列出当前上下文的分类占用——你会看到系统提示、CLAUDE.md 等已经占了一块（还没聊天就有占用，这很正常），底部给一个总用量和优化建议。记下这个初始数字。

第二步：故意「喂」它一些内容，再看变化

随便让它读几个文件、聊几轮，比如：

读一下这个项目的主要源码文件，给我讲讲整体结构

等它读完、回答完，再敲一次：

/context

预期：占用明显涨上去了，对话历史和文件那几栏数字变大。这就是「工作台被填满」的过程，你亲眼看到了。

第三步：用 /compact 把它压回去

/compact 保留这个项目的整体结构结论，丢掉逐个文件的原始内容

预期：终端出现一条类似「Conversation compacted」（对话已压缩）的提示，压缩在后台静默完成，不会把摘要刷一屏给你。压缩完再 /context 看一眼，对话历史那栏的占用应该掉下来了——结构结论它还记得，但逐个文件的原始字节被压成了摘要。

对照验证：压缩前后各跑一次 /context，对话历史的 token 数前高后低，就说明 /compact 生效了。想验证它「没失忆」，接着问一句「刚才你总结的项目结构是什么」，它应该还能答上来。

⚠️ 一个细节：压缩是有损操作。它保留你指定的重点和大致脉络，但早先工具输出的逐字内容会被丢掉。所以真正重要的结论，养成习惯按第 18 篇讲的做法落到 CLAUDE.md——直接让 Claude「加进 CLAUDE.md」，或用 /memory 自己编辑，比压在对话里保险。

💡 一句话总结：跑一遍 /context → 喂内容 → /compact → 再 /context，你就亲眼看到上下文怎么涨、压缩怎么把它压回去；前后对比对话历史的 token 数，就知道有没有生效。

08 小结

这一篇咱们把「上下文窗口」这块工作台从里到外摸了一遍：

你现在应该能： 看懂上下文窗口里装着什么、为什么它满了 Claude 会变蠢；在该压缩时用 /compact、该重开时用 /clear；用 /context 和 /usage 实时盯住占用；并且从提需求那一刻起就用一堆省 token 的习惯，让台子始终留着干活的空地。

说到底，管理上下文的本质就一句话：把 Claude 有限的注意力，省着用在真正要紧的事情上。

这张图把上下文窗口比成工作台：塞满了文件和对话（图里到约 92%），就靠 /compact 把一摞聊天压成一页要点（留着继续用），或 /clear 把整张台面扫空（从头开始）——前者保信息、后者图干净。

下一篇 20 · 权限配置 ——这一篇咱们管的是 Claude「能记住多少」，下一篇要管的是它「能动手做多少」。它读文件、改代码、跑命令到底哪些要先问你、哪些可以放行，怎么配一套既安全又顺手的权限规则？留个问题给你先想想：你愿意让它在没你点头的情况下，直接跑 git push 吗？