name: 代码库上板 description: 探索一个陌生的代码库并生成一个ARCHITECTURE.md文件，包含组件图、模式目录和开发工作流指南。适用于加入新项目、接手开源仓库或需要理解代码库如何工作时。关键词：上板，架构，探索，理解，代码库，新项目，映射，文档，如何工作 context: fork agent: Explore disable-model-invocation: true allowed-tools: Read, Grep, Glob, Bash(find *), Bash(wc *), Bash(ls *), Write
代码库上板
系统性地探索一个陌生的代码库，并生成一个ARCHITECTURE.md，为开发者提供开始贡献所需的一切。
何时使用
- 加入新团队或项目
- 接手开源仓库进行贡献
- 长时间后重新访问代码库
- 为新团队成员提供引导式介绍
工作流
1. 调查仓库结构
从仓库布局的高级扫描开始：
# 顶级结构
ls -la
# 目录树（2-3层深度）
find . -maxdepth 3 -type d -not -path './.git*' -not -path './node_modules*' -not -path './.direnv*' -not -path './target*' -not -path './dist*' -not -path './.next*' | sort
# 按扩展名计数文件以识别主要语言
find . -type f -not -path './.git/*' -not -path './node_modules/*' | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
# 仓库规模和大小
find . -type f -not -path './.git/*' -not -path './node_modules/*' | wc -l
2. 识别技术栈
阅读关键配置文件以确定技术栈：
检查以下文件（按优先级顺序）：
| 文件 | 揭示内容 |
|---|---|
package.json |
Node.js生态系统、依赖、脚本 |
Cargo.toml |
Rust包、依赖 |
go.mod |
Go模块、依赖 |
pyproject.toml / setup.py / requirements.txt |
Python项目 |
flake.nix / default.nix |
Nix管理项目 |
Makefile / Justfile |
构建命令和工作流 |
docker-compose.yml / Dockerfile |
容器化 |
.github/workflows/*.yml |
CI/CD流水线 |
tsconfig.json |
TypeScript配置 |
.tool-versions / .mise.toml |
运行时版本管理 |
阅读每个存在的配置文件。注意：
- 主要语言和框架
- 构建工具和任务运行器
- 包管理器
- 测试框架
- 代码格式化工具/代码检查工具
- 关键依赖（定义架构的依赖）
3. 查找入口点
定位执行开始的地方：
# 常见入口点
find . -maxdepth 3 -name "main.*" -o -name "index.*" -o -name "app.*" -o -name "server.*" -o -name "cli.*" | grep -v node_modules | grep -v .git
# API路由/处理器
find . -maxdepth 4 -type d -name "routes" -o -name "handlers" -o -name "controllers" -o -name "api" | grep -v node_modules
# 二进制/可执行定义
# （检查Cargo.toml [[bin]], package.json "bin", go main包等）
阅读2-3个入口点文件以理解应用启动。
4. 映射架构
通过阅读关键文件追踪主要组件：
识别组件：
- 顶级目录是什么，每个拥有什么？
- 哪些目录代表不同的服务、包或模块？
- 业务逻辑、基础设施和表示层分别位于哪里？
追踪数据流：
- 从入口点跟随请求通过各层
- 识别数据库/存储层
- 映射外部服务集成
- 注意消息队列、事件总线或异步模式
绘制Mermaid组件图：
graph TD
A[入口点] --> B[路由器/处理器]
B --> C[服务层]
C --> D[数据访问]
D --> E[(数据库)]
C --> F[外部API]
根据实际发现的架构调整此图。包括关键组件及其关系。
5. 目录模式和约定
搜索重复出现的模式：
# 错误处理模式
rg "catch|Error|Result<|anyhow|thiserror|raise|except" --type-list
rg -l "error" --type [主要语言] | head -5
# 测试模式
find . -type f -name "*test*" -o -name "*spec*" | head -10
# 阅读一个测试文件以理解约定
# 配置模式
rg -l "config|env|settings" --type [主要语言] | head -5
文档化：
- 错误处理：错误如何创建、传播和报告
- API模式：REST、GraphQL、RPC约定；请求/响应形状
- 测试约定：文件命名、测试结构、夹具、模拟方法
- 状态管理：应用状态如何存储和访问
- 配置：配置值如何流入应用
6. 文档化开发工作流
查找工作流线索：
# 检查文档化命令
cat Makefile 2>/dev/null || cat Justfile 2>/dev/null || true
# 包管理器脚本
cat package.json 2>/dev/null | jq '.scripts' 2>/dev/null || true
# README说明
cat README.md 2>/dev/null | head -100 || true
文档化：
- 构建：如何编译或打包
- 测试：如何运行测试套件
- 本地运行：如何启动应用进行开发
- 部署：部署如何工作（如果可从CI配置发现）
- 关键环境变量：所需环境变量及其控制内容
7. 编写ARCHITECTURE.md
将最终文档写入仓库根目录。使用此结构：
# 架构
> 由代码库探索自动生成。最后更新日期：[日期]
## 概述
[2-3句话总结：项目做什么、为谁服务、核心技术]
## 技术栈
| 层 | 技术 |
|-------|-----------|
| 语言 | [例如，TypeScript 5.x] |
| 框架 | [例如，Next.js 14] |
| 数据库 | [例如，通过Prisma的PostgreSQL] |
| 测试 | [例如，Vitest + Playwright] |
| 构建 | [例如，Turborepo + pnpm] |
| CI/CD | [例如，GitHub Actions] |
## 架构
[Mermaid图此处]
### 组件描述
- **[组件A]**：[其功能、关键文件]
- **[组件B]**：[其功能、关键文件]
### 数据流
[描述典型请求如何流经系统]
## 关键抽象
- **[抽象1]**：[是什么、位于哪里、为何存在]
- **[抽象2]**：[是什么、位于哪里、为何存在]
## 模式与约定
### 错误处理
[如何处理错误]
### API约定
[请求/响应模式、命名约定]
### 测试约定
[文件命名、测试结构、如何编写新测试]
### 配置
[如何管理配置值]
## 开发工作流
### 先决条件
[需要安装什么]
### 构建
```bash
[构建命令]
测试
[测试命令]
本地运行
[运行命令]
部署
[部署如何工作，或“参见CI配置”]
入口点
| 入口点 | 目的 | 文件 |
|---|---|---|
| [主] | [应用启动] | src/main.ts |
| [CLI] | [命令行接口] | src/cli.ts |
| [API] | [HTTP服务器] | src/server.ts |
目录结构
[带注释的顶级目录树]
## 质量检查清单
在完成前，验证ARCHITECTURE.md覆盖：
- [ ] 新人在30秒内能理解项目做什么
- [ ] 技术栈表格完整且准确
- [ ] Mermaid图反映实际组件关系
- [ ] 至少3个模式/约定被文档化并附示例
- [ ] 开发工作流命令已验证（存在于Makefile/package.json等中）
- [ ] 入口点列出文件路径
- [ ] 无占位文本剩余
## 示例调用
/onboard
从任何仓库根目录运行。无需参数——该技能探索当前工作目录。