Beyond the Hype: My Production Workflow with Claude Code

TL;DR: Coding effectively with Claude Code requires a structured three-phase framework—Design, Plan, and Execute—anchored by persistent markdown plans inside the repository. By treating the agent as a delegated collaborator rather than an autocomplete tool, engineers can eliminate mechanical friction while retaining full control over architecture, code review, and production releases.

What Claude Code Actually Is (And What It Isn't)

Claude Code is an agentic, terminal-native AI coding assistant that runs directly in your local repository to inspect files, execute shell commands, edit code across files, and create git commits.

Most discussions about AI coding oscillate between breathless hype and dismissal from people who only tried autocomplete plugins. Claude Code is neither autocomplete nor a chat box where you copy-paste snippets back and forth. It has full shell access, reads your whole repository, runs test suites, inspects compiler errors, and writes multi-file diffs directly to disk.

Why Terminal Agents Beat Autocomplete for Multi-File Refactors

Editor autocomplete excels at writing the next 5 lines of a function you already understand. It fails completely when a task spans multiple files, requires running a build command, or involves diagnosing why a test suite failed after a dependency bump.

┌────────────────────────────────────────────────────────┐
│                   Developer Terminal                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │ Claude Code (Terminal REPL Agent)                │  │
│  └────────┬─────────────────────┬───────────────────┘  │
│           │ Tool Calls          │ Shell Commands       │
│           ▼                     ▼                      │
│  ┌─────────────────┐   ┌─────────────────────────────┐ │
│  │ Local Filesystem│   │ Test Runner / Build Tooling │ │
│  │ (Multi-file edit│   │ (pytest, vitest, tsc, cargo)│ │
│  └─────────────────┘   └─────────────────────────────┘ │
└────────────────────────────────────────────────────────┘

The difference comes down to three operational capabilities:

• Repository-Wide Context: It inspects package manifests, config files, and internal utilities rather than guessing from open editor tabs.
• Closed Execution Loops: It runs tests, sees the exact stack trace, adjusts its implementation, and reruns the suite until it passes.
• Git Native Operation: Every edit produces standard git diffs you can review with git diff before committing.

The Design-Plan-Execute Loop: Keeping Agents on Rails

Giving an agent free rein on a blank prompt produces sprawling, over-engineered messes. The fix is strictly separating work into three distinct phases.

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│     DESIGN      │ ────▶ │      PLAN       │ ────▶ │     EXECUTE     │
│ Trade-offs & UX │       │ Markdown on Disk│       │ Code & Verify   │
└─────────────────┘       └─────────────────┘       └─────────────────┘

1. The Design Phase: Argue Before You Code

2. The Planning Phase: Persistent Memory on Disk

• Exact files to create or modify
• The verification command (e.g., npm test -- api/auth.test.ts)
• The expected outcome

3. The Execution Phase: Step-by-Step Verification

Setting Up Your Repository for Claude Code

Here is the setup that keeps agent work organized and safe:

Step 1: Configure Project Directories

mkdir -p .claude docs/plans

Step 2: Write an Atomic Task Plan

<!-- docs/plans/2026-04-28-vercel-migration.md -->
# Task: Migrate Express Analytics Proxy to Vercel Functions

1. Extract shared authentication helpers to api/_utils/auth.ts.
2. Implement serverless handler in api/analytics.ts.
3. Port environment variable bindings from existing Railway config.
4. Run integration suite: npm test -- api/analytics.test.ts.
5. Verify response payload matches existing API contract.

Step 3: Run in Isolated Git Worktrees

git worktree add ../migration-branch -b feat/migration
cd ../migration-branch
claude

Step 4: Review Every Diff Manually

Four Real Tasks I Regularly Offload to Claude Code

1. Express to Serverless Migrations: Splitting monolithic route handlers into isolated serverless functions, extracting utility files, and updating routing tables. 2. Static Prebuild Scripts: Generating custom Groq/GraphQL extraction scripts that pull data from a headless CMS and format dynamic XML sitemaps. 3. Test Suite Expansion: Taking an existing module and generating targeted unit tests for unhandled error branches and boundary conditions. 4. Dependency Upgrades: Bumping major versions of libraries, running the test suite, and fixing deprecated API call sites until all tests pass green.

Comparison: AI Coding Paradigms

| Dimension | Editor Autocomplete (Copilot) | Chat Windows (ChatGPT Web) | Terminal Agent (Claude Code) | | :--- | :--- | :--- | :--- | | Context Scope | Current file & open tabs | Copy-pasted snippets | Entire local repository | | Command Execution| None | None | Full shell access (tests, git, build)| | Multi-File Edits | Single-line suggestions | Manual copy-pasting | Autonomous across whole tree | | Memory Persistence| None | Session-based | Markdown plans saved in repo | | Best Used For | Fast boilerplate typing | Brainstorming concepts | Multi-step refactors & workflows |

Failure Modes: Where Claude Code Breaks Down

• Premise Acceptance: If you say "I think our Redis cache is corrupt," the agent will often spend 20 minutes proving your incorrect theory right. Always provide raw error logs instead of your diagnosis.
• Context Degradation in Long Sessions: After 30+ turns, the agent forgets early decisions. Keep task plans in markdown on disk to ground the session.
• Aesthetic Decisions: Terminal agents write clean TypeScript and passing tests, but their CSS aesthetics are mediocre. Handle visual layout and spacing yourself.

Frequently Asked Questions

How does Claude Code differ from GitHub Copilot?

Why should I write plans in markdown before writing code?

Is it safe to give Claude Code terminal command access?

What tasks are best suited for Claude Code?

Does Claude Code eliminate the need for code review?

Conclusion & Key Takeaways

Claude Code turns development from manual typing into structured delegation. Use a Design-Plan-Execute workflow, write task plans to disk, run tests continuously, and review every diff before committing.

Frequently Asked Questions (FAQ)