The Field Guide: 14 Principles

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.

1. 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.

2. 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.

3. 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.

4. 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).

5. 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.

6. 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.

7. 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.

8. 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.

9. 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.

10. 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.

11. 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.

12. 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.

13. 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.

14. 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.