How to Set Up Claude Code on a New Project: CLAUDE.md, Skills and Model Routing

A practical setup guide: install, CLAUDE.md, skills, subagents, model routing, and the habits that make Claude Code actually fast.

Why setup matters

Out of the box, Claude Code is smart but knows nothing about your project. Every session starts with a fresh context window. It doesn't know your build command, your architecture rules, or that you hate !! in Kotlin.

Ten minutes of setup fixes that. Here's the setup I use on new projects, from install to model routing.

Step 1: Install and log in

Claude Code needs a Pro, Max, Team, Enterprise, or Console account. The free plan doesn't include it.

macOS, Linux, WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Prefer a package manager? brew install --cask claude-code or winget install Anthropic.ClaudeCode also work, but they don't auto-update like the native installer does.

Then check it works and start your first session:

claude --version
cd my-android-app
claude

The first run opens your browser to log in. If anything feels off later, claude doctor prints a read-only health check of your install and settings.

Step 2: Generate your CLAUDE.md with /init

CLAUDE.md is a markdown file Claude reads at the start of every session. Think of it as onboarding notes for a new teammate who forgets everything overnight.

Inside a session, run:

/init

Claude scans your codebase and writes a starting CLAUDE.md with the build commands, test commands, and conventions it finds. If one already exists, /init suggests improvements instead of overwriting it.

Then edit it yourself. The value is in what Claude can't discover by reading code: your team's rules, the gotchas, and the "never do this" list.

Where CLAUDE.md files can live

They don't override each other. Claude loads them all and combines them, with the file closest to where you launched read last.

What a good CLAUDE.md looks like

Here's a trimmed example for a Jetpack Compose app:

# Project: MyApp (Android)

## Build and test
- Build: ./gradlew assembleDebug
- Unit tests: ./gradlew testDebugUnitTest
- Lint: ./gradlew ktlintCheck detekt
- Run tests for one module: ./gradlew :feature:home:testDebugUnitTest

## Architecture
- Multi-module, Clean Architecture: :app, :core:*, :domain, :data, :feature:*
- :domain and :core:model must have ZERO Android imports
- MVVM + Hilt. One ViewModel per screen, exposing a single StateFlow<UiState>

## Rules
- Kotlin only. No `!!`. Prefer sealed interfaces for UI state
- Never edit generated files under build/
- New screens need a Compose preview and a ViewModel unit test
- Ask before adding a new Gradle dependency

Keep it short

The docs recommend keeping each CLAUDE.md under 200 lines. Longer files eat context and Claude follows them less reliably. A few tips:

• Be specific. "Run ./gradlew ktlintCheck before committing" beats "keep code clean".
• Remove contradictions. If two rules conflict, Claude may pick one at random.
• Split by topic once it grows. Put files like testing.md or security.md in .claude/rules/. Rules can be scoped to file paths, so they only load when Claude touches matching files.
• Import, don't paste. Use @docs/architecture.md inside CLAUDE.md to pull in another file.
• Audit occasionally. /doctor prompt-audit checks your CLAUDE.md, rules, skills, and agents for outdated or conflicting instructions.

One important limit: CLAUDE.md is guidance, not enforcement. If something must never happen (like editing .env files), use a hook to block it.

Step 3: Add skills for repeatable workflows

A skill is a folder with a SKILL.md file that teaches Claude how to do one specific job: release a build, write a migration, review a PR your way.

The big difference from CLAUDE.md: only the skill's short description loads every session. The full instructions load only when needed. So you can have dozens of skills without bloating context.

Where skills live

A minimal skill

.claude/skills/new-screen/SKILL.md:

---
name: new-screen
description: Scaffold a new Compose feature screen with ViewModel, UiState, preview and tests
---

When creating a new screen called <Name>:

1. Create the module under :feature:<name> using the existing
   :feature:home module as the template
2. Add <Name>UiState as a sealed interface (Loading, Content, Error)
3. Add <Name>ViewModel with Hilt, exposing StateFlow<<Name>UiState>
4. Add <Name>Screen composable plus a @Preview for each state
5. Add a ViewModel unit test using Turbine
6. Register the route in the app NavHost
7. Run ./gradlew :feature:<name>:testDebugUnitTest and fix failures

Claude can use it two ways:

• Automatically, when your request matches the description ("add a settings screen")
• Manually, by typing /new-screen at the start of your message

Useful frontmatter fields

Skills can also bundle supporting files, like a reference.md or a scripts/ folder, in the same directory.

Rule of thumb: if you've explained the same multi-step process to Claude three times, make it a skill.

Step 4: Subagents and model routing

A subagent is a separate Claude instance with its own context window. You hand it a task, it works in isolation, and it returns a report. Your main conversation stays clean.

You define them in .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: code-reviewer
description: Reviews a diff for bugs, missing tests and architecture violations
tools: Read, Glob, Grep
model: opus
---

You are a senior Android reviewer. Check the changes against CLAUDE.md.
Report: bugs, missing tests, :domain layer Android imports, and risky
Gradle changes. Be specific, cite file and line.

