▲ Claude Academy
Sign in

Vault / course/projects/p10-claude-code-onboarding.md

updated 2026-06-25

Project 10 — Claude Code Onboarding

Enforces: install & launch, agentic file editing, permissions, and project memory (from claude-code-101) Surface: Claude Code (terminal) · Time: ~50 min · Difficulty: 🟢 starter

Why this project

Claude Code is not "chat with a code field." It's an agent that reads, edits, and runs commands in your repo. The only way that lands is to point it at a real codebase, let it do a real task, and then write the CLAUDE.md that makes every future session better. This project gets you from zero install to a committed memory file.

What you'll build

A real repository, onboarded for Claude Code: you'll run the agent on it, complete one guided change end-to-end, and author a hand-written CLAUDE.md (project overview, commands, conventions) that Claude reads automatically on every future session.

Steps

  1. Install — Install the CLI: npm install -g @anthropic-ai/claude-code (Node 18+). Run claude once and complete auth.
  2. Pick a real repo — Use an existing project of yours (or clone a small one). cd into it and launch claude. Confirm it reads your files: ask "Give me a one-paragraph tour of this repo and where the entry point is."
  3. Run /init — Let Claude draft a starter CLAUDE.md by scanning the repo. Read it critically; it's a draft, not the deliverable.
  4. Do a first guided task — Pick something small and real: fix a failing test, add a CLI flag, tidy a README. Watch how Claude proposes edits and asks before running commands. Accept/deny deliberately so you learn the permission flow.
  5. Author the real CLAUDE.md — By hand, rewrite the file into something tight (see claude-code-md). It must contain:
    • What this is — one paragraph of orientation: what the repo does, where the entry point and core modules live.
    • How to run / test — the exact commands (pnpm test, make lint, uv run ...). No guessing.
    • Conventions — naming, formatting, "imports sorted by tool," language-version rules.
    • Do NOT — landmines: generated dirs, npm vs pnpm, files never to touch.
  6. Prove it took — Start a fresh claude session and ask a question whose answer only comes from your CLAUDE.md (e.g., "How do I run the test suite here?"). It should answer without re-scanning.

Acceptance criteria — you're done when

  • claude runs in a real repo and correctly summarizes it.
  • You completed one real change, consciously accepting/denying at least one command.
  • A hand-curated CLAUDE.md exists with all four sections (what / run / conventions / do-NOT) and exact commands.
  • A fresh session answers a project question using only CLAUDE.md, no re-scan.
  • CLAUDE.md is committed to the repo so teammates inherit it.
  • You journaled the one thing CLAUDE.md should have said but didn't (yet) in learning-journal-template.

Stretch goals

  • Add a personal ~/.claude/CLAUDE.md with your style preferences and confirm it merges with the project one.
  • Add a directory-scoped CLAUDE.md in a subpackage and show a rule that only applies there.
  • Trim a too-long CLAUDE.md and notice better adherence — bury a rule and Claude misses it.

Self-assessment rubric

LevelSignal
🟢 Got itYou drive Claude Code in a real repo, manage permissions intentionally, and your CLAUDE.md makes new sessions productive immediately.
🟡 AlmostIt works, but your CLAUDE.md is the auto-generated draft or has vague commands you re-explain each session.
🔴 RevisitSessions feel like chat; you re-orient Claude every time. Re-watch claude-code-101 and re-read claude-code-md.

See also