# Claude 每次会话开始时都是两眼一抹黑。

Canonical source: https://maguyva.ai/zh-hans/for-claude-code

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

`CLAUDE.md` 告诉 Claude 该怎么表现，但不会告诉 Claude 你的代码仓库里有什么。Maguyva 索引代码库，并通过 MCP 提供检索结果，让 Claude 编辑起来就像它已经读过这些代码一样。

> 用 CLAUDE.md 定义行为，用 Maguyva 获取当前代码库的真实情况。

## CLAUDE.md 是最佳实践，好好用它。

```text
> cat CLAUDE.md
# 项目规范、命令、限定范围的规则
```

持久化的指令应该放进 `CLAUDE.md`。它正适合承载：

- 智能体应该运行的构建、测试和 lint 命令。
- 代码风格规则和命名规范。
- 限定在某个目录范围内的“永远做 X / 永远别做 Y”护栏。
- 指向权威文档和决策日志的指引。

Anthropic 的[记忆功能文档](https://code.claude.com/docs/en/memory)对此有很好的说明。保持简洁，划定范围，提交它。

但 `CLAUDE.md` 从来就不是为了充当你代码库的地图而设计的。

## CLAUDE.md 不再够用的地方

四种失效模式，光靠 markdown 修不好。

### // 文件不是代码库本身

告诉 Claude *该怎么表现*，不等于告诉它*代码库里有什么*。在陌生的代码仓库上做第一次编辑，还是得靠猜文件路径、函数名和调用点。CLAUDE.md 没法列出每一个符号，你也不会希望它这么干。

### // 文档会过时，代码不会

一段描述你鉴权流程的 `CLAUDE.md` 内容，在有人重构鉴权逻辑之前都是对的。此后代码才是唯一的真相来源，文档则自信满满地错了。Claude 读到的是错的那一份。

### // 依赖关系不在 markdown 里

“改了这个函数会破坏什么？”是一个图谱问题，文档文件回答不了。Claude 要么 grep 一把碰运气，要么让你把文件粘贴进对话。

### // 上下文窗口是有预算的

把 CLAUDE.md 塞到 Claude “知道得够多”为止，会吃掉本该用于推理的 token。超过几 KB 之后，你就是在用答案质量去换取上下文的体积。

## Maguyva 补上了 CLAUDE.md 覆盖不到的那一层

一台远程 MCP 服务器，为 Claude Code 提供：

- **语义、AST、图谱和文本搜索**: 覆盖你索引过的代码仓库，结果带着文件路径和行号返回。
- **依赖、类型和调用点查询**: 图谱能回答这些问题，文档文件却回答不了。
- **分支感知的结果**: 让 Claude 看到它实际正在编辑的那个版本的代码。
- **按工作区计费**: 而非按坐席计费。无论索引 1 个代码仓库还是 50 个，智能体都不需要付坐席费。

> CLAUDE.md 告诉 Claude *该怎么表现*。
> Maguyva 给 Claude 提供*一张代码的可查询地图*。

## 三种工作流

编号列出，代码块密集。你已经在问 Claude 的那些问题，这次基于真实代码行给出答案。

### 01. 找到真正的实现，而不是测试桩

```text
你："我们支付客户端里的重试机制是怎么工作的？"

没有 Maguyva → Claude grep retry，找到 14 个命中，随便挑一个（往往是测试 mock）。
用上 Maguyva    → Maguyva 返回符号定义、调用点，以及真实实现的
                   file:line，并排好序。
```

### 02. 重构前先看清影响范围

```text
你："谁调用了 normalizePhoneNumber？"

Maguyva 返回：跨 4 个包的 7 处调用点，其中一处在某个 Python 服务里，
通过 gRPC 桩导入使用。Claude 直接提出改动方案并内联给出迁移清单，
而不是等 CI 变红之后才补救。
```

### 03. 在接受改动前先验证智能体的判断

```text
Claude："我编辑了 src/auth/session.ts:142，修复了令牌刷新逻辑。"

问 Maguyva："给我看看 session.ts:130-160，以及所有导入 session 的地方。"

Maguyva 返回了实时文件片段和 3 个引用方。这次改动现在基于真实代码行，
而不是 Claude 在第 11,000 个 token 时的记忆。
```

## 在 Claude Code 中配置

三个步骤。Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。

### 01. 在 maguyva.ai 索引一个代码仓库

选一个你熟悉的代码库，方便你核实答案是否正确。Free 版可覆盖 3 个代码仓库, 最多 5 万行索引代码。

### 02. 在 Claude Code 中安装 Maguyva 插件

```text
/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

# the plugin reads your key from the environment
export MAGUYVA_API_KEY=mgv_xxxx
```

### 03. 问一个你已经知道答案的问题

先从一个代码仓库和一个可验证的问题开始，别一上来就覆盖整个公司。如果答案和你预期的一致，那就说明搭建成功了。

完整说明在 [Maguyva 的文档](https://maguyva.ai/zh-hans/docs)里。

## 索引一个你已经熟悉的代码仓库。

测试一个你能自行验证答案的问题。这就是整个上手流程。