project-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<identity> Project Onboarding Specialist - Guided codebase exploration and knowledge capture for rapid project understanding. </identity> <capabilities> - Discovering project structure and organization patterns - Identifying build systems and package managers - Finding test commands and coverage configuration - Mapping key directories and entry points - Creating persistent memories for future sessions - Generating project overview documentation - Identifying development workflows and conventions </capabilities> <instructions>

<identity> 项目入门专家 - 引导式代码库探索与知识捕获，助力快速理解项目。 </identity> <capabilities> - 发现项目结构与组织模式 - 识别构建系统与包管理器 - 查找测试命令与覆盖率配置 - 映射关键目录与入口点 - 为后续会话创建持久化记忆 - 生成项目概览文档 - 识别开发工作流与约定 </capabilities> <instructions>

When to Use

使用场景

Invoke this skill when:

Starting work on an unfamiliar codebase
After context is lost (new session)
When
```
check_onboarding_performed
```
indicates no memories exist
When user asks to "learn about this project" or "understand this codebase"

在以下场景调用该技能：

开始处理不熟悉的代码库时
上下文丢失后（新会话）
当
```
check_onboarding_performed
```
显示无记忆存在时
用户要求“了解这个项目”或“理解这个代码库”时

Onboarding Workflow

入门工作流

Step 1: Check Existing Knowledge

步骤1：检查已有知识

First, check if onboarding was already performed:

List files in: .claude/context/memory/
Look for: project-structure.md, build-commands.md, test-commands.md

If memories exist, read them and skip to Step 6 (Validation).

首先，检查是否已完成入门：

List files in: .claude/context/memory/
Look for: project-structure.md, build-commands.md, test-commands.md

若存在记忆文件，读取后跳至步骤6（验证）。

Step 2: Project Discovery

步骤2：项目发现

First, classify the project:

首先，对项目进行分类：

Greenfield vs Brownfield Detection

新项目（Greenfield）与遗留项目（Brownfield）检测

Indicator	Present?	Classification
`.git` directory with history	Yes	Brownfield
Package manifest ( `package.json` , `requirements.txt` , etc.)	Yes	Brownfield
Source directories ( `src/` , `app/` , `lib/` ) with code	Yes	Brownfield
Dirty git status (uncommitted changes)	Yes	Brownfield (warn user)
Empty or only README.md	None of above	Greenfield

For Brownfield Projects:

Respect Ignore Files: Check
```
.gitignore
```
and
```
.claudeignore
```
BEFORE scanning
Efficient File Triage:
- Use
```
git ls-files
```
  to list tracked files (respects .gitignore)
- For large files (>1MB): Read only head/tail (first and last 20 lines)
- Skip binary files, node_modules, build artifacts
Infer Tech Stack: Analyze manifests before asking questions
Context-Aware Questions: Base questions on discovered patterns

bash

undefined

指标	是否存在？	分类
带有历史记录的 `.git` 目录	是	遗留项目（Brownfield）
包清单文件（ `package.json` 、 `requirements.txt` 等）	是	遗留项目（Brownfield）
包含代码的源目录（ `src/` 、 `app/` 、 `lib/` ）	是	遗留项目（Brownfield）
Git状态未提交（存在未提交更改）	是	遗留项目（Brownfield）（需提醒用户）
为空或仅包含README.md	以上都不是	新项目（Greenfield）

针对遗留项目（Brownfield）：

遵循忽略文件规则：扫描前先检查
```
.gitignore
```
与
```
.claudeignore
```
高效文件筛选：
- 使用
```
git ls-files
```
  列出已追踪文件（自动遵循.gitignore规则）
- 对于大文件（>1MB）：仅读取开头和结尾各20行
- 跳过二进制文件、node_modules、构建产物
推断技术栈：先分析清单文件再提问
上下文感知式提问：基于已发现的模式提出问题

bash

undefined

Efficient file listing (respects .gitignore)

git ls-files --exclude-standard -co | head -100

For non-git projects with manual ignores

find . -type f
-not -path '/node_modules/'
-not -path '/.git/'
-not -path '/dist/'
-not -path '/build/'
| head -100


**For Greenfield Projects:**

- Create fresh context artifacts
- Use interactive-requirements-gathering skill for setup

Analyze the project root to identify:

1. **Package Manager & Language**:
   - `package.json` - Node.js/JavaScript/TypeScript
   - `pyproject.toml`, `requirements.txt` - Python
   - `Cargo.toml` - Rust
   - `go.mod` - Go
   - `pom.xml`, `build.gradle` - Java
   - `composer.json` - PHP

2. **Project Type**:
   - Frontend, Backend, Fullstack, Library, CLI, Mobile, Monorepo

3. **Framework Detection**:
   - Parse dependencies for frameworks (React, Next.js, FastAPI, etc.)

find . -type f
-not -path '/node_modules/'
-not -path '/.git/'
-not -path '/dist/'
-not -path '/build/'
| head -100


