AI Agent / 系统课时
理解工作目录与上下文
理解工作目录与上下文
Claude Code 能否正确找到文件、理解项目边界,首先取决于会话从哪里启动。本节区分主工作目录、其子目录和额外目录:它们决定文件访问的基本范围,却不等于所有文件都会自动进入模型上下文;选对目录能明显减少找错文件和误解项目结构。
学习目标
- 能说明主工作目录、子目录与额外目录分别解决什么问题
- 能判断何时应从共同项目根启动,何时只需额外开放一个目录
- 能避免把“可访问文件”误解成“已加载全部项目上下文”
工作目录是会话的锚点
启动 Claude Code 时所在的目录会成为会话的主要工作目录。这个位置决定相对路径从哪里解释,也决定 Claude 默认围绕哪棵目录树读取和修改项目文件。其子目录天然属于同一棵工作树,因此从项目根启动,通常比从某个过深的源码目录启动更容易获得完整结构。

如果任务只修改 src/api,但它还依赖同仓库的 packages/shared、根级配置和测试,那么从共同仓库根启动更合适。反过来,如果只是处理一个完全独立的子项目,从更小的目录启动可以减少无关文件和权限暴露。
先确认当前会话站在哪里
在开始分析路径问题前,可以先用只读 Shell 信息确认当前目录。下面的命令不会遍历仓库,只输出当前 Bash 进程看到的工作目录。
printf 'cwd=%s\n' "$PWD"预期输出
cwd=<PATH><PATH> 会替换为实际目录。若这里不是你准备让 Claude 处理的项目位置,应先调整主工作目录再继续,否则后面的相对路径、脚本和文件判断都可能建立在错误锚点上。
在终端中,通常应先切到目标项目根再启动 claude。当前版本还支持在会话内用 /cd <path> 移动主工作目录;这与“额外增加一个可访问目录”是两个不同动作:前者更换项目锚点,后者保留原锚点并扩大文件范围。
子目录与额外目录解决不同问题
主工作目录的子目录不需要单独声明。只有任务需要访问当前工作树之外的目录时,才考虑 --add-dir <path>、会话内的 /add-dir <path>,或者持久化的额外目录设置。
| 范围 | 主要作用 | 适合场景 |
|---|---|---|
| 主工作目录 | 定义会话的主要项目锚点 | 单仓库、单服务或共同项目根 |
| 子目录 | 继承主工作树范围 | src、tests、docs 等项目内部内容 |
| 额外目录 | 在不移动主锚点的情况下扩展文件访问 | 共享库、邻接仓库、外部生成目录 |
/cd <path> |
把会话迁移到新的主工作目录 | 当前项目选错,需要真正切换项目根 |
如果团队希望持久允许某个额外目录,可以在适用的 Claude Code 设置文件中配置 permissions.additionalDirectories。下面是一个配置片段示例:
{
"permissions": {
"additionalDirectories": [
"../shared"
]
}
}这个设置扩大的是文件访问范围。它不应被理解成“把 ../shared 变成第二个完整项目根”,因此不要依赖其中的全部 .claude/ 配置自动生效。需要完整采用另一个项目的配置和上下文时,应该切换主工作目录,而不是单纯增加访问范围。
文件可访问不等于已经进入上下文
目录权限解决的是“Claude 能不能去读这个文件”,上下文解决的是“Claude 当前实际看过并正在依据哪些信息推理”。即使一个目录已经可访问,Claude 也不会因为目录很大就自动把全部内容一次性塞进上下文;它仍需要根据任务读取相关文件。
因此,给任务描述时应同时提供目标和边界,例如说明“修改 API 校验逻辑,需要参考 ../shared/schema,不要改共享库”。这样 Claude 知道为什么要读取额外目录,也知道哪些文件只是参考而不是修改目标。
发现目录错位时如何修正
典型信号包括:Claude 反复说找不到明明存在的文件、相对路径指向错误位置、只看到某个子包却缺少根级配置,或者把共享目录当成当前项目的一部分。出现这些现象时,先检查工作目录,再检查任务依赖是否位于工作树之外。
如果只是缺一个共享目录,就增加额外目录;如果真正选错了项目根,就移动或重新从正确目录启动会话。把“主锚点选择”和“临时扩展访问”分开处理,Claude Code 才能在足够的文件范围内工作,同时保持清晰、可控的项目上下文。