How to Use Claude Code: Step-by-Step Tutorial

Introduction: What Is Claude Code?

If you've ever tried to bring an AI coding assistant into your day-to-day terminal workflow, you've probably hit the same wall: you know what you want done, but you're not sure how to set things up safely, avoid constant interruptions, and still trust what's being changed.

In this guide, you'll learn how to use Claude Code in a practical, repeatable way as a command line tool for real development work. You'll start with a safe install, move into read-only planning, then graduate to sandboxed edits and test runs. From there, you'll build reusable Skills, connect external tools with MCP, and automate guardrails with Hooks—all without losing control of your codebase.

This walkthrough is for developers (solo or on a team) who are comfortable in a terminal and want an AI for coding workflow that is safe enough for real codebases. If you are setting this up in an org, it also helps to know where credentials live, for example the encrypted macOS Keychain on macOS.

Let's start by getting access set up so your first session is smooth.

Gather Access, Install Claude Code, and Sign In

Before you start delegating real dev work to Claude Code, you need a clean install and an authentication method that matches how you plan to use it.

Follow these steps to install Claude Code and confirm you can authenticate:

1. Confirm you have Node.js 18+ installed by running node -v and checking that it reports v18 or higher.
2. Install Claude Code globally with: npm install -g @anthropic-ai/claude-code.
3. Start an interactive session by running claude, then sign in by entering /login and completing the browser-based flow for your Claude.ai (recommended) or Console account.
4. If you prefer key-based auth for scripts or non-interactive usage, set ANTHROPIC_API_KEY in your shell environment. If your organization uses cloud providers, confirm whether you should authenticate through Bedrock/Vertex instead so you don't set up the wrong credential type.

A few things to watch out for:

• If you are on WSL and the installer fails due to OS detection or a Windows npm/Node mismatch, use the WSL fix approach (including the documented --force --no-os-check install option) and avoid using sudo, which the docs explicitly warn against.
• If you are signing in with a Free/Pro/Max account, review your data controls: since Aug 28 2025, consumer users can choose whether coding sessions may be used to improve future Claude models.

After this step, claude should launch without errors, and after /login you should be able to send a short prompt and receive a response.

Key Takeaways:

• You installed Claude Code and established a working sign-in method for your environment.
• You must get the credential path right (interactive /login vs API key vs managed provider) before you try real workflows.
• You should watch for WSL/Node path issues and confirm your account's data-sharing setting so you are not surprised later.

Open a Project and Plan Safely: AI Coding Assistant in Read-Only Mode

Before you let Claude Code change files or run commands, you want it to understand your codebase and propose a concrete approach in a mode that prevents execution.

Follow these steps to open your repo and force a safe planning loop:

1. Navigate to your project root by running cd /path/to/your-repo (pick the folder that contains your package.json, pyproject.toml, or go.mod).

2. Start Claude Code from that directory by running claude, then confirm you land in an interactive prompt tied to this repo.

3. Switch into Plan Mode by typing /plan (or toggle modes with Shift+Tab / Alt+M).

4. (Optional) If you want plan mode as the default for every session, create a .claude/settings.json file using the official settings options:

   • Add "defaultMode": "plan" so new sessions open in planning by default.
   • Add a permissions.deny list for files you never want Claude Code to read (.env, secrets/, credential files).

5. Verify your active config by running claude config list as recommended in the config guidance, then confirm your settings are applied.

6. Ask for a plan that's specific enough to approve: "In plan mode, outline the smallest set of changes to fix X, list the exact files you'll touch, and include the commands you'd run to validate it." Confirm Claude only proposes steps (because plan mode is no execution).

A few things to watch out for:

• Keep your first prompt narrow: a plan that names files, functions, and commands is much easier to approve than a high-level rewrite.
• If you're tempted to speed up after you like the plan, treat acceptEdits as an intentional "implementation phase" setting, not something you turn on while you're still exploring.
• If claude config list doesn't reflect your changes, double-check you created .claude/settings.json in the repo you launched Claude Code from.

You'll know this step worked when Claude responds with a structured plan (files-to-change + validation commands) and does not attempt to execute tools or modify files while you remain in Plan Mode.

Key Takeaways:

• You opened Claude Code in the right project context and forced a plan-first workflow before any execution.
• You must get Plan Mode and your .claude/settings.json scope controls in place before asking for multi-step work.
• You should watch for config mismatches (wrong repo, wrong file path) and only switch to faster permission modes after you've approved a concrete plan.

Apply Changes, Run Tests, and Enable Sandboxing for AI Code Generation

Now that you have an approved plan, the goal is to implement it with controlled write access, then validate the change with real test commands in a safer execution environment.

Follow these steps to apply the plan, run validations, and reduce risk:

