One of the biggest changes compared to my traditional way of programming is that I now spend a lot of time in the planning phase. Before it wasn't necessary, with a rough idea of what I needed to do and the intuitions I developed about architecture and requirements over the years, I could plan a bit and jump into coding, solving problems as they came up.

LLMs need as much clarity as possible before getting to work, which means I spend much more time upfront defining what's going to be done. Depending on the size or complexity of the task, I have three planning modes.

Oneshot

For very simple things ("change the color of this"), I just ask Claude directly and that's it. I try to be as clear as possible within a single prompt.

I usually do oneshots mainly for maintenance tasks, like rebasing, asking it to fix some warnings appearing in the logs, and things like that. Also when I want to make minimal changes to something that's already working, install a dependency, etc.

Beyond something that can be determined in a single sentence, you need more infrastructure, otherwise Claude Code (or another agent) doesn't have enough clarity and can do anything.

Plan Mode

For intermediate tasks I use Claude Code's Plan Mode. The trick I found for an efficient requirements definition workflow is to tell it:

"Ask me questions, one by one, start with the first one."

This makes Claude ask me one thing at a time instead of throwing a block of questions at me. It's much more natural and lets me respond concretely without having to worry about accidentally sending the message instead of making a new line.

With each model update I'm more surprised by the level of detail in the questions, and how these conversations often lead me to architectures that are better than what I had been thinking.

Many times it asks questions I don't have a concrete answer to, and I ask it to investigate and give me suggestions, this works really well.

Eventually, the answers get consolidated into the plan that Claude Code generates, and then it executes.

Sometimes, if I want to keep the discussion because it was good, I ask it to create a markdown file in docs with all the questions and answers I gave.

Speckit for Complex Tasks

For more complex things I do several sessions of questions and write them into a SPEC.md document. Then I use this document to feed Speckit.

Speckit has a complete workflow for generating specification documents: specify -> clarify -> plan -> tasks -> analyze. It works really well for complex things I want documented in the repository.

Once I get to analyze and everything is in order (reading through and validating it's correct), I commit the spec and create the PR before running implement. This is to have a quick checkpoint to reset to if the implement goes off the rails and I need to run clarify again.

When during implement I see the spec wasn't specific enough and Claude does something wrong, I revert and go through another clarify loop. If it only deviates a bit, I ask it to fix it and repair the spec to match.

I used to write ADRs¹ (also asking Claude Code to write them), but now I'm sticking more with using specs as executable specifications rather than filling the repo with architecture documentation, since I can reference specs as the source of truth about the architecture anyway.

Deciding Which Mode to Use

I'm not sure I have a very defined heuristic for when to use each mode, I guess I have a sense developed over the years of the relative size of a task.

For very small MVPs I use plan mode, but if I want to build a slightly more complex app in one go, I use speckit, and for large projects it depends on the size of the task and whether I think having the spec will be useful in the future.

Markdown as the Main Interface

Something I discovered is that markdown files are the best interface for interacting with Claude Code.

For example, I tell Claude to explain how such and such part of the code works. If I'm satisfied with that description, I save it in a file in docs/ or as CLAUDE.md in the directory that contains the feature. Then I can reference it without having to go through the whole investigation again.

It's like caching knowledge. The agent investigates, documents, and then I can reference that documentation in future conversations.

Code review agents also generate reports in markdown that I can reference later. Everything ends up being text files I can version, search, and reuse.

What's Next

With specifications defined, the next step is execution. But Claude Code isn't a single monolithic agent: it's an extensible system with specialized agents, skills you can invoke, and commands that automate repetitive tasks.

In the next post I'll cover how I use the different Claude Code agents, how I create my own skills, and how I automate tasks with custom commands.

---