AI Agent / 系统课时

理解工作目录与上下文

理解工作目录与上下文

Claude Code 能否正确找到文件、理解项目边界,首先取决于会话从哪里启动。本节区分主工作目录、其子目录和额外目录:它们决定文件访问的基本范围,却不等于所有文件都会自动进入模型上下文;选对目录能明显减少找错文件和误解项目结构。

学习目标

  • 能说明主工作目录、子目录与额外目录分别解决什么问题
  • 能判断何时应从共同项目根启动,何时只需额外开放一个目录
  • 能避免把“可访问文件”误解成“已加载全部项目上下文”

工作目录是会话的锚点

启动 Claude Code 时所在的目录会成为会话的主要工作目录。这个位置决定相对路径从哪里解释,也决定 Claude 默认围绕哪棵目录树读取和修改项目文件。其子目录天然属于同一棵工作树,因此从项目根启动,通常比从某个过深的源码目录启动更容易获得完整结构。

Claude Code 工作目录与额外目录范围

如果任务只修改 src/api,但它还依赖同仓库的 packages/shared、根级配置和测试,那么从共同仓库根启动更合适。反过来,如果只是处理一个完全独立的子项目,从更小的目录启动可以减少无关文件和权限暴露。

先确认当前会话站在哪里

在开始分析路径问题前,可以先用只读 Shell 信息确认当前目录。下面的命令不会遍历仓库,只输出当前 Bash 进程看到的工作目录。

bash
printf 'cwd=%s\n' "$PWD"

预期输出

text
cwd=<PATH>

<PATH> 会替换为实际目录。若这里不是你准备让 Claude 处理的项目位置,应先调整主工作目录再继续,否则后面的相对路径、脚本和文件判断都可能建立在错误锚点上。

在终端中,通常应先切到目标项目根再启动 claude。当前版本还支持在会话内用 /cd <path> 移动主工作目录;这与“额外增加一个可访问目录”是两个不同动作:前者更换项目锚点,后者保留原锚点并扩大文件范围。

子目录与额外目录解决不同问题

主工作目录的子目录不需要单独声明。只有任务需要访问当前工作树之外的目录时,才考虑 --add-dir <path>、会话内的 /add-dir <path>,或者持久化的额外目录设置。

范围 主要作用 适合场景
主工作目录 定义会话的主要项目锚点 单仓库、单服务或共同项目根
子目录 继承主工作树范围 src、tests、docs 等项目内部内容
额外目录 在不移动主锚点的情况下扩展文件访问 共享库、邻接仓库、外部生成目录
/cd <path> 把会话迁移到新的主工作目录 当前项目选错,需要真正切换项目根

如果团队希望持久允许某个额外目录,可以在适用的 Claude Code 设置文件中配置 permissions.additionalDirectories。下面是一个配置片段示例:

json
{
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ]
  }
}

这个设置扩大的是文件访问范围。它不应被理解成“把 ../shared 变成第二个完整项目根”,因此不要依赖其中的全部 .claude/ 配置自动生效。需要完整采用另一个项目的配置和上下文时,应该切换主工作目录,而不是单纯增加访问范围。

文件可访问不等于已经进入上下文

目录权限解决的是“Claude 能不能去读这个文件”,上下文解决的是“Claude 当前实际看过并正在依据哪些信息推理”。即使一个目录已经可访问,Claude 也不会因为目录很大就自动把全部内容一次性塞进上下文;它仍需要根据任务读取相关文件。

因此,给任务描述时应同时提供目标和边界,例如说明“修改 API 校验逻辑,需要参考 ../shared/schema,不要改共享库”。这样 Claude 知道为什么要读取额外目录,也知道哪些文件只是参考而不是修改目标。

发现目录错位时如何修正

典型信号包括:Claude 反复说找不到明明存在的文件、相对路径指向错误位置、只看到某个子包却缺少根级配置,或者把共享目录当成当前项目的一部分。出现这些现象时,先检查工作目录,再检查任务依赖是否位于工作树之外。

如果只是缺一个共享目录,就增加额外目录;如果真正选错了项目根,就移动或重新从正确目录启动会话。把“主锚点选择”和“临时扩展访问”分开处理,Claude Code 才能在足够的文件范围内工作,同时保持清晰、可控的项目上下文。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

理解工作目录与上下文

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通