Claude Code Guide: Setup, CLAUDE.md, Skills, MCP, CI

Claude Code is useful when the task lives in a repository, not in a chat box. It can search the project, edit files, run the actual build, inspect the diff, and keep working until a concrete verification passes.

That power is also the risk. Claude Code operates with your user account’s files, commands, network, and credentials unless you narrow them. A good setup is therefore less about a clever first prompt and more about three things: accurate project context, explicit permissions, and a short feedback loop.

This guide covers the current configuration surface. For the full command reference, use Anthropic’s official Claude Code documentation.

Install the native binary

Anthropic recommends the native installer. Node.js is not required for this path.

# macOS, Linux, or WSL
curl -fsSL https://claude.ai/install.sh | bash

# macOS or Linux through Homebrew
brew install --cask claude-code

# Windows through WinGet
winget install Anthropic.ClaudeCode

Native Windows is supported; WSL remains useful when the project depends on a Linux toolchain or sandboxed command execution. Exact OS and hardware requirements live in the installation guide.

Verify the binary, then start it inside a repository:

claude --version
cd /path/to/project
claude

The first launch opens the login flow. Subscription OAuth and API credentials serve different use cases; do not copy a personal OAuth token into automation or another product. Anthropic’s authentication policy requires API keys or a supported cloud provider for products and services built on Claude.

Start with a bounded task

“Improve this codebase” gives the agent no finish line. A better first task names the surface, constraints, and verification:

Fix the failing refresh-token test in packages/auth.
Do not change the public API or database schema.
First reproduce the failure, then make the smallest fix.
Run the focused test and the auth package test suite.
Stop and explain if the failure cannot be reproduced.

The working loop should stay visible:

1. reproduce or inspect the current state;
2. locate the relevant code;
3. state the likely cause;
4. make a minimal change;
5. run the cheapest meaningful check;
6. inspect git diff and summarize residual risk.

Do not ask for a commit until you have reviewed the diff. The agent can write a clean commit message for a bad change just as easily as for a good one.

Give Claude the context it cannot infer

CLAUDE.md: always-on project facts

CLAUDE.md is for information useful in almost every session:

# Project guide