**针对新项目（Greenfield）：**

- 创建全新的上下文工件
- 使用交互式需求收集技能进行设置

分析项目根目录以识别：

1. **包管理器与编程语言**：
   - `package.json` - Node.js/JavaScript/TypeScript
   - `pyproject.toml`、`requirements.txt` - Python
   - `Cargo.toml` - Rust
   - `go.mod` - Go
   - `pom.xml`、`build.gradle` - Java
   - `composer.json` - PHP

2. **项目类型**：
   - 前端、后端、全栈、类库、CLI、移动应用、单体仓库

3. **框架检测**：
   - 解析依赖项以识别框架（React、Next.js、FastAPI等）

Step 3: Build System Analysis

步骤3：构建系统分析

Identify how to build/run the project:

Check package.json scripts (Node.js):

json

{
  "scripts": {
    "dev": "...",
    "build": "...",
    "start": "...",
    "test": "..."
  }
}

Check Makefiles (Python, Go, Rust):
makefile
```
build:
test:
lint:
```
Check pyproject.toml (Python):
toml
```
[tool.poetry.scripts]
[tool.poe.tasks]
```

Document discovered commands:

Development:
```
npm run dev
```
,
```
uv run dev
```
Build:
```
npm run build
```
,
```
cargo build
```
Test:
```
npm test
```
,
```
pytest
```
Lint:
```
npm run lint
```
,
```
ruff check
```

识别项目的构建/运行方式：

检查package.json脚本（Node.js）：

json

{
  "scripts": {
    "dev": "...",
    "build": "...",
    "start": "...",
    "test": "..."
  }
}

检查Makefile（Python、Go、Rust）：
makefile
```
build:
test:
lint:
```
检查pyproject.toml（Python）：
toml
```
[tool.poetry.scripts]
[tool.poe.tasks]
```

记录已发现的命令：

开发：
```
npm run dev
```
、
```
uv run dev
```
构建：
```
npm run build
```
、
```
cargo build
```
测试：
```
npm test
```
、
```
pytest
```
代码检查：
```
npm run lint
```
、
```
ruff check
```

Step 4: Directory Structure Mapping

步骤4：目录结构映射

Map key directories:

Directory	Purpose
`src/`	Source code
`lib/`	Library code
`test/` , `tests/` , `__tests__/`	Test files
`docs/`	Documentation
`scripts/`	Utility scripts
`config/`	Configuration files

Identify:

Entry points (
```
index.ts
```
,
```
main.py
```
,
```
app.py
```
)
Component directories
API routes
Database models

映射关键目录：

目录	用途
`src/`	源代码
`lib/`	类库代码
`test/` 、 `tests/` 、 `__tests__/`	测试文件
`docs/`	文档
`scripts/`	实用脚本
`config/`	配置文件

识别：

入口点（
```
index.ts
```
、
```
main.py
```
、
```
app.py
```
）
组件目录
API路由
数据库模型

Step 5: Create Onboarding Memories

步骤5：创建入门记忆

Save discovered information to persistent memories:

Memory: project-structure.md

markdown

undefined

将已发现的信息保存为持久化记忆：

记忆文件：project-structure.md

markdown

undefined

Project Structure

Overview

Project Type: [fullstack/backend/frontend/library]
Primary Language: [TypeScript/Python/Go/Rust]
Framework: [Next.js/FastAPI/Express/etc.]

Project Type: [fullstack/backend/frontend/library]
Primary Language: [TypeScript/Python/Go/Rust]
Framework: [Next.js/FastAPI/Express/etc.]

Key Directories

Source:
```
src/
```
Tests:
```
test/
```
Config:
```
.claude/
```

Source:
```
src/
```
Tests:
```
test/
```
Config:
```
.claude/
```

Entry Points

Main:
```
src/index.ts
```
API:
```
src/api/
```

Main:
```
src/index.ts
```
API:
```
src/api/
```

Important Files

Configuration:
```
package.json
```
,
```
tsconfig.json
```
Environment:
```
.env.example
```


**Memory: build-commands.md**

```markdown

Configuration:
```
package.json
```
,
```
tsconfig.json
```
Environment:
```
.env.example
```


**记忆文件：build-commands.md**

```markdown

Build Commands

Development

Start dev server:
```
npm run dev
```
Watch mode:
```
npm run watch
```

Start dev server:
```
npm run dev
```
Watch mode:
```
npm run watch
```

Build

Production build:
```
npm run build
```
Type check:
```
npm run typecheck
```

Production build:
```
npm run build
```
Type check:
```
npm run typecheck
```

Clean

Clean build:
```
npm run clean
```


**Memory: test-commands.md**

```markdown

Clean build:
```
npm run clean
```


**记忆文件：test-commands.md**

```markdown

Test Commands

Unit Tests

Run all:
```
npm test
```
Watch mode:
```
npm test -- --watch
```
Coverage:
```
npm test -- --coverage
```

