Building Big Features With Claude Code, Step by Step

To fix "an old refresh token still works after logout," step one of the plan is to have Claude Code write a failing test that proves the bug exists. The test does fail, and everything seems on track.

Then you read the failure message: the client can't even connect to the service. The test proves the environment is broken and says nothing about tokens. Move on to the next step now, and you may end up "fixing" the environment and calling it an auth fix.

The most common mistake with big tasks in Claude Code is pushing straight through: research with no end point, a plan that's just "update the auth service, add tests," and an implementation done file by file, leaving intermediate states nothing can verify. When something breaks at the end, you can't tell which step caused it.

Breaking a big task into research, planning, and implementation is often called RPI. The name matters less than each stage's exit condition:

• research answers only the questions that would change the approach, and stops once the evidence supports a decision;
• the plan spells out what changes, what stays, how to roll back, and which checks run at each stage;
• implementation is sliced by behavior you can verify on its own, not by file;
• every slice waits for evidence from the one before.

That failing test from the opening is caught at the first exit: it failed, but for the wrong reason. Let's follow this auth fix through each stage's method and completion criteria.

01 Use the Stages, Write Files Only When Needed

Research, Plan, Implement, often shortened to RPI, is a useful order, but Claude Code doesn't require it, and it doesn't require creating REQUEST.md, RESEARCH.md, PLAN.md, and IMPLEMENT.md every time.

Whether to write files depends on whether something later will use them. For switching sessions, team review, or long-term tracking, keep formal material. For a small task finished in the current session, research and planning can stay in the conversation. High-risk changes deserve a careful record; small changes keep records only as far as later use requires.

Research and planning provide the basis for implementation; implementation, verification, and review then check against the original acceptance requirements. Where those requirements come from is covered in how to accept work when Claude Code says it's done.

02 Research: Answer Only the Questions That Change the Approach

Research answers only the decision questions that would change the approach. Before starting, you might list:

1. Where are refresh tokens stored now, and can they be revoked per session?
2. Does the logout endpoint only clear browser state, or does it already update a server-side record?
3. How does the refresh endpoint decide a token is valid, and does it support rotation and replay detection?
4. Does the current multi-device policy allow logging out one device while keeping others signed in?
5. Which tests can reproduce the bug, and which fixtures are missing?

You can do this stage in Plan mode: read, search, and investigate read-only without changing source. The Claude Code common workflows documentation describes Plan mode this way: Claude reads files and proposes a plan but makes no edits until you approve. Tracing the call chain, sorting test logs, and checking official docs can each go to a read-only subagent, with the main session combining conclusions and evidence locations; the same documentation recommends delegating research to subagents to keep the main context clean.

Research results should give the next step what it needs to decide:

• confirmed facts and where they live in the files;
• assumptions that are still unconfirmed;
• modules and data that may be affected;
• options and their key tradeoffs;
• a recommended direction and the reasons for it.

Once the evidence supports the next decision, end this round of research. Further investigation needs a new question that could change the approach. Independent research can run in parallel; how to divide it is covered in how to run Claude Code subagents in parallel safely.

03 Plan: Detailed Enough to Verify Stage by Stage

"Update the auth service and add tests" doesn't say how. A plan should at least cover:

• which modules change, and why;
• how data, function contracts, or API behavior will change;
• which existing behavior must be preserved;
• how old state migrates, and how to roll back if something goes wrong;
• which checks run after each stage;
• what this change explicitly won't do.

Suppose research confirmed two things: the system already has revocable session records, and logout should only affect the current device. Then the plan can look like this. If tokens had no server-side record, you'd first need to solve how to revoke them before writing an implementation plan.

Stage 1: Add a failing test showing an old refresh token still works after logout.
Complete when: It fails consistently on current code for the defect-related reason.

Stage 2: Write the current session's revocation time on logout and check it in the refresh path.
Complete when: The new test passes, as do normal refresh and token rotation tests.

Stage 3: Cover multi-device and concurrent-refresh boundaries.
Complete when: One device's logout leaves other sessions intact; concurrent replay returns the expected error.

Stage 4: Run authentication tests, typecheck, and build.
Complete when: Every command succeeds and actual output is summarized.

Each stage should produce a behavior change you can verify on its own. When stages depend on each other, go in order; the next step waits for evidence from the previous one.

When stage 1's test fails, ask why it failed. If the client can't reach the service, it proves an environment problem; only when the request reaches the target endpoint and the old token is still accepted has the test captured this bug. Keep the actual response so the next stage has something to compare against. Stage 1's completion criterion, "for the defect-related reason," exists to stop exactly the case in the opening.

04 Implement: Slice by Verifiable Behavior

Slice implementation by verifiable behavior. If the first slice is "logout invalidates the current session," the revocation state, the logout write, the refresh check, and the test all need to land together. Adding a field alone can't verify that behavior, and one slice touching several files is normal.

Once that slice passes, move on to other devices and concurrent refresh, so interdependent code and tests don't get split into intermediate states that are hard to judge.

Git commits should be logically cohesive too:

• each commit expresses one clear purpose;
• after the commit, the project is in an understandable and ideally verifiable state;
• unrelated refactors stay out of bug fixes;
• reverting one commit fully undoes one behavior, which splitting by isolated files can't achieve.

For example, the field in session.ts, the check in refresh.ts, and the test in refresh.test.ts together implement revocation, so they can go in the same commit.

After each slice, run the nearest and fastest check first, then widen to integration tests, typecheck, and build. When something fails, it's easier to tell which step caused it. The Claude Code best practices explain why this works: give Claude a check that comes back pass or fail, and it can close the loop itself, making the change, running the check, and if something broke, reading the output and fixing it before running the check again.

05 Save a Stable Workflow as a Skill

When the same "research, plan, implement, verify, review" sequence keeps recurring on a team, you can create a project Skill:

---
name: safe-feature
description: Complete cross-module features through research, planning, implementation, verification, and independent review.
argument-hint: "[feature or defect description]"
disable-model-invocation: true
---

1. Confirm goal, scope, non-goals, and observable acceptance evidence.
2. Research relevant implementation, tests, and project rules read-only; list facts and open questions.
3. Propose a plan sliced by verifiable behavior; wait for user confirmation before edits.
4. Implement by slice, running the nearest check after each.
5. Run full acceptance commands and record commands, results, and unverified areas.
6. Use a read-only subagent for independent review; check valid findings before finishing.

Save it as .claude/skills/safe-feature/SKILL.md and invoke it explicitly with /safe-feature. disable-model-invocation: true keeps Claude from launching a whole complex workflow when you haven't chosen it.

The Skill keeps the stable method. This run's file names, error logs, and temporary decisions stay in the current session; templates or verification scripts get read when needed.

06 Manage Context in a Long Task

Context management means keeping the information you're still using. Check usage with /context first, then choose:

• between unrelated tasks, use /clear or a new session;
• in a long task whose decisions you need to keep, use /compact with something like "keep the current key conclusions and test commands";
• hand heavy searches and logs to a subagent to sort through when that fits;
• check progress on background tests and long-running commands with /tasks;
• write decisions that need to survive across stages or sessions into project docs or the plan.

Before compacting, keep the debugging leads you're still using, and clear out only what's irrelevant or easy to find again.

Each slice delivers one behavior change that can be verified on its own, and the next step waits for evidence from the last. The test from the opening that "failed for the wrong reason" gets stopped at stage 1's exit, so everything after it builds on a bug you actually caught.