DEV Community

Alvarito1983
Alvarito1983

Posted on

Claude Code: The Complete Guide from Zero to Autonomous Development

#ai #claude #cli #tutorial

Claude Code is not a code editor plugin. It's not a chatbot you paste code into. It's an autonomous agent that lives in your terminal, reads your entire codebase, plans multi-step work, executes it, checks the results, and fixes what breaks.

This guide covers everything: what it is, how it thinks, how to set it up, and how to use it at a level most developers haven't reached yet.

Table of contents

  1. What Claude Code actually is
  2. How it works under the hood
  3. Installation and setup
  4. The CLAUDE.md file — your most important tool
  5. Writing prompts that work
  6. Phase-based development
  7. Slash commands and shortcuts
  8. What Claude Code can and cannot do
  9. Workflow patterns that scale
  10. Common mistakes and how to avoid them

1. What Claude Code actually is

Most AI coding tools work like this: you write a prompt, you get code back, you copy it somewhere.

Claude Code works differently. It has direct access to:

  • Your file system (read and write)
  • Your terminal (execute bash commands)
  • Your project structure (it reads everything before acting)

When you give it a task, it doesn't guess at your codebase. It reads the relevant files first, builds a mental model of what exists, then acts. It can create files, edit files, run builds, check logs, install packages, and verify its own output.

The mental model shift: stop thinking of it as a code generator. Think of it as a developer you can delegate to.

2. How it thinks

Claude Code follows a loop:

1. Read context (files, structure, your CLAUDE.md)
2. Plan the approach
3. Execute step by step
4. Verify output
5. Fix problems it finds
6. Report back
Enter fullscreen mode Exit fullscreen mode

This loop runs autonomously. It doesn't wait for you to approve each file. It moves forward, and if something fails (a build error, a missing dependency, a broken import), it diagnoses and fixes it.

The implication: your job is to set context well at the start, then review the result at the end. Not to supervise every step.

3. Installation and setup

Claude Code runs as a CLI tool. Install it via npm:

npm install -g @anthropic-ai/claude-code
Enter fullscreen mode Exit fullscreen mode

Authenticate with your Anthropic account:

claude
Enter fullscreen mode Exit fullscreen mode

This opens a browser for OAuth. Once authenticated, you're ready.

To start a session in your project:

cd your-project
claude
Enter fullscreen mode Exit fullscreen mode

That's it. Claude Code will read your project structure on first use.

Platform notes:

  • macOS/Linux: works natively
  • Windows: use PowerShell or CMD. Note that && chaining doesn't work in PowerShell — Claude Code knows this and uses separate commands automatically

4. The CLAUDE.md file — your most important tool

This is the single highest-leverage thing you can do. A CLAUDE.md file at the root of your project is read automatically at the start of every session. It's your persistent context.

Without it: Claude Code reads your code and makes reasonable guesses about conventions, stack, and intent.

With it: Claude Code knows exactly what you're building, how it's structured, what decisions you've already made, and what rules to follow.

What to put in CLAUDE.md 

# Project name and purpose
Brief description of what this is and what it does.

## Tech stack
- Framework: React 18 + Vite
- Backend: Node.js + Express
- Styling: CSS custom properties (no Tailwind)
- Icons: Lucide React
- Auth: JWT

## Architecture
Explain the key structural decisions. What talks to what.
Where the main files live. How modules are organized.

## Conventions
- One component per file
- No inline styles — use CSS variables
- All API routes under /api/
- Error responses always { error: string }

## Design system (if applicable)
Color tokens, spacing rules, typography scale.
The more specific, the better the UI output.

## Infrastructure
- Dev path: /your/local/path
- Production: where it runs
- Ports: which service runs where
- CI/CD: how deploys work

## Known issues / current state
What's in progress. What's broken. What to avoid.
Enter fullscreen mode Exit fullscreen mode

Initialize it automatically 

claude
/init
Enter fullscreen mode Exit fullscreen mode

This generates a starter CLAUDE.md from your existing project. Edit and expand it — the generated version is a starting point, not a finished document.

CLAUDE.md at multiple levels

You can have CLAUDE.md files at different levels:

your-project/
  CLAUDE.md          ← root: ecosystem-wide context
  service-a/
    CLAUDE.md        ← service-specific context
  service-b/
    CLAUDE.md        ← service-specific context
Enter fullscreen mode Exit fullscreen mode

Claude Code reads both — root first, then the most specific one for the files it's working in.

5. Writing prompts that work

The quality of Claude Code's output is directly proportional to the quality of your prompt. Here's the difference:

Weak prompt 

Add authentication to the app
Enter fullscreen mode Exit fullscreen mode

This works, but the result will be generic. Claude Code will make decisions you'd probably make differently.

Strong prompt 

Add JWT authentication to the Express backend following the existing 
pattern in src/routes/users.js. 

The middleware should:
- Verify the token from the Authorization: Bearer header
- Attach req.user with { id, username, role }
- Return 401 { error: 'Unauthorized' } if invalid
- Skip auth for POST /api/auth/login and GET /health

Add the middleware to all routes in src/routes/ except auth.js.
Do not change the existing token generation logic.
Enter fullscreen mode Exit fullscreen mode

Same task. Completely different output.

Key principles

Reference specific files. "Follow the pattern in src/services/docker.js" is worth more than "follow existing patterns".

State what not to do. "Do not modify the database schema" or "do not change the auth flow" prevents unwanted side effects.

Specify the output format. If you want a specific response structure, API contract, or file layout — say so explicitly.

