Claude Code: The Definitive Engineering Guide (Beyond the Hype)

I’ve spent the last few weeks living inside my terminal with Claude Code (CC), Anthropic’s system-level AI agent.

Claude Code isn’t Copilot in your terminal. Copilot suggests; Claude Code acts. It has permission to read your file system, run terminal commands, manage git, and even browse the web. It’s the difference between a smart autocomplete and a junior engineer who needs supervision but types at 1,000 WPM.

If you’ve read the documentation, you know how to install it. But the docs won’t tell you how to keep it from burning through your API credits, or how to stop it from hallucinating file paths.

Here is the engineering guide to actually shipping code with Claude Code, focusing on architecture, memory management, and safety.

---

1. The Setup: Beyond npm install

Yes, you install it via npm install -g @anthropic-ai/claude-code. But if you stop there, you’re doing it wrong.

The Model Strategy (Cost vs. Intelligence)

By default, CC might default to a model that doesn’t fit your specific task. You need a strategy.

• Haiku 3.5/4.5: Use for quick syntax checks, log parsing, or simple refactors. It’s cheap and fast.
• Sonnet 3.5/4.5: The daily driver. Good balance of reasoning and coding capability.
• Opus 4.5 (with Thinking): The “Architect.” Use this for system design, complex debugging, or when you need ultrathink mode. It’s expensive, but cheaper than spending 4 hours debugging a race condition.

Pro Tip: Create Aliases Don’t manually switch models. Add these to your .zshrc or .bashrc:

# The Daily Driver
alias cc='claude'

# The Cheapskate (for simple tasks)
alias cc-fast='ANTHROPIC_MODEL=claude-3-haiku-20240307 claude'

# The Big Gun (for architecture)
alias cc-arch='ANTHROPIC_MODEL=claude-3-opus-20240229 claude --dangerously-skip-permissions'

The “Doctor” Check

Before you dive in, run the diagnostic tool. It’s surprisingly hidden but essential for debugging MCP (Model Context Protocol) connections.

claude /doctor

---

2. The Brain: CLAUDE.md is Your Project’s Hippocampus

Most people ignore CLAUDE.md. This is the single most important feature of the tool.

Think of CLAUDE.md as the “onboarding document” for the AI. Every time you start a session, CC reads this file. If you don’t have one, CC is amnesiac, relearning your project structure every single time (and costing you tokens).

The Perfect CLAUDE.md Structure

Don’t just dump a README here. Include architectural decisions and “Don’t Do This” rules.

# Project: E-Commerce Core

## Architecture
- **Backend:** Node.js 20 (Express), TypeScript
- **DB:** PostgreSQL 15 (Prisma ORM)
- **State:** Redis for caching, not for persistent session storage.

## Critical Rules (Learned Lessons)
- ❌ NEVER use `enum` in TypeScript; use string unions.
- ❌ Do not use `any`; use `unknown` if necessary.
- ✅ All async functions must be wrapped in `try/catch` at the controller level.
- ✅ Use `bun` instead of `npm` for all scripts.

## Common Commands
- Build: `bun run build`
- Test: `bun test` (Do not use Jest)
- DB Migrate: `bun prisma migrate dev`

The “Evolutionary” Workflow

When Claude messes up (e.g., uses npm instead of bun), don’t just correct the code. Correct the memory.

Prompt: “You used npm again. Update CLAUDE.md to explicitly forbid npm and mandate bun for all future tasks.”

This creates a feedback loop where the agent gets smarter the longer you work on the project.

---

3. The “Plan Mode”: Stop the Hallucinations

The biggest mistake users make is giving a complex command immediately. Claude will often start editing files based on a guess of your directory structure.

Always use Plan Mode (Shift+Tab twice) for tasks involving >2 files.

In Plan Mode, Claude acts as an Architect:

1. It scans the file system.
2. It reads relevant code.
3. It proposes a step-by-step plan.
4. It waits for your approval.

Why this matters:

