要让CodeBuddy准确识别src、api、store、tests这些目录之间的依赖关系，不能指望它自动猜。关键一步是触发全量项目结构索引：先输入/analyze-project-structure直到显示“Project graph built successfully”，然后运行/show-dependency-map查看依赖树。如果失败，检查根目录并加载pyproject.toml或package.json；多模块项目需要/set-root-dir或/load-config-file；重构中的项目应启用/enable-git-metadata-mode；遇到自定义结构则导入codebuddy-structure.yaml，最后用/list-known-modules验证。

如果想让CodeBuddy准确识别项目里src、api、store、tests这些目录之间的关系，而不是只盯着当前打开的单个文件猜逻辑——那它需要真正“看见”整个Git仓库的骨架，而非靠片段推测。

触发全量项目结构索引

CodeBuddy默认不会自动扫描整个仓库，必须手动唤醒它的结构建模能力。否则它只会基于当前文件做局部推理，跨文件修改时极易漏掉依赖项。在聊天对话框里直接输入：/analyze-project-structure，然后等待界面返回“Project graph built successfully”提示。这一步绝不能跳过——没有这个提示，说明AST映射和模块依赖图压根没生成，后面的跨文件操作都缺乏底层支撑。

完成后，执行/show-dependency-map就能看到文本树状图形式的依赖关系。如果输出为空或只显示当前文件，说明索引失败，得检查一下是否在正确的根目录下操作。

强制指定项目锚点与配置文件

当项目包含多级子模块、monorepo结构或者自定义构建路径时，CodeBuddy很容易把主入口位置搞错，导致结构层级乱掉。这时需要人工钉住分析起点。

方法一是设置根目录：运行/set-root-dir ./，不过得确保当前已经在Git仓库根目录。

方法二是加载关键配置文件：执行/load-config-file pyproject.toml或/load-config-file package.json。这两类文件是CodeBuddy识别技术栈和模块边界的锚点，缺一不可。比如没加载package.json，它可能把TypeScript类型定义当成普通JS文件处理。确认响应中间出现“Config loaded, structure inference updated”字样，配置才算生效并触发二次结构推断。

启用Git元数据感知模式

重构过的项目通常有文件移动、重命名或分支合并的痕迹，只靠当前快照很难还原真实演化路径。Git历史才是理解“为什么这个service被拆进core包”的唯一依据。

第一步，运行/enable-git-metadata-mode。CodeBuddy会自动读取.git/config与.git/logs/HEAD，构建时间线索引，整个过程不需要人工干预，但要求.git目录完整且没有被清理过。

验证效果时可以直接提问：“user.service.ts在v2.1分支中是否曾位于legacy模块？”如果它能精准定位到commit哈希和路径变更记录，说明Git元数据模式已经激活。

注入自定义结构描述文件

对于使用私有DSL、混合语言子系统或非标准目录约定的项目，CodeBuddy的启发式推断基本抓瞎。这时必须用机器可读的YAML文件接管结构定义权。

在仓库根目录创建codebuddy-structure.yaml，内容必须包含modules、entrypoints、excluded_paths等字段；然后执行/import-structure-spec codebuddy-structure.yaml；最后用/list-known-modules验证，应该逐行返回YAML里定义的全部模块名称。

需要注意：这个YAML文件一旦导入，CodeBuddy会完全忽略自动推断结果，所有上下文加载都以其中声明为准。如果字段缺失或格式错误，导入会静默失败，不会报错提示。