U2xAI
…
Skip to content
Topics
On this page

Claude Code Tutorial

Claude Code is an agentic coding tool from Anthropic that runs in the terminal and works directly inside a software repository. It reads files, runs shell commands, edits code and explains its reasoning, and it asks for permission before actions that change the project.

  • Session: An interactive conversation started with the claude command inside a project directory.
  • Tools: Built-in abilities to read and search files, edit code and run shell commands such as tests.
  • Instructions: A CLAUDE.md file with project rules that Claude Code reads at the start of each session.
  • Permissions: Prompts and rules that decide which edits and commands run with or without approval.
  • Extensions: Slash commands, custom commands and MCP servers that add workflows and external tools.
How a Claude Code session worksA developer sends a request to Claude Code, which runs an agent loop. The loop loads project instructions from CLAUDE.md and can call tools on MCP servers, shown with dashed lines. Every edit or shell command passes a permission check that allows, asks or denies it before it reaches the repository's files and tests, and results return to the loop. The flow is illustrative.DeveloperrequestClaude Codeagent loopPermissionsallow, ask, denyRepositoryfiles, testsCLAUDE.mdMCP servers
How a Claude Code session works

For example, an engineer asks Claude Code to find why the checkout service returns 5xx errors after release v2.41.0, and it reads the incident log, runs the failing check and proposes a configuration fix.

Frameworks such as CrewAI build the incident triage agent from code, as the CrewAI tutorial shows. Claude Code is different, because it is a finished AI agent for developers, so the engineering work consists of directing it precisely and configuring safe limits, not implementing an agent loop.

Prerequisites

  • Runtime: A recent Node.js release, which the npm installation method requires.
  • Account: A Claude subscription or an Anthropic Console account with API access.
  • Repository: A Git repository for experimentation; the sample checkout service below is sufficient.
  • Background: Familiarity with the terminal, Git and the idea of human-in-the-loop approval.

Setup

One Claude Code install method uses npm: install the package globally, then confirm the installation.

Bash
npm install -g @anthropic-ai/claude-code
claude --version

A native installer script is also documented as an alternative that does not depend on Node.js.

Bash
curl -fsSL https://claude.ai/install.sh | bash

Step 1: Create a Sample Service with a Failing Check

The sample repository reproduces the incident: release v2.41.0 lowered the payments client timeout below the p99 latency of the payments API. Save this as check_timeout.py in a new Git repository with a short logs/incident.log containing the 502 timeout lines.

Python
# check_timeout.py: the failing check in the sample checkout service.
PAYMENTS_P99_MS = 4200  # p99 latency of payments-api, from the dashboard

CONFIG = {
    "v2.40.3": {"payments_timeout_ms": 10000, "retries": 2},
    "v2.41.0": {"payments_timeout_ms": 3000, "retries": 1},
}

def timeout_covers_p99(cfg):
    return cfg["payments_timeout_ms"] > PAYMENTS_P99_MS

for version, cfg in CONFIG.items():
    status = "PASS" if timeout_covers_p99(cfg) else "FAIL"
    print(f"{version}: timeout {cfg['payments_timeout_ms']} ms vs p99 {PAYMENTS_P99_MS} ms -> {status}")

Output:

Example
v2.40.3: timeout 10000 ms vs p99 4200 ms -> PASS
v2.41.0: timeout 3000 ms vs p99 4200 ms -> FAIL

Step 2: Start a Claude Code Session

Start Claude Code from the repository root, so its file access is scoped to the project directory. The first run opens an authentication flow for the account.

Bash
cd checkout-service
claude
# or answer one question non-interactively and exit
claude -p "Summarise logs/incident.log in three bullets"
# continue the most recent conversation in this directory
claude -c

Step 3: Investigate the 5xx Incident

Describe the goal, the evidence and the limits in one request. Plan mode is a good start for an investigation, because Claude Code then reads and proposes without editing files.

Example
The checkout service returns 502 errors since release v2.41.0.
Read logs/incident.log, run python check_timeout.py, and find the likely cause.
Propose a fix and a test. Do not edit files yet and do not run any deploy or rollback.
  • Evidence: Claude Code reads the log, runs the check and compares the two configurations before it presents a conclusion.
  • Constraints: The request states explicitly what must not happen, which complements the permission rules configured in Step 5.
  • Iteration: Follow-up requests refine the investigation, for example by asking for the exact commit that changed the timeout or for an additional regression test.
  • Verification: The proposed explanation should be checked against the dashboard and the deploy history, because the model can misread incomplete evidence.

Step 4: Add Project Instructions in CLAUDE.md

Run /init to generate a starting CLAUDE.md, then keep it short and specific. Claude Code loads this file at the start of every session in the repository.

