Community编程与开发github.com

codemap

一次调用即可按目录分组列出项目中指定类型的所有文件,并可附带每个文件的类、函数、导出项。在需要获取某种类型的所有文件(例如所有 .php 控制器、所有 .css/.scss 源文件)或了解目录整体定义时,先于读取文件使用。如果已知文件名或单个 glob 模式,请改用 Glob。

codemap 是什么?

这是一个用于快速生成项目文件结构地图的技能,称为 codemap。它允许开发者或 AI 代理在单次调用中,按目录分组列出所有指定扩展名的文件,并可选地提取每个文件中的顶层符号(如 PHP 类/函数、JS/TS 导出、Python 类/def、Go 类型/func 等)。该技能主要面向需要了解项目整体文件结构但又不知具体文件位置的场景,例如当需要查看所有 .php 控制器或所有 .css/.scss 源文件时,codemap 能高效生成紧凑、排序的映射,而无需逐个搜索目录。它支持通过 --ext 指定扩展名、--dir 限定目录、--symbols 提取符号、--max 限制输出行数、--exclude 排除文件等选项,并自动遵守 .gitignore 规则。典型用法包括:在读取文件前获取目录概览以决定真正需要阅读的文件,或者将子目录的 codemap 传递给子代理以加快其上手速度。请注意,codemap 的符号提取基于行级模式而非编译器,因此应将其视为文件内容的“目录表”,后续仍需实际读取文件以获取详细信息。建议在输出被截断时,通过限定目录、扩展名或排除规则来优化,而非大幅提高 --max 上限。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Borcioo/claude-skills/tree/HEAD/experiments/codemap/skills/codemap

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

codemap 是做什么的?

运行捆绑脚本。每次调用都会读取当前工作树,并打印紧凑、排序的映射;它从不写入任何文件。

${CLAUDE_SKILL_DIR}/scripts/codemap --ext php,blade.php --dir app
${CLAUDE_SKILL_DIR}/scripts/codemap --ext css,scss --symbols
${CLAUDE_SKILL_DIR}/scripts/codemap --ext ts,tsx --dir src --symbols --max 150

选项:--ext(逗号分隔,无需点号)、--dir、--symbols、--max(输出行限制,默认 300)、--exclude REGEX(可重复)。

输出样例:

# codemap: 12 files in 3 dirs (dir: app, ext: php, via rg)
Http/Controllers/
  UserController.php: class UserController, fn index, fn store

使用场景

  • 你需要一种或多种类型的所有文件,但不知道它们位于何处。
  • 你正准备读取多个文件,但只想了解它们定义了哪些内容:先使用 --symbols 运行,然后只阅读真正需要的文件。
  • 子代理进入一个不熟悉的区域:将那个目录的 codemap 传递给它,而不是让它从头开始搜索。

何时不该使用

  • 你知道文件名或精确模式:请使用 Glob。
  • 你需要文件内的文本内容:请使用 Grep。
  • 你需要某个符号的定义或引用,且已启用 LSP 插件:请使用 LSP 工具。

注意事项

  • 当 ripgrep 或 git 可用时,会遵守 .gitignore;vendor/、node_modules/、构建输出、压缩文件和源映射始终被跳过。
  • 符号提取基于行级模式,而非解析器:顶层 PHP 类/函数、JS/TS export、Python 顶层 class/def、Go type/func、CSS 自定义属性(计数)以及 SCSS/Less mixins。将其视为文件目录表,然后再读取文件。
  • 当输出以 # ... truncated 结束时,请使用 --dir、--ext 或 --exclude 缩小范围,而非大幅提高 --max。

相关技能