1. When your plan is ready, Claude Code will prompt you with "How would you like to proceed?" and offer options like "Yes, and auto-accept edits" or "Yes, manually approve edits"—choose one to begin implementing.
2. Approve file edits one batch at a time, then immediately review what changed by running git diff in a separate terminal pane.
3. Enable sandboxed command execution by running the /sandbox command and selecting the sandbox option that fits your workflow.
4. Prefer sandbox auto-execution for routine tasks by choosing Auto-allow mode so Claude can run common test and lint commands without repeatedly stopping for approvals.
5. Run your project's test command from the repo root, such as npm run test or pytest && coverage report as shown in the bash tool examples.
6. Handle sandbox-incompatible commands intentionally: if Claude Code offers the escape hatch to run something outside the sandbox, stop and verify the command is safe before allowing it.

A few things to watch out for:

• Keep the "edit phase" and the "verify phase" separate: review diffs first, then run tests second.
• Treat command execution as higher risk because it can be direct system access; when in doubt, run the command yourself or keep it sandboxed.
• If tests fail, don't broaden scope; ask Claude to fix only the failing tests or the minimal code path implicated by the failure, then re-run.

At this point, your repo should show only the intended edits in git diff, and your test command should complete successfully.

Key Takeaways:

• You implemented an approved plan and moved into a tight loop of "edit → diff review → test run" before doing anything else.
• You get the most safety and speed by enabling sandboxing early and running tests inside it whenever possible.
• You should watch for requests to use the sandbox escape hatch and treat them as a signal to slow down and verify.

Create Your First Skill: A Claude Code Tutorial

Once you're comfortable with "plan → implement → test," the fastest way to level up is to make your best prompts reusable. Skills are the modern way to do this in Claude Code—they're self-contained capability packages that Claude automatically discovers and loads when your request matches the skill's description.

A skill is a folder containing a required SKILL.md file plus optional supporting directories. Claude uses a progressive disclosure model: it reads metadata first (for discovery), loads the main instructions when triggered, and pulls in supporting files only as needed—keeping your context lean.

Here's the recommended folder structure:

pr-summarizer/
├── SKILL.md          # Required: frontmatter + core instructions
├── references/       # Optional: deep docs, edge cases, API specs
├── examples/         # Optional: sample inputs/outputs
└── scripts/          # Optional: executable helpers (Python/Bash/Node)

Follow these steps to create and test your first skill:

1. Create the skill folder in your project by running mkdir -p .claude/skills/pr-summarizer (use .claude/skills/ for project-shared skills that get committed to git, or ~/.claude/skills/ for personal skills).
2. Create the required SKILL.md file with YAML frontmatter containing a name and description—the description is critical because Claude uses it to decide when to load the skill:

---
name: pr-summarizer
description: Summarize a pull request diff and produce a changelog entry. Use when asked to summarize, review, or create release notes from a PR or diff.
allowed-tools: Read, Grep, Glob, Bash(git diff)
---

When triggered, follow these steps:

1. Read the PR title, body, and diff
2. Extract high-level changes, breaking changes, and impacted modules
3. Return a 3-sentence summary and a one-paragraph changelog entry

Example output format:
**Summary:** Added user authentication flow with OAuth2 support...
**Changelog:** This release introduces OAuth2-based authentication...

1. Keep SKILL.md lean (aim for 1,500–2,000 words; stay under 3,000) by organizing supporting content into subfolders:

   • references/ — detailed documentation, schemas, troubleshooting guides
   • examples/ — sample inputs/outputs, runnable demos
   • scripts/ — executable helpers that run without loading into context

2. (Optional) Add a reference file for edge cases. Create references/EDGE-CASES.md:

# Edge Cases for PR Summarizer

## Merge commits
When summarizing merge commits, focus on the merged branch's changes, not the merge commit itself.

## Empty diffs
If the diff is empty, return: "No code changes detected. This may be a metadata-only update."

Then reference it in your SKILL.md: "For edge cases, see references/EDGE-CASES.md."

1. Restart Claude Code in the repo, then test discovery by asking something that should trigger the skill (for example: "Summarize the changes in my last commit as a changelog entry") and confirm Claude loads and follows your skill's instructions.
2. If Claude doesn't trigger the skill when expected, improve your description field by adding clearer trigger keywords and example user phrasings, then test again.

A few things to watch out for:

• The name field must be lowercase letters, numbers, and hyphens only (max 64 characters); the folder name must match. The description has a max of ~1,024 characters.
• Never hardcode secrets or API keys in SKILL.md or supporting files—use MCP connections or environment variables for external service access.
• For skills that need isolated execution (keeping the main conversation clean), add context: fork to your frontmatter; this runs the skill in a separate sub-agent context.
• Use allowed-tools in frontmatter to restrict which tools the skill can access—grant only what's needed.

You'll know this step worked when Claude automatically loads your skill based on a matching request and produces output in the format you specified in SKILL.md.

