Stop Pasting Chat Logs Into Your Terminal: The Architect-Contractor Workflow for Claude
Your AI planning tool and your AI coding tool shouldn’t share a brain. Here’s the two-tool workflow that turns scattered conversations into compounding project intelligence.
TL:DR - Using Claude.ai for planning and Claude Code for building is the right instinct — but most engineers ruin it with sloppy handoffs. The fix isn’t switching tools; it’s treating Claude.ai as your architect and Claude Code as your contractor, with a structured spec file (not a pasted chat log) as the contract between them. The real unlock: a living CLAUDE.md that accumulates your architectural decisions across sessions, so Claude Code gets smarter about your project every time you open it — without you copying anything.
The Pattern That Emerges Naturally
If you’ve spent any real time building with AI coding tools, you’ve probably landed on some version of this workflow without anyone telling you to:
Open Claude.ai. Think out loud. Explore architecture options. Debate tradeoffs with yourself (and Claude). Draw diagrams. Stress-test ideas.
Open your terminal. Fire up Claude Code. Start building.
Copy-paste something from step 1 into step 2.
That third step is where most engineers silently lose 30% of the value from step 1.
Here’s the thing — the separation is correct. Planning and building require fundamentally different cognitive modes. When you’re planning, you want expansive thinking: “What are the three ways we could model this?” When you’re building, you want precise execution: “Create the migration file for this schema.” Mixing them in a single tool creates the worst of both worlds — half-baked plans that get coded before they’re finished, or coding sessions that get derailed into philosophical debates about folder structure.
The problem isn’t the two-tool approach. The problem is the bridge between them.
What Actually Happens When You Paste
When you copy a chunk of Claude.ai conversation into Claude Code, here’s what you’re actually transferring:
What makes it across: The final answer. The code snippet. The bullet-point plan.
What gets left behind: Every rejected alternative. The constraints that shaped the decision. The “we considered X but ruled it out because Y” reasoning. The edge cases you discussed. The assumptions you agreed on.
This matters more than it seems. Claude Code is a fresh instance with no memory of your planning session. When it hits an ambiguous implementation choice — and it will — it has no way to know you already resolved that ambiguity forty minutes ago in a different window. So it makes its own call. Sometimes it picks the exact approach you’d already rejected, and now you’re debugging a decision you already made.
Paste-driven development is essentially a lossy compression algorithm for architectural intent.
The Architect-Contractor Mental Model
The fix is a role separation that builders in every other industry figured out centuries ago: architects design, contractors build, and a spec document sits between them.
Here’s how that maps:
Claude.ai = Your Architect. This is your war room. You explore options, sketch diagrams, debate approaches, and make decisions. The output of this phase is never raw conversation — it’s a document.
The Spec File = Your Contract. Not a chat transcript. A structured artifact that captures decisions, rationale, implementation order, and known constraints. More on the format below.
Claude Code = Your Contractor. It receives the spec, understands the scope, and builds against it. When it hits a question the spec doesn’t answer, that’s a signal to go back to the architect, not to improvise.
The Spec File Format That Actually Works
After iterating on this across multiple projects, here’s the structure that transfers the most context with the least noise:
# Project: [Name]
## Goal
What we're building and the single sentence explaining why.
## Architecture Decisions
- Decision 1: [What we chose] — because [rationale]
- Decision 2: [What we chose] — because [rationale]
- Rejected: [Alternative] — because [why not]
## Implementation Plan (Ordered)
1. File/module — what it does — dependencies
2. File/module — what it does — dependencies
3. ...
## Constraints & Gotchas
- [Thing that will bite you if you forget]
- [External dependency or environment requirement]
## Out of Scope
- [What we explicitly decided NOT to do this round]
The “Rejected” and “Out of Scope” sections are doing more work than they look like. They’re negative constraints — they tell Claude Code what not to build, which is often more valuable than telling it what to build.
The CLAUDE.md Flywheel
Here’s the part most people miss entirely.
Every repo that uses Claude Code can have a CLAUDE.md file at its root. Claude Code reads this file automatically at the start of every session. Most people treat it as a static setup doc — “here’s the tech stack, here are the lint rules.”
But CLAUDE.md can be a living architectural record. After each planning session in Claude.ai, update your CLAUDE.md with the decisions you made:
## Architecture Decisions Log
### 2026-04-02: Auth approach
- Chose JWT with refresh tokens over session-based auth
- Reason: Need to support mobile clients hitting the same API
- Rejected: OAuth2 device flow — overkill for our user base
### 2026-03-28: Database choice
- Chose Postgres over DynamoDB
- Reason: Complex queries on relational data, team knows SQL
- Rejected: DynamoDB — would require denormalization we can't maintain
Now something interesting happens. Every time Claude Code opens your project, it reads this file and starts with the accumulated context of every planning session you’ve had. Without you pasting anything. Without you re-explaining decisions. The handoff becomes automatic.
This is the flywheel: plan in Claude.ai → distill into CLAUDE.md → Claude Code inherits the context → build → hit a new design question → go back to Claude.ai → update CLAUDE.md → repeat.
Each cycle makes Claude Code more effective on your project. The decisions compound.
The Rule That Keeps It Clean
There’s one discipline that makes this whole workflow hold together:
Don’t ask your contractor to redesign the floor plan mid-pour.
When you’re in Claude Code and you hit a genuine architectural question — “should this be a separate microservice or a module in the monolith?” — resist the urge to hash it out right there. Claude Code will happily debate architecture with you. It’s a capable model. But you’re now doing planning work in a building context, which means:
The decision won’t get captured in your planning history
You’ll forget you made it
Next session, you might make the opposite decision
Your CLAUDE.md stays stale
Instead: note the question, switch to Claude.ai, resolve it properly, update your spec, update CLAUDE.md, and then go back to building. It adds five minutes. It saves hours of inconsistency downstream.
When This Matters Most
This workflow pays the biggest dividends on projects that span multiple sessions. If you’re building a one-off script, paste away — the overhead isn’t worth it.
But if you’re working on something across days or weeks — a side project, an internal tool, an open-source library — the gap between “I paste things between tools” and “I maintain a living spec with an architectural decision log” widens with every session. By week three, the developer running the flywheel has a Claude Code instance that understands their project deeply. The developer who pastes has a fresh Claude Code every time, re-explaining context that should have been captured on day one.
The Five-Minute Version
If you take nothing else from this:
Keep planning in Claude.ai. It’s the right tool for expansive thinking.
Keep building in Claude Code. It’s the right tool for precise execution.
Stop pasting raw chat. Produce a structured spec file instead.
Update your CLAUDE.md after every planning session. It’s the persistent memory bridge.
When you hit a design question in Claude Code, go back to Claude.ai. Don’t blur the roles.
The tools are already good enough. The workflow between them is where the leverage is.