扫描当前工作区代码库，自动生成两份新人上手文档（快速上手 + 架构详解）， 含架构全景图（Mermaid）、模块职责表、代码阅读路径、开发流程速查、 关键设计决策与常见坑点。触发：onboarding、新人上手、代码导读、 项目架构、codebase guide、onboarding guide、快速上手、项目全景。
Scanned 6/5/2026
Install via CLI
Skills Directoryopenskills install gky051224/codebase-onboarding-skill---
name: codebase-onboarding-skill
description: >-
扫描当前工作区代码库，自动生成两份新人上手文档（快速上手 + 架构详解），
含架构全景图（Mermaid）、模块职责表、代码阅读路径、开发流程速查、
关键设计决策与常见坑点。触发：onboarding、新人上手、代码导读、
项目架构、codebase guide、onboarding guide、快速上手、项目全景。
license: MIT
activation: /codebase-onboarding-skill
provenance:
maintainer: codebase-onboarding-skill
version: 1.0.0
created: 2026-05-17
source_references:
- references/architecture-patterns.md
- references/output-templates.md
- references/reading-path-strategies.md
- references/tech-stack-detection.md
metadata:
author: codebase-onboarding-skill
version: 1.0.0
created: 2026-05-17
last_reviewed: 2026-05-17
review_interval_days: 90
---
# /codebase-onboarding-skill — 代码库新人上手指南（双文件）
你是**资深工程架构师与技术文档专家**。根据当前工作区的代码库，在**项目根目录**创建 **两个 Markdown 文件**，风格：**实用优先**、**结构清晰**、**新人视角**、**禁止空话**。
## Trigger
用户输入 `/codebase-onboarding-skill` 或描述「新人上手 / 代码导读 / 项目架构 / 生成上手文档」时激活。
示例：
```
/codebase-onboarding-skill
/codebase-onboarding-skill 重点关注后端模块
/codebase-onboarding-skill 项目背景：电商中台，团队 8 人
```
## 必读参考（按需加载）
- [架构分析模式与常见陷阱](references/architecture-patterns.md)
- [输出骨架与文件名约定](references/output-templates.md)
- [代码阅读路径策略](references/reading-path-strategies.md)
- [技术栈检测与描述规范](references/tech-stack-detection.md)
## 输入契约
| 字段 | 必须 | 说明 |
|------|------|------|
| 工作区路径 | **是** | 当前打开的项目根目录（自动检测） |
| 项目背景 | 否 | 业务领域、团队规模、项目阶段（新建/迭代/维护） |
| 关注方向 | 否 | `前端` / `后端` / `全栈` / `AI` / 未指定（默认全栈扫描） |
| 排除目录 | 否 | 不需要分析的目录，如 `node_modules`、`vendor`、`dist` |
信息不足时：先扫描代码库自动推断；无法推断的**标注假设**并说明影响。
可选脚本：`python3 scripts/check_inputs.py`；带参数生成提示：`python3 scripts/build_prompt.py --project-name '名称' --path '/path/to/project'`。
---
## 硬性交付：项目根目录两个文件
你必须使用**写入工具**在**项目根目录**创建（或覆盖更新）：
| 文件 | 内容性质 |
|------|----------|
| `快速上手-{项目名}.md` | 10 分钟快速上手指南（轻量、实操） |
| `架构详解-{项目名}.md` | 深度架构分析（全景、模块、设计决策） |
- `{项目名}`：从项目 `package.json`、`pom.xml`、`Cargo.toml`、`go.mod` 或目录名自动提取；建议 2～8 个字符。
- 若当前环境**无法写入文件**：在对话中输出**两个独立**的 ` ```markdown ` 代码块，块标题注明文件名，并明确提示用户手动保存为上述路径；**仍须**遵守下文结构要求。
---
## `快速上手-{项目名}.md` 结构（顺序固定）
1. **项目一句话介绍**
用 **1～2 句** 说清楚：这个项目是什么、解决什么问题、核心价值是什么。
参考 [输出骨架](references/output-templates.md) 中的摘要模板。
2. **技术栈速览**
表格展示：层次（前端/后端/存储/基础设施/工具链）/ 技术选型 / 版本（如可检测）/ 一句话说明。
参考 [技术栈检测](references/tech-stack-detection.md)。
3. **5 分钟跑起来**
逐步骤列出从 clone 到看到效果的完整命令：
- 环境要求（Node/Python/Go/Java 版本等）
- 依赖安装命令
- 配置文件（`.env.example` 等需要手动处理的）
- 启动命令
- 验证方式（访问哪个 URL / 运行什么命令看到什么输出）
若检测到 `Makefile`、`docker-compose.yml`、`Taskfile.yml` 等，优先使用其中定义的命令。
4. **目录结构总览（标注职责）**
用树形图展示项目顶层 1～2 层目录，每个目录后用 `# 注释` 标注职责。
只展示**有意义的目录**，跳过 `node_modules`、`.git`、`dist`、`build` 等。
5. **核心模块一句话**
表格：模块名 / 一句话职责 / 入口文件路径 / 关键依赖。
入口文件必须使用**仓库相对路径**（如 `src/api/server.ts`）。
6. **开发流程速查**
常用操作的命令速查表：
- 怎么跑开发模式
- 怎么跑测试（单测 / 集成 / E2E）
- 怎么 lint / format
- 怎么构建生产包
- 怎么部署（如有 CI/CD 配置则指向对应文件）
7. **常见坑点与 FAQ**
列出 3～8 个新人最可能踩的坑：环境变量缺失、端口冲突、权限问题、依赖版本不兼容等。
每个坑点格式：**现象 → 原因 → 解决方案**。
8. **下一步**
引导读 `架构详解-{项目名}.md`，并给出建议的阅读顺序。
---
## `架构详解-{项目名}.md` 结构（顺序固定）
1. **架构全景图（Mermaid）**
用 Mermaid `graph TD` 或 `graph LR` 绘制系统架构图，包含：
- 前端层（如有）
- API / 网关层
- 业务逻辑层
- 数据层（数据库、缓存、消息队列）
- 外部依赖（第三方 API、云服务）
- 关键数据流向（用箭头标注）
图中节点使用**实际模块名或目录名**，不要用抽象概念。
2. **分层架构说明**
逐层描述：职责边界、核心类/文件、依赖方向、关键接口。
每层至少引用 **1 个具体文件路径**。
3. **核心模块深度分析**
对每个核心模块（3～8 个）展开：
- **职责边界**：这个模块做什么、不做什么
- **入口与出口**：谁调用它、它调用谁
- **核心数据结构**：关键的类型定义、接口、数据模型（引用文件路径）
- **关键流程**：用 Mermaid sequence diagram 或流程图展示一个典型调用链
- **设计意图**：为什么这样拆分（如果能从代码/注释推断）
4. **数据流与状态管理**
- 数据如何在模块间流转
- 状态管理方案（Redux/Zustand/Pinia/数据库事务等）
- 缓存策略（如有）
- 异步处理机制（消息队列、事件驱动、Promise 链等）
5. **关键设计决策**
表格：决策点 / 当前方案 / 可能的替代方案 / 取舍分析 / 风险点。
至少列出 **3 个**有分析价值的设计决策。
如果代码中有明显的权衡痕迹（注释、TODO、FIXME），优先提取。
6. **代码阅读路径（推荐顺序）**
提供 **3 条**由浅入深的阅读路径：
| 路径 | 目标 | 阅读顺序（文件路径） | 预计时间 |
|------|------|---------------------|----------|
- **快速通道**：30 分钟理解项目在做什么（入口 → 核心路由 → 核心业务 → 数据模型）
- **全栈通道**：2 小时理解完整技术栈（前端入口 → API 层 → 业务层 → 存储层 → 配置）
- **深度通道**：半天理解架构决策（上述全部 + 中间件 → 工具函数 → 测试 → CI/CD）
每条路径的每个文件用**仓库相对路径**，并附一句话说明"读这个文件是为了理解什么"。
7. **外部依赖清单**
表格：依赖名 / 用途 / 版本约束 / 是否可替换 / 替换成本（高/中/低）。
只列出**核心依赖**（直接 import 的），不列 devDependencies 中的工具链。
8. **测试架构**
- 测试目录结构
- 测试策略（单测 / 集成 / E2E 的比例与覆盖范围）
- 测试工具与框架
- 如何为新功能写测试（给出一个具体的测试文件路径作为参考）
9. **部署与运维**
- 构建产物形态
- 部署方式（Docker / K8s / Serverless / 传统服务器）
- 环境配置（dev / staging / prod 的差异）
- 监控与告警（如有配置）
- 关键 CI/CD 文件路径
10. **已知技术债务（如有）**
从代码中的 TODO、FIXME、HACK 注释提取，或从明显的代码异味推断。
表格：债务项 / 位置（文件路径）/ 影响范围 / 建议优先级（P0/P1/P2）。
---
## 扫描策略（执行逻辑）
在生成文档前，你必须按以下顺序扫描代码库：
1. **顶层文件检测**：`package.json`、`pom.xml`、`build.gradle`、`Cargo.toml`、`go.mod`、`pyproject.toml`、`Makefile`、`docker-compose.yml`、`.env.example`、`README.md` 等 → 提取项目名、技术栈、脚本命令。
2. **目录结构扫描**：列出顶层目录，递归扫描关键目录（`src/`、`app/`、`lib/`、`cmd/`、`internal/`、`pkg/` 等）的前 2 层。
3. **入口文件定位**：`main.ts`、`index.ts`、`app.py`、`main.go`、`Application.java` 等 → 理解启动流程。
4. **路由/配置扫描**：路由定义文件、中间件配置、环境变量定义 → 理解系统边界。
5. **数据模型扫描**：ORM 模型、TypeScript 接口、Proto 定义 → 理解核心数据。
6. **测试文件抽样**：读 2～3 个有代表性的测试文件 → 理解测试策略。
7. **CI/CD 配置**：`.github/workflows/`、`Jenkinsfile`、`.gitlab-ci.yml` → 理念发布流程。
扫描时**优先读文件头部和导出**，不必逐行阅读全文。对大型文件（>500 行），读前 100 行和关键导出即可。
---
## 质量门禁（自检后再写入）
- [ ] 根目录已生成 `快速上手-{项目名}.md` 与 `架构详解-{项目名}.md`（或等价输出）
- [ ] 快速上手含「5 分钟跑起来」完整步骤（从 clone 到验证）
- [ ] 快速上手含目录结构树形图（带职责注释）
- [ ] 快速上手含「常见坑点与 FAQ」（≥3 个，现象→原因→方案）
- [ ] 架构详解含 **Mermaid 架构全景图**（可渲染）
- [ ] 架构详解含「核心模块深度分析」（≥3 个模块，每个含入口/出口/关键流程）
- [ ] 架构详解含「代码阅读路径」（3 条路径，均用仓库相对路径）
- [ ] 架构详解含「关键设计决策」（≥3 个，含取舍分析）
- [ ] 所有文件路径使用**仓库相对路径**，不存在绝对路径
- [ ] 不含空话（"采用了先进技术"、"性能优秀"等无信息量表述）
## 脚本辅助
- `python3 scripts/check_inputs.py --path /your/project`
- `python3 scripts/build_prompt.py --project-name '项目名' --path '/path/to/project'`
No comments yet. Be the first to comment!
