explore-codebase

name	explore-codebase
description	对陌生代码工程进行系统化探索、逆向梳理与文档化总结。用于用户要求“先熟悉项目”“分析仓库/代码架构”“输出项目概览”“梳理核心流程、模块边界、接口、数据模型、部署运行机制”时；适合接手新仓库、入职交接、历史系统盘点、重构前调研、技术方案前置摸底。

代码工程探索技能

围绕“先建立事实地图，再组织结论输出”执行。不要一上来就凭感觉讲架构，那玩意儿十有八九会跑偏，像闭眼摸大象还非说自己看过全景图。

总体原则

1. 先读入口文件和构建运行文件，再下沉到实现细节。
2. 先确认事实，再做推断；推断必须明确标注为“推测”或“根据代码迹象判断”。
3. 优先找系统边界、主流程、依赖方向和数据流，不要沉迷局部函数细枝末节。
4. 输出结论时必须附证据来源，至少给到具体文件路径；关键判断尽量补充函数、类、路由、配置项名称。
5. 如果某一维度在仓库里不存在，不要硬编，直接写“未发现明确实现”并说明你查了哪些位置。

工作流

1. 建立项目事实地图

先快速识别项目类型、技术栈、运行边界和目录结构：

1. 查看根目录文件与顶层目录，定位 README、构建脚本、包管理文件、容器/部署配置、CI 配置。
2. 识别技术栈与工程形态：
   • 前端：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/
3. 识别主入口、进程类型和上下游依赖：Web 服务、Worker、定时任务、CLI、SDK、单体、微服务、插件式工程等。

优先使用仓库约定的快速搜索工具：

• 文件搜索：fd
• 文本搜索：rg
• 结构化代码搜索：sg / ast-grep

2. 识别主执行链路

围绕“请求或任务从哪进，经过哪些层，最后落到哪”梳理主流程：

1. 找入口：
   • Web 服务从路由注册、控制器、handler、中间件开始。
   • 前端应用从启动文件、路由配置、页面装配、状态管理入口开始。
   • Worker/任务系统从消费者注册、任务调度、消息订阅开始。
2. 找中间层：
   • 服务层、领域层、应用层、仓储层、RPC client、消息发布器、适配器。
3. 找落点：
   • 数据库写入、外部 API 调用、消息队列、缓存、文件系统、对象存储。
4. 用 1-2 条最重要的用户路径或系统任务链路做代表，不要妄图一次性画完整宇宙图。

如果存在多个主流程，优先梳理：

1. 最常见的核心业务路径
2. 对系统边界影响最大的异步链路
3. 初始化/启动流程

分专题分析

3. 项目概览

最少回答这些问题：

1. 这是个什么系统，解决什么问题。
2. 它由哪些主要模块或子系统组成。
3. 使用了什么关键技术栈与基础设施。
4. 哪些目录最值得继续读。

4. 系统架构

从代码和配置里抽取架构信息，而不是拿空泛术语糊墙：

1. 划分层次：表现层、应用层、领域层、基础设施层、共享库。
2. 划分组件：服务、模块、包、子应用、插件、任务进程。
3. 描述依赖方向：谁调用谁、谁依赖谁、谁持久化、谁集成外部系统。
4. 识别横切能力：认证、鉴权、日志、监控、配置、事务、缓存、消息机制。

如果需要更完整的排查项，读取 references/survey-checklist.md。

5. 接口说明

接口不只指 HTTP，也包括 RPC、消息、CLI、内部服务契约：

1. 列出暴露的入口类型：REST、GraphQL、gRPC、WebSocket、消息主题、命令行参数。
2. 说明每类接口的位置、注册方式、主要入参与输出。
3. 识别鉴权、中间件、错误处理、版本策略、限流或幂等机制。
4. 如果没有集中式接口文档，就从路由定义、控制器、DTO、schema、proto 里还原。

6. 数据模型

围绕“核心实体、关系、状态变化”组织，而不是机械抄字段：

1. 找实体定义：ORM model、entity、schema、migration、DTO、事件载荷。
2. 找关系：一对多、多对多、聚合根、外键、嵌套文档、缓存 key。
3. 找生命周期：创建、更新、状态流转、归档、删除、补偿。
4. 区分持久化模型、接口模型、领域模型，避免混成一锅粥。

7. 部署与运行机制

至少覆盖以下方面：

1. 本地运行方式：启动命令、依赖服务、环境变量、初始化步骤。
2. 构建产物：二进制、容器镜像、前端静态资源、JAR/Wheel 等。
3. 部署形态：单机、容器、Compose、Kubernetes、Serverless、PaaS。
4. 运行时依赖：数据库、缓存、MQ、对象存储、第三方 API。
5. 配置注入方式：.env、配置中心、启动参数、Secret、CI/CD。

如果需要组织输出，可读取 references/output-template.md。

推荐阅读顺序

默认按下面顺序收集证据，避免一头扎进业务细节出不来：

1. 根目录说明文件与工程清单
2. 构建/包管理/运行配置
3. 应用入口与路由/任务注册
4. 核心业务模块
5. 数据模型与迁移
6. 部署、容器、CI/CD 配置
7. 监控、日志、告警、运维脚本

输出要求

最终输出默认包含以下小节；缺项时明确写“未发现”：

1. 项目概览
2. 技术栈与目录结构
3. 核心流程
4. 系统架构
5. 接口说明
6. 数据模型
7. 部署与运行机制
8. 关键风险与待确认问题

输出时：

1. 优先写事实，再写判断。
2. 每个结论尽量附文件证据。
3. 复杂流程优先用“步骤列表”或“请求 -> 服务 -> 存储/外部系统”的方式表达。
4. 对拿不准的地方单列“待确认”，别装懂。

深挖策略

当用户继续追问时，沿以下方向扩展：

1. “这个模块怎么工作的” -> 顺着调用链继续下钻。
2. “系统瓶颈在哪” -> 查缓存、数据库访问、异步队列、批处理、锁、事务。
3. “改造风险是什么” -> 查耦合点、共享模型、隐式配置、脚本依赖、跨服务契约。
4. “怎么部署上线” -> 查镜像构建、环境变量、发布流水线、健康检查、回滚方式。

禁忌

1. 不要把 README 的宣传词直接当事实。
2. 不要只看目录名就断言采用了某种架构。
3. 不要从单个文件推出全局设计，除非有多处证据互相印证。
4. 不要在没确认的情况下编造接口、库表或部署方式。