/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'