Your First Claude Code Session: What to Expect and How to Get 10x Results
Start by running `claude` in your project root, then give Claude a concrete task with clear success criteria. Don't paste code in your first message — Claude will read the relevant files itself using its tools. Before your first session, create a CLAUDE.md file with your stack, conventions, and commands to avoid re-explaining context every time.
Most first-time Claude Code users underperform because they use it like a chat interface: paste a block of code, ask a question, get a code snippet back. That's not how Claude Code works. Claude Code is an agent — it has file read/write, bash execution, and search tools. Give it a task, not a snippet.
The most effective first prompt describes the outcome you want, not the implementation. 'Add pagination to the user listing page' works better than 'here is my component, add the next/prev buttons and the API call'. Claude will read the component itself, understand your data layer, check your existing patterns, and write code that actually fits.
The session workflow is: you describe a task → Claude explores the codebase (using Read, Glob, Grep tools) → Claude proposes a plan (especially in plan mode) → Claude implements → Claude runs tests → Claude reports results. You can interrupt at any step to redirect. The `/clear` command resets context if the session gets confused.
Before your very first session, spend 15 minutes writing CLAUDE.md. The payoff is massive — every future session starts with Claude already knowing your stack, naming conventions, test framework, build commands, and critical rules. Without CLAUDE.md, you'll explain these things in every session.
The `/memory` command (in interactive mode) lets Claude append to your CLAUDE.md during a session. When Claude discovers something about your codebase ('ah, you use Zod for validation everywhere'), type `/memory This project uses Zod v3 for all runtime validation` and it'll be remembered permanently.
Common first-session mistakes: (1) Starting with too large a task — Claude works best on tasks scoped to a single feature or file group. (2) Not running `claude doctor` first to confirm the API connection. (3) Interrupting mid-task and restarting instead of redirecting — Claude can recover from partial work if you clarify rather than abandon. (4) Expecting Claude to know your internal APIs without reading the code — it will, but you can speed it up by mentioning the relevant file paths.
Examples
# GOOD: concrete task with implicit success criteria
"Add server-side validation to the /api/users POST endpoint using Zod. The schema should match the UserCreate type in src/types/user.ts. Return 422 with field errors on validation failure."
# GOOD: explicit files + outcome
"Refactor src/lib/database.ts to use connection pooling. Current implementation creates a new connection per request. Use pg-pool. Keep the same exported API surface."
# GOOD: debugging task with symptoms
"The /dashboard route is throwing 'Cannot read property map of undefined' in production. Error originates in src/app/dashboard/page.tsx around the data fetching. Investigate and fix."
# BAD: too vague
"Make the code better"
# BAD: treating Claude like a code generator, not an agent
"Here is my component: [pastes 200 lines]. Add dark mode."
# Better: "Add dark mode support to the UserProfile component in src/components/UserProfile.tsx. We use Tailwind and next-themes — follow the pattern in src/components/NavBar.tsx."# Project: [Your Project Name]
## Stack
- [Framework and version]
- [Language (TypeScript/Python/etc)]
- [Database]
- [Test framework]
## Run commands
- `[dev command]` — start dev server
- `[test command]` — run tests
- `[lint command]` — lint and typecheck
## File layout
- `[src directory]` — main source
- `[test directory]` — tests
## Critical rules
- [One rule that Claude MUST follow, e.g. "never edit files in /generated/"]
- [Another must-follow rule]# In interactive Claude Code session:
/clear # Reset context (fixes confused sessions)
/memory [text] # Append text to CLAUDE.md permanently
/compact # Compress conversation history to free context
/status # See current token usage and context size
/help # List all slash commands
# Interrupt a running task:
Ctrl+C # Cancel current tool call and return to promptTips
- →Run `claude doctor` before your first session to verify API connectivity and node version — saves debugging time later.
- →Start with a small, self-contained task (add a single endpoint, write tests for one function) to learn how Claude Code works before giving it large refactors.
- →After Claude completes a task, review the diff with `git diff` and run your tests before accepting the changes — Claude is right most of the time but not always.
- →Use `/clear` freely — Claude Code sessions accumulate context and can become confused on long tasks. Start fresh on each new task rather than continuing in a stale session.
- →Ask Claude to explain its plan before acting on complex tasks: 'Before making changes, describe what you plan to do and which files you'll modify.' This surfaces misunderstandings early.
- →Set Claude's model explicitly for your first session: `claude --model claude-sonnet-4-5` — Sonnet is the best cost/capability tradeoff for most tasks in 2026.
FAQ
Should I paste my code into the prompt or let Claude read files?+
Let Claude read files — that's what it's for. When you paste code, Claude works from a snapshot that may be stale by the time it finishes editing. When Claude reads files via its Read tool, it always gets the current state. You only need to paste code if you're asking a theoretical question without an actual file to reference.
How long should my prompts be?+
First prompt: 2-5 sentences with the task, relevant file paths or component names, and any constraints. You don't need to explain the whole codebase — Claude will explore. For follow-up messages within a session, one or two sentences is usually enough to redirect or clarify.
What should I do if Claude makes a mistake?+
Don't abandon the session. Tell Claude specifically what was wrong: 'That approach breaks the existing tests in users.test.ts because X' or 'You added a new dependency but we can't add dependencies without approval — use the built-in Node crypto module instead.' Claude recovers well from correction within the same session.
How many files can Claude handle in one session?+
Claude Code can handle projects with thousands of files because it uses tools to read only what it needs, not load everything at once. Practical limits: the context window (200K tokens for claude-sonnet-4-5) fills with long sessions. Use /compact to compress history and /clear to start fresh when sessions feel slow.