Skip to content
Skills Library
Programming · Writing

codebase-onboarding-skill

/codebase-onboarding-skill

扫描当前工作区代码库,自动生成两份新人上手文档(快速上手 + 架构详解), 含架构全景图(Mermaid)、模块职责表、代码阅读路径、开发流程速查、 关键设计决策与常见坑点。触发:onboarding、新人上手、代码导读、 项目架构、codebase guide、onboarding guide、快速上手、项目全景。

Licence
MIT
Last repository change
17.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: install.sh

What it does and when to use it

扫描当前工作区代码库,自动生成两份新人上手文档(快速上手 + 架构详解), 含架构全景图(Mermaid)、模块职责表、代码阅读路径、开发流程速查、 关键设计决策与常见坑点。触发:onboarding、新人上手、代码导读、 项目架构、codebase guide、onboarding guide、快速上手、项目全景。

Original author description

扫描当前工作区代码库,自动生成两份新人上手文档(快速上手 + 架构详解), 含架构全景图(Mermaid)、模块职责表、代码阅读路径、开发流程速查、 关键设计决策与常见坑点。触发:onboarding、新人上手、代码导读、 项目架构、codebase guide、onboarding guide、快速上手、项目全景。

How it works

  1. Trigger
  2. 必读参考(按需加载)
  3. 输入契约
  4. 硬性交付:项目根目录两个文件
  5. 快速上手-{项目名}.md 结构(顺序固定)
  6. 架构详解-{项目名}.md 结构(顺序固定)
  7. 扫描策略(执行逻辑)
  8. 质量门禁(自检后再写入)
  9. 脚本辅助
Original SKILL.md headings · 201 lines, 541 words
SKILL.md preview
---
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'`
Files in this package (6)
  • .gitignore 1 KB
  • LICENSE 2 KB
  • README.md 11 KB
  • README_EN.md 8 KB
  • SKILL.md 10 KB
  • install.sh 26 KB

Versions

The database has no other skills named codebase-onboarding-skill.

Database snapshot: 13.11.2026 · package version b0818cfdacc0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100project-docs
    对任意代码项目生成一套面向新人的循序渐进文档集,输出到 docs/ 目录。含架构、设计思想、语言特性、代码导读、运行时模型、构建、对接、调试、设计规范共 9 篇,支持全部生成 / 只写几篇 / 更新已有文档。当用户提到"生成项目文档"、"新人文档"、"上手文档"、"架构文档"、"代码导读"、"项目理解"、"深入理解项目"、"onboarding 文档"、"给新同事看的文档"时使用。要按用户给的格式写论文章节、项目梳理、重点问题、简历项目描述的,用 codegen-doc。
  • 100codebase-onboarding
    Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter AGENTS.md. Use when joining a new project or setting up Claude Code for the first time in a repo.
  • 100codebase-onboarding
    Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter CLAUDE.md. Use when joining a new project or setting up Claude Code for the first time in a repo.
  • 100build-study-guide
    Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.
  • 90codebase-onboarding
    Analyze a codebase and generate onboarding docs: architecture overviews, file maps, setup guides, runbooks, and debugging guides. Use when onboarding new team members, open-sourcing, or documenting after a major refactor.
  • 100codebase-onboarding
    Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter CODEX.md. Use when joining a new project or setting up OpenAI Codex for the first time in a repo.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.