Turning Claude Code Into My Best Design Partner

When I first started using Claude Code, I had a naive approach to working with it. I would describe the task directly in the prompt, press Enter, and cross my fingers. If the agent made mistakes, I would tell it how to fix them. For small tasks, this can be good enough, but as the task grows in complexity, this approach reveals several significant drawbacks.

When Simple Doesn’t Scale

The first problem is that the conversation becomes the only source of truth about the task. This means a new message can override instructions from an old one, but it isn’t always clear when this happens, which can cause mistakes by the agent.

Additionally, the context size for the agent is limited. The more the conversation grows, the more information from the beginning can be “forgotten,” even though Claude Code has a capacity for “compacting” the conversation that’s supposed to improve this issue.

For these reasons, I started experimenting with an approach I’d heard about: asking Claude Code to start by writing a plan document. This document becomes the source of truth instead of a sprawling conversation. When I find the plan document good enough, I’ve taken the habit of clearing the conversation to start fresh with just the plan as context.

Creating the Initial Plan

My first prompt is usually to give Claude Code a description of the feature it should implement (or bug it should fix, or the refactoring it should do) with all the details I have in mind. If I already have an idea of the implementation, I can give it some pointers to existing files for reference. However, I try not to give it too many implementation instructions because I want it to make suggestions and contribute to the design process.

I want to implement a query builder. The page will be displayed as two columns. In the first one, a first box will let the user select a view (for now only one view: “Volume Metrics”), a second box to select fields (“field 1”, “field 2”, “field 3”), and a third one to add filters (don’t fill it yet). The right column will display first the query as human readable, then a table with the query results. (to be continued)

I also try to refer to existing plans for features implemented previously. I don’t have a formal template, but I don’t really need one as long as I have other plans to reference as examples.

(continuing) Check out the previous plan in @plans/chat-playground.md to know about routing and architecture details. (to be continued)

I expect to see several key elements in the document. First, a rephrasing of the feature description I gave it, which helps ensure we’re aligned on requirements. Second, details on how the feature will be implemented—usually it includes some pieces of code or pseudo-code without me having to tell it to do so. Finally, commands to run to make sure the code quality is acceptable, including type checking, linting, and tests.

(continuing) Write a plan in @plans/query-builder.md, and let me validate it before starting the implementation.

The Collaborative Design Process

Sometimes, I’m not satisfied with the suggested implementation. In this case, instead of updating the plan, I tell it why it’s wrong, expecting it to change its approach.

The page should be a subroute of /explore, not /review. Also, it should be accessible only to users with the “admin” role.

It also happens that after a few back-and-forth exchanges, I realize the first suggested approach was better than the one I had in mind. This process is much more efficient than if I had started writing the code by myself and realized my approach was wrong later.

It’s a bit like discussing the plan with a colleague each time I’m about to start a new feature. More specifically, it’s like challenging my implementation plan with a junior colleague (or one who doesn’t know the codebase as well) who will question my choices. The dynamic reminds me of the rubber duck debugging technique, where explaining your approach helps you think through problems. However, it won’t suggest a radically different approach unless I specifically ask it to, which I have never tried.

But the plan document isn’t just a blueprint for the implementation. I discovered that Claude Code is much more efficient when it considers it as a living document.

The Living Document Approach

The key insight is that I don’t just ask Claude Code to write the plan—I also ask it to make it a living document while implementing the feature. I explicitly ask it to update the plan during implementation because the implementation process, and especially the type checking, linting, or test processes, can reveal that some parts of the original plan were incorrect.

I’ve developed the habit of asking it to check that the plan is up to date each time it commits code, treating plan updates the same way as running quality checks.

Make sure the plan is up to date, and commit changes.

This living document approach solves a fundamental problem with AI development: context limits. With an up-to-date plan document, I can start a fresh conversation and simply ask Claude Code to continue the implementation. This usually works great—just the document is usually enough context for a new session to pick up exactly where the previous one left off.

Continue the implementation documented in @plans/query-builder.md.

My Review Process

When the implementation starts, I review changes along the way to ensure everything is progressing correctly. However, if I’m satisfied with the progress, I can let it continue without checking as often. When reviewing the final code, the updated plan document gives me helpful hints about the technical choices that were made during implementation.

Surprisingly, I think that the fact that I need to plan my features carefully before rushing into implementation is making me a better developer overall. This happens simply because it forces me to document the implementation and think it through before jumping into code. I also find myself explaining my reasoning more clearly because I have to write it down for the AI, whereas with colleagues I would typically discuss things in person or via video call.

From Chaos to System

This workflow systematically addresses the fundamental problems I encountered with the naive approach: it creates a clear source of truth, eliminates context limit issues, and forces better architectural thinking. The living document becomes both the specification and the implementation log, creating a complete record of not just what was built, but why and how it was built.

The result is a development process that’s more thoughtful, more documented, and more reliable.

AI isn’t just serving as implementer.

It becomes a collaborative design partner.