I use Claude Projects to onboard engineers 3x faster — here's the setup

I was pairing with a new engineer who kept asking questions I had answered a dozen times before — our auth flow, our database naming conventions, why we use optimistic locking in that one service. Then I realized: all of that knowledge lived in my head, scattered Notion docs, and old Slack threads. I spent an afternoon building a Claude Project with the right context files, and the next new hire barely needed me. Here is how I set it up.

What Claude Projects gives you

Claude Projects lets you attach persistent context — files, docs, knowledge — that stays available across every conversation in that project. The key insight is that you can upload files directly and Claude will have the full content available without you pasting anything.

For onboarding, this means a new engineer can ask "explain our auth flow" and Claude answers from your actual architecture docs — not a hallucinated generic answer.

The five files that matter

After experimenting, I settled on five categories of context that cover 95% of onboarding questions:

1. ARCHITECTURE.md — the system map

A single document that describes every service, how they communicate, and why. Not a diagram — prose that explains decisions.

# System Architecture

## Services

### api-gateway (Node.js / Express)
Entry point for all client requests. Handles auth token validation,
rate limiting (100 req/min per user), and request routing.

Does NOT contain business logic — it proxies to downstream services.

Why: We separated the gateway early to allow independent scaling.
The gateway is stateless and runs 4 replicas behind the load balancer.

### user-service (Python / FastAPI)
Owns all user data. The only service that writes to the `users` table.
All other services call user-service via internal HTTP — never query
the users table directly.

Why: Single source of truth for user state. Easier to add audit logging,
caching, and access control in one place.

## Auth flow
1. Client sends JWT in Authorization header
2. api-gateway validates JWT signature (RS256, public key from env)
3. api-gateway extracts user_id and passes as X-User-ID header
4. Downstream services trust X-User-ID — they do NOT re-validate the JWT

Why: Validation in one place reduces latency. Internal services are
not internet-facing so header injection is not a risk.

2. CONVENTIONS.md — the decisions you repeat

Database naming, API response shapes, error codes, file structure, commit message format. All the things you explain in every code review.

3. LOCAL_SETUP.md — the actual working instructions

Not the README that was accurate in 2023. The current, actually-tested setup steps. I update this every time a new hire tells me a step is wrong.

4. COMMON_PATTERNS.md — code snippets for recurring tasks

The exact pattern for adding a new API endpoint, writing a migration, adding a background job. Copy-paste ready.

# Common Patterns

## Adding a new API endpoint

1. Add route to `src/routes/{service}.ts`
2. Add handler to `src/handlers/{service}/{action}.ts`
3. Add Zod schema to `src/schemas/{service}.ts`
4. Add integration test to `src/tests/{service}.test.ts`

Handler pattern:
```typescript
export async function handleCreateOrder(req: Request, res: Response) {
  const parsed = CreateOrderSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(400).json({ error: parsed.error.flatten() });
  }
  
  const order = await orderService.create(parsed.data, req.userId);
  return res.status(201).json({ data: order });
}
```

## Writing a Postgres migration

Migrations live in `db/migrations/`. Run with `npm run db:migrate`.

Always:
- Make migrations reversible (add `down` function)
- Test the down migration locally before merging
- For column adds: use `DEFAULT NULL` to avoid table locks

5. GLOSSARY.md — internal terminology

Every team invents words. "Shadow user", "reconciliation job", "the V2 endpoint" — define them so new engineers aren't lost in Slack history.

The system prompt that makes it work

In Claude Projects, set a system prompt that frames Claude as a team-specific mentor:

You are a senior engineer on this team with deep knowledge of the codebase,
architecture, and conventions documented in the project files.

When a new engineer asks a question:
- Answer from the actual documentation when it applies
- Be specific about file paths, function names, and conventions
- If the documentation doesn't cover it, say so clearly and suggest where to look
- Don't give generic answers — give team-specific answers
- When showing code, follow the patterns in COMMON_PATTERNS.md exactly

Tone: patient, specific, never condescending.

What new engineers ask most

After running three onboardings with this project, the most common questions were:

• "How do I add a new database table?" — covered by COMMON_PATTERNS.md
• "What's the right way to handle auth in a new endpoint?" — covered by ARCHITECTURE.md
• "Why do we use X instead of Y?" — covered by the "Why:" sections in architecture docs
• "Where does this code live?" — covered by CONVENTIONS.md file structure section

The questions that still come to me are the ones that aren't documented — which tells me exactly what to add next.

Keeping it fresh

The killer of onboarding docs is staleness. My rule: whenever I answer a question that should have been in the docs, I add it immediately. The new engineer's question is a signal, not an interruption.

I keep a LAST_UPDATED line at the top of each file and do a quarterly review. That's enough to keep it 90% accurate, which is enough for Claude to give useful answers.

Try it this week

If you have someone new joining your team, spend two hours this week writing these five documents and uploading them to a Claude Project. Then hand the project link to your new engineer on day one and watch how many questions they can answer themselves before they reach you.