Home▸Claude Code guide

free guide · copy-ready examples

Claude Code, the practical guide

Everything you need to use Claude Code well: setup, CLAUDE.md, plan mode, slash commands, permissions, hooks, subagents, MCP and CI/CD. Short explanations, real examples.

11 partsBy Samir KumarUpdated

1What Claude Code is

Claude Code is Anthropic’s coding agent. You run it in your terminal (it also works inside VS Code, JetBrains and the Claude desktop app). It reads your project, edits files, runs commands and tests, and explains what it is doing. It asks before it changes files or runs commands, unless you allow them.

Think of it as a teammate who can read the whole codebase in seconds: you describe the goal, it plans, writes the code, runs the tests and fixes what fails.

2Install and start

You need Node.js 18 or newer. Install once, then start it inside any project folder. The first run asks you to sign in with your Claude account or an API key.

npm install -g @anthropic-ai/claude-code
cd my-project
claude

3CLAUDE.md: the project memory

CLAUDE.md is a plain text file that Claude Code reads at the start of every session. Put in it what a new teammate needs: how to build and test, the coding rules, and where things live.

Run /init once and Claude writes a first CLAUDE.md from your codebase. Keep it short and specific: commands, conventions and warnings.

# CLAUDE.md
## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint

## Rules
- TypeScript strict mode, no "any"
- Every new function gets a unit test
- Never edit files in /generated

4Plan mode for big changes

Press Shift+Tab to switch modes: normal (asks before each change), auto-accept edits, and plan mode. In plan mode Claude reads the code and writes a plan, but changes nothing until you approve it. Use it before refactors, migrations and anything that touches many files.

5Slash commands, built in and your own

Useful built-in commands: /init (create CLAUDE.md), /clear (start fresh between tasks), /compact (shrink a long conversation), /model (pick the model), /permissions (see what is allowed). Make your own by saving a Markdown file in .claude/commands/. The file name becomes the command, and $ARGUMENTS is replaced with what you type after it.

# .claude/commands/fix-issue.md
Read GitHub issue $ARGUMENTS.
Find the cause, write a failing test first, fix it,
run the full test suite and summarise the change.

# then, inside Claude Code:
/fix-issue 142

6Settings and permissions

Settings live in JSON files with layers: ~/.claude/settings.json (you, every project), .claude/settings.json (the project, shared) and .claude/settings.local.json (you, this project, not committed). Allow the safe commands you run all day, and deny the dangerous ones and secret files.

{
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Bash(npm run lint)"],
    "deny": ["Bash(rm -rf:*)", "Bash(git push:*)", "Read(./.env)"]
  }
}

7Hooks: rules that always run

Instructions in CLAUDE.md are guidance; hooks are guaranteed. A hook runs your own command on an event, for example after every file edit (PostToolUse) or before a tool runs (PreToolUse, which can block the action). Other events include UserPromptSubmit, Stop and SessionStart. This one formats every file Claude edits:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npx prettier --write ." }]
      }
    ]
  }
}

8Subagents for focused work

A subagent is a helper with its own instructions, its own tools and its own context window, so long searches do not fill your main conversation. Save it as a Markdown file in .claude/agents/; Claude uses it when the task matches its description.

---
name: test-runner
description: Runs the tests after code changes and fixes failures
tools: Read, Edit, Bash
---
Run the test suite. For each failure, find the cause,
fix the code (not the test) and run the suite again.

9MCP: connect your tools

The Model Context Protocol (MCP) connects Claude Code to tools and data: GitHub, a database, your ticket system, a browser. Add a server with one command. With --scope project it is saved in .mcp.json, so the whole team gets it.

claude mcp add my-server -- npx -y my-mcp-server
claude mcp add --scope project tickets -- npx -y tickets-mcp
claude mcp list

10Claude Code in scripts and CI/CD

Run Claude Code without the interactive screen using -p (print mode). Ask for JSON output and your script or pipeline can read the result: review a pull request, write release notes, generate tests. Anthropic also publishes a GitHub Action for running it on pull requests.

claude -p "Review the staged changes for bugs and security issues" --output-format json

git diff main | claude -p "Summarise this change for the release notes"

11Tips that make the biggest difference

Questions people ask

What is Claude Code?

Claude Code is Anthropic's coding agent. It runs in your terminal and in editors like VS Code, reads your project, edits files, runs commands and tests, and asks before making changes unless you allow them.

How do I install Claude Code?

Install Node.js 18 or newer, run npm install -g @anthropic-ai/claude-code, then type claude inside your project folder and sign in with your Claude account or an API key.

What is CLAUDE.md?

CLAUDE.md is a text file Claude Code reads at the start of every session. It holds the build and test commands, coding rules and project notes. The project file is shared with the team; ~/.claude/CLAUDE.md holds personal notes for every project.

What is the difference between CLAUDE.md and hooks?

CLAUDE.md is guidance the model reads and usually follows. Hooks are commands that always run on events, such as formatting a file after every edit or blocking a risky command, so they are used for rules that must never be skipped.

Can Claude Code run in CI/CD?

Yes. Run it non-interactively with claude -p "your prompt" and --output-format json so your pipeline can read the result, for example to review pull requests or generate tests.

preparing for the certification?

Practise for the Claude Certified Architect exam

40 free exam-style questions across all five domains, including Claude Code configuration and workflows.

Practice questions ▸The full exam prep course