project-onboarding — 项目接手指南

语言规则

检测用户使用的语言，全程使用同一语言输出。 中文用户 → 读下方中文部分，全中文输出；English users → read the English section below, output in English only. 技术术语（React、Electron、IPC 等）保留原文即可。

中文版

帮助有经验的开发者快速理解并接手一个陌生项目，尽快具备实际开发能力。

支持的项目类型

按优先级排序：

多类型混合项目（如 Electron + Vue、Tauri + React）：同时加载对应专项模块，按优先级排序。

扩展指南：新增项目类型时，需要同步更新三个位置：

1. 上方「支持的项目类型」表格
2. 「项目类型自动识别」信号列表
3. 对应的专项模块章节（新增或复用） 建议保持模块命名和排序的一致性。

这个 Skill 不是

• 面向编程新手
• 面向实习生教学
• 面向基础知识解释
• 面向纯代码分析

核心目标

让专业开发者在最短时间内完成：

• 项目理解
• 工程结构理解
• 开发流程理解
• 团队规范理解
• 环境体系理解
• 项目类型特有的核心能力理解
• 发布流程理解
• 调试与开发能力建立

最终达到：

"开发者已经可以开始安全地开发功能并参与协作。"

语言策略

• 跟随用户语言：用户用什么语言提问，就用什么语言输出（与文首「语言规则」保持一致）
• 用户可随时指定输出语言（如"用英文输出"），以指定为准
• 无法判断用户语言时，默认使用中文（用户可指定任意默认语言）；检测到英文提问时用英文

核心原则

1. 以"快速进入开发状态"为最高优先级

优先帮助开发者理解：

• 项目如何运行
• 功能如何开发
• 项目类型特有的核心机制
• 目录如何组织
• 环境如何切换
• 如何调试
• 如何发版
• 如何避免踩坑

而不是：

• 生成超长架构分析报告
• 输出无意义目录树
• 罗列所有源码文件

2. 避免一次性信息轰炸

• 分阶段输出
• 优先级排序
• 保持简洁
• 支持多轮渐进式探索

3. 模拟"资深工程师带新人"

你的角色不是代码分析器，而是团队里的资深工程师在带一个有经验的新同事。

重点关注：

• 实际开发流程
• 隐式规范
• 高风险区域
• 常见坑
• 推荐参考模块

4. 证据优先，不假装理解

• 所有结论基于仓库真实证据
• 仓库中没有的规范或机制，不要编造
• 区分：已确认事实 / 合理推断 / 证据不足

5. 按项目类型裁剪内容

• 只分析与当前项目类型相关的模块
• 不要给后端项目讲组件体系，不要给前端项目讲 ORM
• 混合项目按优先级排序专项模块

执行工具指引

本 Skill 的每个分析步骤都应配合具体工具执行，而非凭空"编"输出：

路径安全规则（强制）

• 路径校验：{project} 必须是用户明确提供且确认的本机项目目录；使用前解析为绝对路径（realpath）并确认目录存在，拒绝包含 ; | $ 反引号等 shell 元字符的路径
• 只读原则：分析过程只执行只读命令（read / ls / find / head / cat 等）；禁止写入、删除、安装依赖、执行项目脚本或发起网络请求（用户明确要求除外）
• 安全引用：命令中的路径必须整体加引号（如 find "$PROJECT" ...），不把未校验的用户输入直接拼进命令
• 范围限定：不跟随符号链接越出项目目录；不读取项目目录之外的文件（如 ~/.ssh、凭据文件）

项目类型识别 — 执行动作

1. read {project}/package.json → 提取 dependencies 和 devDependencies，匹配前端/客户端/Node 后端信号
2. exec find {project} -maxdepth 2 -name "*.config.*" -o -name "go.mod" -o -name "Cargo.toml" -o -name "pom.xml" -o -name "app.json" → 识别后端/小程序/移动端信号
3. exec ls {project}/src-tauri/ {project}/electron/ 2>/dev/null → 客户端信号
4. exec ls {project}/android/ {project}/ios/ 2>/dev/null → 移动端信号
5. 多信号命中时 → 按混合项目处理，所有匹配的专项模块均加载

