Rajesh Royal

Posted on Jan 27

/init: Let Claude Write Its Own Onboarding Docs

#tutorial #claudecode #productivity #beginners

Every developer needs onboarding docs. Claude writes its own.

From: x.com/adocomplete

Introduction

Picture this: A new developer joins your team. They clone the repo and immediately face questions. How do you build this? Where do tests live? What's the naming convention? They spend hours piecing together tribal knowledge, bothering senior developers, and making educated guesses.

Now imagine the same scenario, but with Claude Code. Claude needs the same onboarding. It needs to know your build commands, your test patterns, your project structure, your conventions. Without this context, it's just a smart assistant guessing at how your specific project works.

The difference? Claude can read your entire codebase in seconds and write its own onboarding documentation. That's /init.

The Problem

Claude Code is brilliant, but it's not psychic. Every codebase has:

Unique build processes: Maybe you use npm. Maybe pnpm. Maybe a custom shell script that runs three things in sequence.
Custom test setups: Unit tests here, integration tests there, E2E tests in a completely different directory with their own framework.
Project conventions: That utils/ folder everyone knows not to touch. The naming pattern for service files. The reason legacy/ exists but should never be modified.
Hidden context: The PR that explains why authentication works that way. The Slack thread about the caching layer. The README that's six months out of date.

Without understanding these specifics, Claude operates at a disadvantage. It suggests patterns that don't match your codebase. It looks for files in wrong locations. It proposes changes that violate your conventions.

You could write a CLAUDE.md file manually. Or you could let Claude do it.

The Solution

The /init command triggers Claude to analyze your codebase and generate comprehensive onboarding documentation—for itself.

How to Use It

Basic Initialization

Navigate to your project root and run:

/init

Claude scans your codebase: file structure, configuration files, package manifests, existing documentation, code patterns. Then it generates a CLAUDE.md file containing everything it learned.

What Gets Generated

A typical CLAUDE.md includes:

# Project: my-awesome-app

## Build Commands
- `npm run dev` - Start development server (Vite)
- `npm run build` - Production build
- `npm run test` - Run Jest tests
- `npm run test:e2e` - Run Playwright E2E tests
- `npm run lint` - ESLint + Prettier check

## Project Structure
- `src/components/` - React components (PascalCase naming)
- `src/hooks/` - Custom React hooks (use* prefix required)
- `src/services/` - API service modules
- `src/utils/` - Shared utility functions
- `tests/` - Unit tests (mirror src/ structure)
- `e2e/` - End-to-end tests

## Key Conventions
- TypeScript strict mode enabled
- All API calls go through src/services/api.ts
- State management via Zustand (not Redux)
- CSS Modules for component styling
- No default exports (named exports only)

## Testing Requirements
- Unit tests required for all utility functions
- Integration tests for API services
- E2E tests for critical user flows
- Minimum 80% coverage for new code

## Important Notes
- `src/legacy/` contains deprecated code - do not modify
- Authentication uses custom JWT implementation in src/auth/
- Environment variables must be prefixed with VITE_

Reviewing and Refining

After generation, Claude shows you the proposed CLAUDE.md and asks for feedback:

I've analyzed your codebase and generated onboarding documentation. 
Would you like me to:
1. Save this as CLAUDE.md
2. Modify specific sections
3. Add additional context you'd like me to know

Add your own insights. Correct any misunderstandings. The result is a living document that combines Claude's analysis with your expertise.

Pro Tips

Re-run After Major Changes: Refactored your project structure? Added a new build step? Run /init --refresh to update the documentation without starting from scratch.

Multiple CLAUDE.md Files: Large monorepos can have a CLAUDE.md at the root and in each package directory. Claude respects the nearest one to where you're working.

Version Control It: Commit your CLAUDE.md to the repository. It's useful documentation for humans too, and it ensures every developer gets the same Claude experience.

Add Team-Specific Context: After generation, add sections Claude can't infer:

## Team Practices
- PRs require two approvals
- Feature branches named: feature/TICKET-description
- Hotfixes go directly to main with post-merge review

Combine with Skills: Reference existing skills in your CLAUDE.md for deeper context on specific topics.

Real-World Use Case

Scenario: You maintain an open-source library with 50+ contributors. Each contributor has different levels of familiarity with the codebase. They all use Claude Code.

Before /init: Contributors ask Claude for help, but Claude doesn't know your contribution guidelines, your test requirements, or your release process. Pull requests arrive with inconsistent patterns. Reviews take longer because Claude-assisted code doesn't match project conventions.

After /init: You run /init, refine the output, and commit CLAUDE.md to the repo. Now every contributor's Claude knows:

Your preferred code style
Where to add new features
How to write tests that match existing patterns
What the PR checklist requires

Contributions arrive cleaner. Reviews go faster. The tribal knowledge is documented—by an AI that never forgets to follow it.

Conclusion

/init solves a bootstrapping problem. Claude needs context to be effective, but writing that context is work. So Claude does the work itself. It reads your codebase, extracts patterns, documents conventions, and creates its own onboarding guide.

The result? An AI assistant that understands your specific project from day one. No manual documentation required.

Tomorrow, we're looking at the flip side of documentation—exporting your conversations. Day 24 explores /export—dumping your entire Claude session to markdown for documentation, training, or just proving to yourself that yes, you did try that approach already.

Follow along with the series to discover a new Claude Code feature every day. What conventions would you add to your CLAUDE.md? Share in the comments!

DEV Community