Then just say "use the code-reviewer agent on my changes", or @agent-code-reviewer to guarantee it runs.

The models you can route to

Switch the main model anytime with /model sonnet, or start with claude --model fable. On a Pro, Max or API account, opus maps to Opus 5.5 and sonnet to Sonnet 5.5 (the mappings differ on Bedrock, Vertex and Foundry).

A note on Sonnet 5.5: it launched on September 28, 2026 and actually beats Opus 5.5 on some coding benchmarks (70.6% vs 66.4% on Terminal-Bench 4.0) at half the price. The catch: at maximum effort it uses noticeably more tokens per task, which eats into the savings. Use it at normal effort for well-scoped tasks, and keep Opus for work that needs longer judgment.

The viral CLAUDE.md: should you use it?

This snippet has been going around from a popular video:

Never do the work yourself.
Always dispatch a sub-agent.
Don't always use Fable.
Use Opus 5.5 for easier tasks.
# Model routing
- Fable 5.1: architecture, hard bugs, review
- Opus 5.5: edits, tests, docs, refactors
- Haiku 4.5: lookups and summaries
- Pass `model` on every Agent call
# Delegation
- One sub-agent per task, plan first
- Run independent sub-agents in parallel
- Read the report, never the files

What it gets right:

• Model routing is the real win. Running Fable on every typo fix burns money and time. Matching the model to the task is the biggest cost lever you have.
• "Pass model on every Agent call" works. Claude Code checks the per-call model first, before the agent's own setting.
• Parallel subagents for independent work, like auditing three modules at once, are a genuine speed-up.
• Plan first catches bad approaches before any code is written.

Where I'd push back:

• "Never do the work yourself" is too absolute. Each subagent starts cold. It has to re-read files and rebuild context, and its tokens count toward your usage. For a two-line fix, dispatching a subagent is slower and more expensive than just doing it.
• "Read the report, never the files" is risky. A report is a summary, and summaries can be wrong. Someone should verify the actual diff, either the main session or you.
• It skips Sonnet 5.5, which is now the best value for most everyday coding.

My improved version

# Model routing
- Fable 5.1: architecture decisions, hard bugs, final review of risky changes
- Opus 5.5: multi-step features, refactors that span modules
- Sonnet 5.5: well-scoped edits, bug fixes, tests, docs
- Haiku 4.5: lookups, file searches, summaries
- Pass `model` on every Agent call

# Delegation
- Small, local changes: do them directly, no subagent
- Broad exploration or many-file searches: dispatch a subagent, ask for conclusions only
- Independent tasks: run subagents in parallel
- One subagent per task, plan first

# Verification
- Read the report, then check the diff before accepting
- Run ./gradlew testDebugUnitTest after every change

The skills YOU need to use Claude Code well

Tools are half of it. These human skills decide whether Claude Code feels like a senior teammate or a slot machine.

1. Write clear specs

Vague in, vague out. Compare:

• Weak: "Add login"
• Strong: "Add Google Sign-In using Credential Manager. Store the user in the existing UserRepository. Show errors in the current Snackbar host. Add a ViewModel test for the failure path."

Say what, where, constraints, and how you'll know it's done.

2. Plan before you build

For anything bigger than a small fix, use plan mode (press Shift+Tab to cycle modes). Claude explores and proposes a plan without touching files. Fixing a plan takes seconds. Fixing 30 changed files takes an afternoon.

3. Break work into small pieces

One feature per session, one concern per prompt. Small tasks are easier to review, easier to revert, and Claude stays more accurate.

4. Manage context

Context is a budget. As it fills up, quality drops.

• /clear when switching to an unrelated task
• /compact to summarize a long session and keep going
• /context to see what's using space

5. Give Claude a way to check itself

The best prompt upgrade is a feedback loop: "Run the tests and fix failures until they pass." Tests, lint, type checks, and builds let Claude catch its own mistakes before you do.

6. Review like a senior engineer

You still own the code. Read diffs, question surprising changes, and watch for skipped tests or quietly deleted assertions. Claude is fast, not infallible.

7. Use git as your safety net

Commit before big changes. Work on a branch. If a session goes sideways, git restore is faster than arguing with it.

8. Know your architecture

Claude follows your patterns. If you can't explain your architecture, you can't write a good CLAUDE.md or catch when Claude breaks the rules. This is where years of experience still pay off.

9. Turn repetition into skills

Notice what you keep explaining, and codify it as a skill, a rule, or a subagent. Your setup should get better every week.

Your new-project checklist

The takeaway

Claude Code doesn't get better because you found a magic prompt. It gets better because you gave it context (CLAUDE.md), taught it your workflows (skills), sent work to the right model (routing), and stayed the engineer in charge (specs, plans, reviews).

Set it up once, and every session after that starts smarter.

Sources

• Claude Code setup (official docs)
• How Claude remembers your project: CLAUDE.md (official docs)
• Skills (official docs)
• Subagents (official docs)
• Model configuration (official docs)
• Models overview and pricing (Claude Platform docs)
• Claude Sonnet 5.5 release (Decrypt)

— ByteBrain Apps · Calm interfaces. Intelligent motion.