codebase-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Onboarding

代码库入职指南

Generate a comprehensive onboarding document for a codebase by exploring it in parallel.
通过并行探索代码库,生成一份全面的入职文档。

Workflow

工作流程

1. Launch Parallel Explorers

1. 启动并行探索Agent

Spawn 5
explore
subagents, each investigating a different area:
Agent 1 — Architecture & Structure
"Map the top-level directory structure. Identify the framework (Next.js, Express, Django, etc.), monorepo tools (turbo, nx), and key config files. List every app/package and what it does."
Agent 2 — Data Models & Database
"Find all database schemas, ORM models, migrations, and seed files. List every entity, its fields, and relationships. Identify the database (Postgres, MySQL, MongoDB, etc.) and ORM (Prisma, Drizzle, SQLAlchemy, etc.)."
Agent 3 — API Routes & Endpoints
"Find all API route definitions. List every endpoint with its HTTP method, path, auth requirements, and what it does. Identify the API style (REST, GraphQL, tRPC)."
Agent 4 — Authentication & Authorization
"Find how auth works. Identify the auth provider (Auth.js, Clerk, Supabase Auth, custom), session management, protected routes, role/permission checks, and middleware."
Agent 5 — Deployment & Infrastructure
"Find deployment config (Dockerfile, Vercel config, fly.toml, terraform), CI/CD pipelines (GitHub Actions, etc.), environment variables needed, and how to run the app locally."
生成5个
explore
子Agent,每个负责调查不同领域:
Agent 1 — 架构与结构
"梳理顶级目录结构。识别框架(Next.js、Express、Django等)、单仓库工具(turbo、nx)以及关键配置文件。列出所有应用/包及其功能。"
Agent 2 — 数据模型与数据库
"查找所有数据库模式、ORM模型、迁移文件和种子文件。列出每个实体及其字段和关系。识别数据库(Postgres、MySQL、MongoDB等)和ORM(Prisma、Drizzle、SQLAlchemy等)。"
Agent 3 — API路由与端点
"查找所有API路由定义。列出每个端点的HTTP方法、路径、认证要求及其功能。识别API风格(REST、GraphQL、tRPC)。"
Agent 4 — 认证与授权
"查找认证机制的工作原理。识别认证提供商(Auth.js、Clerk、Supabase Auth、自定义实现)、会话管理、受保护路由、角色/权限检查以及中间件。"
Agent 5 — 部署与基础设施
"查找部署配置(Dockerfile、Vercel配置、fly.toml、terraform)、CI/CD流水线(GitHub Actions等)、所需环境变量,以及本地运行应用的方法。"

2. Synthesize

2. 整合结果

Combine the results from all 5 agents into a single onboarding document:
markdown
undefined
将5个Agent的调查结果合并为一份入职文档:
markdown
undefined

Codebase Onboarding

Codebase Onboarding

Quick Start

Quick Start

  1. Clone the repo
  2. Install dependencies:
    <command>
  3. Set up environment: copy
    .env.example
    to
    .env
  4. Run database migrations:
    <command>
  5. Start dev server:
    <command>
  1. Clone the repo
  2. Install dependencies:
    <command>
  3. Set up environment: copy
    .env.example
    to
    .env
  4. Run database migrations:
    <command>
  5. Start dev server:
    <command>

Architecture

Architecture

<Agent 1 findings>
<Agent 1 findings>

Data Models

Data Models

<Agent 2 findings>
<Agent 2 findings>

API Reference

API Reference

<Agent 3 findings>
<Agent 3 findings>

Authentication

Authentication

<Agent 4 findings>
<Agent 4 findings>

Deployment

Deployment

<Agent 5 findings>
<Agent 5 findings>

Key Files to Know

Key Files to Know

  • <file>
    — <why it matters>
undefined
  • <file>
    — <why it matters>
undefined

3. Save

3. 保存文档

Write the document to
ONBOARDING.md
in the project root, or wherever the user specifies.
将文档写入项目根目录的
ONBOARDING.md
,或用户指定的其他位置。

Tips

提示

  • Each explore agent is read-only and fast — the whole process takes under a minute
  • For monorepos, consider one additional agent per app/package
  • The document should be opinionated — highlight the "start here" files, not just list everything
  • Include gotchas: common setup issues, env vars that are easy to forget, required system dependencies
  • 每个探索Agent均为只读模式且运行快速——整个过程耗时不到一分钟
  • 对于单仓库(monorepo),可考虑为每个应用/包额外添加一个Agent
  • 文档应具备针对性——重点标注“入门必看”文件,而非简单罗列所有内容
  • 包含注意事项:常见的配置问题、容易遗漏的环境变量、必需的系统依赖