Key Takeaways:

• Skills are the modern, recommended way to package reusable capabilities in Claude Code—they've largely replaced subagents for most workflows.
• You get the best discovery by writing a clear description with explicit trigger keywords and keeping SKILL.md focused on core instructions.
• You should use the folder structure (references/, examples/, scripts/) to keep your main skill lean while still providing Claude with deep context when needed.

Connect External AI Coding Tools with MCP

MCP (Model Context Protocol) is an open standard that lets Claude Code talk to external servers which expose tools, resources, and data. Think of it as a universal adapter: instead of pasting issue descriptions or database results into your prompt, you wire up an MCP server and Claude queries it directly.

Follow these steps to add your first MCP server:

1. Decide whether you need a remote HTTP server (for cloud services like Notion, Linear, or hosted APIs) or a local stdio server (for tools that need direct file system access); HTTP is recommended for most integrations.
2. Add a remote MCP server using the CLI: claude mcp add --transport http notion https://mcp.notion.com/mcp (replace with your actual service endpoint).
3. For servers requiring authentication, include the header flag: claude mcp add --transport http linear https://api.linear.app/mcp --header "Authorization: Bearer your-token".
4. Verify your server was added by running claude mcp list, then inspect its configuration with claude mcp get <name>.
5. Test the connection by asking Claude to use the integration (for example: "List my open issues from Linear" or "Find the Notion page about onboarding").

For local servers or team-shared configuration, create a .mcp.json file at your project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

A few things to watch out for:

• Minimize token scope and restrict ALLOWED_PATHS for filesystem servers—principle of least privilege applies here.
• MCP servers have had security vulnerabilities patched in the past; keep your servers updated and only use servers from trusted sources.
• Tool output triggers a warning at 10,000 tokens and caps at 25,000 tokens by default; consider pagination or scoping queries more narrowly for large responses.

You'll know this step worked when Claude can successfully query or act on an external system (like listing issues or reading a document) without you pasting the content manually.

Key Takeaways:

• MCP is how you connect Claude Code to external tools and data sources—it's an open protocol supported across multiple AI platforms.
• You get the most value by starting with one integration you'll use daily (like your issue tracker) and expanding only after that works reliably.
• You should watch for overly broad permissions; scope file paths and API tokens narrowly, and keep MCP servers updated.

Automate Guardrails with Hooks

Hooks let you run shell commands automatically at specific points in Claude Code's lifecycle—when you submit a prompt, before or after a tool runs, or when a session starts. Use them for lightweight automation like enforcing code style, logging commands, or blocking risky operations.

Follow these steps to add your first hook:

1. Decide on a low-risk automation to start with, such as logging when Claude runs certain commands or auto-formatting code after edits.
2. Add a hook to your project's .claude/settings.json (or ~/.claude/settings.json for user-scope) following the hooks guide. Here's a starter that logs every Bash command Claude runs:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $(echo $CLAUDE_TOOL_INPUT | jq -r '.command')\" >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

1. For a more practical hook, auto-run Prettier on TypeScript files after every edit by adding a PostToolUse hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path') 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

1. Restart Claude Code and trigger the hook by running a command that matches your matcher, then verify the hook fired by checking your log file or formatted output.
2. Debug hooks by running /hooks inside Claude Code to inspect registered hooks, or use claude --debug to see hook execution logs.

A few things to watch out for:

• Hooks execute arbitrary shell commands as your user, so start with read-only or logging actions before adding anything that mutates state.
• Hooks run with a 60-second timeout by default; keep commands fast so they don't delay Claude's workflow.
• Use exit code 2 to block an operation (for PreToolUse hooks that should reject dangerous commands); other non-zero codes are non-blocking warnings.

You'll know this step worked when your hook reliably fires and produces observable output (a log entry, formatted file, or blocked command) at the expected trigger point.

Key Takeaways:

• Hooks are lightweight automation that runs shell commands at specific points in Claude Code's lifecycle—use them for guardrails, formatting, and logging.
• You get the most safety by starting with harmless, observable hooks before graduating to anything that modifies files or blocks operations.
• You should watch for slow or flaky hooks; test them in isolation and use /hooks or --debug to troubleshoot.

Build Faster with DeepStation

Reading a guide is a great start—but the real speed gains come when your Claude Code setup becomes muscle memory across projects. DeepStation helps you do exactly that by accelerating AI education and innovation through the power of community—so you can compare real workflows, explore AI coding tips from other developers, and turn "one-off prompts" into a consistent, safer Claude Code process you can rely on.

If you're ready to build momentum this week, join now and start leveling up alongside other builders refining their Claude Code workflow, AI coding best practices, and developer automation routines. Signup for Claude Code workflow training & AI education today! Spots in active community sessions fill quickly—lock in your seat and turn your next terminal session into measurable progress.