Architecting with Claude: The Principles

A customer of mine still runs a pile of old Adobe Flex apps. Internal tools, mostly, the kind that quietly keep a business going long after everyone has forgotten who wrote them. My job was to move them to React.

It went well. Almost suspiciously well. One simple prompt per app, and each app came out converted. No Claude Code, no agent framework, no elaborate setup: just VS Code and Claude Opus 5.5, an old MXML codebase on one side and a working React app on the other.

Then my boss asked me to present to the dev team how I used AI.

That's where it got interesting. My honest answer was "it just worked." I've built dozens and dozens of apps and a lot of content with Claude, so I know what it can do. But knowing what it can do is not the same as knowing why it works, and "it just worked" is not something a team can repeat, budget for or trust in production.

So I went looking for what happens behind the scenes. Anthropic publishes a surprising amount of it: engineering articles on agents, context and evals, the platform docs, the Claude Code docs. The more I read, the more the notes turned into chapters. The result is a short book, a one-page cheat sheet, and the slide deck I used for the talk.

Quick Links

• The book: Architecting with Claude: The Principles (PDF, 74 pages)
• The cheat sheet: The twelve principles on one page (PDF, 1 page, tabloid)
• The slides: The talk version (PDF, 20 slides)

All three are free. Read them, print them, share them with your team.

What the book is (and isn't)

It's not a prompt cookbook, and it's not about one model. Models change every few months. The decisions around them don't.

The book is about architecture: the choices you make before, around and after the model call. What outcome are we actually buying? How much autonomy does this need? What is the system allowed to touch? How will we know it works? What must never happen? Who runs it after I leave?

Those questions arrive in a predictable order, so the book follows them, one chapter per phase of an AI system's life:

Phase	The question	Chapter
1. Frame	What outcome are we buying?	Start from the Outcome, Not the Model
2. Shape	How much autonomy is needed?	Use the Simplest Shape That Works
3. Configure	Which model, and what context?	Pick the Model, Then Spend Context Deliberately
4. Connect	What may it touch, and how?	Give Agents Less, Connect Them Carefully
5. Ground	Where do the facts come from?	Ground Answers in the Right Data
6. Prove	How will we know it works?	Define "Good" Before You Build
7. Operate	What does it cost, and how fast?	Make Cost and Speed Visible
8. Govern	What must never happen?	Enforce, Don't Request
9. Align	Do the people agree?	Bring People Along
10. Enable	How does the team move fast, safely?	Make the Team Faster, Safely

The twelve principles

Everything in the book boils down to twelve decisions an architect makes again and again:

1. Start from the outcome, not the model. Name the number that must move, and measure today's baseline first.
2. Verify it or contain it. Code does rules, lookups and arithmetic; Claude does the messy judgment. Unchecked output never triggers an irreversible action.
3. Use the simplest shape that works. A single call, then an augmented model, then a workflow, then an agent. Climb only on evidence.
4. Fit the model with evidence, then spend context deliberately. The smallest set of high-signal tokens, stable content first so it can be cached.
5. Grant the least capability, and authorize every hop. Remove tools before you guard them.
6. Send each question where its answer lives. Text to search, totals to a query, current state to the system that owns it.
7. Define "good" before you build. A metric, a threshold, a test set and a grader for every criterion.
8. Change one thing and measure it. Offline evals, shadow traffic, canary, A/B.
9. Attack the dominant cost, and trace every hop.
10. Enforce, don't request. If the model ignored a rule, something else must still stop the harm.
11. Say it out loud, and write it down. Constraints, trade-offs and failure rates, early.
12. Configure the team, not just the tool. Settings, permissions and hooks enforce; instructions only inform.

That's the short version. The full cheat sheet below puts the practical detail on the same page: the workflow patterns under Shape, the cost levers under Operate, and the review-by-stakes table under Govern. Download the PDF to print it (tabloid size, 11 × 17 in).

What Surprised Me

Looking back at the Flex conversions with this lens, "it just worked" turned out to have reasons:

• I had picked the simplest shape without knowing it. One prompt, one app, a human reviewing the result. No agent, no orchestration. The book's ladder says start at the bottom rung and climb only on evidence. I never needed to climb.
• The outcome was crystal clear. "Same app, same behavior, React instead of Flex" is about as measurable as a goal gets. Most AI projects that struggle never wrote that sentence down.
• The old code was the context. The best possible grounding is the thing you're replacing. Claude wasn't guessing at the business rules; they were right there in the MXML and ActionScript.
• A CLAUDE.md file informs; it doesn't enforce. If breaking a rule would be an incident, it belongs in permissions, hooks or managed settings, not in a markdown file the model reads as advice.
• People approve almost everything. Anthropic's data shows users approved about 93% of permission prompts. A human in the loop who clicks "yes" by reflex is not a control. Route review by stakes instead.
• Half the cost advice is about not optimizing the wrong thing. Halving a line that's 5% of your bill does less than trimming 10% off the one that's 60%. Batch work nobody is waiting on runs at half price.

Read the Source

The book is my synthesis, not the source of truth. These are the five Anthropic pages I'd read first:

• Building effective agents: workflows vs. agents, and why simple, composable patterns win.
• Effective context engineering for AI agents: context as a finite budget, and how to spend it.
• Prompting best practices: the official guide to writing prompts for current Claude models.
• Demystifying evals for AI agents: how to define "good" and actually measure it.
• Claude Code overview: settings, permissions, hooks, skills, and how a team shares them.

How It Was Made

With Claude, of course. I did the reading, the outlining and the arguing; Claude helped draft, fact-check against the Anthropic docs, typeset the book, lay out the cheat sheet and build the deck. Which is, in a way, the whole point: the same principles that made the Flex conversions work made the book come together in days.

This is independent work. It is not affiliated with, endorsed by, or reviewed by Anthropic.

---

Daniel Wanja is a developer and founder of Nouvelles Solutions, Inc. When not converting decade-old Flex apps to React with a single prompt, he's reading Anthropic's engineering blog to find out why that works.