Codebase Onboarding Guide from Source
Turns an unfamiliar repo into a day-one onboarding doc: run commands from config, one traced request flow, real conventions, gotchas.
Before & after
Same prompt, same agent — the only difference is the skill.
Generating good onboarding docs requires understanding your project structure, tech stack, and team workflows. You'd want to cover: how to set up the local environment, repository structure, key dependencies, how to run tests and deploy, coding standards, how to contribute. For Next.js specifically, you'd need to explain your app router vs. pages router setup, data fetching patterns, styling approach, and any custom tooling. You'd probably want to ask: How large is the team? What's your deployment process? Do you have specific patterns or libraries you use heavily? That would help create more targeted docs.
NEW ENGINEER ONBOARDING GUIDE - Next.js Project
DAY 1: LOCAL SETUP
PREREQUISITES
→ Node 18+, pnpm (not npm), VS Code
→ GitHub access (fork + upstream configured)
→ Figma viewer access (design system link)
SETUP STEPS (30 min total)
1. git clone (fork) → cd project
2. pnpm install (handles dependencies)
3. cp .env.example .env.local (copy env template)
4. pnpm dev (starts http://localhost:3000)
5. pnpm test (verify all tests pass)
CODEBASE ARCHITECTURE MAP
project/
├── app/ (Next.js app router routes)
│ ├── (dashboard)/ (authenticated routes)
│ ├── (marketing)/ (public landing pages)
│ ├── api/ (API endpoints)
│ └── layout.tsx (root layout)
├── components/ (React component library)
│ ├── UI/ (buttons, forms, cards)
│ ├── Features/ (feature-specific components)
│ └── *.stories.tsx (Storybook examples)
├── lib/ (utilities, helpers, types)
│ ├── db.ts (database client)
│ ├── auth.ts (auth middleware)
│ └── api-client.ts (fetch wrapper)
├── public/ (static assets, logos)
├── prisma/ (database schema + migrations)
└── tests/ (unit + integration tests)
KEY PATTERNS YOU'LL SEE
DATA FETCHING (Server Components)
// app/posts/page.tsx
const Posts = async () => {
const posts = await db.post.findMany();
return <PostList items={posts} />;
};
→ Rationale: Data fetches run server-side, no client overhead
FORM HANDLING (Server Actions)
'use server'
export async function createPost(formData) {
const data = new FormData(formData);
await db.post.create({...});
revalidatePath('/posts');
}
→ Rationale: No API route needed, form submission direct
STYLING
→ Tailwind CSS for components
→ CSS modules for page-specific overrides
→ Design tokens in tailwind.config.js
DAY 1-2 GETTING UNBLOCKED
COMMON ISSUE: Port 3000 already in use
→ Solution: lsof -i :3000 | kill -9 <PID> OR pnpm dev -p 3001
COMMON ISSUE: Prisma migrations failing
→ Solution: Check .env.local DATABASE_URL (must point to development DB)
→ Run: pnpm prisma migrate dev
SLACK CHANNEL: #engineering (ask here, veterans monitor)
PAIR BUDDY: (assigned person, 30 min introduction call)
FIRST TASK: Pick from 'Good First Issue' label on GitHub
→ Expected: 2-4 hours to complete
→ Expected: 1-2 code review rounds before merge
WEEK 2 MILESTONES
→ Deployed one small feature end-to-end
→ Attended architecture sync (Friday 10am)
→ Added one test to existing suite
→ Read: CONTRIBUTING.md + architecture decision logAbout this skill
Your new engineer spends their first week asking the same questions: how do I run this, where does a request actually go, and why are there two ways of doing everything? The README is stale and the person who knew the answers left. This skill reads the code itself and writes the guide that should have existed, with every claim tied to a file.
What it does
- Pulls setup, test, and run commands from CI config, Makefiles, manifests, and Dockerfiles, and flags where the README disagrees with them
- Finds every entry point, including the hidden ones: queue workers, cron jobs, webhooks, and Procfile processes
- Traces one real write path file by file: auth, validation, the transaction boundary, side effects, and error mapping
- Counts the conventions the code actually follows, names the legacy exceptions, and points to an exemplar file to copy
- Lists the gotchas that waste a newcomer's first day: code generation, ORM hooks, middleware order, required env vars, seed data
- Tags each claim as confirmed, inferred, or unknown, and leaves TODO slots for team facts it cannot know
What you get
A one-to-three screen onboarding guide covering local setup, an annotated map, a traced request flow, conventions, gotchas, a suggested first change, and open questions for the team. For narrower requests it returns a short orientation, a single traced flow, a stale-docs review, or a tech-lead handoff brief focused on risks.
Best for
Engineering managers and tech leads onboarding new hires or contractors, teams inheriting a codebase from another team, and engineers who need to get productive in an unfamiliar repo fast.
SKILL.md preview
---
name: codebase-onboarding-guide-from-source
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.