Ask for analysis first. For complex tasks, start with: "Read these files and tell me what you find before writing any code". This catches misunderstandings before they become wrong code.

6. Phase-based development

For large tasks, break the work into numbered phases. This is the pattern that makes Claude Code genuinely powerful for complex projects.

## PHASE 1 — Analysis (no code yet)
Read and understand:
- src/backend/server.js
- src/backend/src/routes/ (all files)
- src/frontend/src/App.jsx

Identify and report:
1. How authentication currently works
2. What routes exist and their patterns
3. Any inconsistencies or potential conflicts

Do not write any code until you've reported your findings.

## PHASE 2 — Backend changes
[detailed instructions]

## PHASE 3 — Frontend changes  
[detailed instructions]

## PHASE 4 — Tests and verification
[what to check]
Enter fullscreen mode Exit fullscreen mode

Why this works:

  • Phase 1 forces analysis before action. You catch wrong assumptions early.
  • Numbered phases give Claude Code a clear structure to follow.
  • You can pause between phases to review.
  • If something goes wrong in Phase 2, Phases 3 and 4 haven't been touched.

7. Slash commands and shortcuts

Claude Code has built-in commands you can use mid-session:

/init          # Generate CLAUDE.md from your project
/clear         # Clear conversation context (start fresh)
/compact       # Summarize conversation to save context space
/cost          # Show token usage for the current session
/help          # List all available commands
Enter fullscreen mode Exit fullscreen mode

The Ctrl+C behavior: pressing once interrupts the current action. Claude Code stops, tells you what it was doing, and waits. You can then redirect or continue.

The --print flag — useful for scripting:

claude --print "What does this function do?" < src/utils/parser.js
Enter fullscreen mode Exit fullscreen mode

Outputs directly to stdout, no interactive session needed.

8. What Claude Code can and cannot do

It can

  • Read and write any file in your project
  • Run bash commands (builds, tests, installs, docker commands)
  • Fix its own errors when a build fails
  • Work across multiple files and services simultaneously
  • Remember context within a session
  • Follow complex multi-step instructions

It cannot

  • Remember anything between sessions (CLAUDE.md solves this)
  • Access the internet during a task
  • Start system processes it doesn't have permission for
  • Make git commits or pushes (by design — you stay in control)
  • Replace code review (it makes mistakes, especially on subtle logic)

The git boundary

Claude Code deliberately doesn't push to git. This is the right call. Every commit should be a human decision. Claude Code generates the code; you review, commit, and push. This keeps you in the loop on what's actually going into your repository.

9. Workflow patterns that scale

The morning brief

Start each session by telling Claude Code the current state:

Context for this session:
- We're working on the authentication module
- Last session we completed the backend JWT middleware
- Today's goal: add the login/logout UI components
- Known issue: the token refresh endpoint returns 500 intermittently
- Do not touch src/backend/auth.js — it's being refactored separately
Enter fullscreen mode Exit fullscreen mode

This takes 2 minutes and saves a lot of confusion.

The reference pattern

When building something new, always point to the closest existing thing:

Create a new NotificationsPanel component.
Follow the exact structure of src/components/SettingsPanel.jsx —
same file layout, same CSS variable usage, same props pattern.
Only change the content and specific functionality.
Enter fullscreen mode Exit fullscreen mode

This keeps your codebase consistent even as it grows.

The verification step

Always end complex tasks with an explicit verification instruction:

After completing the changes:
1. Run the build and confirm it succeeds
2. Check that these endpoints respond correctly: /health, /api/auth/login
3. Report any warnings in the build output
Enter fullscreen mode Exit fullscreen mode

Claude Code will do this and tell you what it found.

Splitting sessions for large projects

Context has limits. For very large tasks, split into sessions:

  • Session 1: Backend changes → verify → commit
  • Session 2: Frontend changes → verify → commit
  • Session 3: Integration and testing → verify → commit

Each session starts fresh but CLAUDE.md provides continuity.

10. Common mistakes and how to avoid them

Vague task descriptions
The vaguer the prompt, the more decisions Claude Code makes for you. Those decisions may not match your intent. Be specific.

Skipping the analysis phase
Jumping straight to "build this" on complex tasks leads to code that doesn't fit your existing patterns. Always read first.

Not updating CLAUDE.md
Every architectural decision you make should go into CLAUDE.md. If you decide to use a specific error handling pattern, write it down. Future sessions will inherit that decision.

Letting it run too long without review
For tasks over 15-20 minutes, check in. Ask it to report what it's done so far. This catches drift early.

Not using explicit file references
Generic instructions produce generic code. Specific file references produce code that fits your project.

Treating it as infallible
It makes mistakes. Especially on:

  • Complex business logic
  • Security-sensitive code
  • Subtle state management bugs
  • Anything requiring domain knowledge you haven't documented

Review the output. Always.

Summary

Claude Code is most powerful when you treat it as a skilled developer who:

  • Needs good context to do good work
  • Benefits from explicit instructions over implicit expectations
  • Should be given clear scope and boundaries
  • Needs review on their output, not rubber-stamping

The developers who get the most out of it aren't the ones who give it the least guidance. They're the ones who invest in their CLAUDE.md, structure their prompts carefully, and review the output critically.

The ceiling on what a solo developer can ship has moved. But the floor — the minimum investment in clear thinking and good specification — hasn't.

If this was useful, I write about self-hosted tools, Docker, and AI-assisted development.

  • GitHub: github.com/Alvarito1983
  • Docker Hub: hub.docker.com/u/afraguas1983

claudecode #ai #programming #webdev #docker #devtools #opensource #productivity #softwaredevelopment

Top comments (0)