mcpField
P
project-onboarding

project-onboarding

github.com/mgd34msu开发662 次安装10 周前更新
代码仓库

关于 project-onboarding

Project Onboarding Quality Skill 引导开发者了解陌生代码库并做好参与开发的准备。它使用 GoodVibes precision tools,覆盖架构、代码规范、依赖、环境配置、构建与测试流程以及入门文档生成。

主要功能

  1. 01发现项目结构和入口文件
  2. 02检查依赖与配置
  3. 03梳理架构和数据流
  4. 04识别代码规范与模式
  5. 05检查环境、构建和测试
  6. 06生成项目入门文档

适用场景

  1. 01加入陌生项目
  2. 02贡献代码前梳理代码库
  3. 03配置并验证开发环境
  4. 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. 项目结构(阶段 1)
  2. 环境配置(阶段 5)
  3. 构建工作流(阶段 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 - 编写符合项目惯例的测试

评论

支持 Markdown