gky051224

codebase-onboarding-skill

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

gky051224 4 Updated 2mo ago

Resources

7
GitHub

Install

npx skillscat add gky051224/codebase-onboarding-skill

Install via the SkillsCat registry.

SKILL.md

/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. 项目一句话介绍
    用 1～2 句 说清楚：这个项目是什么、解决什么问题、核心价值是什么。
    参考 输出骨架 中的摘要模板。

  2. 技术栈速览
    表格展示：层次（前端/后端/存储/基础设施/工具链）/ 技术选型 / 版本（如可检测）/ 一句话说明。
    参考 技术栈检测。

  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'

Categories

CI/CD Templates
GitHub

Install

npx skillscat add gky051224/codebase-onboarding-skill

Install via the SkillsCat registry.

Recommended Skills