Claude Code

The workflow

Explore, Plan, Implement, Commit. The four-phase cycle that turns a Claude Code session from "let's see what happens" into something consistently productive.

The single biggest difference between someone who gets value from Claude Code and someone who does not is whether they plan before they implement. Jumping straight to "build me X" works for tiny tasks. For anything that touches more than one file, the plan step is the difference between one pass and five frustrated retries.

The four phases

The four phases, with a loop-back from implement to plan when the approach needs revising.

Phase 1: Explore

Start by understanding the codebase before touching it. Launch Claude Code in plan mode (claude --plan) so it can only read, not write. Ask it to read the relevant files and explain how they work.

explore phase

$ claude --plan

Plan mode: Claude can read files but will not make changes.

> Read the auth module and explain how session handling works. What happens when a token expires?

Read src/auth/session.ts (87 lines)

Read src/auth/middleware.ts (42 lines)

Read src/auth/token.ts (63 lines)

Sessions are stored in Redis with a 24-hour TTL. The middleware checks the token on every request, and if it's expired, it tries a refresh from the refresh token stored in an HTTP-only cookie. If the refresh also fails, it returns 401 and clears the cookie.

The one thing to note: the refresh endpoint doesn't rate-limit, so a compromised refresh token could be used indefinitely until someone revokes it.

Now you understand the code. The next question is better because you know the context.

Phase 2: Plan

Ask Claude to plan the change before making it. "What files need to change? What is the approach? What could go wrong?" Review the plan. Push back on anything that does not feel right.

plan phase

> I want to add rate-limiting to the token refresh endpoint. What is the best approach given this codebase?

Three options, ranked by how well they fit this codebase:

1. Use the existing express-rate-limit middleware (already a dependency) with a per-IP limit on the /auth/refresh route. Simplest, matches how you rate-limit the login endpoint.

2. Token-bucket in Redis (since you already have Redis for sessions). More granular but more code.

3. Rate-limit at the reverse proxy level. Cleanest separation but requires infra changes.

I'd recommend option 1. Files to change: src/auth/routes.ts (add the limiter), src/auth/__tests__/refresh.test.ts (add rate-limit tests). Want me to proceed?

The plan is concrete: two files, one approach, clear rationale. Now you can say "go" with confidence.

Phase 3: Implement

Switch out of plan mode (Shift+Tab to acceptEdits) and tell Claude to execute the plan. The tight loop kicks in: Claude edits, runs tests, adjusts based on results.

implement phase

> Go with option 1. Implement and run the tests.

Edit src/auth/routes.ts (8 lines added)

Edit src/auth/__tests__/refresh.test.ts (24 lines added)

Run npm test

1 test failed: "should allow refresh after wait period"

The test is using fake timers but the rate limiter checks real Date.now(). Fixing the test to mock the rate limiter's clock.

Edit src/auth/__tests__/refresh.test.ts (3 lines changed)

Run npm test

All 14 tests passed.

Done. Rate limiting on /auth/refresh with a 5-request-per-minute per-IP limit. All tests pass including the three new ones.

Notice how Claude hit a test failure, diagnosed it, fixed it, and re-ran the tests. This is the tight loop: implement, test, fix, test. It handles the iteration without you needing to intervene.

Phase 4: Commit

Once the code works and tests pass, Claude can commit, push, and open a PR.

commit phase

> Commit this, push, and open a PR.

Run git checkout -b feat/rate-limit-refresh

Run git add src/auth/routes.ts src/auth/__tests__/refresh.test.ts

Run git commit -m "Add rate limiting to token refresh endpoint"

Run git push -u origin feat/rate-limit-refresh

Run gh pr create

PR #47 opened: "Add rate limiting to token refresh endpoint"

PR is up. Description includes the rationale (unrate-limited refresh endpoint), the approach (express-rate-limit, 5/min/IP), and the test coverage (3 new tests).

Permission modes

Press Shift+Tab during a session to cycle between four permission modes. Each one changes what Claude can do without asking.

Mode	Auto-approves	Best for
default	Reads only	Getting started, sensitive work, first sessions
acceptEdits	File edits + basic filesystem (mkdir, touch, mv, cp)	Active coding sessions where you review the plan but trust the execution
plan	Reads only, no changes allowed at all	Exploring unfamiliar code, understanding before changing
auto	Everything, with a background safety classifier	Long tasks where approval fatigue is a risk. Team/Enterprise only.

The progression most people follow: start on default for the first few sessions. Switch to acceptEdits once you are comfortable with the interaction model. Use plan mode when exploring unfamiliar code. Graduate to auto mode when you trust the tool and want to hand off longer tasks.

Course-correcting mid-session

Things go wrong. Here is how to recover without starting over.

Esc

Stop mid-action. If Claude is editing a file or running a command and you want it to stop, press Esc. It halts immediately.

/rewind

Undo the last step. Reverts to the state before Claude's most recent action. Like Ctrl+Z for the whole session.

/clear

Reset the conversation. Wipes the context window. Use this between unrelated tasks, or when the conversation has drifted and Claude is confused. Start fresh with a better prompt.

/compact

Compress the context. If the conversation is getting long but you do not want to reset, /compact summarises it while preserving the key decisions. Add instructions: /compact Focus on the auth changes.

After two failed corrections on the same issue, stop correcting. Type /clear, rewrite your prompt based on what you learned from the failures, and start the task fresh. The third rewrite is almost always better than the third correction.

Managing context

Claude Code has a 1M token context window (on Sonnet 4.6 and Opus 4.6), which is enormous. But it is not infinite, and long sessions eventually degrade in quality as the context fills with old conversation, file contents, and command outputs.

Run /clear between unrelated tasks. One session, one logical problem. Mixing "fix the login bug" with "update the README" in the same session means both get worse context.
Use subagents for investigation. If you need to explore a part of the codebase to answer a question, ask Claude to use a subagent. Subagents explore in their own context window and report back a summary, keeping your main context clean.
Trust auto-compaction. Claude automatically compresses the context when it hits about 83% capacity. It preserves key decisions and code states. You can customise this in CLAUDE.md: "When compacting, always preserve the list of modified files and test commands."

The tight-loop principle

The single most important habit for Claude Code productivity: keep the feedback loop short. Plan one thing, implement one thing, verify one thing. Not "build the whole feature, then test everything at the end".

Loose loop vs tight loop

YouBuild the entire user authentication system: registration, login, password reset, email verification, session management, and admin controls.

What happens

Claude writes hundreds of lines across a dozen files. The first three are right. The fourth has a subtle bug. Files five through twelve are built on top of the bug. By the time you notice, unwinding the mistake takes longer than writing it would have from scratch.

YouStep 1: Build the registration endpoint. Just the POST /auth/register route, the handler, and one test that confirms a user is created in the database. Run the test before moving on.

What happens

Claude builds one endpoint, one test, verifies it passes. You check the code. Then: "Step 2: add login." Then: "Step 3: add password reset." Each step is verified before the next begins. Bugs are caught in the step they were introduced, not six files later.

The tight-loop prompt is: "do this one thing, test it, show me the result". The loose-loop prompt is: "build me everything". The first produces better code in less total time.

The workflow is: explore to understand, plan to agree on approach, implement in tight loops, commit when it works. The tool is powerful enough to skip steps, and disciplined enough to benefit from not skipping them.

Next: Patterns shows ten common tasks as complete worked examples. Or go back to the Claude Code overview.