用途
Project Indexer 用于为任意代码库生成结构化索引,帮助 Claude Code 在新会话中以尽量少的上下文快速理解项目结构。索引的作用是充当导航地图,而不是代码副本,提供足够的信息让 Claude 能够全局了解项目(类型、技术栈、架构)、按需导航到特定区域(功能地图、文件索引),并在不读取全部文件的情况下知道存在哪些函数与类(符号索引)。
适用场景
- 开始处理新项目或不熟悉的项目
- 开始新的 Claude Code 会话并需要项目上下文
- 用户说“explore the project”“understand the codebase”“project structure”
- 用户说“了解项目”“探索项目”“项目结构”“索引项目”
- 用户说“generate index”“create project map”“生成索引”
- 用户显式调用 /project-indexer
- 用户希望重新生成或更新索引:“regenerate index”“更新索引”
工作流程
首先检查项目根目录下是否存在 .claude-index/index.md。若存在,则读取该索引文件,并在存在时读取独立的项目约定文件 CLAUDE.md,然后告知用户已加载项目索引并列出已掌握的概览。此后使用索引进行导航:用户询问功能时用功能地图定位相关文件,需要特定函数时用文件索引查找,仅在需要详细工作时才读取实际源文件。
若不存在索引,则进行首次生成。首先向用户收集配置,包括排除目录(默认排除 node_modules、.git、dist、build、pycache、.venv、vendor、coverage、.next、.nuxt、.cache、target、bin、obj,可选择默认、追加或自定义)、优先详细索引的目录(可自动检测、指定或平均索引),以及可选的技术栈指定(否则自动检测)。
随后扫描并分析项目:按排除规则遍历文件结构;检测项目类型(frontend / backend / fullstack / library / CLI / monorepo);识别主要语言及其占比;检测框架(React、Vue、Next.js、Express、FastAPI、Django 等);查找入口点(main.ts、index.js、app.py、main.go 等);按功能或领域分组文件(auth/、api/、components/、utils/ 等);提取导出的符号(公共类、函数、常量及其签名);为每个文件或模块生成一行 AI 描述;分析模块级依赖关系。
接着根据项目规模应用自适应尺寸策略:小项目(少于 50 个文件)使用详细索引,包含所有文件与完整符号提取;中型项目(50–200 个文件)使用标准索引,完整覆盖并配简洁描述;大型项目(200 个以上文件)使用聚焦索引,优先核心代码并概括周边区域,对优先目录进行详细索引,对其他区域提供摘要级覆盖,并将相似的工具文件分组。
然后在 .claude-index/ 下生成两个文件:config.md 保存排除目录、优先目录、技术栈、生成时间戳、项目根路径与索引版本等配置,供未来重新生成使用;index.md 为主索引文件,包含项目概览、功能地图、模块依赖与文件索引。
之后更新项目中的 CLAUDE.md:若已存在则查找 ## Project Index 章节,存在则整体替换,不存在则追加到文件末尾;若 CLAUDE.md 不存在则创建新文件并加入该章节,同时告知用户可继续添加项目专属说明。该章节说明索引位置(.claude-index/index.md)、最后更新时间、内容范围,并提示可通过“regenerate index”或“更新索引”重新生成。
最后向用户报告生成结果,包括已创建的文件、索引涵盖的概览与技术栈、识别的功能区域数量、已索引文件数与导出符号数、模块依赖图,并说明后续 Claude Code 会话会从 CLAUDE.md 自动获知该索引。
重新生成流程
当用户请求重新生成索引时,读取 .claude-index/config.md 以保留排除规则、优先目录与技术栈设置;与用户确认是否按既有配置重新生成或更新配置;然后按首次生成的第 2 至 6 步重新扫描并生成,保留 config.md、重新生成 index.md,并更新 CLAUDE.md 中 Project Index 章节的时间戳。
索引文件格式
index.md 的结构包括:标题与自动生成说明及最后更新时间;项目概览(类型、语言及占比、框架、入口点);功能地图,按功能区域列出路径、入口文件、一行描述与关键导出(含函数签名与说明);模块依赖,描述模块之间的依赖关系;文件索引,按目录以表格列出文件及其描述。
语言支持
优先支持(完整符号提取):JavaScript / TypeScript(.js、.jsx、.ts、.tsx、.mjs)、Python(.py)。尽力支持:Java、Kotlin、Go、Rust、C/C++、C#、Ruby、PHP。对于不支持或未知文件类型,仍会列入文件列表,提供基本文件信息(大小、类型),跳过详细符号提取,并基于文件名与位置生成描述。
最佳实践
保持索引聚焦,不必记录所有内容,重点是导航价值;结构变化后应更新索引,重大重构后重新生成;与 CLAUDE.md 配合使用,索引提供结构,CLAUDE.md 提供约定;信任地图,用索引导航,实际实现细节再读取源文件。
故障排查
索引过大时,可增加排除目录、减少优先目录,自适应尺寸通常会自动处理;缺少重要文件时,检查 config.md 中的排除规则、确认优先目录设置正确,并用更新后的配置重新生成;信息过时时,运行重新生成命令,因为索引是快照,显著变更后应重新生成。
限制
本技能依赖 Claude Code 会话环境,索引文件存放于项目的 .claude-index/ 目录下。资料未提供其支持的平台范围、收费方式、价格、性能指标或效果保证,这些信息暂未提供。