Claude Code is not an editor — it’s a development agent that lives in your terminal. You tell it what to do, and it reads your code, plans, implements, executes commands, runs tests, and commits. This guide takes you from installation to a real workflow.
Prerequisites
- Node.js 18+ installed
- Anthropic Account (you can authenticate with your Claude account or API key)
- Git configured on your machine
- An existing project with git repository initialized
Step 1: Installation
npm install -g @anthropic-ai/claude-code
Verify the installation:
claude --version
Navigate to your project:
cd your-project
claude
The first time, Claude Code will ask you to authenticate. You can use your Anthropic account directly or configure an API key.
Step 2: Your First Session
When you run claude, you enter a conversational mode in the terminal. Try something simple first:
> Analyze the structure of this project and give me a summary of the
architecture, main dependencies, and any potential issues you notice.
Claude Code will:
- Read your file structure
- Analyze package.json, configurations, and key files
- Give you an organized summary of the project
This is useful to confirm that Claude Code understands your project before asking it to make changes.
Step 3: Create CLAUDE.md
The CLAUDE.md file in your project root is the most important piece for getting good results. It’s the equivalent of Cursor’s Rules or Copilot’s custom instructions.
Create CLAUDE.md:
# Project: Inventory Management API
## Stack
- Runtime: Node.js 20 with TypeScript
- Framework: Fastify
- ORM: Drizzle with PostgreSQL
- Auth: JWT with refresh tokens
- Testing: Vitest
- Linting: Biome
## Structure
src/
routes/ → Fastify routes organized by resource
services/ → Business logic
repositories/ → Data access with Drizzle
schemas/ → Validation with Zod
middleware/ → Auth, rate limiting, logging
utils/ → Shared helpers
## Conventions
- Repository pattern: routes → services → repositories
- Input validation always in routes layer with Zod
- Typed errors with custom classes (AppError, ValidationError, NotFoundError)
- Variable and function names in English
- Commits in English following Conventional Commits
- Tests alongside the file they test (file.test.ts)
## Commands
- `npm run dev` — development server
- `npm run test` — run all tests
- `npm run test:watch` — tests in watch mode
- `npm run lint` — linting with Biome
- `npm run db:migrate` — run migrations
- `npm run db:generate` — generate migrations from schema
## Important Notes
- Database is on Supabase, don't create destructive migrations without confirmation
- Public endpoints need rate limiting
- Never hardcode secrets, always use environment variables
Claude Code reads this file automatically when starting each session.
Step 4: Workflow for Implementing a Feature
Let’s see a complete flow for adding functionality:
> I need to add an endpoint to manage product categories.
Each category has: id, name, description (optional), slug
(generated from name), and timestamps.
I need:
1. Drizzle schema and migration
2. Repository with full CRUD
3. Service with business validation (unique name, unique slug)
4. Routes: GET /categories, GET /categories/:id, POST /categories,
PUT /categories/:id, DELETE /categories/:id
5. Tests for the service
Follow the existing patterns in the project.
Claude Code will:
- Read existing files to understand patterns (current routes, services, repositories)
- Plan the implementation
- Create each file following your project conventions
- Generate the database migration
- Write the tests
After implementing, you can ask it to run the tests:
> Run the tests to verify everything works
Claude Code executes npm run test (or the command you defined in CLAUDE.md), sees the results, and if there are failures, fixes them automatically.
Step 5: Essential Commands
Within a Claude Code session:
/compact— summarizes the current conversation to free up context window space. Essential for long sessions./clear— clears the conversation history/cost— shows how many tokens you’ve consumed in the session/help— lists all available commands
Permissions: Claude Code will ask for permission before executing terminal commands or writing files. You can configure more permissive permissions if you trust what it’s doing:
- Press
Allowfor an individual action - Press
Allow alwaysto allow that type of action in the future
Step 6: MCP (Model Context Protocol)
MCP allows you to connect Claude Code to external tools. Configure MCP servers in ~/.claude/claude_desktop_config.json or in .claude/settings.json of your project:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server"],
"env": {
"SUPABASE_URL": "your-url",
"SUPABASE_SERVICE_KEY": "your-key"
}
}
}
}
With MCP configured, Claude Code can query your database directly, read current schemas, and generate more accurate code.
Some useful MCP servers:
- Supabase — direct access to your database
- GitHub — create issues, PRs, review code
- Filesystem — expanded access to files outside the project
- Brave Search — search documentation and solutions on the web
Step 7: Debugging Workflow
Claude Code is excellent for debugging. Practical workflow:
> The POST /products endpoint is returning 500 when I send a
product with decimal price. Investigate the error, identify the
cause, and fix it. Then add a test that covers this case.
Claude Code will:
- Read the relevant route, service, and repository
- Identify where it breaks (probably type validation or parsing)
- Fix the bug
- Write a test that reproduces the case
- Run the tests to confirm it works
Step 8: Hooks for Automation
Hooks execute scripts before or after Claude Code actions. Configure in .claude/settings.json:
{
"hooks": {
"afterWrite": {
"command": "npx biome check --write {{file}}"
}
}
}
This runs the linter automatically after each file Claude Code writes, ensuring the format is always correct.
Other useful hooks:
afterWrite— lint, format, type validationbeforeCommit— run tests before committingafterCommit— notifications, deploy preview
Common Mistakes
Not creating CLAUDE.md. Without context, Claude Code generates generic code. With a good CLAUDE.md, it generates code that integrates naturally with your project.
Sessions too long without /compact. The context window fills up and response quality drops. Use /compact regularly in long sessions.
Not letting it run tests. Claude Code is most effective when it can iterate: write code → run tests → see errors → fix. If you don’t give it permission to execute commands, it loses this ability.
Asking for too much in a single prompt. For large features, break it into steps. “First create the schema and migration” → verify → “Now the repository and service” → verify → “Now the routes and tests”.
Result
Your workflow with Claude Code:
- You open the terminal in your project
- Claude Code reads CLAUDE.md and understands your context
- You describe the task in natural language
- It plans, implements, tests, and commits
- You review the changes and adjust if necessary
It’s like having a very fast junior developer available 24/7 who follows your conventions to the letter — as long as you give it a good CLAUDE.md.
Already using Claude Code? Share your CLAUDE.md and your workflows. 