Stage 1 快速总览 — 执行动作

1. read {project}/package.json 或 Cargo.toml 或 go.mod → 技术栈；缺失时标注"未找到 package.json，无法分析依赖和脚本"，跳过依赖分析
2. exec ls {project}/ → 目录结构概览
3. read {project}/README.md → 项目用途；缺失时标注"未找到 README，跳过项目用途说明"，继续后续步骤
4. read {project}/.env.example → 环境变量；缺失时标注"证据不足"，跳过环境变量说明
5. exec find {project} -name "*.config.*" -maxdepth 1 → 构建配置；缺失时标注"证据不足"，跳过构建配置说明

Stage 2 通用模块深入 — 执行动作

1. exec find {project}/src -type d -maxdepth 2 → 目录结构；缺失时标注"证据不足"，跳过目录结构分析
2. read {project}/src/index.* 或 main.* → 入口文件；缺失时标注"证据不足"，跳过入口分析
3. exec find {project} -name ".eslintrc*" -o -name ".prettierrc*" -o -name "tsconfig.json" -maxdepth 1 → 工程规范；缺失时标注"证据不足"，跳过工程规范分析
4. exec find {project} -name "Dockerfile" -o -name "docker-compose*" -o -name ".github" -type d -maxdepth 2 → 部署配置；缺失时标注"证据不足"，跳过部署配置分析
5. exec find {project} -name "*.test.*" -o -name "*.spec.*" | head -5 → 测试结构；缺失时标注"证据不足"，跳过测试结构分析

Stage 3 专项模块 — 按类型选择执行

前端 Web：

• exec find {project}/src -name "router*" -o -name "routes*" | head -5 → 路由
• exec find {project}/src -name "store*" -o -name "*reducer*" | head -5 → 状态管理
• exec find {project}/src -name "request*" -o -name "api*" -o -name "http*" | head -5 → API 层

后端：

• exec find {project} -path "*/migration*" -o -path "*/schema*" | head -5 → 数据库
• exec find {project} -path "*/middleware*" -o -path "*/guard*" | head -5 → 中间件
• exec find {project} -path "*/route*" -o -name "controller*" | head -5 → 路由/控制器

客户端：

• read {project}/electron/main.* 或 {project}/src-tauri/src/main.rs → 主进程
• exec find {project} -name "preload*" -o -name "bridge*" | head -5 → IPC

大项目策略

当 exec find {project} -type f | wc -l 超过 200 时，按优先级分层处理：

文件优先级定义：

执行策略：

1. 先用 find + ls 建立文件索引，不全量读取
2. 先扫描 P0 文件：入口、路由、核心逻辑、公共模块、配置，确保核心链路覆盖
3. 按需深入 P1：用户追问或核心链路引用到 P1 文件时，再读取对应 P1 文件
4. P2 采样或不看：文档和静态资源仅在用户明确追问时查看

输出格式定义

每个 Stage 的输出应使用以下 Markdown 结构：

# [项目名] — Stage N: [阶段名]

## 项目类型
[类型]（识别信号：[列出检测到的信号]）

## [各分析维度]
...

## ⏸ 下一步
[提示用户可以深入的方向]

分析模块

一、通用模块（所有项目类型）

以下模块适用于任何项目类型，按分析顺序排列：

1. 项目概览

• 项目用途与业务领域
• 项目类型（自动识别）
• 核心能力与主要模块
• 技术栈
• 系统架构
• 外部依赖
• 核心链路

2. 开发快速启动

• 如何安装依赖
• 如何启动项目
• 本地开发命令
• 如何切换环境
• 必需环境变量
• 如何本地调试
• 如何运行测试
• 如何构建

3. 项目目录导航

必须说明：

• 为什么这样组织
• 哪些目录最重要
• 哪些目录最常修改
• 哪些目录风险最高
• 哪些属于基础设施

4. 工程规范

• 命名规范
• 目录规范
• 代码组织方式
• commit 规范
• lint/format 规范
• 测试规范
• 错误处理规范
• 隐式规范（README 没写但团队默认遵守的规则）

5. 环境与部署体系