• Cost: It prevents “flailing” (writing code, failing tests, rewriting, failing again).
• Safety: You see exactly which files it intends to touch before it touches them.

---

4. Supercharging with MCP (Model Context Protocol)

Claude Code is an MCP client. This means it can connect to external tools. The “Killer App” here is Chrome DevTools.

Scenario: Frontend Debugging

Instead of pasting HTML into the chat, let Claude see the browser.

Installation:

claude mcp add chrome-devtools npx chrome-devtools-mcp@latest

The Workflow:

1. Start your local server (localhost:3000).
2. Prompt: “Open localhost:3000, click the ‘Login’ button, and tell me why the console is throwing a 403 error.”
3. Claude drives the browser, inspects the network tab, and finds the missing CSRF token.

Other Essential MCPs

• Postgres: Let Claude query your DB directly to verify migrations.
• GitHub: Let Claude read issues and PRs to understand context before coding.

---

5. Advanced: Parallelism & Subagents

Boris Cherny (from the Claude Code team) suggests a “Manager/Worker” workflow. Don’t stare at the terminal waiting for Claude to finish.

The “Subagent” Pattern

You can define specialized agents in ~/.claude/agents.json. These are like specialized employees with specific prompts and tools.

{
  "agents": {
    "security-auditor": {
      "description": "Audits code for OWASP vulnerabilities",
      "model": "claude-3-opus-20240229",
      "instructions": "You are a security expert. Focus ONLY on SQL injection, XSS, and auth bypass. Do not fix style issues.",
      "tools": ["read", "search"],
      "permissions": { "allowWrite": false }
    },
    "test-writer": {
      "description": "Writes Jest tests",
      "model": "claude-3-sonnet-20240229",
      "instructions": "You write comprehensive unit tests. Aim for 100% branch coverage.",
      "tools": ["read", "write", "bash"]
    }
  }
}

Usage:

“I just finished auth.ts. Please run the security-auditor to check for flaws, and simultaneously have test-writer generate the spec file.”

This runs parallel contexts, speeding up the workflow significantly.

---

6. CI/CD Integration: The “Headless” Reviewer

You can run Claude Code in non-interactive mode (-p flag). This allows you to add AI code review to your GitHub Actions.

Example Workflow:

name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD > diff.txt
          cat diff.txt | claude -p "Review this diff for security issues and performance bottlenecks. Be concise." > review_output.txt
      - name: Post Comment
        uses: actions/github-script@v6
        with:
          script: |
            // Script to post review_output.txt to the PR

---

7. Safety & Cost: The Critical “Gotchas”

The “rm -rf” Risk

Claude Code has system access. While it asks for permission, “alert fatigue” is real. You will eventually just hit “Yes” without reading.

Configure the Sandbox (~/.claude/settings.json): Explicitly deny dangerous commands.

{
  "permissions": {
    "allow": {
      "bash": ["npm run *", "git *", "ls", "cat"],
      "write": ["src/**/*", "tests/**/*"]
    },
    "deny": {
      "bash": ["rm -rf *", "shutdown", "reboot", "chmod"],
      "write": [".git/**/*", ".env", "/etc/*"]
    }
  }
}

Token Burn

Claude Code maintains a massive context window. If you keep a session open for days, every simple “Hello” sends 100k+ tokens to the API.

• Use /compact: This summarizes the conversation history, freeing up context space while keeping the “gist.”
• Use /clear: Start fresh for distinct tasks.
• Use /cost: Check this frequently. It’s sobering.

---

Summary: The New Workflow

If you adopt Claude Code, your development loop changes from Write -> Run -> Fix to Plan -> Delegate -> Verify.

1. Init: claude /init to generate CLAUDE.md.
2. Plan: Shift+Tab to architect the change.
3. Execute: Let Claude write the code.
4. Verify: Ask Claude to run the tests (!npm test).
5. Refine: Update CLAUDE.md with any new lessons learned.

This isn’t just faster typing; it’s higher-level engineering. Just remember: you are the pilot, Claude is the engine. Don’t fall asleep at the wheel.