关于 codemap
codemap 是一项指导开发者使用 codemap CLI 探索代码库的技能，适用于语义搜索、符号查找和依赖分析。它强调先确认索引状态，再选择范围最窄的查询，也可通过 MCP 服务提供工具访问。
主要功能
- 01混合向量与 BM25 代码搜索
- 02查找函数、类和类型符号
- 03查看文件摘要与依赖关系
- 04分析重要性、耦合和循环依赖
- 05索引状态检查与文件变更监视
适用场景
- 01按意图查找实现代码
- 02追踪文件的依赖方与被依赖方
- 03检查代码库架构健康状况
MCP 相关
codemap 可通过 `codemap serve` 作为 MCP 服务运行，向 Agent 暴露代码搜索等工具。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/codemap确认已加载。
详细介绍
不可妥协的规则：
- 依赖结果之前，先检查
codemap --version和codemap status。 - 如果项目尚未配置 codemap，运行
codemap init前先征求同意。 - 优先使用能够回答问题的最精简 codemap 命令。
- 需要解读结构化结果时，优先使用机器可读的输出。
- 不要仅为了启用 codemap 而自动修改 Claude 或项目设置。
codemap
输入
$request：搜索或分析目标
目标
在以下情况下，使用 codemap CLI 回答架构和探索类问题，以获得比纯文本搜索更准确的结果：
- 目标是语义而非字面内容
- 需要查找符号
- 需要了解依赖方向
- 需要了解文件的重要性或耦合程度
第 0 步：验证工具可用性和索引状态
检查：
codemap --versioncodemap status
如果缺少 codemap，告知用户使用 npm install -g @ulpi/codemap 安装，然后停止。不要自动安装。
如果仓库尚未配置：
- 说明
codemap init会创建项目配置 - 运行
codemap init前先征求同意 - 配置完成后，运行
codemap index
如果仓库已配置，但索引已过时，则运行 codemap index 重新建立索引。
成功标准：当前仓库已建立可用的 codemap 索引。
第 1 步：选择合适的命令
命令参考
| 命令 | 功能 | 关键标志 |
|---|---|---|
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 | 通过 stdio 启动 MCP 服务 |
快速选择命令
| 目标 | 命令 |
|---|---|
| 查找执行 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 |
需要结构化输出而非文本说明时，优先使用 --json。
成功标准：命令与实际问题相匹配，不要过度获取结果。
第 2 步：运行最精简且有用的 codemap 查询
从范围较窄的查询开始：
- 限制结果数量
- 已知文件或模块时，指定具体文件或模块
- 每次只分析一个维度
只有在首批结果明显不足时，才扩大查询范围。
规则：
- 不要“以防万一”运行所有 codemap 命令
- 使用精确的
grep更简单时，不要使用 codemap - 找到文件后，如需查看文件内容，请对返回的具体文件路径使用
Read
成功标准：使用 codemap 进行探索，并且只对相关的具体文件使用 Read。
步骤 3：以便于决策的形式报告结果
总结：
- 使用了什么命令
- 为什么该命令合适
- 最相关的结果
- 值得继续打开查看的文件
如果没有显著结果，请明确说明，而不是给出毫无依据的确定结论。
成功标准：用户无需解析原始 codemap 输出，即可根据结果采取行动。
MCP 替代方案
Codemap 也可以作为 MCP 服务运行，让 AI Agent 无需使用 Bash 即可直接调用工具：
claude mcp add codemap codemap serve
这会开放 mcp__codemap__search_code、mcp__codemap__search_symbols 等工具。CLI 技能（即此文件）使用 Bash 命令。MCP 则为 Agent 提供原生工具调用。两者都可用，按 Agent 设置选择即可。
防护措施
- 不要自动修改设置文件来添加权限。
- 未经用户批准，不要运行
codemap init来创建新配置。 - 不要将过时或为空的索引视为权威来源。
- 如果简单的精确匹配工具已足够，不要改用 codemap。
- 不要添加
disable-model-invocation；这是一项通用发现技能。
输出约定
报告：
- codemap 是否可用以及索引状态
- 选择的命令
- 最相关的命中结果或图谱结果
- 如需深入阅读，接下来要打开的文件
- 索引缺失或结果不明显等限制