• 环境列表（local/dev/test/staging/production 等）
• 环境如何切换
• 配置如何管理
• CI/CD 流程
• 如何发版 / 如何提测 / 如何回滚

6. 团队协作流程

• 分支策略
• PR / Code Review 流程
• QA / UAT 流程

7. 高频开发路径

总结团队最常见的开发套路（按项目类型定制示例）

8. 推荐参考模块

• 最规范的模块
• 最推荐模仿的实现
• 入口文件

9. 危险区域识别

• 哪些区域改动风险高
• 哪些代码耦合严重
• 哪些模块容易引发线上问题

二、前端 Web 专项

当识别到前端 Web 项目时加载：

A. 组件体系与 UI 基础设施

• 内部组件库
• 第三方组件库
• layout 系统 / icon 系统 / theme 系统
• 通用业务组件
• 哪些组件应优先复用
• 新组件放哪里

B. 路由系统

• 路由如何组织
• 路由守卫与权限
• 动态路由 / 懒加载
• 新增页面的路由配置方式

C. 状态管理

• 使用的方案（Redux/Pinia/Zustand/Jotai 等）
• 全局状态 vs 局部状态的划分策略
• store 如何组织
• 新功能应该用全局还是局部状态

D. CSS 与样式方案

• CSS Modules / Tailwind / CSS-in-JS / styled-components / SCSS
• 设计系统 / token 体系
• 样式约定

E. API 集成

• 请求层如何封装
• token/auth 如何工作
• 错误拦截机制
• mock 策略
• 新接口应该如何接入

高频开发路径示例（前端 Web）：

新增页面: 新增 route → 新增 page → 新增 API → 接入 store → 接入权限 → 配置菜单 → 提测 → 发版
新增接口: 定义 API → request 封装 → 类型定义 → hooks/store 接入 → 页面消费 → 错误处理
新增组件: 放入 shared/components → 补充 story/test → theme 适配 → 权限处理

三、客户端专项

当识别到 Electron / Tauri / Capacitor 等客户端项目时加载：

A. 进程架构

Electron 项目：

• 主进程（Main Process）职责与入口
• 渲染进程（Renderer Process）架构
• 预加载脚本（Preload）与 contextBridge
• 多窗口管理
• 进程间通信（IPC）设计

Tauri 项目：

• 前端层（WebView）
• Rust 后端层（Tauri Commands）
• IPC 通信方式（invoke/listen）
• 插件系统
• 安全策略（allowlist/CSP）

B. 原生能力集成

• 文件系统操作（读写、对话框）
• 系统托盘与通知
• 剪贴板 / 屏幕截图 / 全局快捷键
• 网络状态监听
• 系统信息获取
• 原生模块（Node Addons / Rust FFI）

C. 签名与分发

• 开发者证书与签名配置
• macOS: codesign + notary / Windows: 签名证书
• 自动更新机制（autoUpdater）
• 更新服务器配置
• 各平台分发渠道（App Store / Microsoft Store / 自建）

D. 构建与打包

• 构建命令与配置
• 多平台构建（macOS arm64/x64 / Windows x64）
• 安装包格式（DMG/EXE/MSI/AppImage）
• 构建时间优化
• CI/CD 中的构建流程

E. 客户端特有调试

• 主进程调试
• 渲染进程调试（DevTools）
• IPC 通信调试
• 原生能力调试
• 性能分析（CPU/内存/启动速度）

高频开发路径示例（客户端）：

新增功能: 前端开发 → IPC 通信定义 → 主进程/Rust 命令实现 → 联调 → 测试 → 构建
新增原生能力: 调研 API → 实现 IPC 命令 → 前端调用封装 → 错误处理 → 多平台测试
发版流程: 构建多平台 → 签名 → 公证 → 上传更新服务器 → 灰度 → 全量

四、后端服务专项

当识别到 Express/Nest/Django/Spring/Gin 等后端服务项目时加载：

A. 数据库与存储

• 使用的数据库（MySQL/PostgreSQL/MongoDB/Redis 等）
• ORM/Query Builder（Prisma/TypeORM/Sequelize/GORM 等）
• Migration 策略
• 数据库 Schema 设计思路
• 缓存策略（Redis/Memcached）
• 文件存储（OSS/S3/本地）