Bash
cat > CLAUDE.md <<'EOF'
# checkout-service
- Run checks with: python check_timeout.py
- Payments client settings live in CONFIG; never lower a timeout below the p99 latency.
- Never run deploy or rollback scripts. A person approves and performs any rollback.
EOF
  • Specificity: Exact commands and firm rules are followed more reliably than general advice about code quality.
  • Maintenance: The file is committed to the repository, so changes to the instructions are reviewed like changes to code.

Step 5: Set Claude Code Permissions and Modes

By default, Claude Code asks before editing a file or running a command that changes something, and each prompt can be approved once or for the rest of the session. Rules in .claude/settings.json make these decisions permanent for the project.

Bash
mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": ["Bash(python check_timeout.py)"],
    "deny": ["Bash(./scripts/rollback.sh:*)", "Bash(kubectl rollout undo:*)"]
  }
}
EOF
  • Default: Claude Code requests confirmation for edits and commands that are not already allowed by a rule.
  • Accept-edits: File modifications are applied without a prompt, while shell commands still follow the configured rules.
  • Planning: Plan mode restricts Claude Code to analysis and a proposed plan, without modifying any files.
  • Denial: Blocked commands never execute, which keeps the production rollback decision with the on-call engineer.

Step 6: Use Slash Commands

Slash commands control the session itself, such as its context, permissions and connected servers. Custom commands are Markdown files in .claude/commands/, so triage.md becomes /triage.

Example
/help         list available commands
/init         create a CLAUDE.md for the repository
/permissions  view and edit permission rules
/mcp          show connected MCP servers and their status
/compact      summarise the conversation to reclaim context
/clear        start a fresh conversation

Step 7: Connect Claude Code MCP Servers

MCP (Model Context Protocol) servers give Claude Code external tools, such as a logs service or an issue tracker. The server below is illustrative; a custom one can be written by following build an MCP server in Python.

Bash
# a remote MCP server over HTTP (illustrative URL)
claude mcp add --transport http logs https://logs.internal.example/mcp
# a local MCP server started as a process
claude mcp add metrics -- python metrics_server.py
claude mcp list
  • Scope: A server can be registered for one user or shared with the whole team through a project configuration file.
  • Least privilege: Read-only servers for logs and metrics suit incident investigation, while servers that can write data deserve separate approval rules.

Output

Illustrative final answer from the Step 3 request (the wording varies between runs):

Example
Likely cause: v2.41.0 set payments_timeout_ms to 3000, below the payments-api p99 of 4200 ms.
Evidence: logs/incident.log shows 502 "timeout after 3000 ms"; check_timeout.py fails for v2.41.0.
Proposed fix: restore payments_timeout_ms to 10000 and add a check that fails below p99.
Rollback: not run. A production rollback needs approval from the on-call engineer.

Common Errors

  • command not found: claude: The global npm directory is not on PATH, so add it to the shell profile or use the native installer.
  • EACCES: permission denied during install: The global npm directory is owned by root, so change the npm prefix to a user directory instead of using sudo.
  • Login or API key rejected: The session uses a missing or revoked credential, so run /login again.
  • MCP server shows as failed in /mcp: The server command or URL is wrong, so run it manually and check the output.
  • Repeated permission prompts: A routine command is not allowed yet, so add an exact allow rule instead of switching to a mode that bypasses every prompt, which would also remove the protection for destructive commands.

Next Steps

Quick Quiz

Pick an answer to check yourself. Nothing is saved.

Question 1 / 3

  1. 1. Which file gives Claude Code standing instructions for a repository?

Frequently Asked Questions

What is Claude Code used for?

Claude Code is used for software engineering tasks inside a repository, such as explaining unfamiliar code, fixing failing tests, investigating errors and preparing commits. It reads files and runs commands in the terminal, so it works with the project's own tools.

Is Claude Code the same as the Claude Agent SDK?

No. Claude Code is a ready-made coding agent that a developer uses interactively in the terminal. The Claude Agent SDK is a library for building custom agents in code with a similar agent loop and tool handling.

Can Claude Code change files without asking?

By default it asks for permission before editing files or running commands that change something. Permission rules and modes can allow routine actions automatically, and deny rules can block commands such as deployment or rollback scripts completely.

What should a Claude Code CLAUDE.md file contain?

It should hold the facts a new engineer needs on the first day: build and test commands, code style rules, important directories and actions that are not allowed. Short, specific instructions work better than long general guidance.

Does Claude Code work with an existing editor?

Claude Code runs in any terminal, including the terminal inside an editor. Integrations for common editors are also available, and changes appear in the working tree like edits made by a person.

Related Articles