Small projects forgive an idea dump. Describe what you want in a few prompts, let Claude build, and patch the rough edges later. Big projects don't. Once real users, client data, permissions and long-term maintenance are involved, the hard part stops being code and becomes structure and decisions.

Why the idea dump breaks

  • Claude plans against wrong assumptions. Without research, it fills gaps confidently, and the plan inherits every guess.
  • Everything competes for context. One session holding research, requirements and code loses track of what matters.
  • The output is too big to review. A giant first pass hides decisions you never agreed to.
  • Changes get expensive. Architecture you didn't choose on purpose is hard to undo once features depend on it.

Four phases, separate sessions

Start each phase in a fresh session. Each one produces a document the next phase reads.

1. Research, before any code

Ask Claude to split the research into a few areas, such as similar products, the tools and APIs involved, data handling and industry conventions. Have it research the areas in parallel with subagents, then verify the main findings with fresh subagents that check each claim against sources.

Output: research.md with a short index at the top, most important finding first. Later sessions load only the section they need.

2. Specification

Have Claude interview you, one question at a time, until the goals, constraints, deal-breakers and scope boundaries are clear. Claude Code has a built-in multiple-choice question tool, and asking for it by name keeps the interview structured.

Output: a SPEC.md for the whole project, plus one feature file for each piece small enough to plan in a single session.

For client work, get sign-off on the spec before architecture. Skipping that step is how you end up rebuilding.

3. Architecture and roadmap

Write down the decisions that everything else depends on: data model, permissions, where data lives, integrations. Anchor them on a handful of principles, like "client files never leave the client's region" or "every action is logged".

Then order the work in vertical slices, where each phase works end to end and has a clear exit condition.

Output: architecture.md and roadmap.md.

4. Build one feature per session

For each feature file:

  1. Start a new session and enter plan mode with Shift+Tab or /plan. Claude explores and proposes without editing files.
  2. For a large codebase, ask it to split exploration across subagents before it plans.
  3. Approve the plan, build, test against the feature's exit condition, and commit.
  4. Update the docs if anything changed, then start the next feature fresh.

Keep context lean as the project grows

  • Keep CLAUDE.md short. Anthropic suggests under about 200 lines: what the system does, what it must never do, locked decisions and naming conventions.
  • Put folder-specific rules in folder-level CLAUDE.md files. Claude Code loads those only when it reads files in that folder.
  • Keep project knowledge in a docs/ folder. Research, spec, architecture and roadmap live there, not in chat history.
  • Treat every client conversation as context. Meeting notes and decisions go into the docs as soon as they happen, so the next session builds on current information.

Where the chat app fits

The Claude or ChatGPT chat apps are good for early thinking: talking through the problem, who it's for and what matters, before anything is written down.

Don't use chat to write code you paste into Claude Code. Chat can't see your repository. Claude Code can, and it writes code against the real files.

A second model is also useful for pressure-testing a plan. Paste in the spec or architecture and ask what's missing or risky.

Starter prompts

Research:

PROMPT / COPY-PASTE
This session is research only. Don't write code.
Project: [one-paragraph description].
Split the research into 4-5 areas, research them in parallel with subagents, then verify the key findings with fresh subagents against sources.
Write research.md with an index at the top, most important finding first.

Specification:

PROMPT / COPY-PASTE
Read the index of research.md. Then interview me one question at a time using your multiple-choice question tool.
Cover goals, users, constraints, deal-breakers and what's out of scope.
Then write SPEC.md and one feature file per piece that can be planned in a single session.

Build:

PROMPT / COPY-PASTE
Read CLAUDE.md, architecture.md and features/[feature].md.
Plan this feature only. List the files you'll change, the risks, and how we'll know it's done.
Wait for my approval before editing anything.

Go deeper: Subagents · Claude Code Commands I Use on Repeat · How I Keep My Claude Code Setup From Drifting