Home▸Claude Code guide
free guide · copy-ready examplesClaude 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.
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
claude3CLAUDE.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.
- ./CLAUDE.md at the project root: shared with the team, committed to the repository.
- ~/.claude/CLAUDE.md: your personal notes, used in every project.
- CLAUDE.md in a subfolder: extra rules for that part of the code.
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 /generated4Plan 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 1426Settings 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 list10Claude 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
- Be specific. “Add input validation to the signup form, with tests” beats “improve the form”.
- Give it a way to check its work: tests, a linter, a screenshot. It fixes far more when it can see what fails.
- Plan first for anything big, then let it execute.
- One task per conversation. Use
/clearbetween tasks so old context does not confuse the next one. - Put repeated instructions in CLAUDE.md or a slash command, not in every prompt.
- Use hooks and permissions for anything that must always happen (formatting) or must never happen (pushing to main).
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.
Practise for the Claude Certified Architect exam
40 free exam-style questions across all five domains, including Claude Code configuration and workflows.