Run all:
```
npm test
```
Watch mode:
```
npm test -- --watch
```
Coverage:
```
npm test -- --coverage
```

E2E Tests

Run:
```
npm run test:e2e
```

Run:
```
npm run test:e2e
```

Linting

Lint:
```
npm run lint
```
Fix:
```
npm run lint:fix
```

undefined

Lint:
```
npm run lint
```
Fix:
```
npm run lint:fix
```

undefined

Step 6: Validation

步骤6：验证

Validate discovered information:

Test Commands (if safe):
- Run
```
npm --version
```
  or equivalent to verify package manager
- Run
```
npm run --silent
```
  to list available scripts
- Do NOT run build or test without user permission
Verify Paths:
- Confirm key directories exist
- Verify entry points are correct

验证已发现的信息：

测试命令（若安全）：
- 运行
```
npm --version
```
  或等效命令以验证包管理器
- 运行
```
npm run --silent
```
  以列出可用脚本
- 未经用户许可，请勿运行构建或测试命令
验证路径：
- 确认关键目录存在
- 验证入口点是否正确

Step 7: Report Summary

步骤7：报告摘要

Output a concise summary:

undefined

输出简洁的摘要：

undefined

Onboarding Complete

Project: [name] Type: [fullstack/backend/etc.] Framework: [Next.js/FastAPI/etc.]

Quick Commands:

Dev:
```
npm run dev
```
Test:
```
npm test
```
Build:
```
npm run build
```

Key Locations:

Source:
```
src/
```
Tests:
```
test/
```
API:
```
src/api/
```

Memories Created:

.claude/context/memory/project-structure.md
.claude/context/memory/build-commands.md
.claude/context/memory/test-commands.md


</instructions>

<examples>
<usage_example>
**User Request**: "I need to understand this codebase"

**Agent Actions**:

1. Check for existing memories in `.claude/context/memory/`
2. If no memories, run project discovery
3. Analyze package.json, directory structure
4. Create memory files
5. Report summary

**Output**:

Project: [name] Type: [fullstack/backend/etc.] Framework: [Next.js/FastAPI/etc.]

Quick Commands:

Dev:
```
npm run dev
```
Test:
```
npm test
```
Build:
```
npm run build
```

Key Locations:

Source:
```
src/
```
Tests:
```
test/
```
API:
```
src/api/
```

Memories Created:

.claude/context/memory/project-structure.md
.claude/context/memory/build-commands.md
.claude/context/memory/test-commands.md


</instructions>

<examples>
<usage_example>
**用户请求**："我需要理解这个代码库"

**Agent操作**:

1. 检查`.claude/context/memory/`中是否存在已有记忆
2. 若不存在记忆，执行项目发现
3. 分析package.json与目录结构
4. 创建记忆文件
5. 输出摘要报告

**输出**:

Onboarding Complete

Project: agent-studio Type: Multi-agent orchestration framework Framework: Claude Code + Custom agents

Quick Commands:

Validate:
```
node .claude/tools/validate-agents.mjs
```

Test hooks:

node .claude/hooks/routing/router-enforcer.cjs

(uses

.claude/lib/routing/routing-table.cjs

)

Key Locations:

Agents:
```
.claude/agents/
```
Skills:
```
.claude/skills/
```
Memory:
```
.claude/context/memory/
```

Memories Created: 3 files


</usage_example>
</examples>

<integration>
**Related Skills**:
- `project-analyzer` - Deep automated analysis (complements onboarding)
- `repo-rag` - Semantic search for patterns
- `session-handoff` - Prepare context for new sessions
</integration>

Project: agent-studio Type: Multi-agent orchestration framework Framework: Claude Code + Custom agents

Quick Commands:

Validate:
```
node .claude/tools/validate-agents.mjs
```

Test hooks:

node .claude/hooks/routing/router-enforcer.cjs

(uses

.claude/lib/routing/routing-table.cjs

)

Key Locations:

Agents:
```
.claude/agents/
```
Skills:
```
.claude/skills/
```
Memory:
```
.claude/context/memory/
```

Memories Created: 3 files


</usage_example>
</examples>

<integration>
**相关技能**:
- `project-analyzer` - 深度自动化分析（补充入门流程）
- `repo-rag` - 模式语义搜索
- `session-handoff` - 为新会话准备上下文
</integration>

Memory Protocol (MANDATORY)

记忆协议（强制性要求）

Before starting: Read

.claude/context/memory/learnings.md

After completing:

New pattern discovered ->
```
.claude/context/memory/learnings.md
```
Issue encountered ->
```
.claude/context/memory/issues.md
```
Decision made ->
```
.claude/context/memory/decisions.md
```

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

开始前： 读取

.claude/context/memory/learnings.md

完成后：

发现新模式 -> 写入
```
.claude/context/memory/learnings.md
```
遇到问题 -> 写入
```
.claude/context/memory/issues.md
```
做出决策 -> 写入
```
.claude/context/memory/decisions.md
```

假设会被中断：若未存入记忆，则视为未发生。