project-index

Project Index 是一个面向 AI 智能体的技能，用于生成项目上下文和代码库文档。它通过在项目中创建 .agents/ 目录，产出项目概览与深度代码库分析文档，供 AI 智能体按需加载使用。

用途

该技能的核心目标是为 AI 智能体提供结构化的项目上下文。它把代码库中的稳定模式、接口和约定整理成文档，写入 .agents/ 目录，使智能体在后续任务中能够按需读取，而不必每次重新分析整个代码库。

技能通过不同的触发词路由到对应的文档生成流程：

一次性设置（"initialize"、"setup project index"、"index project"）→ initialize.md
项目上下文（"overview"、"project context"、"refresh project"）→ overview.md
代码库摘要（"map codebase"、"analyze codebase"、"summary"）→ 通过子智能体并行分派 6 个代码库引用，然后以输出为上下文运行 review.md
增量刷新（"refresh codebase"、"sync codebase"、"patch index"）→ refresh.md
单文档刷新：architecture.md、conventions.md、testing.md、integrations.md、checklist.md、workflows.md、features.md（仅垂直切片项目）
自我评估（分派后）→ review.md
整合反馈（"integrate feedback"、"sync knowledge"、"integrate discoveries"）→ integrate-feedback.md
合并策略（任何引用在重跑时加载）→ merge-policy.md

工作流分为两条路径：

initialize：首次设置的入口。始终运行 overview。如果项目是棕地项目（已有源代码），则分派代码库并行分派：6 个子智能体并行运行（architecture、conventions、testing、integrations、checklist、workflows），当检测到垂直切片时增加第 7 个（features），然后主智能体以分派输出为上下文运行 review。
refresh：当 .agents/codebase/ 已存在时更经济的重跑路径。它从上次同步标记开始对 git 做 diff，将变更路径路由到其领域被触及的子智能体，只分派该子集。当阈值（文件数量、清单变动、入口点变化）表明发生大范围重构时，回退到完整分派。

代码库分派中，每个子智能体只读取其领域所需内容，输出写入磁盘，不通过上下文返回发现。所有子智能体完成后，主智能体以所有输出为上下文运行 review.md。评审不能拆分给子智能体，由主智能体负责综合。

各子智能体的读取与写入：

architecture：读取入口点、目录树、层边界；写入 .agents/codebase/architecture.md；始终执行
conventions：读取代表性源文件；写入 .agents/codebase/conventions.md；始终执行
testing：读取测试文件、测试配置；写入 .agents/codebase/testing.md；始终执行
integrations：读取 API 客户端、数据库模型、环境文件；写入 .agents/codebase/integrations.md；始终执行
checklist：读取脚本（package.json / Makefile）、pre-commit 配置；写入 .agents/codebase/checklist.md；始终执行
workflows：读取入口点到追踪的数据流；写入 .agents/codebase/workflows.md；始终执行
features：读取垂直切片目录、路由前缀、同位置测试/处理器/视图；写入 .agents/codebase/features.md；检测到垂直切片时执行

适用于需要为 AI 智能体建立项目上下文和代码库文档的软件项目，尤其是已有源代码的棕地项目。可用于首次初始化、代码库映射、增量同步、单文档刷新以及反馈整合等场景。

技能包含若干准则：读取实际代码文件以提取模式，而不仅是列出；按观察到的实际情况记录约定，而非按规定；关注稳定模式和接口，而非易变的实现细节；重跑时更新现有文档（合并，绝不覆盖）；在 .agents/codebase/*.md 中保持详尽，因为这些文档按需加载，不总是处于上下文中。

技能还明确了两条反模式：

源边界泄漏：.agents/codebase/*.md 只捕获当前可观察状态。绝不将 .artifacts/（简报、PRD、设计文档、史诗、路线图）作为代码库事实来源。前瞻性内容（(planned)、(TBD)、里程碑标签、功能 ID、"shipped through feature X"）属于规划产物，不属于代码库地图。如果某个模块、路由或依赖在 .artifacts/ 中有描述但当前文件系统中不存在，则它不存在。
按依赖名称记录约定：基于 package.json 中列出的内容记录约定是猜测。应读取实际配置文件和源代码，以理解项目如何使用（或扩展、或覆盖）每个库。项目实际的值才重要，而非框架的默认值。