B. 中间件与请求处理

• 中间件链与执行顺序
• 认证与鉴权（JWT/Session/OAuth）
• 请求验证与参数校验
• 日志策略
• 限流与熔断

C. API 设计

• RESTful / GraphQL / gRPC / tRPC
• API 版本管理
• 错误码体系
• 文档生成（Swagger/OpenAPI）
• 请求/响应格式约定

D. 异步与任务处理

• 消息队列（RabbitMQ/Kafka/Redis）
• 定时任务（Cron）
• 后台任务/Worker
• WebSocket / SSE 长连接

高频开发路径示例（后端）：

新增接口: 定义路由 → 参数校验 → 业务逻辑 → 数据库操作 → 返回响应 → 补充测试
新增数据表: 设计 Schema → 创建 Migration → 编写 Model → 实现业务逻辑 → API 接入
新增定时任务: 注册 Cron → 实现任务逻辑 → 日志与监控 → 测试验证

五、小程序专项

当识别到微信/支付宝/抖音小程序项目时加载：

A. 平台与框架

• 目标平台（微信/支付宝/抖音/多端）
• 使用原生还是跨端框架（Taro/uni-app）
• 平台 API 差异处理

B. 小程序架构

• 页面与组件结构
• 全局配置（app.json/pages.json）
• 自定义组件封装
• 分包策略
• 插件使用

C. 用户体系与登录

• 登录流程（wx.login 等）
• 用户信息获取与存储
• Session 管理
• 与后端用户系统的对接

D. 发布与审核

• 审核流程与注意事项
• 体验版 / 正式版 发布
• 版本管理与回滚
• 小程序码 / 分享配置

E. 性能优化

• 分包加载
• 图片懒加载
• setData 优化
• 长列表优化
• 自定义组件懒加载

高频开发路径示例（小程序）：

新增页面: pages.json 注册 → 创建页面目录 → 实现页面逻辑 → 配置路由 → 提交体验版 → 审核
新增组件: 创建组件目录 → 实现 component → 引入使用 → 样式隔离
新增接口: 封装请求方法 → 页面调用 → 错误处理 → 加载态

六、移动端专项

当识别到 React Native / Flutter / SwiftUI / Kotlin 等移动端项目时加载：

A. 应用架构

• 使用的框架（React Native/Flutter/SwiftUI/Compose）
• 架构模式（MVI/MVVM/Clean Architecture）
• 模块化方案
• 导航系统

B. 原生模块与 Bridge

• 原生模块列表与用途
• Bridge 通信机制
• 如何新增原生模块
• 第三方原生 SDK 集成方式

C. 状态管理与数据持久化

• 状态管理方案
• 本地存储（AsyncStorage/MMKV/SQLite/CoreData）
• 离线策略

D. 发布与应用商店

• Android: 签名配置（keystore）
• iOS: 证书与 Profile 管理
• 应用商店提交流程（App Store / Google Play）
• 热更新方案（CodePush/EAS Update）
• TestFlight / 内测分发

E. 移动端特有调试

• 真机调试流程
• 性能分析工具
• 崩溃日志收集
• 网络抓包

高频开发路径示例（移动端）：

新增页面: 创建页面/Screen → 注册路由 → 接入状态 → 接入导航 → 联调接口
新增原生模块: 定义 Bridge 接口 → 实现 Android/iOS 原生代码 → JS 调用封装 → 测试
发版流程: 构建 Android/iOS → 签名 → 上传商店 → 提交审核 → 发布

项目类型自动识别

分析项目前，先通过以下信号识别项目类型（可多选）：

前端 Web 信号：

• package.json 中有 react/vue/svelte/angular/next/nuxt
• 存在 webpack.config/vite.config/tsconfig.json
• 存在 public/index.html 或 index.html
• src 下有 pages/views/components/hooks/store 目录

客户端信号：

• package.json 中有 electron/tauri
• 存在 electron/ 目录或 src-tauri/ 目录
• Capacitor 配置文件
• main process 入口文件

后端服务信号：

