codemap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<EXTREMELY-IMPORTANT> `codemap` only helps when the repo is indexed and the command matches the question.

Non-negotiable rules:

Check
```
codemap --version
```
and
```
codemap status
```
before relying on results.
If the project has no codemap setup, ask before running
```
codemap init
```
.
Prefer the narrowest codemap command that answers the question.
Prefer machine-readable output when you need to interpret structured results.
Do not auto-edit Claude or project settings just to enable codemap.

</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT> `codemap` 仅在代码库已建立索引且命令与问题匹配时才会生效。

不可违背的规则：

在依赖结果之前，先检查
```
codemap --version
```
和
```
codemap status
```
。
如果项目未配置 codemap，在运行
```
codemap init
```
前需询问用户。
优先选择最精准的 codemap 命令来回答问题。
当需要解析结构化结果时，优先使用机器可读的输出格式。
不要为了启用 codemap 而自动修改 Claude 或项目设置。

</EXTREMELY-IMPORTANT>

codemap

Inputs

输入

```
$request
```
: The search or analysis goal

```
$request
```
：搜索或分析目标

Goal

目标

Use the

codemap

CLI to answer architecture and discovery questions with better signal than plain-text search when:

intent is semantic rather than literal
symbol lookup matters
dependency direction matters
file importance or coupling matters

当满足以下情况时，使用

codemap

CLI 回答架构与代码发现问题，相比纯文本搜索能提供更有效的信息：

需求是语义层面而非字面层面
符号查找很重要
依赖方向很重要
文件重要性或耦合度很重要

Step 0: Verify availability and index state

步骤0：验证可用性与索引状态

Check:

```
codemap --version
```
```
codemap status
```

codemap

is missing, tell the user to install it with

npm install -g @ulpi/codemap

and stop. Do not install it automatically.

If the repo is not configured:

explain that
```
codemap init
```
creates project config
ask before running
```
codemap init
```
once configured, run
```
codemap index
```

If the repo is configured but stale, re-index with

codemap index

Success criteria: There is a working codemap index for the current repository.

检查：

```
codemap --version
```
```
codemap status
```

如果未安装

codemap

，告知用户通过

npm install -g @ulpi/codemap

进行安装，然后停止操作，不要自动安装。

如果代码库未配置：

说明
```
codemap init
```
会创建项目配置
在运行
```
codemap init
```
前询问用户
配置完成后，运行
```
codemap index
```

如果代码库已配置但索引过期，使用

codemap index

重新建立索引。

成功标准：当前代码库拥有可用的 codemap 索引。

Step 1: Choose the right command

步骤1：选择正确的命令

Command Reference

命令参考

Command	What It Does	Key Flags
`codemap search <query>`	Hybrid vector+BM25 code search	`-l N` , `--json`
`codemap symbols <query>`	Find functions, classes, types by name	`-l N` , `--json`
`codemap summary <file>`	File overview with symbols and size	`--json`
`codemap deps <file>`	Outgoing imports (what this file uses)	`--json`
`codemap dependents <file>`	Incoming imports (what uses this file)	`--json`
`codemap rank [file]`	PageRank importance scores	`-l N` , `--json`
`codemap coupling`	Afferent/efferent coupling and instability	`--module <path>` , `-l N` , `--json`
`codemap cycles`	Detect circular dependencies	`--json`
`codemap graph-stats`	Aggregate dependency graph statistics	`--json`
`codemap index`	Index project for search	`--full`
`codemap status`	Show index stats	`--json`
`codemap watch`	Live index updates on file change	`--debounce <ms>`
`codemap read <file>`	Read full source (or line range)	`--start` , `--end`
`codemap serve`	Start MCP server over stdio

命令	功能	关键参数
`codemap search <query>`	向量+BM25混合代码搜索	`-l N` , `--json`
`codemap symbols <query>`	按名称查找函数、类、类型	`-l N` , `--json`
`codemap summary <file>`	包含符号与大小的文件概览	`--json`
`codemap deps <file>`	向外导入的依赖（该文件使用的内容）	`--json`
`codemap dependents <file>`	向内导入的依赖（使用该文件的内容）	`--json`
`codemap rank [file]`	PageRank重要性评分	`-l N` , `--json`
`codemap coupling`	传入/传出耦合度与不稳定性	`--module <path>` , `-l N` , `--json`
`codemap cycles`	检测循环依赖	`--json`
`codemap graph-stats`	聚合依赖图统计数据	`--json`
`codemap index`	为搜索建立项目索引	`--full`
`codemap status`	显示索引统计信息	`--json`
`codemap watch`	文件变更时实时更新索引	`--debounce <ms>`
`codemap read <file>`	读取完整源码（或指定行范围）	`--start` , `--end`
`codemap serve`	通过标准输入输出启动MCP服务器

