project-index

项目索引

为 AI Agent 生成项目上下文和代码库文档。

触发条件

• 一次性设置（“initialize”“setup project index”“index project”）→ initialize.md
• 项目上下文（“overview”“project context”“refresh project”） → overview.md
• 代码库摘要（“map codebase”“analyze codebase”“summary”） → 通过子 Agent 扇出并行调度 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 + (codebase fan-out + review when brownfield)
refresh    --> git diff range --> subset fan-out + review
                                     (fallback: full fan-out)

initialize 是首次设置的入口点。它始终会运行 overview。如果项目属于棕地项目（已有源代码），它会 启动代码库扇出：并行运行 6 个子 Agent （架构、约定、测试、集成、检查清单、 工作流）；检测到垂直切片时，再运行第 7 个（功能）， 然后主 Agent 以扇出输出为上下文运行 review。

.agents/codebase/ 存在后，可通过 refresh 进行成本更低的重新运行。 它会从上次同步标记开始对 git 进行差异比较，将变更路径分配给 其领域受到影响的子 Agent，并且只调度这些子 Agent。 如果阈值（文件数量、清单变动、入口点变更） 表明存在大范围重构，则回退到完整扇出。

代码库扇出

映射整个代码库时（对棕地项目执行 initialize，或触发“summary”）， 在同一轮中将全部 6 个代码库参考文档作为独立子 Agent调度。 仅当项目呈现垂直切片结构时，才会调度第 7 个子 Agent（features） （参见 features.md 中的 Detection Gate）。

子 Agent	读取内容	写入内容	条件
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）、提交前配置	.agents/codebase/checklist.md	始终
workflows	用于追踪数据流的入口点	.agents/codebase/workflows.md	始终
features	垂直切片目录、路由前缀、共置的测试/处理程序/视图	.agents/codebase/features.md	检测到垂直切片时

每个子 Agent 只读取其领域所需的内容。输出会写入磁盘 — 子 Agent 不会通过上下文返回发现结果。

所有子 Agent 完成后，主 Agent 会以全部输出为上下文运行 review.md。审查不能拆分给多个子 Agent——这项综合工作由主 Agent 负责。

指南

• 阅读实际代码文件以提取模式，而不只是列出文件
• 记录观察到的约定，而非规定应遵循的约定
• 聚焦于稳定的模式和接口，而非易变的实现细节
• 重新运行时更新现有文档（合并，绝不覆盖）
• .agents/codebase/*.md 中的内容要详尽……这些文件会按需加载，并非始终处于上下文中

反模式：源边界泄漏

.agents/codebase/*.md 仅记录当前可观察到的状态。 绝不要将 .artifacts/（简报、PRD、设计文档、史诗、路线图）作为代码库事实的来源。前瞻性内容（(planned)、 (TBD)、里程碑标签、功能 ID、“已交付至功能 X”） 属于规划资料，而非代码库地图。如果 .artifacts/ 中描述了某个模块、路由 或依赖，但它目前并不存在于文件系统中，那它就不存在。

反模式：根据依赖名称推断约定

根据 package.json 中列出的内容来记录约定，属于臆测。请阅读实际的配置文件和源代码，了解项目如何使用（或扩展、覆盖）每个库。重要的是项目的实际配置值，而非框架的默认值。