· 11 min read
How I use Claude Code: the loop, the memory files and a starter kit
By Ayush Gupta, AI Engineer in Bengaluru
Most people use Claude Code like a vending machine. They type "build me X", get 4,000 lines back, and spend the next three days debugging code they never understood.
I've built with AI coding agents every day for two years: Claude Code, Codex, Cursor. That includes an iOS and watchOS app, a GitHub App, agent tooling, and security benchmark work. The biggest lesson isn't about prompts. Claude is an extremely fast builder, and you are the architect. You decide what gets built, how the pieces fit, and what "correct" means. Claude does the typing.
This guide is the exact loop I run on every project, the files that make each session smarter than the last, and a starter kit you can paste in tonight.
1. The loop
Every feature I ship goes through six steps:
- Requirements. Claude interviews me until the what and the why are clear.
- Product design. We fix how it looks and behaves before any code exists.
- Read the design. I actually read it. If it's long, Claude turns it into a visual deck.
- Technical design. Architecture, schema, boundaries and edge cases, written down.
- Review. Claude attacks the design and later the code, as a separate pass.
- Build. Implementation with the Superpowers skills: plan, tests first, small verified steps.
It looks slow, but it isn't. Agentic work is waterfall at very high speed: each step takes minutes, and the code comes out right the first time. Skip steps 1 to 5 and you still do them, just later and more expensively, as debugging.
The split of ownership matters more than the steps. I own the architecture, the schema, the tests and the edge cases. Claude owns environment setup, dependencies, boilerplate, wiring and running the suite. When I start a hard task, I literally write that split into the first prompt:
You do: environment and Docker, dependencies, running the test suite, wiring.
I do: the architecture, the data model, what the tests must prove, and the edge cases.
Propose anything in my list; never decide it silently.If you can't explain why your codebase is shaped the way it is, you aren't using an agent. The agent is using you.
2. Decide what you're building (steps 1 to 3)
Step 1: Make Claude interview you
The most expensive bug is a confident guess about a requirement you never stated. So before any code, I make Claude ask questions.
Install the Superpowers plugin first. It's the backbone of this whole workflow:
/plugin install superpowers@claude-plugins-officialThen start every new feature with its brainstorming skill, or say it in plain words:
/superpowers:brainstorming
Read CLAUDE.md and inspect the project. Ask me focused questions about the first
working version, one at a time, as multiple choice with your recommendation and
the trade-off. After my answers, propose a small, testable plan and wait for my approval.Claude Code can ask multiple-choice questions natively, so this takes a couple of minutes of clicking, not an essay. On my last big feature it asked 16 questions. Each one closed a gap I would otherwise have found in production.
When I already know what I want, I write the requirement as an outcome plus constraints, including what not to build. A line like "No chat, no global feed, no public leaderboard in this version" is the most valuable sentence in a brief, because scope creep from the model is real.
Step 2: Fix the product design before the code
Left alone, every agent drifts towards the same generic UI. So I never let the first design be the only one:
Before building the frontend, show me 4-5 genuinely different UI directions
for this screen. I'll pick one and tweak it.Two more moves pay off here. First, ask Claude to research how established products solve the same problem before it designs anything. Second, stress-test the design against real users: "Walk through each screen as these five types of user and tell me where each one gets confused or drops off." Choosing between five mockups costs minutes. Redesigning after implementation costs days.
Step 3: Actually read the design
This is the step everyone skips. Claude writes a 600-line spec, you skim it, type "looks good", and the mismatch shows up 3,000 lines later.
I read it. Honestly, reading the spec in full is the highest-leverage thing you can do in this loop. If you know you won't read a long document, don't pretend. Make it something you will read:
Build me a really visual presentation of this design. I don't want to read that much.Claude Code can publish a private slide deck to claude.ai straight from your session; newer versions also have /slides. For my last feature, a voice-command system for a watch app, that one prompt turned a long spec into 9 slides: the idea, what you see on each device, how it works, the safety rails, privacy, and next steps. I caught two wrong assumptions on slide 6 and approved the rest in five minutes.
Other formats work too: a mermaid diagram of the logic, an architecture diagram, or a short explainer. The rule is simple. Never approve something you haven't understood.
3. Design the system, then attack it (steps 4 and 5)
Step 4: The technical design
Now, and only now, Claude designs the system. I set the frame and the hard boundaries myself:
Act as a senior staff engineer. Write the technical design and architecture for the
approved product design: components, data model, API contracts, the main flows as
mermaid diagrams, and the edge cases. Web search for the current SDK and library docs
before choosing anything. Ask me whenever an architectural choice is ambiguous.
I'll review it and say "start" once we agree.Three things make this step work:
- Boundaries in your words. "Don't put SDK or network calls in the core logic." "Authorize from the verified session, never from a client-supplied user ID." These sentences are the architecture. Claude carries them into the plan and the review.
- Current docs, not training data. Models happily use an API that was deprecated last year. Tell Claude to web search, or connect the Context7 MCP server so it pulls live library docs.
- Difficulty per decision. "Tell me the implementation difficulty and risk of each decision I made." That's a cheap way to find the decision that will hurt later.
Step 5: Review as a separate pass
The model that wrote something is the worst reviewer of it. So review is its own step with its own instructions, and I say explicitly that it shouldn't fix anything while it audits.
For the design: open a fresh session or a subagent, give it the spec, and ask it to find the gaps, contradictions and missing edge cases. I also bounce specs between models. Codex reviewing a Claude spec, and the other way round, catches a different class of mistake.
For the code, Claude Code ships a review command with effort levels:
/code-review xhigh
Find every issue. Do NOT fix anything yet. Group them into high, medium and low,
each with a one-line fix idea.Then fix and review again: "Fix the high ones, then run /code-review again on the fixes." For the biggest changes there's /code-review ultra, a multi-agent review that runs in the cloud.
I also keep a security review running on every change through Anthropic's security-guidance plugin. On one feature it caught a push-token takeover, a race condition in a write path, a privacy leak, and a sign-out that failed open. All four passed the happy-path tests. None of them would have survived a real user.
4. Build it in versions (step 6)
Let the skills drive
With an approved and reviewed design, the Superpowers skills take over:
- writing-plans turns the design into small tasks, each with exact files, code and a check.
- using-git-worktrees gives each piece of work its own isolated branch, so nothing touches main by accident.
- test-driven-development writes each test first and watches it fail before writing the code.
- subagent-driven-development or executing-plans works through the tasks one at a time, reviewing as it goes.
- systematic-debugging finds the root cause before anyone proposes a fix.
- verification-before-completion means nothing is called done without proof.
- finishing-a-development-branch runs the tests, then merges, opens a PR, or cleans up.
My last big feature became an 8-task plan. Each task got its own worktree, from the backend through to the TestFlight build, and every test was written to fail first. When the plan is solid, I set the finish line and let it run: /goal don't stop until this is implemented and on TestFlight.
For parallel work, I run a second Claude session in its own worktree with ground rules: "Work only in your worktree. Commit only when I say so. Don't push." Then I ask the main session a question that saves hours: "What can I hand to the other session in parallel without conflicts?"
V1, then V2, then V3
I never build the whole thing in one go. V1 is the thinnest version that includes the important base: core data model, main flow, tests passing. Then I review it, run it, and use it. V2 and V3 add what V1 taught me. A big-bang build gives you nothing that works end to end and a diff nobody can review.
Writing it down helps: "Let's decide what launches as V1 and design around that." Then keep the next versions in a file like IMPROVEMENTS_V2.md, so the next session starts from a list instead of your memory.
Verify with your own eyes
"All tests pass" is not the same as "it works". Before I accept a version, I see it:
- Run it. "Open the simulator and take me through it from onboarding." That's how I've caught missing screens that every unit test was happy with.
- Use the browser. Start Claude Code with
claude --chromeand it can click through your web app, read console errors and take screenshots. - Inspect the tests. "Show me the exact inputs you're testing against." Agents sometimes test the easy case and call it done.
- Read the logs. "Walk me through the logs step by step." That's how I found tasks being routed to the wrong model.
- Quiz yourself. At each milestone I ask Claude for a short multiple-choice quiz on what changed. Under a deadline I skip it. When I don't skip it, I actually understand my codebase.
5. FACTS, FLOW, DECISIONS: memory that compounds
Every new Claude session starts with amnesia. Without help, it relearns your repo, makes the mistake it made yesterday, and burns tokens searching the web for the fix it already found last week. Three plain Markdown files fix that, and Claude keeps them updated as it writes code.
FACTS.md holds the repo truths and the hard-won fixes: patterns specific to this codebase, every mistake Claude made with its root cause and fix, and a "retired" section for facts that stopped being true.
FLOW.md says where we are: the current step, the next action and who owns it, any blockers, the whole system in one line, and a short log. Any new session, or any teammate, can pick up from this file alone.
DECISIONS.md records why the code looks the way it does. Each decision gets the options considered, what we chose and why, what it locks in, and a mermaid diagram whenever structure or flow changed. Diagrams are much faster to understand than paragraphs.
The part that makes it compound is one global rule:
If an issue isn't solved in 1 run + 2 retries, stop. Check FACTS.md for a known fix. If it isn't there, web search. Once it's fixed, write the symptom, cause and fix back into FACTS.md.
That rule turns every bug into a permanent lesson. The first time, it costs a search. Every later time, it costs one file read. Across sessions you get a recursive self-improvement loop: the agent stops repeating mistakes, and your token bill drops because it stops searching for things it already knows.
Two refinements I added later:
- Unlearn, too. When new evidence says an old fact is wrong, Claude moves it to "retired" with the reason, instead of deleting it. Otherwise the same bad idea comes back two months later.
- Restart from the files. A fresh session or a teammate gets one prompt: "Read FLOW.md, then FACTS.md, then DECISIONS.md, and pick up from the current state. The code wins when the docs disagree."
6. Starter kit
Paste this into ~/.claude/CLAUDE.md so it applies to every project. One honest caveat: CLAUDE.md is context, not enforcement. Claude follows it well, but for anything that must never happen, use a hook.
# How we work
- I own architecture, schema, tests and edge cases. Propose; never decide those silently.
- Ask me questions whenever in doubt: one at a time, multiple choice, with your recommendation.
- If an SDK, library or architecture choice is ambiguous or might be outdated, web search
(or use context7) before choosing. Never say "can't be done" without searching first.
- Ship V1 first: the thinnest version with the important base and passing tests. Then V2, V3.
- Keep FLOW.md and DECISIONS.md updated in the same commit as the code they describe.
Add a mermaid diagram to a DECISIONS entry whenever structure or flow changed.
- Debugging rule: if an issue isn't solved in 1 run + 2 retries, read FACTS.md.
If the fix isn't there, web search. Once fixed, add symptom, cause and fix to FACTS.md.
- Never claim done without evidence I can see: test output, a screenshot, or logs.Then create these three files in your repo root and tell Claude to keep them current.
# FACTS: repo truths and hard-won fixes (read before retrying anything)
## Patterns in this repo
- <e.g. Core logic never imports SDKs; services own all network calls>
## Mistakes and learnings
- <date> | Symptom: <error text> | Cause: <why> | Fix: <what worked> | Ref: <commit>
## Retired (no longer true)
- <old fact>, retired <date> because <evidence># FLOW: where we are
## Now
- Step: <n, name>
- Next action: <what>, owner: <me or Claude>
- Blockers: <none>
## The system in one line
<request> → <entry point> → <core logic> → <storage> → <response>
## Log (newest first)
- <date>: <what we did> → <what it showed># DECISIONS
## D-001: <title> (<date>, accepted | superseded by D-00x)
- Context: <the problem>
- Options: <A>, <B>, <C>
- Chose: <x>, because <reason>
- Consequences: <what this locks in, what to revisit>
- Diagram: a mermaid block like the one belowflowchart LR
App --> Service --> API[(Backend)]And the loop, one prompt per step:
/superpowers:brainstorming, then "Ask me questions one at a time, with options and your recommendation."- "Show me 4-5 different design directions before building anything."
- "Build me a really visual presentation of this design."
- "Act as a senior staff engineer. Write the technical design with mermaid flows. Web search before choosing libraries."
/code-review xhigh: "Find everything, fix nothing yet, group by severity."/superpowers:writing-plans, then build V1 with tests first, in a worktree, and verify it with your own eyes.
That's it. None of it is magic. It's what a good tech lead does with a very fast junior engineer, except the junior never sleeps and the whole loop takes an afternoon.
If this helped, I post how I build with AI agents on Instagram, X and LinkedIn. Send me what you ship with it.