15 Principles for Building with AI - Playbook

Short, quotable, teachable. Each pairs a one-liner with the RadiusOS evidence. This list is the spine of the course; modules are built around it.

AI changes the cost of execution, not the need for judgment. It removes the cost of writing code. Your leverage moves to deciding, reviewing, and integrating.
Briefing is the skill, not coding. The clearer the prompt and the more context loaded up front, the less churn on the back end. Most time "saved" gets reinvested in better specs.
CLAUDE.md is the moat. The project brief is the highest-leverage artifact in the repo. It accreted sentence by sentence as the founder learned what the agent needed reminding of. Without it, the agent writes generic B2B slop and leaks multi-tenant data.
Ship small, reversible. 3 to 10 PRs a day, each small enough to hold in your head. The cost of being wrong is reverting one commit. Small PRs are also what make real review possible (see #9).
Build-pass is not ship-pass. Type-checks and green CI are necessary, not sufficient. A build passed and the page still crashed when a user clicked the button (the hooks-ordering prod crash). Verify by using it.
Cost discipline is a feature. Haiku-first, cache the system prompt on every call, batch anything the user will not see for 5 minutes, gate free-tier spend behind a DB pool with a killswitch. The difference is roughly $0.30 vs $3.00 per user per month.
Marketing claims must be true today. Either pure positioning or backed by verifiable data plus a working feature. Build gates (check-marketing-coverage, check-help-articles, check-no-em-dashes) fail the build to enforce it. Audit every surface when a feature's tier or behavior changes.
Worktrees: parallelism vs control. Worktrees let multiple branches (and multiple agents) run at once in separate folders sharing one .git. The benefit is parallel throughput; the risks are operational (wrong directory, missing per-tree .env, wrong deploy target, orphaned trees). RadiusOS gotcha: claude/* branches deploy to a separate Vercel project, not radiusos.ai. Cap parallelism at your review-and-merge throughput - more agents than you can review is risk backlog, not speed.
Approval is the governor. As AI writes more, control lives in what you let through. Build a graduated ladder, cheapest gate first: tool-permission allowlists and plan mode → diff review → automated prebuild gates → manual smoke → draft-PR-then-explicit-merge → deploy approval → confirm-first for anything irreversible. Match rigor to blast radius; never auto-approve the irreversible. Anti-pattern: approval theater (clicking yes without reading). Meta-example: RadiusOS's flagship feature is a customer quote approval flow - the same principle, pointed at the user.
Claude Code is multimodal - show, don't describe. It has vision. Drag and drop or paste screenshots, mockups, error dialogs, logs, and diagrams; it reasons over them alongside the code. When something is visual (a layout bug, a clipped value, a confusing flow), an image collapses three rounds of text into one shot. Live example: the cost-column clip bug was diagnosed and fixed from a single dropped screenshot (PR #486). Caveats: it is one frame, not the live app (pair with a sentence for dynamic/timing bugs); crop and annotate; and scrub PII/secrets from screenshots before sharing.
The journey is recoverable from receipts. Git tells you what shipped, the pass-offs tell you what was decided, and the Claude transcripts hold the actual prompts and reasoning. The literal first prompt survives only in chat/session history, not in the repo. Export and braid the three together for the real story.
Distribution ships with the product, not after. One MCP layer, two front doors (the public server external clients hit, and the in-product chat that bridges to it in-process). Build in public; every feature is also content.
Discipline is forged from failure: convention to miss to gate. Do not trust a rule you have to remember. Almost every build guard RadiusOS has today was written the day after the thing it prevents shipped to production: the db-push killswitch after the outage, the marketing-coverage and help-article gates after Walk & Talk shipped uncovered, the feature-visuals gate after blank cards shipped, the soft-org-gate check after a cross-tenant leak. The honest arc of building with AI is that the model writes fast and the guardrails are what you add after it burns you. If something matters, make it fail the build. See phase2-decisions.md for the full evidence.
Building is commoditized; distribution is the moat. Build the SEO flywheel from day one, and enforce it. When anyone can ship a product with an AI assistant, "I built it" stops being an advantage. The durable edge is being found. RadiusOS captured personas in a file (docs/personas.md), then shipped every feature with a help article and a search-intent blog post, and every persona with a landing page that names its pain (~38 help articles, 20 blogs, 22 vertical landing pages). The believability comes from enforcement: build gates (check-help-articles, check-marketing-coverage, the vertical-copy rule) fail the build if the distribution work is skipped, so the flywheel cannot rot. This is principle #13 pointed at growth. See modules/09-distribution-flywheel.md.
Write so it sounds human, not machine. When anyone can generate fluent prose, fluent stops being worth anything; what is scarce is writing that does not read as auto-generated. The no-em-dash rule that protects the product copy is one instance of a wider cadence discipline: limit the "it is not X, it is Y" construction, do not end every section on a tidy aphorism, and do not let parentheses smuggle back the interrupted rhythm the dash ban removed. This very playbook tripped all three in a first draft and was revised before release; the rules now live in the project brief and in a slop-check reporter. It stays judgment, not a gate: only the em-dash rule fails the build, because mechanically flattening the rest just trades one machine rhythm for another. See modules/07-marketing-honest.md.