你有没有盯着Claude Code的光标闪了五分钟，不知道它在干嘛
上周我让Claude Code帮我重构一个有47个组件的React项目。敲下回车之后，屏幕上的光标就开始一闪一闪。
一分钟过去了，没动静。
三分钟过去了，还是没动静。
我开始怀疑它是不是卡了，是不是理解错了我的意思，是不是正在往我代码里塞什么奇怪的东西。后来我在CLAUDE.md里加了一段进度汇报的提示词，这个问题就解决了。但在那之前，这种感觉就像你点了外卖，配送页面显示"骑手已接单"之后就再没更新过——你不知道他是已经到了你楼下，还是骑到了隔壁小区。
这个问题在Claude Code用户里特别普遍。Reddit上有人吐槽说"我让它处理100个文件，等了8分钟什么都没看到，最后ctrl+c了重来"。GitHub的issue区里也有人提，说长任务的用户体验像在看一面白墙。
但说实话，Claude Code本身是流式输出的，它一直在干活。问题不是它不干活，是它不汇报。就像你公司里那种闷头做事的程序员，活干得不错，但从来不在群里说一声"我这边搞完了"，搞得大家都不知道项目进展到哪了。
我花了大概两个月时间，在30多个真实项目里反复测试，最后找到一套让Claude Code主动汇报进度的方法。核心就是一段写在CLAUDE.md里的提示词。
先看效果：加了这段提示词之后什么样
贴一段对比。
没加提示词之前，让Claude Code整理一个有200多个文件的项目：
> 帮我把这个项目的所有测试文件按模块重新组织
（光标闪烁...长时间沉默...突然一大段输出涌出来）
你等了4分钟，心里没底，不知道它在做什么。
加了提示词之后，同样的任务：
> /进度 帮我把这个项目的所有测试文件按模块重新组织
📌 任务拆解（共4步）：
1. 扫描所有测试文件，统计数量和分布
2. 分析现有模块结构，确定目标目录
3. 逐个移动文件并更新import路径
4. 运行测试验证没有破坏
⏳ 第1步：正在扫描...
找到 47 个测试文件，分布在 12 个目录
其中 23 个在根目录的 __tests__ 下，15 个散落在各组件目录，9 个在 utils 里
✅ 第1步完成。进入第2步...
⏳ 第2步：分析模块结构...
识别出 6 个核心模块：auth、dashboard、payment、user、common、api
建议目录结构：tests/{模块名}/__tests__/
区别一目了然。你知道它打算怎么干，干到哪了，接下来干什么。
CLAUDE.md里加什么：核心提示词配方
打开你项目根目录的 CLAUDE.md（没有的话新建一个），在里面加上这段：
## 工作模式：进度汇报
当用户在指令前加上「/进度」前缀时，启用进度汇报模式：
1. **任务拆解**：先把任务拆成3-7个可执行的小步骤，列出来让用户确认
2. **逐步汇报**：每完成一个步骤，立刻报告：
- 这一步做了什么
- 关键数据（处理了多少文件、改了多少行、发现了什么问题）
- 下一步要做什么
3. **异常即报**：遇到任何问题或需要决策的地方，立刻停下来问，不要自己猜
示例触发方式：
- /进度 整理所有文件
- /进度 批量处理图片
- /进度 分析数据文件
就这么多。保存，下次对话的时候Claude Code会自动读取。
为什么管用？因为CLAUDE.md是Claude Code启动时第一个读的文件，相当于你给新来的实习生写了一份入职手册，里面写了"干活要汇报"。
五个实战模板，覆盖你80%的使用场景
光靠上面那段通用提示词还不够。不同类型的任务，需要汇报的信息不一样。下面这5个模板是我在实际项目中反复打磨出来的。
模板一：批量文件处理
最常见的场景。你让Claude Code处理几十上百个文件，想知道它处理到第几个了。
## 批量文件处理汇报规则
处理多个文件时，按以下格式汇报：
- 开始前：列出要处理的文件总数和处理计划
- 每处理完5个文件（或每完成一个目录），汇报一次当前进度
- 格式：「已完成 X/Y，当前正在处理 [文件名]，预计还需处理 Z 个」
- 遇到处理失败的文件，单独标记，不要跳过也不要停下
我用这个模板处理过一个遗留项目的代码迁移，200多个文件从JavaScript转TypeScript。Claude Code每处理完5个文件就报一次数，整个过程花了12分钟，我全程知道进展。中间有3个文件因为循环引用转换失败，它也立刻标出来了，没偷偷跳过去。
模板二：代码重构
重构是最容易出岔子的操作，你需要更密集的反馈。
## 代码重构汇报规则
执行重构任务时：
- 第一步必须列出所有受影响的文件和函数
- 每修改一个文件前，说明要改什么、为什么改
- 每修改一个文件后，说明改了什么、影响了哪些依赖
- 如果改动可能破坏现有测试，提前警告
这个模板救过我一次。当时重构一个支付模块，Claude Code按模板要求在修改 payment-service.ts 之前报告说"这个文件被 12 个其他文件引用"，我才意识到这次改动的影响面比我预想的大得多，让它先列出所有依赖关系再动手。
模板三：数据分析和处理
分析类任务的特点是中间步骤不可见，你不知道它看到了什么。
## 数据分析汇报规则
分析数据时：
- 先报告数据概览：总量、格式、质量（有没有空值、异常值）
- 每个分析维度完成后，先给出关键发现的一句话摘要
- 发现异常数据时，给出具体的行号或记录ID
- 最终结论之前，先列出分析依据
模板四：环境搭建和配置
配环境这种事最怕中间某一步出错了不知道。
## 环境配置汇报规则
配置环境或安装依赖时：
- 列出完整的操作步骤清单
- 每执行一个命令前，说明这个命令的作用
- 每执行一个命令后，报告结果（成功/失败/警告）
- 遇到版本冲突或依赖问题，给出解决方案选项让用户选择，不要自己拿主意
模板五：调试排查
Debug的时候你最想知道的是"它查到哪了"。
## 调试排查汇报规则
排查bug时：
- 先列出排查思路（从哪里开始查，怀疑哪些地方）
- 每排除一个可能的原因，报告排除理由
- 找到关键线索时，标记「关键发现」
- 缩小范围后，给出结论和修复方案
上次用这个模板排查一个生产环境的内存泄漏问题。Claude Code按汇报规则一步步排除了7个可能的原因，第8个命中，是一个没有清理的事件监听器。看它排查的过程就像跟着侦探破案，推理链条一环扣一环。
进阶玩法一：用自定义命令替代手动前缀
每次都在指令前面敲 /进度 是不是有点烦？可以做成Claude Code的自定义命令。
在项目根目录创建 .claude/commands/progress.md：
---
description: 以进度汇报模式执行任务
---
请以进度汇报模式执行以下任务。要求：
1. 先将任务拆解为3-7个小步骤
2. 每完成一步立即汇报进展和关键数据
3. 遇到异常立即停下来确认
任务内容：$ARGUMENTS
保存之后，你在Claude Code里就能直接用：
/progress 重构auth模块
/progress 把所有CSS改成Tailwind
$ARGUMENTS 会自动替换成你后面跟的内容。这比每次手动加前缀方便多了。
进阶玩法二：配合Tasks API做持久化追踪
Claude Code从 v2.1.16 开始内置了Tasks API（以前叫TodoWrite）。你可以在CLAUDE.md里加一段，让进度汇报和任务列表联动：
## 进度汇报增强
进度汇报模式下，同时使用Tasks工具：
- 任务拆解后，用TaskCreate为每个步骤创建任务
- 开始某步骤时，用TaskUpdate标记为in_progress
- 完成某步骤时，用TaskUpdate标记为completed
- 这样即使对话中断，任务进度也不会丢
这解决了一个真实痛点：Claude Code的对话如果太长会被压缩，之前汇报过的进度信息可能被截掉。但Tasks API的数据存在文件系统里（~/.claude/tasks/），不受对话压缩影响。
我在一个持续3天的大型迁移项目中用了这个方案。每次重新打开Claude Code，它都能通过任务列表接上上次的进度，省得我重新交代背景。
进阶玩法三：Status Line实时进度条
Claude Code支持自定义状态栏（Status Line），底部那一行可以显示任何你想看的信息。你可以配一个脚本，把当前任务进度显示在底部。
在你的 Claude Code 设置里配置一个状态栏脚本：
#!/bin/bash
# 读取Claude Code传来的JSON数据
read -r input
# 提取当前对话的token使用情况
tokens=$(echo "$input" | jq -r '.tokenUsage.total // 0')
cost=$(echo "$input" | jq -r '.cost // "0.00"')
model=$(echo "$input" | jq -r '.model // "unknown"')
echo "🔄 ${model} | Tokens: ${tokens} | Cost: \$${cost}"
或者更简单——直接在Claude Code里输入 /statusline，用自然语言描述你想看到什么：
/statusline 显示当前模型名称、已用token数和费用
它会自动帮你生成脚本并配置好。
状态栏不直接显示任务进度，但它能告诉你Claude Code是不是还在跑（token数在增加），以及当前这个任务花了多少钱。和进度汇报模式搭配着用，你能掌握的信息就比较全面了。
为什么CLAUDE.md提示词能改变Claude Code的行为
你可能好奇，为什么往CLAUDE.md里写几段话就能改变Claude Code的行为？
这跟Claude的工作方式有关。Claude Code启动的时候会把CLAUDE.md的内容加到系统提示词（system prompt）里。系统提示词相当于这个AI的"行为准则"，权重比你在对话里说的话更高。
打个比方。你在群里跟同事说"以后干完活在群里说一声"，他可能听了，也可能忘了。但如果你把这条写进公司的员工手册，变成"工作规范"，那遵守概率就高多了。CLAUDE.md对Claude Code来说就是这份手册。
但也不是什么都能往里写。Anthropic的官方建议是，CLAUDE.md里的有效指令控制在150-200条以内。系统提示词本身已经用掉了大概50条的"注意力配额"，你的自定义指令太多的话，Claude Code会开始选择性忽略——跟人一样，规矩太多了哪条都记不住。
所以，进度汇报的提示词要精炼。写短了比写长了好。
进度汇报提示词踩过的坑，你不用再踩
用了两个月，有几个教训值得分享。
坑一：步骤拆得太细，反而变慢了
我最开始的提示词要求"每处理一个文件就汇报一次"。结果呢？Claude Code处理200个文件，中间插入了200段汇报文字，整体耗时翻了一倍。后来改成"每5个文件汇报一次"，速度和信息量才平衡。
找到一个合适的汇报频率很关键。我的经验是：文件级操作每5-10个汇报一次，模块级操作每完成一个模块汇报一次，调试类任务每排除一个可能性汇报一次。
坑二：提示词和任务冲突了
有一次我在CLAUDE.md里写了"遇到问题立刻停下来问"，然后让Claude Code自动修复一个有30多个lint错误的项目。它每修一个错就停下来问我"这样改行不行"——30多次。那天我点"确认"点到手酸。
后来我加了一个条件限定：
遇到以下情况停下来确认：
- 需要删除文件
- 需要修改API接口
- 修改可能影响超过5个文件
以下情况自行处理并汇报：
- 格式修复
- import路径调整
- 类型标注补充
分清哪些决策需要人介入，哪些可以放手让它自己处理，这条提示词的性价比特别高。
坑三：忘了加"不要重复已有上下文"
Claude Code在汇报进度的时候，有时候会把之前已经说过的背景信息再说一遍。200个文件的任务，它每次汇报都要重复一遍"我们的目标是重新组织测试文件"。浪费token不说，看着也烦。
在提示词里加一句就好了：
汇报时不要重复已知信息，只说新进展和新发现。
一个完整的CLAUDE.md配置示例
把上面说的整合起来，这是我目前在用的完整配置（进度相关的部分）：
## 进度汇报模式
当指令包含「/进度」前缀时，启用进度汇报模式：
### 基本规则
1. 先把任务拆成3-7个步骤，列出来
2. 每完成一步立即汇报：做了什么、关键数据、下一步
3. 汇报时不要重复已知信息
4. 配合Tasks工具记录进度
### 自主处理与确认边界
自行处理并汇报：格式修复、import调整、类型标注
停下来确认：删除文件、修改接口、影响超过5个文件的改动
### 汇报频率
- 文件级操作：每5-10个文件汇报一次
- 模块级操作：每完成一个模块汇报一次
- 调试排查：每排除一个可能性汇报一次
加起来不到20行，该说的都说到了，多余的废话没有。
最后说一句
Claude Code是一个很强的工具，但它的默认行为是"闷头干活"。这不是bug，可能是设计上更倾向于不打断你的工作流。但对于长任务来说，没有进度反馈的体验确实糟糕。
这套方案用的全是Claude Code自带的东西：流式输出、CLAUDE.md读取、Tasks API。没有黑魔法，只是用一段提示词把它们串起来了。
不用装插件，不用改配置，CLAUDE.md里加几行字就完事了。
如果你试了觉得好用，或者你自己有其他让Claude Code更顺手的提示词玩法，评论区聊聊。
常见问题
CLAUDE.md放在哪里才能生效？
放在你项目的根目录就行。Claude Code启动时会自动读取当前目录和父目录中的CLAUDE.md文件。如果你想让配置对所有项目生效，可以在 ~/.claude/CLAUDE.md 放一份全局配置。项目级配置会覆盖全局配置中的同名规则。
这套方法对token消耗有多大影响？
根据我的统计，开启进度汇报后token消耗大约增加15%-25%。200个文件的批量操作，不开汇报大概用12000个token，开了之后用14000-15000个。多花的这点token，换来的是你不用在黑箱前面干等，我觉得值。
Claude Code版本有要求吗？
CLAUDE.md从Claude Code最早的版本就支持了。Tasks API需要v2.1.16及以上版本（2026年1月发布）。自定义命令和Status Line也是比较早就有的功能。建议保持更新到最新版，用 claude update 就行。