📦 Codebase Survey — 代码库调查

代码库调查系统 系统地发现现有代码库的内容、组织结构和复杂性所在。产生一个综合报告，而不是原始文件转储。

何时使用 用户说：“深入研究这个项目”，“探索这个代码库”，“调查这个项目”，“了解架构”，“将我介绍到这个项目”，“带我浏览这个仓库”，“我们这里有什么”

长时间没有工作过的项目，需要在开始工作之前刷新 预规划侦察：需要在估计功能之前了解模式、API 表面和依赖图 交接上下文：向用户（或未来的读者）解释代码库当前包含的内容 重要：CLAUDE.md 覆盖了通用调查 许多项目（尤其是这个用户的项目）维护一个 CLAUDE.md 文件，包含“哪里可以找到东西”的地图。如果项目有一个结构良好的 CLAUDE.md，请先阅读它——在以下步骤之前。使用“哪里可以找到东西”的地图作为主要调查指南。以下步骤成为 CLAUDE.md 没有涵盖的领域的备用方案。 一个丰富的 CLAUDE.md 将告诉你： 项目的文档树结构（哪些文件用于架构、模式、功能、管道） 分支 → 环境拓扑 当前状态/已发布的内容 硬性规则和约定 合同（哪些工件很重要） 这比运行通用广度优先扫描更高效。仅当 CLAUDE.md 不存在、稀疏或过时时，才回退到通用工作流。

变体：目标域深度探索 何时：用户要求对已经熟悉的项目中的特定域或功能进行“深度探索”（例如“预订导入和创建的深度探索”），而不是整个代码库。 项目的 CLAUDE.md 上下文已经加载或可用。 何时不使用：项目不熟悉——首先进行完整的代码库调查。 何时不使用：用户只对一个文件有一个狭窄的问题——直接阅读该文件。

目标深度探索模式 在热身（CLAUDE.md、CLAUDE.local.md、回顾、活动计划加载）后： 阅读相关功能文档——docs/feature-.md 或 docs/technical-documentation.md 中的该域部分。这给出了合同：它应该做什么、API 模式、提示策略、业务规则、验收标准。 阅读 Prisma 模式模型——模型 Booking { ... } 块。注意每个字段、关系、索引和 @map 列名。 交叉引用功能文档的字段描述。 阅读该域下的所有 API 路由——src/app/api//route.ts 中的每个文件和任何子路由。 在预订导入系统中，这是提取、重新处理和导入——三个链接在一起的路由。注意验证模式、身份验证守卫、功能标志守卫和事务模式。 阅读管道/基础设施文件——路由依赖的共享库文件：AI 客户端、提取器、提示解析器、匹配器、日志记录器、成本计算器。这些将包含实际实现深度（视觉与文本提取、空间排序、模糊匹配算法）。 阅读 UI 组件——页面和审查组件。注意数据流：如何从 API 提取数据 → UI 状态 → 提交。 特别注意验证 UX、错误状态、部分提交和休眠功能（如隐藏重新处理按钮）。 合成成结构化报告： 架构概述——ASCII/流程图，显示阶段和数据移动 数据模型——带有字段到字段映射的 Booking 模型，从提取到导入 详细流程——每个阶段（提取 → 审查 → 导入）带有端点、身份验证、处理逻辑 边缘情况和业务规则——规则表及其执行位置（前端 vs 后端 vs 两者） 共享基础设施——src/lib/ai/ 管道及其结构以便重用 休眠/隐藏路径——在代码中存在但从 UI 无法访问的功能（如 Sonnet 重新处理端点） 字段级映射——哪些提取字段映射到哪些导入字段，包括转换（回填、默认值、类型强制） 格式：纯文本或 markdown。不要粘贴原始文件内容——合成。报告应传达从输入到持久化的完整数据流。

与完整调查的比较 方面 完整代码库调查 目标域深度探索 范围 整个项目 一个域/功能 方法 广度优先（14 步） 深度优先（6 步） 阅读模式 代表性样本 该域的每个文件 输出 项目级状态摘要 域级架构 + 数据流 先决条件 项目不熟悉 已经处理过这个项目 何时不使用（完整调查） 项目很小（< 20 个文件）——直接跳到阅读文件 已经处于会话中，用户指定要编辑的文件——直接阅读该文件 用户想要一个狭窄的答案，如“X 在哪里定义”——使用 grep 或知识图谱 工作流 按顺序运行这些步骤。在每个步骤中，合成所发现的内容，然后继续。最终