003、第一次交互：从启动到文件读写的完整流程
一个让我深夜抓狂的bug
上周五晚上，我盯着终端里Claude Code的输出，血压直接拉满。一个简单的文件读取任务，它居然把整个项目目录结构打印了三遍，然后告诉我“无法确定你要读取哪个文件”。我明明在prompt里写了“读取src/config/index.ts”，它却跑去读了个dist目录下的编译产物。
这不是Claude Code的锅，是我自己没搞懂它的工作流。那次之后，我花了两个通宵，把Claude Code从启动到文件读写的完整流程扒了个底朝天。今天这篇笔记，就是那次debug的产物。
启动那一刻发生了什么
当你敲下claude命令，终端里那个闪烁的光标背后，其实跑了一整套初始化流程。我习惯用--verbose参数启动，这样能看到它到底在干什么：
claude--verbose别用claude -m直接指定模型，除非你清楚知道自己在做什么。默认的模型选择机制会基于任务复杂度自动切换，你强行指定反而可能让它在简单任务上浪费token。
启动后Claude Code会做三件事：加载项目配置文件（如果有.claude目录下的配置）、扫描当前目录结构建立索引、初始化对话上下文。这里有个坑——它扫描目录时默认会忽略.gitignore里的文件，但如果你项目里没有.gitignore，它会把node_modules也扫进去，导致上下文窗口被无关文件塞满。
我的做法是在项目根目录放一个.claudeignore，明确告诉它哪些目录别碰：
node_modules/ dist/ .git/ *.log第一次对话：别让它猜你的意图
很多人第一次用Claude Code，上来就写“帮我看看这个项目”。然后它就真的“看看”——把项目结构列一遍，问你“你想看哪个文件”。这不是它傻，是你没给约束。
我总结了一个prompt模板，专门对付这种“第一次交互”场景：
当前工作目录是{项目名}，我需要你： 1. 读取 src/config/index.ts 文件 2. 检查文件中是否有 DATABASE_URL 这个环境变量 3. 如果有，输出它的值；如果没有，告诉我缺少哪个配置注意，我明确说了“当前工作目录是{项目名}”，这能防止它跑到上级目录去乱翻。另外，我把任务拆成了三个步骤，每个步骤都是可验证的。Claude Code的思维链在处理多步骤任务时，步骤越清晰，出错概率越低。
文件读写的底层逻辑
Claude Code读写文件用的是它自己的工具调用机制，不是直接操作文件系统。这意味着它每次读写都会经过一个“意图解析→工具选择→参数组装→执行→结果解析”的循环。
读文件时，它默认会尝试用read_file工具，这个工具有个隐藏参数max_length，默认是5000字符。如果你的配置文件超过这个长度，它只会读到前半段。我遇到过好几次，因为配置文件太长，它只读了前半段就下结论说“配置完整”，结果部署时炸了。
解决方案是在prompt里显式指定读取范围：
读取 src/config/index.ts 的全部内容，不要截断或者更狠一点，直接让它用cat命令（如果Claude Code配置了shell执行权限）：
执行 cat src/config/index.ts 并输出完整内容写文件时，Claude Code默认会先创建一个临时文件，写入内容，然后原子替换原文件。这个机制的好处是不会因为写入中断导致文件损坏，坏处是如果你在写入过程中手动修改了原文件，Claude Code不会感知到冲突，直接覆盖。
我踩过这个坑：一边在IDE里改代码，一边让Claude Code写同一个文件，结果我的修改被覆盖了。现在我的规矩是：Claude Code写文件时，我绝不碰那个文件。
一个实战案例：自动化配置检查
上周我写了一个自动化脚本，让Claude Code在项目启动时自动检查配置文件完整性。流程是这样的：
- 读取
.env.example获取所有必需的环境变量列表 - 读取
.env文件获取当前配置 - 对比两个列表，输出缺失的变量
- 如果缺失，自动从
.env.example复制默认值到.env
这个流程看起来简单，但第一次跑的时候翻车了——Claude Code读取.env.example时，把注释行也当成了变量名。因为.env文件里经常有# 数据库配置这样的注释，它没区分。
我加了一个过滤条件：
读取 .env.example 文件，只提取以 export 开头或包含等号的行，忽略注释行和空行这次它准确识别了所有变量。关键点在于：Claude Code对文件格式的理解依赖于你的描述，它不会自动推断“这是.env文件，所以注释是#开头的行”。你必须把规则说清楚。
调试技巧：让Claude Code自己解释它做了什么
当Claude Code的行为不符合预期时，别急着重写prompt。先让它解释刚才的操作：
你刚才读取了哪些文件？读取的顺序是什么？为什么先读那个文件？这个追问能暴露它的决策逻辑。有一次我问它为什么读了一个不相关的文件，它回答“因为该文件在项目根目录，且文件名包含config，我认为它可能是配置文件”。这就是典型的“过度泛化”——它把文件名匹配当成了唯一依据。
知道了原因，我就在prompt里加了一个限定条件：
只读取 src/config/ 目录下的文件，不要读取其他目录中文件名包含 config 的文件个人经验：第一次交互的黄金法则
写了这么多，其实核心就三条：
第一，永远给Claude Code一个“工作边界”。告诉它哪些目录能碰，哪些不能碰，文件读取的深度和范围是什么。别指望它自己“理解”你的项目结构，它只是个工具，不是你的结对程序员。
第二，每次交互都要有“可验证的输出”。别让它只做不说。让它把读取到的文件内容摘要输出，让它把修改前后的diff展示出来。这样你一眼就能看出它有没有跑偏。
第三，建立“检查点”机制。在关键步骤后加一个验证prompt，比如“确认一下你刚才写的文件内容是否正确”。Claude Code会重新读取文件并对比，这个自我纠错机制能拦截大部分低级错误。
最后说一句：别把Claude Code当成黑盒。它的每一次文件读写、每一次代码生成，背后都是可解释的。你花时间理解它的工作流，比花时间调prompt模板要值得多。毕竟，prompt可以抄，但工作流的理解只能自己踩坑踩出来。
