Skip to content
Easy AI How-To

AdvancedClaudeBuilding

Get started with Claude Code: fix a bug from your terminal

This guide is for developers who want an AI agent that works inside their real codebase. You will install Claude Code, let it learn your project, plan and fix a reproducible bug with a test, commit the fix, and save project rules in CLAUDE.md. Each step was checked against Anthropic's Claude Code docs in October 2026; Claude Code updates often, so menu names and defaults can shift.

Time
About 25 minutes
Checked
Tools
Claude Code quickstart, Claude Code setup, Permission modes, CLAUDE.md and memory

If a button name on the screen does not match this guide, follow the action. These products rename buttons often. This is an advanced guide: it uses code, and each technical term is explained the first time it appears. Model names and prices change, so check the linked docs before you ship.

Steps

  1. Install Claude Code

    Claude Code is Anthropic's coding agent: a program in your terminal that reads your files, runs commands, and edits code when you ask. Install it with the native installer, which keeps itself updated:

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

    # Windows PowerShell
irm https://claude.ai/install.ps1 | iex

    Homebrew (brew install --cask claude-code) and WinGet (winget install Anthropic.ClaudeCode) also work, but they don't auto-update. Open a new terminal window and run claude --version. It should print a version number followed by (Claude Code). If you see "command not found," the install folder isn't on your PATH (the list of folders your terminal searches for programs); claude doctor and the setup page explain the fix.

  2. Start a session in your project and sign in

    Go to your project folder and start Claude Code:

    cd /path/to/your/project
claude

    The first time, it asks you to log in. Pick your Claude subscription or Console account and finish in the browser. Your login is saved, so you won't do this again. Type /help to see commands, or /login later to switch accounts.

  3. Let it read the project first

    Claude Code finds and reads files on its own, so you don't paste code in. Ask it to orient itself before you ask for changes:

    Prompt to paste

    What does this project do? Explain the folder structure, how to run it,
and how to run the tests.

  4. Choose how much it can do without asking

    A permission mode decides which actions need your OK. Press Shift+Tab to cycle modes and watch the status bar at the bottom. Manual (⏸ manual mode on) asks before anything except reading. Accept edits (⏵⏵ accept edits on) lets it edit files without asking. Plan (⏸ plan mode on) lets it research and write a plan but blocks edits until you approve. Auto runs actions with background safety checks. Depending on your version and plan, a session may start in Auto or Manual. For a first bug fix, switch to Plan.

  5. Describe the bug and ask for a plan

    Be specific: what happens, what should happen, and how to reproduce it. Replace the brackets. In Plan mode, Claude reads code and runs exploring commands, then shows a plan. Read it. Choose No, keep planning to correct it, or choose Yes, manually approve edits so you review each edit as Claude makes it.

    Prompt to paste

    Bug: [what happens, e.g. "submitting the signup form with an empty email
shows a blank page"]. Expected: [what should happen].
Reproduce with: [command or steps, e.g. "npm test -- signup"].
Find the root cause, write a failing test that shows the bug,
then propose the smallest fix.

  6. Let it fix and verify

    After you approve the plan, Claude makes the edits, showing each one for your OK, and asks before running commands such as your test suite unless your mode allows them. Ask it to prove the fix: "run the tests again and show me the result." Then ask "what files have I changed?" to see the diff before anything is committed.

  7. Commit the change

    Claude Code can run Git for you. Review the diff yourself first, then ask:

    Prompt to paste

    Create a branch called fix/[short-name], and commit these changes
with a clear message that explains the bug and the fix.

  8. Save project rules in CLAUDE.md

    CLAUDE.md is a file of instructions Claude Code loads at the start of every session in that folder. Type /init and Claude analyzes the codebase and drafts one with build commands, test commands, and conventions. If one already exists, /init suggests improvements instead of overwriting it. Add what Claude can't discover on its own, such as "always run npm test before saying a fix is done." Commit CLAUDE.md so your team shares it; put personal notes in CLAUDE.local.md and add that file to .gitignore. If your repo already has an AGENTS.md and no CLAUDE.md, recent versions of Claude Code read AGENTS.md instead.

  9. Check the work like a reviewer

    Before you merge, read every changed line, run the tests yourself, and try the original reproduction steps by hand. Confirm the fix addresses the root cause and not just the one input you tested. Claude Code does the typing; you still own what ships.

Tips

  • Press Shift+Tab any time to change permission modes. Use Manual or Plan in unfamiliar or sensitive code.

  • claude -p "explain this function" runs one question and exits, which is handy in scripts. claude -c continues your most recent conversation in that folder.

  • Type /clear between unrelated tasks so old context doesn't steer the next one.

  • Don't keep secrets such as API keys in files Claude reads or in CLAUDE.md. Use environment variables.

Common questions

Does Claude Code work on the free Claude plan?

No. Anthropic's setup page says the free claude.ai plan doesn't include Claude Code. You need Pro, Max, Team, or Enterprise, a Claude Console account (billed per use), or access through a supported cloud provider such as Amazon Bedrock. Plans and prices change, so check Anthropic's site.

Do I have to use the terminal?

No. Claude Code also runs as a desktop app, in VS Code and JetBrains IDEs, and on the web. The terminal is the most direct way to learn how it works, and the same CLAUDE.md applies everywhere.

What's the difference between CLAUDE.md and auto memory?

CLAUDE.md holds instructions you write and control. Claude Code also keeps its own notes between sessions, which Anthropic calls auto memory. Put rules you want followed every time in CLAUDE.md.

How does this fit the Software Factory pattern?

Claude Code is one of the agents that can run a factory. Your AGENTS.md or CLAUDE.md plays the Factory Manager that defines the steps. See the Software Factory series for the full setup.

More guides

Occasional notes

Hear when a new guide is up

A short note when a guide is added. No account, and no emails until this form is connected to a real list.

Placeholder. This form is not connected to an email service. Nothing you type is saved or sent.