Claude Code complete beginner's guide: set up, first project, real tips

Claude Code is Anthropic's official terminal-based AI coding agent. Unlike ChatGPT or Claude.ai, it runs directly in your project folder — it reads your files, writes code, runs tests, and executes shell commands on your behalf. This guide gets you productive from zero. What Claude Code actually is ------------------------------ Most "AI coding tools" are glorified autocomplete. Claude Code is different in one key way: it has agency. When you say "add a dark mode toggle to my React app", it doesn't just suggest code — it reads your existing components, finds the right file, writes the change, and runs your linter to verify it compiles. You approve each step or let it run autonomously. The mental model shift: Claude Code is more like a junior engineer who can read and write every file in your repo than an autocomplete system that finishes your current line. What you need before starting ------------------------------- - Node.js 18+ (check with: node --version) - An Anthropic API key (get one at console.anthropic.com — the free tier is enough to start) - A terminal you're comfortable with (macOS Terminal, Windows Terminal, iTerm2 — any of them work) - A project to work on (new or existing — both work fine) Installation (one command) --------------------------- npm install -g @anthropic-ai/claude-code Then set your API key: export ANTHROPIC_API_KEY=sk-ant-your-key-here Add that line to your ~/.zshrc or ~/.bashrc so it persists across sessions. Verify it's working: claude --version Your first session ------------------- Navigate to a project folder and run: cd my-project claude Claude Code reads a summary of your codebase (file tree, package.json, README) and is ready. Try: > what does this project do? It will read your files and explain the codebase back to you — surprisingly useful for jumping into an unfamiliar repo. Now try something real: > add form validation to the signup form. use zod. show me what you're planning before you make changes. The "show me what you're planning" instruction is one of the most important habits to build. Claude Code will explain its approach in plain English before touching a single file. You catch bad assumptions early, before they become wrong diffs. The five commands you'll use every day ---------------------------------------- 1. claude — start an interactive session in the current directory 2. claude "your task here" — run a one-shot task without an interactive session 3. claude --continue — resume the last session (useful for multi-step work) 4. /clear — clear conversation history within a session (frees context for a new task) 5. /status — see which files have been read and which are in the agent's active context Understanding context windows ------------------------------- Claude Code's biggest practical limit is context. Each model has a window (roughly 200,000 tokens for Claude 3.5 Sonnet). For a large codebase, that fills fast. When context gets full: - Summaries replace full file contents - The agent may miss details from earlier in the session - Long sessions degrade in quality The fix: break big tasks into small sessions. "Add auth" is a bad session. "Add the Supabase client setup" → new session → "Add the sign-in page" → new session → "Add the protected route wrapper" is a good pattern. Skills: the feature most beginners miss ----------------------------------------- Skills are reusable context files (SKILL.md) that you install once and activate in every relevant session. They're the difference between starting from scratch every time and having Claude Code already know your tech stack. Install a skill: claude skills add nextjs-app-router-pro Now every time you open a Next.js project and ask Claude Code something, it already knows your patterns — App Router, Server Components, the works. No re-explaining. Browse 2,800+ skills at claudeskil.com/explore. The most common beginner mistakes ----------------------------------- 1. Tasks that are too vague. "Make this better" gets mediocre results. "Refactor this function to use early returns, add JSDoc, and add a unit test" gets great results. 2. Not reviewing diffs. Claude Code will tell you what it changed — read every diff before approving, especially on business logic. The agent is fast but not infallible. 3. Running in a directory with no context. Always run claude from inside the project folder. The agent reads the local file tree on start — if you run it from ~ it has almost nothing to work with. 4. Using it only for new code. The real power is on existing code: "explain this function", "why does this test fail", "what would break if I changed this type". Those tasks are hard for a human to do quickly and trivial for the agent. 5. Not setting ANTHROPIC_API_KEY in .zshrc. You'll have to re-export it every terminal session otherwise. A practical first week plan ----------------------------- Day 1: Install, run in one project, ask it to explain the codebase. Day 2: Ask it to fix a real (small) bug you've been putting off. Day 3: Install one skill that matches your main tech stack. Day 4: Use it to write a component or API route from scratch. Review the diff carefully. Day 5: Try the autonomous mode on a task you're comfortable with, let it run, see what it produces. By the end of the week you'll have a strong intuition for where the agent shines (refactoring, explanation, boilerplate) and where it needs supervision (complex business logic, auth, migrations). Where to go next ----------------- - The full docs: claudeskil.com/docs - Browse skills by your stack: claudeskil.com/categories - The Anthropic Claude Code docs: docs.anthropic.com/claude-code If you get stuck, the ClaudeSkill community has answers for most common setup issues. The agent itself is usually good at explaining why something went wrong — asking it "why did that fail?" is often faster than a Google search.