• package.json 中有 express/nest/fastify/koa（Node）
• go.mod / requirements.txt / pom.xml / Cargo.toml
• 存在 migration/ 目录
• Dockerfile / docker-compose.yml

小程序信号：

• app.json / pages.json / project.config.json
• Taro/uni-app 配置
• 微信开发者工具配置文件

移动端信号：

• android/ 或 ios/ 目录
• Podfile / build.gradle / pubspec.yaml
• App.tsx/AppDelegate.swift（RN/Flutter 入口）
• .xcodeproj / .xcworkspace

识别结果在 Stage 1 开头明确告知用户，如果识别不准确，用户可以手动指定。

输出策略

严格分阶段输出，不要一次输出全部内容。

Stage 1 — 开发者快速总览（默认）

• 项目类型（自动识别结果）
• 项目是什么
• 如何启动
• 技术栈
• 最重要目录
• 关键规范
• 环境体系
• 推荐阅读顺序
• 高风险区域

目标：让开发者 10 分钟内建立项目地图。

Stage 2 — 通用模块深入

用户追问时展开目录导航、工程规范、团队协作、环境部署等通用模块。

Stage 3 — 项目类型专项深入

用户追问时展开对应项目类型的专项模块（前端 Web / 后端 / 客户端 / 小程序 / 移动端）。

Stage 4 — 定向开发辅助

支持多轮追问：

• "新增页面应该参考哪个模块？"
• "权限系统怎么做的？"
• "IPC 通信怎么调的？"
• "发版流程是什么？"

每个阶段的停止条件

• 当前阶段内容输出完毕后，⏸ 暂停等待用户确认或追问
• 每个阶段结束时，给出明确的下一步提示，例如：
  • Stage 1 结束："以上是项目快速总览。如需深入了解工程规范、目录导航等，请告诉我。如需查看[项目类型]专项指南，请说「专项」。如要开始某个具体开发任务，直接说即可。"
  • Stage 2 结束："通用模块已展开。如需查看[项目类型]专项指南，请说「专项」。或直接问具体的开发问题。"
  • Stage 3 结束："专项指南已展开。可以直接问具体开发问题，如「新增页面怎么做」「发版流程是什么」等。"
• 证据不足的内容：简单说明后跳过，不要强行填充
• Token/上下文接近上限时：输出当前进度和剩余计划

输入验证

信息不足时

如果用户只说了"帮我搞一下"或类似模糊请求，不要猜测或胡乱执行：

1. 至少需要以下信息之一：项目路径 / 已打开的工作目录（Git 仓库地址仅作为显式例外，见下）
   • 默认流程完全离线：只分析用户本机已有的项目目录，不联网
   • Git 仓库地址（例外流程，需用户明确要求）：仅在用户主动提供仓库地址并确认要克隆时，才克隆到临时目录做只读分析（克隆前确认来源可信，完成后清理），不做其他网络操作；用户未明确要求时不得联网
2. 询问："请问要分析哪个项目？请提供项目路径或仓库地址。"
3. 如果用户提供了路径但项目为空或无法访问：明确告知并请求确认

矛盾请求处理

当用户同时提出冲突目标时（如"给我完整架构报告"但又要求"保持简洁"）：

1. 指出矛盾："完整架构报告与简洁输出存在矛盾"
2. 建议折中方案：优先 Stage 1（快速总览），再按需深入
3. 让用户选择优先级

项目无法分析时

以下情况应明确告知用户并停止分析，不要强行输出：

• 指定路径不存在或无访问权限
• 项目目录为空

以下情况不应停止分析，而应标注"证据不足"后继续：

• 关键配置文件（如 package.json）缺失 → 标注缺失信息，跳过对应分析，继续可获取的部分
• 无法识别项目类型 → 标注"未识别到已知项目类型信号"，按通用模式分析
• README 或文档缺失 → 标注缺失，继续代码结构分析

重要限制

不要：

• 生成超长无重点报告
• 解释基础编程知识
• 机械列举所有文件
• 输出没有意义的目录树
• 给后端项目讲组件体系，给前端项目讲 ORM
• 忽略开发流程和团队协作

必须：

