| name | explore-codebase |
| description | 对陌生代码工程进行系统化探索、逆向梳理与文档化总结。用于用户要求“先熟悉项目”“分析仓库/代码架构”“输出项目概览”“梳理核心流程、模块边界、接口、数据模型、部署运行机制”时；适合接手新仓库、入职交接、历史系统盘点、重构前调研、技术方案前置摸底。 |
代码工程探索技能
围绕“先建立事实地图，再组织结论输出”执行。不要一上来就凭感觉讲架构，那玩意儿十有八九会跑偏，像闭眼摸大象还非说自己看过全景图。
总体原则
- 先读入口文件和构建运行文件，再下沉到实现细节。
- 先确认事实，再做推断；推断必须明确标注为“推测”或“根据代码迹象判断”。
- 优先找系统边界、主流程、依赖方向和数据流，不要沉迷局部函数细枝末节。
- 输出结论时必须附证据来源，至少给到具体文件路径；关键判断尽量补充函数、类、路由、配置项名称。
- 如果某一维度在仓库里不存在，不要硬编，直接写“未发现明确实现”并说明你查了哪些位置。
工作流
1. 建立项目事实地图
先快速识别项目类型、技术栈、运行边界和目录结构：
- 查看根目录文件与顶层目录，定位
README、构建脚本、包管理文件、容器/部署配置、CI 配置。
- 识别技术栈与工程形态：
- 前端：
package.json、vite.config.*、next.config.*、src/main.*
- 后端：
pom.xml、build.gradle*、requirements.txt、pyproject.toml、go.mod、Cargo.toml
- 服务治理/部署：
Dockerfile、docker-compose.*、helm/、charts/、k8s/、.github/workflows/
- 接口描述：
openapi.*、swagger.*、proto/
- 数据模型：
schema.sql、prisma/、migrations/、models/、entities/
- 识别主入口、进程类型和上下游依赖：Web 服务、Worker、定时任务、CLI、SDK、单体、微服务、插件式工程等。
优先使用仓库约定的快速搜索工具：
- 文件搜索：
fd
- 文本搜索：
rg
- 结构化代码搜索：
sg / ast-grep
2. 识别主执行链路
围绕“请求或任务从哪进，经过哪些层，最后落到哪”梳理主流程：
- 找入口：
- Web 服务从路由注册、控制器、handler、中间件开始。
- 前端应用从启动文件、路由配置、页面装配、状态管理入口开始。
- Worker/任务系统从消费者注册、任务调度、消息订阅开始。
- 找中间层：
- 服务层、领域层、应用层、仓储层、RPC client、消息发布器、适配器。
- 找落点：
- 数据库写入、外部 API 调用、消息队列、缓存、文件系统、对象存储。
- 用 1-2 条最重要的用户路径或系统任务链路做代表，不要妄图一次性画完整宇宙图。
如果存在多个主流程，优先梳理：
- 最常见的核心业务路径
- 对系统边界影响最大的异步链路
- 初始化/启动流程
分专题分析
3. 项目概览
最少回答这些问题：
- 这是个什么系统，解决什么问题。
- 它由哪些主要模块或子系统组成。
- 使用了什么关键技术栈与基础设施。
- 哪些目录最值得继续读。
4. 系统架构
从代码和配置里抽取架构信息，而不是拿空泛术语糊墙：
- 划分层次：表现层、应用层、领域层、基础设施层、共享库。
- 划分组件：服务、模块、包、子应用、插件、任务进程。
- 描述依赖方向：谁调用谁、谁依赖谁、谁持久化、谁集成外部系统。
- 识别横切能力：认证、鉴权、日志、监控、配置、事务、缓存、消息机制。
如果需要更完整的排查项，读取 references/survey-checklist.md。
5. 接口说明
接口不只指 HTTP，也包括 RPC、消息、CLI、内部服务契约：
- 列出暴露的入口类型：REST、GraphQL、gRPC、WebSocket、消息主题、命令行参数。
- 说明每类接口的位置、注册方式、主要入参与输出。
- 识别鉴权、中间件、错误处理、版本策略、限流或幂等机制。
- 如果没有集中式接口文档，就从路由定义、控制器、DTO、schema、proto 里还原。
6. 数据模型
围绕“核心实体、关系、状态变化”组织，而不是机械抄字段：
- 找实体定义：ORM model、entity、schema、migration、DTO、事件载荷。
- 找关系：一对多、多对多、聚合根、外键、嵌套文档、缓存 key。
- 找生命周期：创建、更新、状态流转、归档、删除、补偿。
- 区分持久化模型、接口模型、领域模型，避免混成一锅粥。
7. 部署与运行机制
至少覆盖以下方面：
- 本地运行方式：启动命令、依赖服务、环境变量、初始化步骤。
- 构建产物：二进制、容器镜像、前端静态资源、JAR/Wheel 等。
- 部署形态：单机、容器、Compose、Kubernetes、Serverless、PaaS。
- 运行时依赖：数据库、缓存、MQ、对象存储、第三方 API。
- 配置注入方式：
.env、配置中心、启动参数、Secret、CI/CD。
如果需要组织输出，可读取 references/output-template.md。
推荐阅读顺序
默认按下面顺序收集证据，避免一头扎进业务细节出不来：
- 根目录说明文件与工程清单
- 构建/包管理/运行配置
- 应用入口与路由/任务注册
- 核心业务模块
- 数据模型与迁移
- 部署、容器、CI/CD 配置
- 监控、日志、告警、运维脚本
输出要求
最终输出默认包含以下小节；缺项时明确写“未发现”：
- 项目概览
- 技术栈与目录结构
- 核心流程
- 系统架构
- 接口说明
- 数据模型
- 部署与运行机制
- 关键风险与待确认问题
输出时：
- 优先写事实，再写判断。
- 每个结论尽量附文件证据。
- 复杂流程优先用“步骤列表”或“请求 -> 服务 -> 存储/外部系统”的方式表达。
- 对拿不准的地方单列“待确认”，别装懂。
深挖策略
当用户继续追问时，沿以下方向扩展：
- “这个模块怎么工作的” -> 顺着调用链继续下钻。
- “系统瓶颈在哪” -> 查缓存、数据库访问、异步队列、批处理、锁、事务。
- “改造风险是什么” -> 查耦合点、共享模型、隐式配置、脚本依赖、跨服务契约。
- “怎么部署上线” -> 查镜像构建、环境变量、发布流水线、健康检查、回滚方式。
禁忌
- 不要把 README 的宣传词直接当事实。
- 不要只看目录名就断言采用了某种架构。
- 不要从单个文件推出全局设计，除非有多处证据互相印证。
- 不要在没确认的情况下编造接口、库表或部署方式。
