project-onboarding

项目入门引导专家——指导用户探索代码库并捕获知识，帮助快速了解项目。 - 发现项目结构和组织模式 - 识别构建系统和包管理器 - 查找测试命令和覆盖率配置 - 梳理关键目录和入口点 - 创建可在后续会话中使用的持久记忆 - 生成项目概览文档 - 识别开发工作流和约定

适用场景

在以下情况下调用此技能：

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

入门引导工作流

步骤 1：检查现有知识

首先，检查是否已执行过入门引导：

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

如果存在记忆，请阅读并跳到步骤 6（验证）。

步骤 2：发现项目

首先，对项目进行分类：

检测全新项目与现有项目

指标	是否存在？	分类
.git 目录且有历史记录	是	现有项目
包清单（package.json、requirements.txt 等）	是	现有项目
含有代码的源代码目录（src/、app/、lib/）	是	现有项目
Git 状态不干净（存在未提交的更改）	是	现有项目（提醒用户）
为空或仅包含 README.md	以上均无	全新项目

对于现有项目：

1. 遵守忽略文件：扫描前检查 .gitignore 和 .claudeignore
2. 高效筛选文件：
   • 使用 git ls-files 列出已跟踪的文件（会遵守 .gitignore）
   • 对于大型文件（>1MB）：仅读取文件头尾（前 20 行和后 20 行）
   • 跳过二进制文件、node_modules 和构建产物
3. 推断技术栈：先分析清单，再提出问题
4. 结合上下文提问：根据发现的模式提出问题

# 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

对于全新项目：

• 创建全新的上下文材料
• 使用 interactive-requirements-gathering 技能进行设置

分析项目根目录以确定：

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 等）

步骤 3：分析构建系统

确定如何构建和运行项目：

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

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

2. 检查 Makefile（Python、Go、Rust）：

   build:
   test:
   lint:
   

3. 检查 pyproject.toml（Python）：

   [tool.poetry.scripts]
   [tool.poe.tasks]
   

4. 记录发现的命令：

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

步骤 4：梳理目录结构

梳理关键目录：

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

识别：

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

### 步骤 5：创建入门记忆

将发现的信息保存到持久化记忆中：

记忆：project-structure.md

# Project Structure

## Overview

- 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/`

## Entry Points

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

## Important Files

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

记忆：build-commands.md

# Build Commands

## Development

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

## Build

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

## Clean

- Clean build: `npm run clean`

记忆：test-commands.md

# Test Commands

## Unit Tests

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

## E2E Tests

- Run: `npm run test:e2e`

## Linting

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

步骤 6：验证

验证发现的信息：

1. 测试命令（安全时）：

   • 运行 npm --version 或等效命令，确认包管理器
   • 运行 npm run --silent，列出可用脚本
   • 未经用户许可，不要运行构建或测试

2. 验证路径：

   • 确认关键目录存在
   • 验证入口点正确

步骤 7：汇总报告

输出简洁的摘要：

## 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

**用户请求**：“我需要了解这个代码库”

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/cli/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>

**相关技能**： - `project-analyzer` - 深度自动化分析（与入门流程互为补充） - `repo-rag` - 对模式进行语义搜索 - `session-handoff` - 为新会话准备上下文

铁律

1. 始终在运行发现流程前检查是否已有入门记忆——重复入门会产生互相矛盾的知识条目，误导后续 Agent。
2. 绝不未经验证就假设项目采用标准惯例——运行命令，确认它们在此项目环境中实际可用。
3. 始终将发现的命令和路径写入持久化记忆文件——会话上下文会重置，但命名记忆文件会永久保留。
4. 始终先通过安全测试步骤验证发现的命令，再记录下来——入门记忆中的错误命令会误导每个读取它们的 Agent。
5. 绝不在项目演进后不重新检查记忆就完成入门流程——过时的入门资料比没有入门资料更危险。

反模式

反模式	失败原因	正确做法
未经检查就假设采用标准惯例	每个项目的构建、测试和 lint 命令都不尽相同；错误的假设会导致静默失败	阅读 package.json、Makefile 或 pyproject.toml，并运行 --version 进行确认
跳过对发现命令的验证	记录下来的错误命令会误导后续每次 Agent 会话	使用安全的空操作或 --help 标志运行每条命令，确认其可用
仅在会话上下文中保存入门信息	每次新对话都会重置上下文；发现的信息会永久丢失	将所有发现写入 .claude/context/memory/named/ 中以名称命名的记忆文件
将入门流程视为一次性事件	项目会不断演进；过时的命令会静默失效，浪费 Agent 时间	每当项目结构发生重大变化后，更新入门记忆
记录过多却不优先安排关键命令	包含大量低优先级信息的文件会掩盖关键的构建和测试命令	按 Quick Start 命令优先、详细信息在后的方式组织记忆

记忆协议（强制）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 发现新模式 -> .claude/context/memory/learnings.md
• 遇到问题 -> .claude/context/memory/issues.md
• 做出决定 -> .claude/context/memory/decisions.md

假设会发生中断：如果没写入记忆，就等于没发生。