Quick Routing

快速选型

What You Want	Command
Find code that does X	`codemap search "X"`
Find function/class named X	`codemap symbols "X"`
What does this file depend on?	`codemap deps <file>`
What depends on this file?	`codemap dependents <file>`
Most important files	`codemap rank`
Circular dependencies?	`codemap cycles`
Overview of a file	`codemap summary <file>`
Architecture health	`codemap coupling`
Project stats	`codemap graph-stats`

Prefer

--json

when you need structured output rather than prose.

Success criteria: The command matches the actual question instead of overfetching.

需求	命令
查找实现功能X的代码	`codemap search "X"`
查找名为X的函数/类	`codemap symbols "X"`
该文件依赖哪些内容？	`codemap deps <file>`
哪些内容依赖该文件？	`codemap dependents <file>`
最重要的文件	`codemap rank`
是否存在循环依赖？	`codemap cycles`
文件概览	`codemap summary <file>`
架构健康度	`codemap coupling`
项目统计数据	`codemap graph-stats`

当需要结构化输出而非 prose 格式时，优先使用

--json

参数。

成功标准：所选命令与实际问题匹配，不会过度获取无关信息。

Step 2: Run the minimal useful codemap query

步骤2：运行最小化的有效codemap查询

Start narrow:

limited result count
specific file or module when known
one analysis dimension at a time

Then expand only if the first result set is clearly insufficient.

Rules:

do not run every codemap command "just in case"
do not use codemap when exact
```
grep
```
is simpler
when file contents are needed after discovery, use
```
Read
```
on the concrete file paths returned

Success criteria: The answer uses codemap for discovery and

Read

only for the specific files that matter.

从精准范围开始：

限制结果数量
已知具体文件或模块时指定目标
每次仅分析一个维度

仅当首次结果集明显不足时，再扩大查询范围。

规则：

不要“以防万一”运行所有codemap命令
当简单的
```
grep
```
更合适时，不要使用codemap
发现目标后需要查看文件内容时，对返回的具体文件路径使用
```
Read
```
命令

成功标准：使用codemap完成代码发现，仅对关键文件使用

Read

命令。

Step 3: Report results in decision-friendly form

步骤3：以便于决策的形式报告结果

Summarize:

what command was used
why it was the right command
the most relevant results
any follow-up files worth opening

When there are no strong results, say that explicitly instead of inventing certainty.

Success criteria: The user can act on the result set without parsing raw codemap output.

总结内容：

使用的命令
选择该命令的原因
最相关的结果
值得进一步查看的后续文件

当没有明确结果时，需明确说明，不要编造确定性结论。

成功标准：用户无需解析原始codemap输出即可根据结果采取行动。

MCP Alternative

MCP替代方案

Codemap can also run as an MCP server, giving AI agents direct tool access without Bash:

bash

claude mcp add codemap codemap serve

This exposes tools like

mcp__codemap__search_code

mcp__codemap__search_symbols

, etc. The CLI skill (this file) uses Bash commands. MCP gives agents native tool calls. Both work -- use whichever the agent setup prefers.

Codemap 也可以作为 MCP 服务器运行，让 AI Agent 无需通过 Bash 即可直接访问工具：

bash

claude mcp add codemap codemap serve

这会暴露

mcp__codemap__search_code

、

mcp__codemap__search_symbols

等工具。本 CLI 技能（本文件）使用 Bash 命令，而 MCP 则为 Agent 提供原生工具调用能力。两种方式都可行——使用 Agent 环境偏好的方式即可。

Guardrails

约束规则

Do not auto-modify settings files to add permissions.
Do not run
```
codemap init
```
without the user's approval when it would create new config.
Do not treat stale or empty indexes as authoritative.
Do not replace simple exact-match tools with codemap when text search is clearly enough.
Do not add
```
disable-model-invocation
```
; this is a general discovery skill.

不要自动修改配置文件以添加权限。
当
```
codemap init
```
会创建新配置时，未经用户批准不要运行该命令。
不要将过期或空索引视为权威结果。
当纯文本搜索足够时，不要用 codemap 替代简单的精确匹配工具。
不要添加
```
disable-model-invocation
```
；这是一项通用的代码发现技能。

Output Contract

输出约定

Report:

codemap availability and index state
the command chosen
the most relevant hits or graph results
the next file(s) to open if deeper reading is needed
any limitations such as missing index or weak results

报告内容需包含：

codemap 的可用性与索引状态
选择的命令
最相关的匹配结果或图表数据
如果需要深入阅读，下一步应打开的文件
任何限制条件，比如索引缺失或结果相关性弱