## Verified commands
- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm --filter @acme/auth test`
- Full check: `pnpm lint && pnpm test && pnpm build`

## Constraints
- Never edit generated files under `src/generated/`.
- Database changes require a migration in `db/migrations/`.
- API errors use `{ code, message, requestId }`.

## Architecture
- `apps/api/` owns HTTP transport.
- `packages/domain/` has no framework dependencies.

The official memory guide recommends keeping CLAUDE.md under 200 lines. That is a context budget, not a formatting target. Remove rules the agent can discover from configuration, and replace vague advice such as “write clean code” with commands or constraints that can be checked.

Claude loads user and project instruction files from the start directory upward. It discovers nested instructions when it works inside those subdirectories. Run /memory to see what is actually loaded instead of guessing.

For a deeper explanation of why small, relevant instruction sets work better, see the context engineering guide.

Rules and local settings

Use .claude/rules/ for path-specific instructions, such as different conventions for mobile and backend code. Use .claude/settings.json for team configuration committed to Git, and .claude/settings.local.json for personal project overrides that should not be committed.

~/.claude.json is not the global settings file. Global permissions, hooks, and environment values belong in ~/.claude/settings.json. This distinction explains many “Claude ignored my settings” bugs; /status shows the active sources.

Treat permissions as policy, not click fatigue

Claude Code uses allow, ask, and deny rules. Read-only operations usually run without a prompt; file edits and shell commands follow the active permission mode and rules. You can inspect the merged result with /permissions.

A conservative project file might start here:

{
  "permissions": {
    "allow": [
      "Bash(pnpm test *)",
      "Bash(pnpm lint *)",
      "Bash(git diff *)",
      "Bash(git status *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(curl *)"
    ]
  }
}

Adjust patterns to the real commands and paths in your repository. Permission prefix rules are not a shell security parser: an equivalent command may use another binary or syntax. Use a PreToolUse hook, OS sandbox, restricted container, and managed settings when a rule must hold even if the command is expressed differently. Anthropic documents the precedence and matcher behavior in the permissions reference.

Three practical rules:

• never expose production credentials to a coding session that does not need them;
• never allow unattended deploy or push commands just to remove prompts;
• review a project-owned .mcp.json before trusting it, because an MCP server is executable or network-connected code with its own permissions.

Choose the right extension mechanism

Claude Code has several features that look interchangeable. They are not.

Anthropic’s feature overview is the best source when two mechanisms seem to overlap.

Skills: procedures that should not live in CLAUDE.md

Project skills live at .claude/skills/<name>/SKILL.md:

---
name: verify-change
description: Verify a code change before it is committed.
disable-model-invocation: true
---

1. Read the current diff.
2. Run the narrowest relevant tests.
3. Run the repository lint command.
4. Report failures and unverified surfaces. Do not commit.

Invoke it as /verify-change. Claude can also load model-invocable skills when their description matches the task. The older .claude/commands/ format still works, but skills support directories, references, scripts, and clearer invocation controls. The skills documentation covers the current frontmatter.

For advanced skill and subagent patterns, continue with Claude Code Skills and Agents.

Subagents: isolate context, not responsibility

A custom subagent is a Markdown file in .claude/agents/:

---
name: migration-reviewer
description: Reviews database migrations without editing files.
tools: Read, Grep, Glob, Bash
---

Inspect the migration and the schema it changes.
Run read-only validation commands only.
Return findings ordered by severity with file and line references.

Subagents are useful when a worker must read many files but the main conversation only needs the conclusion. They start with isolated context, so the delegation must contain the task and constraints. Do not assume they inherit the entire conversation. The current subagent reference documents scope, tools, memory, skills, and worktree isolation.

MCP: connect tools without pasting data into chat

MCP servers can expose issue trackers, observability, databases, or your own internal API. Add a team-shared HTTP server at project scope:

claude mcp add \
  --transport http \
  --scope project \
  issue-tracker https://mcp.example.com/mcp

Project scope writes .mcp.json; local and user scopes live in ~/.claude.json. Reference credentials through environment variables instead of committing them:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_API_URL}/mcp",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_TOKEN}"
      }
    }
  }
}

Use /mcp to inspect connections and complete OAuth. The official MCP guide explains scope precedence, transport options, environment expansion, and project trust. If you are new to the protocol itself, read MCP Servers Explained first.

Hooks: enforce what prompts cannot guarantee

A sentence in CLAUDE.md can be misunderstood or ignored. A hook runs at a lifecycle event such as tool use, stop, prompt submission, or compaction. Use hooks for mechanical checks: blocking protected paths, running a formatter after edits, or requiring a test before completion.

Keep hooks fast and deterministic. They run inside the developer workflow, inherit an environment, and can become another command-execution surface. Review them like code and configure them under the hooks key in a settings file, not in a fictional .claude/hooks.json. See the hooks reference.

Isolate parallel work with Git worktrees

Multiple agents editing one checkout will eventually collide. Start a separate session in its own worktree:

claude --worktree feature-auth

Claude creates the worktree and branch under .claude/worktrees/ by default. Run a normal trusted session in the repository once before using --worktree, and keep the worktree directory out of version control. The worktree guide covers base refs, cleanup, subagent isolation, and copying selected ignored files.

Worktrees isolate files, not external side effects. Two sessions can still hit the same development database, queue, cloud account, or port. Give each one separate test resources where that matters.

Use checkpoints for local undo, Git for history

Press Esc twice or run /rewind to restore code, conversation, or both to an earlier checkpoint. This is useful for trying another implementation without restarting the session.

Checkpointing only tracks direct file edits made by Claude. It does not track files changed by Bash commands, manual edits, or other sessions. Anthropic explicitly says it is not a replacement for version control in the checkpointing guide.

Before a risky task:

git status --short
git diff --check
git switch -c agent/task-name

Do not use git checkout . or git reset --hard as generic recovery advice: both can destroy unrelated uncommitted work.

Run Claude Code in CI without disabling the guardrails

Print mode makes Claude Code scriptable:

claude -p "Review the diff for security regressions. Do not edit files." \
  --output-format json \
  --permission-mode dontAsk

dontAsk denies actions outside explicit allow rules and the built-in read-only set. For a job that must run tests, add only the required tool or command patterns. Use a restricted CI identity, no production secrets, a timeout, a spend limit, and a clean checkout.

JSON output includes structured result and usage metadata; --json-schema can enforce a machine-readable response. The headless-mode guide documents output formats, allowed tools, permission modes, and stdin limits.

Avoid --dangerously-skip-permissions in CI. It removes the exact control that matters most in an unattended environment.

Data and cost: check policy, do not copy an old price table

Claude Code sends the context required for model processing. Consumer users choose in privacy settings whether their data may be used for model improvement. Under commercial terms, Anthropic says it does not train on code or prompts unless the customer has explicitly opted into a program that provides data. Retention and local transcript behavior vary by account type; verify the current data-usage policy before using private repositories.

Pricing and plan limits change. Use the live pricing page for subscriptions and Anthropic’s cost guide for API tracking. In API mode, /cost reports the current session; non-interactive JSON output includes total_cost_usd. Pilot on representative repositories before setting a team budget.

A setup that stays maintainable

1. Install the native binary and authenticate with the correct account type.
2. Add a short CLAUDE.md containing verified commands and non-obvious constraints.
3. Commit conservative project permissions; keep personal overrides local.
4. Move repeatable procedures into skills and enforcement into hooks.
5. Add MCP servers one at a time, with least-privilege credentials and a reviewed config.
6. Use worktrees for parallel edits and separate external test resources.
7. Require tests, diff review, and a human decision before commit, push, or deploy.

Claude Code works best when it is easy to prove what it changed. The durable advantage is not a longer prompt. It is a repository where instructions are accurate, tools are bounded, and verification is cheaper than guessing.