重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
project-onboarding by mgd34msu/goodvibes-plugin
npx skills add https://github.com/mgd34msu/goodvibes-plugin --skill project-onboardingscripts/
validate-onboarding.sh
references/
onboarding-patterns.md
此技能教你如何使用 GoodVibes 精准工具系统地入职新项目。一个彻底的入职流程会梳理架构、识别模式、验证环境并生成文档,以便快速高效地贡献。
在以下情况加载此技能:
触发短语:"onboard to this project", "understand this codebase", "setup dev environment", "map the architecture", "generate project docs"。
理解目录布局、monorepo 配置和入口点。
使用 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
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
这揭示了什么:
查找主应用程序入口点、服务器文件和公共 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
这揭示了什么:
使用 precision_read 检查 package.json 和关键配置文件。
precision_read:
files:
- path: "package.json"
extract: content
- path: "tsconfig.json"
extract: content
verbosity: standard
这揭示了什么:
分析依赖项的版本时效性、安全漏洞和包大小。
从 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
运行 npm/yarn/pnpm 命令来检查更新。
precision_exec:
commands:
- cmd: "npm outdated --json"
- cmd: "npm audit --json"
verbosity: standard
这揭示了什么:
识别大型依赖项和潜在的优化点。
precision_exec:
commands:
- cmd: "npx bundle-phobia-cli --json react react-dom next"
verbosity: minimal
这揭示了什么:
映射模块边界、数据流和 API 表面。
使用 precision_read 配合大纲提取来映射代码库结构。
# 注意:路径 "src" 作为目录使用 - precision_read 将递归提取大纲
precision_read:
files:
- path: "src"
extract: outline
output:
max_per_item: 100
verbosity: standard
这揭示了什么:
使用 precision_read 配合符号提取来查找导出的函数、类和类型。
# 首先发现文件
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
# 然后从发现的文件中读取符号
precision_read:
files:
# 使用 discover 结果中的文件路径
- path: "src/lib/index.ts" # 示例 - 使用实际发现的路径
extract: symbols
- path: "src/api/index.ts" # 示例 - 使用实际发现的路径
extract: symbols
symbol_filter: ["function", "class", "interface", "type"]
verbosity: minimal
这揭示了什么:
追踪导入和导出来理解模块依赖关系。
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
这揭示了什么:
识别代码风格、命名模式和文件组织规则。
在文件和符号中搜索命名模式。
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
这揭示了什么:
use 前缀分析目录结构以了解组织规范。
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
这揭示了什么:
查找 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
这揭示了什么:
使用所需的依赖项、配置文件和数据库设置开发者环境。
读取 .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
这揭示了什么:
运行包管理器安装命令。
precision_exec:
commands:
- cmd: "npm install"
timeout_ms: 300000
verbosity: minimal
对于 pnpm 或 yarn:
precision_exec:
commands:
- cmd: "pnpm install"
timeout_ms: 300000
verbosity: minimal
从 .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
这揭示了什么:
检查数据库模式文件、迁移和种子脚本。
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
这揭示了什么:
理解构建命令、开发服务器、热重载和测试运行器。
从 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 命令运行构建命令以验证设置。
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
verbosity: standard
这揭示了什么:
运行开发命令以验证热重载是否工作。
precision_exec:
commands:
- cmd: "npm run dev"
timeout_ms: 60000
until:
pattern: "(ready|compiled|listening|started)"
kill_after: true # 模式匹配后停止开发服务器
verbosity: standard
这揭示了什么:
执行测试套件以验证测试设置。
precision_exec:
commands:
- cmd: "npm test"
timeout_ms: 120000
verbosity: standard
这揭示了什么:
识别状态管理、错误处理、身份验证和路由的重复模式。
搜索状态管理库和模式。
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
这揭示了什么:
查找错误边界、try-catch 模式和错误报告。
# 对多行模式使用 precision_grep 而不是 discover
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
这揭示了什么:
识别身份验证库和模式。
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
这揭示了什么:
理解路由架构。
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
这揭示了什么:
生成 CLAUDE.md、架构文档和入职指南。
编写包含项目上下文的综合性 CLAUDE.md。
precision_write:
files:
- path: ".claude/CLAUDE.md"
mode: fail_if_exists
content: |
# 项目名称
## 概述
[项目简要描述、其目的和关键特性]
## 架构
- **框架**: [Next.js 14 App Router / Remix / 等]
- **语言**: [TypeScript]
- **数据库**: [PostgreSQL with Prisma]
- **身份验证**: [Clerk / NextAuth]
- **状态管理**: [Zustand / Redux / 等]
## 目录结构
```
src/
app/ # Next.js App Router 页面和布局
components/ # React 组件
lib/ # 工具函数和共享逻辑
api/ # API 路由处理程序
types/ # TypeScript 类型定义
```
## 开发工作流
1. 安装依赖项: `pnpm install`
2. 设置环境: 复制 `.env.example` 到 `.env.local`
3. 设置数据库: `npx prisma migrate dev`
4. 启动开发服务器: `pnpm dev`
5. 运行测试: `pnpm test`
## 关键模式
- 组件使用 PascalCase 命名
- 工具函数使用 camelCase 命名
- 钩子以 `use` 前缀开头
- 默认使用服务器组件,客户端组件使用 'use client' 指令
## 测试
- 单元测试: Vitest
- E2E 测试: Playwright
- 运行命令: `pnpm test`
## 部署
- 平台: [Vercel / Netlify / 等]
- CI/CD: [GitHub Actions]
- 部署命令: `pnpm build`
verbosity: minimal
创建架构的 mermaid 图。
precision_write:
files:
- path: "docs/ARCHITECTURE.md"
mode: fail_if_exists
content: |
# 架构
## 系统概述
```mermaid
graph TD
A[客户端浏览器] --> B[Next.js App Router]
B --> C[React 服务器组件]
B --> D[API 路由]
D --> E[数据库 - Prisma]
D --> F[外部 API]
C --> E
```
## 模块边界
- `app/`: 页面路由和布局(Next.js App Router)
- `components/`: 可复用的 UI 组件
- `lib/`: 业务逻辑和工具函数
- `api/`: 后端 API 处理程序
## 数据流
1. 用户请求页面 -> Next.js App Router
2. 服务器组件获取数据 -> Prisma -> 数据库
3. 服务器使用数据渲染组件
4. 客户端接收带有水合指令的 HTML
5. 客户端交互 -> API 路由 -> 数据库
## 外部依赖
- 身份验证: Clerk
- 邮件: Resend
- 存储: Vercel Blob
verbosity: minimal
为新开发者生成清单。
precision_write:
files:
- path: "docs/ONBOARDING.md"
mode: fail_if_exists
content: |
# 入职清单
## 先决条件
- [ ] 已安装 Node.js 18+
- [ ] 已安装 pnpm (`npm install -g pnpm`)
- [ ] 已配置 Git
- [ ] 本地已安装 PostgreSQL(或 Docker)
## 设置步骤
1. [ ] 克隆仓库
2. [ ] 安装依赖项: `pnpm install`
3. [ ] 复制 `.env.example` 到 `.env.local`
4. [ ] 填写环境变量(从团队获取)
5. [ ] 设置数据库: `npx prisma migrate dev`
6. [ ] 填充数据库: `npx prisma db seed`
7. [ ] 启动开发服务器: `pnpm dev`
8. [ ] 打开 http://localhost:3000
9. [ ] 运行测试: `pnpm test`
10. [ ] 验证构建: `pnpm build`
## 关键资源
- 架构: [docs/ARCHITECTURE.md](./ARCHITECTURE.md)
- API 文档: [docs/API.md](./API.md)
- 代码审查: 使用 `/code-review` 技能
## 首个任务
1. 通读 CLAUDE.md 了解项目背景
2. 探索代码库结构
3. 查看最近的拉取请求
4. 从 GitHub 选择一个 "good first issue"
verbosity: minimal
理解 Git 分支策略、PR 流程和 CI/CD 流水线。
查找分支保护规则和工作流文件。
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
这揭示了什么:
读取 PR 模板和贡献指南。
precision_read:
files:
- path: ".github/pull_request_template.md"
extract: content
- path: "CONTRIBUTING.md"
extract: content
verbosity: standard
这揭示了什么:
搜索提交消息规范。
# 检查 commitlint 配置
precision_grep:
queries:
- id: commitlint
pattern: '.*'
glob: ".commitlintrc*"
output:
format: matches
verbosity: minimal
# 从最近的提交中检查提交规范
precision_exec:
commands:
- cmd: "git log --oneline -20"
verbosity: standard
这揭示了什么:
端到端验证环境是否正常工作。
执行所有测试并生成覆盖率报告。
precision_exec:
commands:
- cmd: "npm test -- --coverage"
timeout_ms: 180000
verbosity: standard
这揭示了什么:
运行代码检查以确保代码质量。
precision_exec:
commands:
- cmd: "npm run lint"
verbosity: standard
这揭示了什么:
运行 TypeScript 类型检查器。
precision_exec:
commands:
- cmd: "npm run typecheck"
verbosity: standard
这揭示了什么:
any 的使用情况为生产环境构建并检查包大小。
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
- cmd: "ls -lh .next/static/chunks" # Next.js 示例
verbosity: standard
这揭示了什么:
不要试图一次性理解所有内容。从以下开始:
然后深入研究架构、模式和贡献工作流。
discover 配合 verbosity: count_only 来评估范围verbosity: files_only 来构建目标列表precision_read 配合 extract: outlineprecision_grep 配合 output.format: count_only 来检查模式普遍性在入职过程中创建或更新文档:
在入职过程的早期运行构建、测试和代码检查。这可以在你投入时间理解代码库之前发现环境问题。
当你发现以下情况时:
将它们记录为向团队提出的问题。
问题: 在没有安装依赖项的情况下直接开始阅读代码。
解决方案: 始终先运行 npm install。许多工具(TypeScript、ESLint)需要依赖项才能运行。
问题: 缺少 .env.local 文件导致运行时错误。
解决方案: 复制 .env.example 到 .env.local 并填写所需的值。向团队索要密钥。
问题: 假设构建有效而不进行验证。
解决方案: 尽早运行 npm run build 以捕获配置问题、缺失的依赖项或 TypeScript 错误。
问题: 由于缺少数据库模式,应用程序在运行时失败。
解决方案: 在启动开发服务器之前运行迁移(npx prisma migrate dev)和填充数据。
问题: 错过了 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 - 编写符合项目规范的测试每周安装次数
58
仓库
GitHub 星标数
6
首次出现
2026年2月17日
安全审计
安装于
github-copilot58
codex58
kimi-cli58
amp58
gemini-cli58
opencode58
scripts/
validate-onboarding.sh
references/
onboarding-patterns.md
This skill teaches you how to systematically onboard onto new projects using GoodVibes precision tools. A thorough onboarding process maps the architecture, identifies patterns, validates the environment, and generates documentation for rapid productive contribution.
Load this skill when:
Trigger phrases: "onboard to this project", "understand this codebase", "setup dev environment", "map the architecture", "generate project docs".
Understand the directory layout, monorepo configuration, and entry points.
Use discover to map the project's directory layout and identify key configuration files.
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
What this reveals:
Find main application entry points, server files, and public APIs.
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
What this reveals:
Use precision_read to examine package.json and key config files.
precision_read:
files:
- path: "package.json"
extract: content
- path: "tsconfig.json"
extract: content
verbosity: standard
What this reveals:
Analyze dependencies for version currency, security vulnerabilities, and bundle size.
Extract dependencies from package.json files.
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
Run npm/yarn/pnpm commands to check for updates.
precision_exec:
commands:
- cmd: "npm outdated --json"
- cmd: "npm audit --json"
verbosity: standard
What this reveals:
Identify large dependencies and potential optimizations.
precision_exec:
commands:
- cmd: "npx bundle-phobia-cli --json react react-dom next"
verbosity: minimal
What this reveals:
Map module boundaries, data flow, and API surface.
Use precision_read with outline extraction to map the codebase structure.
# 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
What this reveals:
Use precision_read with symbol extraction to find exported functions, classes, and types.
# 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
What this reveals:
Trace imports and exports to understand module dependencies.
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
What this reveals:
Identify code style, naming patterns, and file organization rules.
Search for naming patterns in files and symbols.
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
What this reveals:
use prefix for hooksAnalyze directory structure for organizational conventions.
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
What this reveals:
Find ESLint, Prettier, and other code quality configurations.
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
Read the configs:
precision_read:
files:
- path: ".eslintrc.json"
extract: content
- path: ".prettierrc"
extract: content
verbosity: standard
What this reveals:
Set up developer environment with required dependencies, config files, and database.
Read .nvmrc, package.json engines, or .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
What this reveals:
Run the package manager install command.
precision_exec:
commands:
- cmd: "npm install"
timeout_ms: 300000
verbosity: minimal
For pnpm or yarn:
precision_exec:
commands:
- cmd: "pnpm install"
timeout_ms: 300000
verbosity: minimal
Identify required environment variables from .env.example or code.
precision_read:
files:
- path: ".env.example"
extract: content
verbosity: standard
Search for env var usage in code:
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
What this reveals:
Check for database schema files, migrations, and seed scripts.
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
Run database setup:
precision_exec:
commands:
- cmd: "npx prisma generate"
- cmd: "npx prisma migrate dev"
- cmd: "npx prisma db seed"
verbosity: standard
What this reveals:
Understand build commands, dev server, hot reload, and test runners.
Extract scripts from package.json.
precision_grep:
queries:
- id: scripts
pattern: '"scripts":\s*\{[\s\S]*?\}'
glob: "package.json"
multiline: true
output:
format: matches
verbosity: standard
What this reveals:
dev or start command for local developmentbuild command for production buildtest command for running testslint command for lintingRun the build command to verify setup.
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
verbosity: standard
What this reveals:
Run the dev command to verify hot reload works.
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
What this reveals:
Execute test suite to verify test setup.
precision_exec:
commands:
- cmd: "npm test"
timeout_ms: 120000
verbosity: standard
What this reveals:
Identify recurring patterns for state management, error handling, authentication, and routing.
Search for state management libraries and patterns.
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
What this reveals:
Find error boundaries, try-catch patterns, and error reporting.
# 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
What this reveals:
Identify authentication library and patterns.
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
What this reveals:
Understand routing architecture.
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
What this reveals:
Generate CLAUDE.md, architecture docs, and onboarding guides.
Write a comprehensive CLAUDE.md with project context.
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
Create a mermaid diagram of the architecture.
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
Generate a checklist for new developers.
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
Understand Git branching strategy, PR process, and CI/CD pipeline.
Find branch protection rules and workflow files.
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
Read GitHub Actions workflows:
precision_read:
files:
- path: ".github/workflows/ci.yml"
extract: content
verbosity: standard
What this reveals:
Read PR template and contributing guidelines.
precision_read:
files:
- path: ".github/pull_request_template.md"
extract: content
- path: "CONTRIBUTING.md"
extract: content
verbosity: standard
What this reveals:
Search for commit message conventions.
# 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
What this reveals:
Verify environment works end-to-end.
Execute all tests with coverage.
precision_exec:
commands:
- cmd: "npm test -- --coverage"
timeout_ms: 180000
verbosity: standard
What this reveals:
Run linting to ensure code quality.
precision_exec:
commands:
- cmd: "npm run lint"
verbosity: standard
What this reveals:
Run TypeScript type checker.
precision_exec:
commands:
- cmd: "npm run typecheck"
verbosity: standard
What this reveals:
any usageBuild for production and check bundle size.
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
- cmd: "ls -lh .next/static/chunks" # Next.js example
verbosity: standard
What this reveals:
Don't try to understand everything at once. Start with:
Then dive deeper into architecture, patterns, and contribution workflow.
discover with verbosity: count_only first to gauge scopeverbosity: files_only to build target listsprecision_read with extract: outline before reading full contentprecision_grep with output.format: count_only for pattern prevalence checksCreate or update documentation during onboarding:
Run builds, tests, and linting early in the onboarding process. This catches environment issues before you invest time in understanding the codebase.
When you find:
Document them as questions for the team.
Problem: Jumping into code reading without installing dependencies.
Solution: Always run npm install first. Many tools (TypeScript, ESLint) need dependencies to function.
Problem: Missing .env.local file causes runtime errors.
Solution: Copy .env.example to .env.local and fill in required values. Ask team for secrets.
Problem: Assuming the build works without verifying.
Solution: Run npm run build early to catch configuration issues, missing dependencies, or TypeScript errors.
Problem: Application fails at runtime due to missing database schema.
Solution: Run migrations (npx prisma migrate dev) and seed data before starting dev server.
Problem: Missing key context in README.md, CONTRIBUTING.md, or project docs.
Solution: Use precision_read to read all markdown files in the root and docs/ folder first.
Use the validation script to check your onboarding completeness:
bash plugins/goodvibes/skills/quality/project-onboarding/scripts/validate-onboarding.sh
This will verify:
For detailed patterns and examples, see:
quality/code-review - Review code quality after understanding the codebasearchitecture/system-design - Design new features following existing patternstesting/test-strategy - Write tests matching project conventionsWeekly Installs
58
Repository
GitHub Stars
6
First Seen
Feb 17, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
github-copilot58
codex58
kimi-cli58
amp58
gemini-cli58
opencode58
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
125,600 周安装