关于 project-onboarding
Project Onboarding Quality Skill 引导开发者了解陌生代码库并做好参与开发的准备。它使用 GoodVibes precision tools,覆盖架构、代码规范、依赖、环境配置、构建与测试流程以及入门文档生成。
主要功能
- 01发现项目结构和入口文件
- 02检查依赖与配置
- 03梳理架构和数据流
- 04识别代码规范与模式
- 05检查环境、构建和测试
- 06生成项目入门文档
适用场景
- 01加入陌生项目
- 02贡献代码前梳理代码库
- 03配置并验证开发环境
- 04审查项目健康状况与技术债
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ mgd34msu/ goodvibes-plugin --skill project-onboarding安装后在 Claude Code 中输入/project-onboarding确认已加载。
附带文件references/onboarding-patterns.mdscripts/validate-onboarding.sh
详细介绍
资源
scripts/
validate-onboarding.sh
references/
onboarding-patterns.md
项目入门质量技能
此技能将教你如何使用 GoodVibes 精准工具系统地熟悉新项目。全面的入门流程会梳理架构、识别模式、验证环境,并生成文档,帮助你快速高效地做出贡献。
何时使用此技能
在以下情况下加载此技能:
- 加入新项目或团队
- 了解不熟悉的代码库
- 编写项目架构文档
- 设置开发环境
- 创建入门指南
- 审查项目健康状况和技术债务
触发语句:“熟悉这个项目”“了解这个代码库”“设置开发环境”“梳理架构”“生成项目文档”。
核心工作流
阶段 1:项目结构分析
了解目录布局、monorepo 配置和入口点。
步骤 1.1:探索目录结构
使用 discover 梳理项目的目录布局并识别关键配置文件。
discover:
queries:
- id: config_files
type: glob
patterns:
- "package.json"
- "tsconfig*.json"
- "*.config.{js,ts,mjs,cjs}"
- ".env*"
- "docker-compose*.yml"
- "Dockerfile*"
- id: src_structure
type: glob
patterns:
- "src/**/*"
- "app/**/*"
- "pages/**/*"
- "lib/**/*"
- id: monorepo_indicators
type: glob
patterns:
- "pnpm-workspace.yaml"
- "lerna.json"
- "nx.json"
- "turbo.json"
- "packages/*/package.json"
- "apps/*/package.json"
verbosity: files_only
这会揭示:
- 项目类型(monorepo 或单个软件包)
- 框架/构建工具(Next.js、Vite、Create React App 等)
- 配置复杂度
- 用于容器化开发的 Docker 设置
步骤 1.2:识别入口点
查找主应用入口点、服务端文件和公共 API。
discover:
queries:
- id: entry_points
type: glob
patterns:
- "src/index.{ts,tsx,js,jsx}"
- "src/main.{ts,tsx,js,jsx}"
- "src/app.{ts,tsx,js,jsx}"
- "app/layout.{ts,tsx,js,jsx}"
- "pages/_app.{ts,tsx,js,jsx}"
- "server.{ts,js}"
- id: api_routes
type: glob
patterns:
- "src/api/**/*"
- "app/api/**/*"
- "pages/api/**/*"
- "routes/**/*"
- id: public_assets
type: glob
patterns:
- "public/**/*"
- "static/**/*"
verbosity: files_only
这会揭示:
- 应用架构(SPA、SSR、仅 API、全栈)
- 路由模式
- 静态资源组织方式
步骤 1.3:阅读核心配置
使用 precision_read 检查 package.json 和关键配置文件。
precision_read:
files:
- path: "package.json"
extract: content
- path: "tsconfig.json"
extract: content
verbosity: standard
这会揭示:
- 依赖项和开发依赖项
- 用于构建、开发、测试、代码检查的脚本
- Node 版本要求(engines 字段)
- 软件包管理器(npm、yarn、pnpm)
阶段 2:依赖项审查
分析依赖项的版本时效性、安全漏洞和打包体积。
步骤 2.1:列出所有依赖项
从 package.json 文件中提取依赖项。
precision_grep:
queries:
- id: dependencies
pattern: '"dependencies":\s*\{[\s\S]*?\}'
glob: "**/package.json"
multiline: true
- id: dev_dependencies
pattern: '"devDependencies":\s*\{[\s\S]*?\}'
glob: "**/package.json"
multiline: true
- id: peer_dependencies
pattern: '"peerDependencies":\s*\{[\s\S]*?\}'
glob: "**/package.json"
multiline: true
output:
format: matches
verbosity: standard
步骤 2.2:检查过时的依赖项
运行 npm/yarn/pnpm 命令检查可用更新。
precision_exec:
commands:
- cmd: "npm outdated --json"
- cmd: "npm audit --json"
verbosity: standard
这会揭示:
- 有可用更新的软件包
- 安全漏洞
- 严重程度(严重、高、中、低)
步骤 2.3:分析打包体积和依赖树
识别体积较大的依赖项和潜在的优化空间。
precision_exec:
commands:
- cmd: "npx bundle-phobia-cli --json react react-dom next"
verbosity: minimal
这会揭示:
- 下载大小和安装大小
- 生产环境中的 Gzip 压缩大小
- 需要留意的重型依赖项
阶段 3:架构梳理
梳理模块边界、数据流和 API 范围。
步骤 3.1:提取模块结构
使用 precision_read 提取大纲,梳理代码库结构。
# Note: path "src" works as a directory - precision_read will recursively extract outline
precision_read:
files:
- path: "src"
extract: outline
output:
max_per_item: 100
verbosity: standard
这会揭示:
- 目录组织模式
- 模块边界
- 各模块的代码量
步骤 3.2:识别关键符号
使用 precision_read 提取符号,查找导出的函数、类和类型。
# First discover the files
discover:
queries:
- id: lib_files
type: glob
patterns: ["src/lib/**/*.{ts,tsx}"]
- id: api_files
type: glob
patterns: ["src/api/**/*.{ts,tsx}"]
verbosity: files_only
# Then read symbols from discovered files
precision_read:
files:
# Use file paths from discover results
- path: "src/lib/index.ts" # Example - use actual discovered paths
extract: symbols
- path: "src/api/index.ts" # Example - use actual discovered paths
extract: symbols
symbol_filter: ["function", "class", "interface", "type"]
verbosity: minimal
这会揭示:
- 公共 API 范围
- 核心抽象和实用工具
- 类型定义
步骤 3.3:梳理数据流
追踪导入和导出,了解模块依赖关系。
discover:
queries:
- id: imports
type: grep
pattern: '^import .* from ["''].*["''];?$'
glob: "src/**/*.{ts,tsx,js,jsx}"
- id: exports
type: grep
pattern: '^export (default|const|function|class|interface|type|enum)'
glob: "src/**/*.{ts,tsx,js,jsx}"
verbosity: count_only
这会揭示:
- 模块耦合情况
- 导入模式(barrel 文件、直接导入)
- 潜在的循环依赖
阶段 4:检测约定
识别代码风格、命名模式和文件组织规则。
步骤 4.1:检测命名约定
搜索文件和符号中的命名模式。
discover:
queries:
- id: component_naming
type: grep
pattern: 'export (default )?(function|const) [A-Z][a-zA-Z]*'
glob: "src/components/**/*.{ts,tsx}"
- id: hook_naming
type: grep
pattern: 'export (default )?(function|const) use[A-Z][a-zA-Z]*'
glob: "src/**/*.{ts,tsx}"
- id: util_naming
type: grep
pattern: 'export (default )?(function|const) [a-z][a-zA-Z]*'
glob: "src/lib/**/*.{ts,tsx}"
verbosity: count_only
这会揭示:
- 组件使用 PascalCase
- 实用工具使用 camelCase
- Hook 使用
use前缀 - 文件命名模式
步骤 4.2:检测文件组织模式
分析目录结构,找出组织约定。
discover:
queries:
- id: index_files
type: glob
patterns: ["**/index.{ts,tsx,js,jsx}"]
- id: type_files
type: glob
patterns: ["**/*.types.{ts,tsx}", "**/types.{ts,tsx}", "**/types/**/*"]
- id: test_colocation
type: glob
patterns:
- "**/*.test.{ts,tsx}"
- "**/__tests__/**/*"
verbosity: count_only
这会揭示:
- Barrel 导出(index.ts 模式)
- 类型定义的组织方式
- 测试文件的位置(与代码放在一起或放在专用目录中)
步骤 4.3:检查代码检查与格式化配置
查找 ESLint、Prettier 和其他代码质量配置。
discover:
queries:
- id: lint_config
type: glob
patterns:
- ".eslintrc*"
- "eslint.config.{js,mjs,cjs}"
- ".prettierrc*"
- "prettier.config.{js,mjs,cjs}"
- id: editor_config
type: glob
patterns:
- ".editorconfig"
- ".vscode/settings.json"
verbosity: files_only
阅读配置文件:
precision_read:
files:
- path: ".eslintrc.json"
extract: content
- path: ".prettierrc"
extract: content
verbosity: standard
这能揭示:
- 代码风格规则(缩进、引号、分号)
- 已启用或禁用的代码检查规则
- 格式化偏好
阶段 5:环境设置
配置开发环境,包括所需依赖、配置文件和数据库。
步骤 5.1:检查 Node 版本要求
读取 .nvmrc、package.json engines 或 .node-version。
precision_grep:
queries:
- id: node_version_nvmrc
pattern: '.*'
glob: ".nvmrc"
- id: node_version_package
pattern: '"engines":\s*\{[\s\S]*?"node":\s*"[^"]+"'
glob: "package.json"
multiline: true
output:
format: matches
verbosity: standard
这能揭示:
- 所需的 Node.js 版本
- 包管理器版本要求
步骤 5.2:安装依赖
运行包管理器的安装命令。
precision_exec:
commands:
- cmd: "npm install"
timeout_ms: 300000
verbosity: minimal
对于 pnpm 或 yarn:
precision_exec:
commands:
- cmd: "pnpm install"
timeout_ms: 300000
verbosity: minimal
步骤 5.3:设置环境变量
从 .env.example 或代码中识别所需的环境变量。
precision_read:
files:
- path: ".env.example"
extract: content
verbosity: standard
在代码中搜索环境变量的使用情况:
precision_grep:
queries:
- id: env_usage
pattern: 'process\.env\.[A-Z_]+'
glob: "src/**/*.{ts,tsx,js,jsx}"
output:
format: matches
max_per_item: 20
verbosity: minimal
这能揭示:
- 所需的环境变量
- 所需的 API 密钥、数据库 URL 和密钥
- 第三方服务集成
步骤 5.4:数据库设置
检查数据库架构文件、迁移文件和种子脚本。
discover:
queries:
- id: prisma_schema
type: glob
patterns: ["prisma/schema.prisma"]
- id: migrations
type: glob
patterns:
- "prisma/migrations/**/*"
- "migrations/**/*"
- "db/migrations/**/*"
- id: seed_scripts
type: glob
patterns:
- "prisma/seed.{ts,js}"
- "db/seed.{ts,js}"
- "scripts/seed.{ts,js}"
verbosity: files_only
运行数据库设置:
precision_exec:
commands:
- cmd: "npx prisma generate"
- cmd: "npx prisma migrate dev"
- cmd: "npx prisma db seed"
verbosity: standard
这能揭示:
- 数据库架构和模型
- 迁移历史
- 用于开发的种子数据
阶段 6:构建与开发工作流
了解构建命令、开发服务器、热重载和测试运行器。
步骤 6.1:识别构建脚本
从 package.json 中提取脚本。
precision_grep:
queries:
- id: scripts
pattern: '"scripts":\s*\{[\s\S]*?\}'
glob: "package.json"
multiline: true
output:
format: matches
verbosity: standard
这能揭示:
- 用于本地开发的
dev或start命令 - 用于生产构建的
build命令 - 用于运行测试的
test命令 - 用于代码检查的
lint命令 - 用于部署、数据库等的自定义脚本
步骤 6.2:测试构建流程
运行构建命令以验证设置。
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
verbosity: standard
这能揭示:
- 构建错误或警告
- 构建产物的位置
- 构建时间和性能
步骤 6.3:启动开发服务器
运行开发命令以验证热重载是否正常工作。
precision_exec:
commands:
- cmd: "npm run dev"
timeout_ms: 60000
until:
pattern: "(ready|compiled|listening|started)"
kill_after: true # Stops dev server after pattern matches
verbosity: standard
这能揭示:
- 开发服务器端口(通常为 :3000、:5173、:8080)
- 热重载配置
- 启动时间
步骤 6.4:运行测试
执行测试套件以验证测试设置。
precision_exec:
commands:
- cmd: "npm test"
timeout_ms: 120000
verbosity: standard
这能揭示:
- 测试框架(Jest、Vitest、Mocha 等)
- 测试覆盖率
- 失败的测试或设置问题
阶段 7:关键模式
识别状态管理、错误处理、身份验证和路由方面的常见模式。
步骤 7.1:状态管理模式
搜索状态管理库和模式。
discover:
queries:
- id: react_state
type: grep
pattern: '(useState|useReducer|useContext)'
glob: "src/**/*.{ts,tsx}"
- id: zustand
type: grep
pattern: "(create|useStore).*from ['\"]zustand"
glob: "src/**/*.{ts,tsx}"
- id: redux
type: grep
pattern: "(useSelector|useDispatch|createSlice)"
glob: "src/**/*.{ts,tsx}"
- id: jotai
type: grep
pattern: "(atom|useAtom).*from ['\"]jotai"
glob: "src/**/*.{ts,tsx}"
verbosity: count_only
这能揭示:
- 主要的状态管理方式
- 全局状态与本地状态模式
- Store 组织方式
步骤 7.2:错误处理模式
查找错误边界、try-catch 模式和错误报告。
# Use precision_grep instead of discover for multiline patterns
precision_grep:
queries:
- id: error_boundaries
pattern: "(class|extends) .*ErrorBoundary"
glob: "src/**/*.{ts,tsx}"
- id: try_catch
pattern: "try \{[\s\S]*?\} catch"
glob: "src/**/*.{ts,tsx,js,jsx}"
multiline: true
- id: error_reporting
pattern: "(Sentry|Bugsnag|ErrorBoundary|reportError)"
glob: "src/**/*.{ts,tsx,js,jsx}"
output:
format: count_only
verbosity: minimal
这能揭示:
- 错误边界的使用情况
- 错误日志记录和报告设置
- 异常处理约定
步骤 7.3:身份验证模式
识别身份验证库和模式。
discover:
queries:
- id: auth_providers
type: grep
pattern: "(NextAuth|Clerk|Auth0|Supabase|Lucia|useAuth)"
glob: "src/**/*.{ts,tsx}"
- id: protected_routes
type: grep
pattern: "(withAuth|requireAuth|ProtectedRoute|middleware)"
glob: "src/**/*.{ts,tsx}"
- id: session_usage
type: grep
pattern: "(getSession|useSession|getServerSession)"
glob: "src/**/*.{ts,tsx}"
verbosity: count_only
这能揭示:
- 身份验证提供方(Clerk、NextAuth、自定义)
- 受保护路由模式
- 会话管理方式
步骤 7.4:路由模式
了解路由架构。
discover:
queries:
- id: app_router
type: glob
patterns: ["app/**/page.{ts,tsx}", "app/**/layout.{ts,tsx}"]
- id: pages_router
type: glob
patterns: ["pages/**/*.{ts,tsx}"]
- id: react_router
type: grep
pattern: "(BrowserRouter|Routes|Route|useNavigate)"
glob: "src/**/*.{ts,tsx}"
verbosity: count_only
这能揭示:
- 路由框架(Next.js App Router、Pages Router、React Router)
- 路由组织方式
- 动态路由模式
阶段 8:文档生成
生成 CLAUDE.md、架构文档和入门指南。
步骤 8.1:创建 CLAUDE.md 项目说明
编写全面的 CLAUDE.md,说明项目背景。
precision_write:
files:
- path: ".claude/CLAUDE.md"
mode: fail_if_exists
content: |
# Project Name
## Overview
[Brief description of the project, its purpose, and key features]
## Architecture
- **Framework**: [Next.js 14 App Router / Remix / etc.]
- **Language**: [TypeScript]
- **Database**: [PostgreSQL with Prisma]
- **Authentication**: [Clerk / NextAuth]
- **State Management**: [Zustand / Redux / etc.]
## Directory Structure
```
src/
app/ # Next.js App Router pages and layouts
components/ # React components
lib/ # Utility functions and shared logic
api/ # API route handlers
types/ # TypeScript type definitions
```
## Development Workflow
1. Install dependencies: `pnpm install`
2. Setup environment: Copy `.env.example` to `.env.local`
3. Setup database: `npx prisma migrate dev`
4. Start dev server: `pnpm dev`
5. Run tests: `pnpm test`
## Key Patterns
- Components use PascalCase naming
- Utilities use camelCase naming
- Hooks start with `use` prefix
- Server components by default, use 'use client' directive for client components
## Testing
- Unit tests: Vitest
- E2E tests: Playwright
- Run with: `pnpm test`
## Deployment
- Platform: [Vercel / Netlify / etc.]
- CI/CD: [GitHub Actions]
- Deploy command: `pnpm build`
verbosity: minimal
步骤 8.2:生成架构图
创建架构的 mermaid 图表。
precision_write:
files:
- path: "docs/ARCHITECTURE.md"
mode: fail_if_exists
content: |
# Architecture
## System Overview
```mermaid
graph TD
A[Client Browser] --> B[Next.js App Router]
B --> C[React Server Components]
B --> D[API Routes]
D --> E[Database - Prisma]
D --> F[External APIs]
C --> E
```
## Module Boundaries
- `app/`: Page routes and layouts (Next.js App Router)
- `components/`: Reusable UI components
- `lib/`: Business logic and utilities
- `api/`: Backend API handlers
## Data Flow
1. User requests page -> Next.js App Router
2. Server Component fetches data -> Prisma -> Database
3. Server renders component with data
4. Client receives HTML with hydration instructions
5. Client-side interactions -> API routes -> Database
## External Dependencies
- Authentication: Clerk
- Email: Resend
- Storage: Vercel Blob
verbosity: minimal
步骤 8.3:创建入门清单
为新开发者生成清单。
precision_write:
files:
- path: "docs/ONBOARDING.md"
mode: fail_if_exists
content: |
# Onboarding Checklist
## Prerequisites
- [ ] Node.js 18+ installed
- [ ] pnpm installed (`npm install -g pnpm`)
- [ ] Git configured
- [ ] PostgreSQL installed locally (or Docker)
## Setup Steps
1. [ ] Clone repository
2. [ ] Install dependencies: `pnpm install`
3. [ ] Copy `.env.example` to `.env.local`
4. [ ] Fill in environment variables (get from team)
5. [ ] Setup database: `npx prisma migrate dev`
6. [ ] Seed database: `npx prisma db seed`
7. [ ] Start dev server: `pnpm dev`
8. [ ] Open http://localhost:3000
9. [ ] Run tests: `pnpm test`
10. [ ] Verify build: `pnpm build`
## Key Resources
- Architecture: [docs/ARCHITECTURE.md](./ARCHITECTURE.md)
- API Docs: [docs/API.md](./API.md)
- Code Review: Use `/code-review` skill
## First Tasks
1. Read through CLAUDE.md for project context
2. Explore the codebase structure
3. Review recent pull requests
4. Pick a "good first issue" from GitHub
verbosity: minimal
阶段 9:贡献工作流
了解 Git 分支策略、PR 流程和 CI/CD 流水线。
Step 9.1:检查 Git 配置
查找分支保护规则和工作流文件。
discover:
queries:
- id: github_workflows
type: glob
patterns: [".github/workflows/**/*.yml", ".github/workflows/**/*.yaml"]
- id: git_hooks
type: glob
patterns: [".husky/**/*", ".git/hooks/**/*"]
- id: branch_config
type: glob
patterns: [".github/CODEOWNERS", ".github/pull_request_template.md"]
verbosity: files_only
读取 GitHub Actions 工作流:
precision_read:
files:
- path: ".github/workflows/ci.yml"
extract: content
verbosity: standard
可了解的内容:
- CI/CD 流水线步骤
- 合并前必须通过的检查
- 部署流程
Step 9.2:了解 PR 流程
阅读 PR 模板和贡献指南。
precision_read:
files:
- path: ".github/pull_request_template.md"
extract: content
- path: "CONTRIBUTING.md"
extract: content
verbosity: standard
可了解的内容:
- PR 描述要求
- 审查流程
- 测试要求
Step 9.3:检查提交规范
搜索提交消息规范。
# Check for commitlint config
precision_grep:
queries:
- id: commitlint
pattern: '.*'
glob: ".commitlintrc*"
output:
format: matches
verbosity: minimal
# Check commit convention from recent commits
precision_exec:
commands:
- cmd: "git log --oneline -20"
verbosity: standard
可了解的内容:
- 提交消息格式(Conventional Commits、自定义格式)
- 提交中使用的范围
阶段 10:验证与确认
端到端验证环境是否正常运行。
Step 10.1:运行完整测试套件
运行所有测试并生成覆盖率报告。
precision_exec:
commands:
- cmd: "npm test -- --coverage"
timeout_ms: 180000
verbosity: standard
可了解的内容:
- 测试覆盖率百分比
- 未覆盖的文件或代码行
- 缓慢或不稳定的测试
Step 10.2:确认代码检查通过
运行代码检查,确保代码质量。
precision_exec:
commands:
- cmd: "npm run lint"
verbosity: standard
可了解的内容:
- 代码检查错误或警告
- 违反代码风格规范的情况
Step 10.3:检查类型安全
运行 TypeScript 类型检查器。
precision_exec:
commands:
- cmd: "npm run typecheck"
verbosity: standard
可了解的内容:
- 类型错误
- 缺失的类型定义
any的使用情况
Step 10.4:确认生产构建正常
构建生产版本并检查打包体积。
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
- cmd: "ls -lh .next/static/chunks" # Next.js example
verbosity: standard
可了解的内容:
- 构建警告或错误
- 打包体积
- 优化机会
最佳实践
1. 从小处入手,深入了解
不要试图一次性了解所有内容。先从以下内容开始:
- 项目结构(阶段 1)
- 环境配置(阶段 5)
- 构建工作流(阶段 6)
然后再深入了解架构、模式和贡献流程。
2. 高效使用精准工具
- 先使用
discover并设置verbosity: count_only,了解项目范围 - 使用
verbosity: files_only构建目标列表 - 先使用
precision_read并设置extract: outline,再阅读完整内容 - 使用
precision_grep并设置output.format: count_only,检查模式的普遍程度
3. 在学习过程中做好记录
在入门过程中创建或更新文档:
- 记录项目背景的 CLAUDE.md
- 架构图
- 配置指南
- 常见问题及解决方案
4. 尽早验证
在入门过程中尽早运行构建、测试和代码检查。这样可以在投入时间了解代码库之前,先发现环境问题。
5. 提出问题
遇到以下情况时:
- 未记录的模式
- 复杂的抽象
- 缺少测试
- 不一致的规范
将它们记录为要向团队提出的问题。
常见陷阱
陷阱 1:跳过依赖安装
问题: 尚未安装依赖就开始阅读代码。
解决方案: 始终先运行 npm install。许多工具(TypeScript、ESLint)需要依赖才能正常运行。
陷阱 2:忽略环境变量
问题: 缺少 .env.local 文件会导致运行时错误。
解决方案: 将 .env.example 复制为 .env.local,并填写所需值。向团队索取密钥。
陷阱 3:不测试构建
问题: 未经验证就假定构建正常。
解决方案: 尽早运行 npm run build,以发现配置问题、缺少的依赖或 TypeScript 错误。
陷阱 4:忽视数据库配置
问题: 缺少数据库架构导致应用在运行时失败。
解决方案: 启动开发服务器前,运行迁移(npx prisma migrate dev)并填充种子数据。
陷阱 5:不阅读现有文档
问题: 未能了解 README.md、CONTRIBUTING.md 或项目文档中的关键信息。
解决方案: 先使用 precision_read 阅读根目录和 docs/ 文件夹中的所有 Markdown 文件。
验证脚本
使用验证脚本检查入门准备是否完整:
bash plugins/goodvibes/skills/quality/project-onboarding/scripts/validate-onboarding.sh
此脚本将验证:
- 是否已安装依赖
- 是否已配置环境变量
- 是否已完成数据库配置
- 测试是否通过
- 构建是否成功
参考资料
如需了解详细模式和示例,请参阅:
相关技能
quality/code-review- 了解代码库后审查代码质量architecture/system-design- 遵循现有模式设计新功能testing/test-strategy- 编写符合项目惯例的测试