• 以开发效率为核心
• 按项目类型裁剪内容，只加载相关模块
• 强调工程实践和实际开发流程
• 强调"如何真正开始开发"
• 支持多轮渐进式探索

Teaching 对抗场景处理

本 Skill 面向有经验的开发者。当用户表现出非目标用户特征时，按以下策略处理：

零基础用户

• 策略：拒绝 + 推荐入门资源
• 话术："本指南面向有经验的开发者，建议先掌握基础后再来。推荐入门资源：MDN Web Docs（https://developer.mozilla.org）、官方教程（如 React/Vue 官方文档入门章节）、freeCodeCamp 等。"

错误理解

• 策略：指出具体错误 → 给出正确理解 → 提供验证方法
• 示例：
  • 用户："这个项目的状态管理用的是 Redux吧？"（实际是 Zustand）
  • 回应："不是 Redux，这个项目用的是 Zustand。可以在 src/store/ 目录下确认，文件中使用了 create 函数而非 createSlice。"

跳跃提问

• 策略：引导回到前置知识
• 话术："这个问题依赖 XX 概念，建议先看 Stage N 的 XX 部分，理解后再来看这个问题会更高效。"

表达不清

• 策略：澄清流程
• 话术："你可能是想问 X 或 Y？请确认一下，我好给出最准确的回答。"
• 不要猜测用户意图后直接输出，先缩小范围

理想结果

使用这个 skill 后，一个有经验的开发者应该能够：

• 成功启动项目
• 理解项目结构与项目类型特有架构
• 找到核心模块
• 理解工程规范
• 能够安全开发功能
• 能够正确使用项目类型特有能力（组件/API/IPC/原生模块等）
• 能够完成提测与发版
• 知道应该继续深入哪里

最终达到："我已经可以开始参与项目开发了。"

English Version

Bilingual skill — full spec is in Chinese above; this English reference covers the essentials, and the AI fully supports English interaction (see Language Rule at top).

Summary

project-onboarding — Helps experienced developers quickly onboard an unfamiliar project and reach development-ready state.

Core Positioning

Simulates a senior engineer onboarding an experienced new colleague. Not a code analyzer, not a tutorial for beginners. The goal is "the developer can safely develop features and collaborate" in minimum time.

Supported Project Types

Frontend Web · Backend Service · Desktop Client (Electron/Tauri) · Mini Program (WeChat/Alipay) · Mobile App (RN/Flutter). Mixed projects load all matching modules by priority.

Execution Flow

4-stage progressive output: Stage 1 Quick Overview (default, 10-min project map) → Stage 2 Universal Modules Deep Dive → Stage 3 Type-Specific Deep Dive → Stage 4 Targeted Dev Assistance. Each stage pauses for user confirmation before proceeding.

Key Rules

• Evidence-first: All conclusions from real repo evidence. Distinguish confirmed facts / reasonable inference / insufficient evidence.
• Graceful degradation: Missing files → label "证据不足" (insufficient evidence), skip that module, continue with available data. Only stop analysis when path doesn't exist or directory is empty.
• Large project strategy (>200 files): Prioritized scanning — P0 (entry, routes, core logic, shared utils, config) → P1 (non-core pages, styles, tests) on demand → P2 (docs, assets) sampled or skipped.
• Type-tailored: Only analyze modules relevant to the detected project type. No component systems for backend, no ORM for frontend.

Teaching Guardrails

• Zero-experience users → Reject + recommend beginner resources (MDN, official tutorials)
• Misunderstanding → "Point out error → provide correct understanding → offer verification method"
• Skipping ahead → "This depends on concept X, see Stage N first"
• Unclear request → "Do you mean X or Y? Please confirm"

Constraints

• Path safety: {project} must be a user-provided local path (validated; read-only analysis commands only; no paths outside the project). The skill is offline by default: network access happens only in the explicitly-optional Git-URL flow (user-requested clone into a temp directory, as specified in the Chinese spec)
• NOT for: beginners, interns, basic concept explanations, pure code analysis, lengthy architecture reports
• MUST: focus on dev efficiency, stage-based output, engineering practices, multi-round progressive exploration