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