Sean’s Thoughts
Field guideFull-stack SaaSUpdated July 21, 2026

The Founder’s Field Guide for Leveraging the Sh*t out of Agents

Lessons learned from a technically non-technical CEO that has never written a line of code by hand.

A business-school case study, technical field manual, and calm first-week playbook for founders building with Claude Code and Codex.

Three systems, one operating model

Read front to back for the complete framework, or use these lenses to enter where your current venture is most fragile.

Entity, money, identity, records

Business operating system

Formation, banking, collaboration, insurance, meetings, contracts, payments, and financial control before code outruns the company.

Architecture, trust, UI, operations

Full-stack product system

An exact modern baseline, its tradeoffs, and the boundaries that turn one repository into a durable modular monolith.

Law, skills, hooks, proof

Agent control plane

How Claude Code, Codex, persistent runtimes, and parallel workers become measurable operating leverage instead of prompt roulette.

Brass tacks

So you have an idea that you’ve validated—or you’re working on a new venture that is already proven.

You know the customer, the painful job, and roughly what someone will pay to make that job easier. You can describe the product without hiding behind the words platform, ecosystem, or AI-powered. The next temptation is to open a coding agent, type “build the app,” and watch a surprisingly convincing demo appear.

Do not confuse that moment with having a software company.

A demo proves that a model can produce a plausible interface. A company needs a system that can preserve customer data, collect money, recover from failure, explain itself to the next person, and accept thousands of future changes without becoming a haunted house. Agentic engineering makes that system dramatically faster to create. It does not make the system optional.

This is the useful way to think about the opportunity:

Agents lower the cost of converting clear judgment into working software. They do not eliminate the need for clear judgment.

The founder’s job is no longer to personally manufacture every line. The job is to define reality precisely enough that a machine can help build it, install rails that keep the machine inside that reality, and create feedback loops that make every future session more capable than the last.

This field guide explains how to do that. It covers the business operating system around the code, the exact full-stack technical baseline I would choose today, the repository documents and automated gates that make agents reliable, the difference between a coding assistant and an agent runtime, the most common architectural traps, and a hands-to-keyboard sequence for your first week.

This stack reflects lessons learned while building real products, including Promptable.

What “technically non-technical” means here

It does not mean incurious. It does not mean outsourcing every decision. It means you may not write production code manually, but you learn to reason about systems: state, contracts, failure modes, security boundaries, component ownership, tests, deployment, and customer impact.

You should be able to answer:

  • What is the source of truth for this data?
  • Which layer is authorized to change it?
  • What happens when an external service is slow or down?
  • How does the interface represent loading, empty, error, partial, and success states?
  • Which automated check would prevent this exact bug from returning?
  • What evidence proves the agent did what it claims?

Those are engineering questions. None require you to enjoy typing semicolons.

The operating loop

The best founder-agent relationship is not “prompt, pray, and refresh.” It is a loop in which business evidence becomes a narrow product decision, the decision becomes repository truth, the agent implements a thin slice, automated and rendered proof expose the gaps, and customer behavior updates the next decision.

A continuous loop from customer evidence through a product decision, repository law, agent implementation, proof, release, and observed behavior.

Open the full-size diagram · Speed compounds when customer evidence and implementation proof update the same operating loop.

The speed comes from tightening this loop, not from making the first generation larger.


Part I — Choose the stack before the stack chooses you

1. Start with constraints, not brands

Technology choices feel permanent when you are new and surprisingly reversible when you understand the boundaries. The dangerous choices are not usually “Postgres versus another competent database.” They are hidden coupling, missing contracts, unowned state, and operational commitments you did not know you were making.

Before comparing tools, write one page that answers:

  1. Who is the customer? Individual, team, enterprise, consumer, regulated operator?
  2. What data enters the system? Public text, customer files, payment data, health data, credentials, proprietary company information?
  3. What must happen synchronously? What does a customer need before the current screen can continue?
  4. What can happen asynchronously? Imports, email, AI generation, indexing, malware scanning, cleanup, reports?
  5. What is the collaboration model? One user, one workspace, many workspaces, guests, role-based access?
  6. What is the failure budget? A lost draft is annoying. A duplicated charge or cross-tenant data leak is existential.
  7. What does distribution require? Search-indexable public pages, authenticated dashboards, browser extensions, mobile apps, API access?
  8. Who will operate this in six months? You, a cofounder, contractors, a small engineering team, or mostly agents?

These constraints select the architecture. The logo on the database comes later.

A compact decision rubric

Score every material choice against six questions:

DimensionAskPrefer
ReversibilityCan we replace it behind a local adapter?Small interfaces and portable data
LegibilityCan a new human or agent locate the truth quickly?Conventional structure and explicit docs
Operational weightWhat must we monitor, patch, back up, and recover?Managed infrastructure until scale proves otherwise
Security boundaryDoes it enforce authorization or merely display it?Server and database enforcement
Feedback speedHow quickly can we prove the change locally and in CI?Deterministic installs and fast tests
Economic fitDoes the cost scale with value or surprise us before revenue?Transparent usage and exit paths

No choice wins every column. The point is to make the trade instead of inheriting it accidentally.

A decision tree that chooses data, asynchronous work, rendering, and contract boundaries from product constraints.

Open the full-size diagram · Start with customer and risk constraints; let them select infrastructure instead of beginning with vendor logos.

2. Build a modular monolith first

For a new full-stack SaaS product, my default is one repository, one primary web application, one database, and a separately runnable worker process in the same codebase. This is a modular monolith.

It gives you:

  • one pull request for a vertical feature;
  • one type system across browser, server, and worker boundaries;
  • one place for agents to read repository law;
  • atomic refactors while the domain is still changing;
  • fewer deployments, credentials, dashboards, and failure modes;
  • enough internal structure to extract a service later if reality demands it.

The word modular matters. Route handlers should not contain the whole business. UI components should not call the database. Email jobs should not be hidden inside button-click requests. Modules need explicit responsibilities even when they share a repository.

Start with folders that communicate those responsibilities:

src/
  app/                 # routes, layouts, server-rendered composition
  features/            # product capabilities and their UI composition
  components/
    ui/                # owned primitives and semantic adapters
    system/            # reusable product-level patterns
  server/
    api/               # request parsing, auth, response mapping
    services/          # business operations
    repositories/      # persistence boundaries
    auth/              # identity and authorization helpers
    jobs/              # queue producers and job definitions
  workers/             # job consumers
  lib/                 # narrow cross-cutting utilities
openapi/               # backend-owned API description
supabase/migrations/   # append-only database history
docs/                  # durable architecture and product law

Microservices become appropriate when independently scaling, deploying, securing, or owning a domain creates more value than the coordination cost. “We may be big someday” is not that evidence. A service boundary before a stable domain often gives you distributed confusion.

3. Learn from two opposite forms of maturity

You will encounter two common codebase archetypes.

The first is operationally mature but structurally weathered. It has customers, migrations, billing webhooks, storage, queues, security patches, and a wide test suite. It also has older framework versions, semver drift, duplicated frontend patterns, handwritten API calls, and documentation that describes a younger system.

The second is structurally modern but operationally incomplete. It has exact dependency pins, a beautiful token system, owned components, excellent agent instructions, browser evidence, and a generated-client direction. It may not yet have real tenancy, durable workers, billing recovery, or years of ugly production edge cases.

Neither is “better.” They have matured along different axes.

ConcernOperationally mature systemStructurally modern foundationWhat to carry forward
DataReal schema history and tenant policyClean but thin contractsReal authorization patterns, documented cleanly
BackendServices, jobs, retries, webhooksBetter boundary intentionsProven operations behind explicit interfaces
FrontendFeature-rich, often inconsistentGoverned tokens and owned componentsModern ownership plus real states
ToolingStable but may be datedExact and reproducibleExact current baseline with upgrade policy
TestsDeep product historyStrong visual and accessibility gatesBoth behavioral depth and rendered proof
AgentsInstructions may be sparseRepository law may be excellentMake operational truth machine-discoverable

A two-axis matrix comparing operational depth with structural clarity and placing the target architecture high on both axes.

Open the full-size diagram · Production learning and structural clarity are independent forms of maturity; the strongest foundation carries both forward.

The target is not a forced code merge. It is a merger of learned constraints: production-grade backend instincts, disciplined frontend ownership, and repository governance that lets agents see both.

4. Pin the foundation; abstract the volatile edge

Use exact versions for the core toolchain. A lockfile tells you what resolved on one install; exact package.json versions tell collaborators and agents what you intended to resolve on the next one.

Pin:

  • framework, runtime, TypeScript, React, CSS toolchain, UI primitives;
  • database and auth clients;
  • job and payment SDKs;
  • test runners and linters;
  • packages with beta or rapidly evolving APIs.

Upgrade deliberately, in a dedicated change with release notes, migration notes, and full verification. Do not let a feature branch quietly upgrade the compiler.

At the same time, wrap volatile providers behind small local modules. Your application should call sendTransactionalEmail, not scatter provider-specific SDK calls across route handlers. It should call generateStructuredResult, not bind every feature to one model identifier. Abstraction earns its keep where change is probable and the local contract is clear.

Do not manufacture generic abstractions for stable domain language. WorkspaceInvitationService is legible. UniversalEntityActionManager<TContext> is usually a tax paid to nobody.


Part II — The business operating system around the code

5. A company is part of the technical architecture

An agent can build a checkout page before you have a legal entity, a bank account, an owner for customer support, or a way to reconcile the money. That is not speed. It is deferred coordination.

The business stack should create a clean chain from identity to money to records:

A business operating system connecting entity formation, banking, identity, work, payments, books, contracts, risk, and decisions.

Open the full-size diagram · The company around the code needs the same clear ownership, records, and control boundaries as the application.

Here is a practical founder stack. These are opinions, not universal endorsements.

JobDefaultWhy it earns a placeImportant boundary
FormationStripe AtlasFormation workflow, standard documents, EIN and founder-equity mechanics in one placeIt is not your lawyer, accountant, or tax adviser
Banking and spendMercuryStartup-oriented banking interface, cards, transfers, invoices, and spend visibilityMercury is a fintech company; banking services come from partner banks
Identity and collaborationGoogle WorkspaceDomain email, Calendar, Meet, Drive, Docs, and Sheets under managed accountsTurn on MFA, recovery controls, groups, and offboarding immediately
InsuranceCorgiA founder-oriented path to understanding and purchasing business coverageCoverage needs are company-specific; read exclusions and limits
Operating modelClaude, Codex, Excel, and Google SheetsFast scenario analysis, reconciliations, forecasts, and board-ready modelsModels can be wrong; preserve formulas, sources, review, and professional books
PaymentsStripeDeep payment, subscription, tax, invoicing, and webhook infrastructurePayment state belongs on the server and must reconcile from webhooks
Merchant-of-record optionPolarWorth evaluating when merchant-of-record simplicity fits the businessCompare product fit, geography, tax handling, margins, and exit path
Contract reviewCrosbyAI-assisted contract workflow can make routine review fasterMaterial agreements still deserve qualified counsel and human accountability
Domains and DNSNamecheapStraightforward registration and DNS managementRegistrar access is a crown-jewel account; use MFA and renewal protection
Meeting memoryGranolaTurns founder calls into searchable notes without converting the meeting into clerical workFollow consent, confidentiality, retention, and customer-policy requirements
Code and change historyGitHubCode hosting, pull requests, issues, actions, and a durable audit trailProtect the default branch and treat admin tokens as production secrets
Local model ecosystemHugging FaceModels, datasets, model cards, and tooling for experiments that can run locallyInspect licenses, provenance, hardware needs, and data-handling implications
EquipmentApple laptop plus external monitorsExcellent battery life, Unix tooling, local model experimentation, and enough screen space for parallel evidenceBuy for workload and reliability, not as a substitute for good system design

The agent subscriptions

At the time of writing, the opinionated power-user setup is:

  • Claude Max 20x at $200 per month, primarily for Claude Code and long, demanding research or implementation sessions.
  • ChatGPT Pro at $200 per month, primarily for Codex, independent review, research, and a second model family with different strengths.

That is $400 per month before API usage. For a founder who uses both as daily production tools, the useful comparison is not another consumer subscription. It is the cost of engineering throughput, research, QA, and cognitive leverage. For an occasional builder, start lower and upgrade only when limits interrupt valuable work.

Subscriptions and API billing are different budgets. A plan may include an interactive coding surface without covering every programmatic model call your product makes. Track:

  • human-facing subscriptions;
  • production inference usage;
  • development and evaluation usage;
  • third-party agent-runtime usage;
  • local hardware and electricity where local models matter.

Granola is a business system, not just a note taker

Customer calls contain product requirements, language for marketing, objections, security concerns, implementation details, and commitments. The mistake is letting all of that remain trapped in memory or a chronological pile of transcripts.

After every important conversation, convert the notes into one or more durable objects:

  • a customer evidence entry;
  • an updated opportunity or risk;
  • a product decision;
  • an exact commitment with owner and date;
  • a quoted phrase approved for external use;
  • a repository issue or specification.

The meeting tool captures. Your operating system routes.

6. Use agents in finance without pretending they are accountants

Claude and Codex are excellent at explaining a workbook, generating formulas, checking reconciliation logic, normalizing transaction exports, building scenarios, and writing the narrative behind a forecast. They are also capable of confidently propagating a false assumption through twenty beautifully formatted tabs.

Use a controlled workflow:

  1. Keep raw exports immutable.
  2. Put transformations in explicit formulas or scripts, not invisible manual edits.
  3. Label assumptions, sources, units, periods, and owners.
  4. Reconcile beginning balance + inflows − outflows = ending balance.
  5. Add checks that fail loudly when totals, dates, or categories drift.
  6. Have the agent explain every material formula in plain English.
  7. Save versions in Git when practical, or use the file platform’s revision history.
  8. Let a qualified accountant own tax filings, formal books, and policies that require professional judgment.

The same pattern applies to contracts, security questionnaires, insurance, and HR: agents prepare, compare, organize, and surface risk. Accountable professionals decide where the law, money, or customer trust requires them.

7. Protect the control plane on day one

Your highest-risk accounts are the domain registrar, company email administrator, GitHub organization, cloud host, bank, payment processor, password manager, and production database. Losing any one can stop the company.

Set up:

  • hardware-backed MFA where supported;
  • a business password manager with shared vaults and recovery policy;
  • separate individual accounts rather than shared logins;
  • least-privilege roles;
  • two trusted administrators for recovery, when the team allows it;
  • protected domains and automatic renewal;
  • secret rotation and an offboarding checklist;
  • an inventory of vendors, data access, owners, and renewal dates;
  • backup codes stored outside the device you use every day.

Do not paste production secrets into chats, issues, screenshots, or repository files. A coding agent should receive credentials through environment or secret-management boundaries, and only the credentials needed for the current scope.


Part III — The full-stack baseline I would choose today

8. The exact foundation

For a greenfield full-stack SaaS application in July 2026, this is a coherent baseline—not a requirement that every package survive forever.

LayerRecommended baselineWhy
Package managerBun 1.3.14, exactFast installs, scripts, and a single lockfile; pin it in packageManager
Production runtimeNode.js 24 LTSConservative production runtime with a long support window
Web frameworkNext.js 16.2.10 App RouterCurrent stable foundation, server rendering, route handlers, metadata, and improved Turbopack behavior
UI runtimeReact 19.2.7Current stable React line aligned with the framework
LanguageTypeScript 6.0.3, strictModern checking without treating an emerging compiler generation as a casual upgrade
CSSTailwind CSS 4.3.3CSS-first configuration, native custom properties, OKLCH-friendly theming, modern browser primitives
Componentsshadcn-owned source on Base UI 1.6.0Accessible behavior from primitives; visual and compositional ownership in the repository
Database and authSupabase Postgres + Auth + RLSManaged relational data, identity, migrations, and database-enforced tenant boundaries
API contractOpenAPI + generated TypeScript clientBackend owns the contract; frontend and agents stop guessing
ValidationZod at request and domain boundariesRuntime data is not made safe by TypeScript alone
Server stateServer Components first; TanStack Query where interactivity needs a cacheAvoid a global client cache until it earns its complexity
Local UI stateURL → server → component → context → storeChoose the narrowest durable owner; add a global store last
QueueBullMQ + managed Redis when durable async work appearsRetries, concurrency, scheduling, and job visibility
Object storagePrivate S3-compatible bucketsCheap durable objects, presigned access, portable API
BillingStripe Checkout Sessions + webhooksLet Stripe own payment UX and authentication where possible
Transactional emailResend behind a local adapterSimple delivery surface without provider calls throughout the domain
AIA local policy layer over provider SDKsCentralize model choice, moderation, budgets, logging, and fallbacks
Unit/integration testsVitestFast TypeScript-native behavioral tests
Browser testsPlaywright + axeRendered behavior, responsive layouts, focus, and accessibility evidence
Lint/formatBiomeOne fast tool for a broad baseline; supplement with architectural checks
HostingVercel for web; managed worker/runtime as neededLow operating burden at the beginning, with explicit worker boundaries

Exact versions are a snapshot. The policy is more durable: choose a supported stable line, pin it, write down why, and upgrade intentionally.

Why Next.js 16 instead of 15

A production system already stabilized on Next.js 15 may rationally stay there until an upgrade window. A new system should not inherit that migration merely because the older system is successful.

Next.js 16.2 includes framework and Turbopack improvements that matter to daily agent loops: faster starts, clearer diagnostics, and a current contract for App Router behavior. Next 16 also makes newer conventions the path of least resistance. Starting current means examples, agents, and documentation are less likely to mix old and new behavior.

The tradeoff is change velocity. Current framework lines move. That is why the version is exact, upgrades are isolated, and the project owns browser and build proof. “Latest” is not a strategy; controlled currency is.

Why TypeScript 6 instead of reaching for the next compiler

TypeScript 6.0 is a deliberate transition release. The rational baseline is the newest version proven compatible with the framework, generated clients, test runner, and editor—not a prerelease chosen to make the version table look ambitious.

Strict mode is non-negotiable. Add narrow lint rules around unsafe assertions, floating promises, and boundary types. Do not turn the codebase into a type puzzle. Types should make illegal product states harder to represent and contracts easier to understand.

Why Tailwind 4 and OKLCH

Tailwind CSS v4 aligns design tokens with CSS custom properties and modern CSS. Store semantic color roles such as --background, --card, --border, --text-paragraph, and --accent, expressed in OKLCH where practical.

Do not name product tokens after a visual accident like --light-blue-box. Name the job: --status-info-surface, --focus-ring, --interactive-primary. Dark mode is then a remapping of semantic roles, not an inversion filter.

Test at least WCAG 2 AA contrast, visible keyboard focus, forced colors, and reduced motion. Color is never the only status signal.

A modular-monolith architecture connecting the browser, Next.js routes, a generated client, domain services, Postgres, object storage, queues, workers, AI, email, and billing.

Open the full-size diagram · One repository can preserve strict internal boundaries while web requests and durable jobs run as separate processes.

The browser never receives a service-role database key. The route layer authenticates, parses, authorizes, and maps errors. Domain services express business operations. Persistence modules contain queries. RLS remains active as a second authorization boundary. Workers consume explicit versioned jobs.

Keep request handlers thin enough to read in one screen:

export const POST = secureHandler(  { auth: "required", body: CreateArtifactSchema },  async ({ user, body, requestId }) => {    const artifact = await artifactService.create({      actorId: user.id,      workspaceId: body.workspaceId,      title: body.title,      requestId,    });    return Response.json({ data: artifact }, { status: 201 });  },);

The wrapper is not magic. It is the single place to standardize request IDs, session resolution, schema validation, CSRF policy where needed, rate limits, safe error responses, logging, and timing.

10. Treat tenancy as a data invariant

If the product has workspaces, every tenant-owned row should carry a stable tenant key. Every query and mutation should be scoped. Database policies should deny cross-tenant access even when application code makes a mistake.

A request sequence from browser authentication through a validated route and tenant-scoped service to Row Level Security in Postgres.

Open the full-size diagram · Authorization is layered through the request, service, query, and database policy instead of entrusted to the interface.

Write tests with two tenants. Create records for each. Prove a user can read and mutate their own records and cannot read, infer, update, or delete the other tenant’s records. Run those tests against the actual policy path, not only a mocked repository.

Service-role credentials bypass RLS by design. Limit them to controlled server and worker operations, and require explicit tenant scope in those operations. “It only runs on the server” is not an authorization policy.

Migrations are an append-only operational history

Use migrations from the first table. Do not edit a migration already applied to a shared environment. Add a new one. Review:

  • forward behavior;
  • backfill and lock risk;
  • nullability transitions;
  • index creation;
  • RLS and grants;
  • rollback or roll-forward plan;
  • application compatibility during deployment.

Agents are very good at generating SQL and very bad at feeling the pain of a locked production table. Put migration constraints in repository law and require review for destructive or high-lock changes.

11. Make the API contract real early

An empty OpenAPI file is intent, not architecture. Build the contract around the first vertical slice.

The backend owns:

  • paths and methods;
  • authentication requirements;
  • request and response schemas;
  • stable error shapes;
  • pagination and idempotency semantics;
  • deprecation policy.

Generate the TypeScript client in CI and fail if generation creates an uncommitted diff. UI features import the generated types and client. They do not invent response interfaces that merely resemble the server.

For code that lives entirely inside server-rendered composition, calling a domain service directly can be appropriate. Do not force an HTTP hop inside the same process for ceremony. The contract matters at actual boundaries: browser to server, external clients, separately deployed services, and durable jobs.

12. Add queues when the user should not wait

Move work out of the request path when it is slow, retryable, scheduled, concurrency-limited, or dependent on an unreliable provider.

Good worker jobs include:

  • file scanning and document extraction;
  • import and export;
  • transactional email;
  • embedding and indexing;
  • long AI generations;
  • webhook fan-out;
  • cleanup and retention;
  • report generation.

Every job needs an identifier, versioned payload, tenant scope, idempotency strategy, retry policy, timeout, structured logs, and a dead-letter or terminal-failure path. A queue is not a place to hide errors. It is a place to manage them explicitly.

Avoid adding Redis and a worker merely because serious architectures have them. Start synchronous when the work is fast and safe. Extract when customer latency, reliability, or provider behavior supplies the evidence.

13. Files are hostile until proven otherwise

If customers upload files:

  1. enforce size and allowlisted types before upload;
  2. use private storage;
  3. isolate new objects in quarantine;
  4. verify type from bytes, not only extension or browser headers;
  5. scan asynchronously for malware when the risk warrants it;
  6. parse with bounded time, memory, and page limits;
  7. never render active user content in a privileged origin;
  8. issue short-lived signed URLs after authorization;
  9. log access without leaking sensitive filenames or contents;
  10. define retention and deletion behavior.

Object storage paths are not authorization. Signed URLs are bearer credentials until expiry. Treat parsing libraries and converters as part of the attack surface.

14. Add AI as a policy layer

A provider SDK call is not an AI architecture. Centralize:

  • task name and approved model family;
  • system instructions and prompt template version;
  • input validation and content handling;
  • structured output schema;
  • timeouts, retries, and fallback behavior;
  • token and cost budgets;
  • moderation or policy checks where appropriate;
  • tenant and user rate limits;
  • redacted logs and trace identifiers;
  • evaluations tied to product outcomes.

Keep provider-specific objects out of feature components. A feature should request a domain result such as classifyImport or draftFollowUp, not “call model X.” That makes local models, provider changes, and evaluation possible without rewriting the product.

Hugging Face is useful when exploring open models, datasets, embeddings, or local inference. “Local” does not automatically mean private, cheap, or good. Check model licenses, model-card limitations, quantization quality, hardware memory, prompt-data persistence, and whether the local result meets the same evaluation as the hosted one.

15. Let Stripe own payment complexity

For most SaaS starts, use Stripe Checkout Sessions rather than building a custom card form. The payment provider should own sensitive payment entry, authentication flows, and much of the lifecycle UI.

Your server should create sessions from server-owned prices. Never trust a price or entitlement supplied by the browser. Webhook handlers should:

  • verify signatures against the raw body;
  • store provider event IDs for idempotency;
  • tolerate duplicate and out-of-order events;
  • map external customer and subscription IDs to internal tenants;
  • update entitlements transactionally;
  • queue side effects such as email;
  • return promptly and retry safely;
  • support reconciliation against provider truth.

Billing status is not simply isPaid: boolean. Model trialing, active, past due, paused, canceled, and grace behavior in domain language. Decide what access each state grants.

If evaluating Polar or another merchant of record, compare who is the legal seller, tax and invoice responsibilities, supported business models and countries, pricing, payout timing, data portability, customer support boundaries, and how you would migrate. Simplicity is valuable, but know which obligations were removed and which were moved.

16. Build the frontend as an owned system

shadcn is valuable because it gives you source, not because it gives you a finished visual identity. Base UI provides accessible, unstyled interaction primitives. Your repository owns the adapter, styling, composition, and product contract.

Use three layers:

  1. Primitives: Button, Dialog, Popover, Menu, Tabs, Field.
  2. System patterns: EmptyState, PageHeader, DataTable, FilterBar, ConfirmAction, FormSection.
  3. Features: customer-facing workflows composed from owned patterns.

Feature code should not import Base UI directly. Only owned components/ui adapters may do that. This prevents every feature from inventing focus, portal, animation, and state behavior.

Document each important component family:

  • semantic purpose;
  • allowed variants;
  • states and keyboard behavior;
  • token and icon rules;
  • responsive behavior;
  • motion behavior and reduced-motion endpoint;
  • examples and certified product surfaces;
  • known exceptions.

State ownership hierarchy

Use the narrowest owner that preserves the product behavior:

  1. URL state for shareable navigation, search, filters, tabs, and pagination.
  2. Server state for database-backed truth.
  3. Local component state for ephemeral interaction.
  4. Context for a stable subtree concern.
  5. A global client store only for genuinely cross-cutting client state.

Avoid duplicating one concept across URL, query cache, and a global store. Derived state should usually be derived, not synchronized through effects.

Typography, icons, and motion

Self-host WOFF2 fonts with next/font/local, declare weight ranges accurately, and subset only when the license allows it. A distinctive display face can support editorial moments; an exceptionally legible sans should carry long reading and product UI. Use tabular numbers for metrics and financial values.

Choose one primary icon family and own small adapters. Icons inherit currentColor, include predictable sizing, and hide from assistive technology when a text label already communicates the action. Brand icons are different assets, not substitutes from a generic set.

Motion should explain continuity, hierarchy, or causality. Keep it interruptible. Give press feedback immediately. Animate opacity and transforms before layout properties. Preserve focus and semantics throughout exits. Honor prefers-reduced-motion with a complete, calm endpoint—not a broken half-animation.


Part IV — Turn the repository into a control plane

17. Agents need a map, laws, tools, and proof

The difference between “vibe coding” and agentic engineering is not whether an AI generated the code. It is whether the repository makes good decisions repeatable and bad decisions difficult.

A repository control plane flowing from README and AGENTS instructions through architecture documents, skills, hooks, CI, evidence receipts, and Git history.

Open the full-size diagram · Repository law becomes useful when procedures and automated proof keep it synchronized with implementation truth.

The control plane should answer four things quickly:

  • Map: Where does this kind of work belong?
  • Law: What must never be violated?
  • Procedure: What sequence and tools apply to this task?
  • Proof: What must pass before the work is done?

18. Create the governing documents before feature volume

Start with a small, accurate set. Empty templates that nobody maintains create false confidence.

README.md

The two-minute entry point:

  • what the product does;
  • prerequisites;
  • exact install and development commands;
  • environment setup;
  • local service setup;
  • verification commands;
  • deployment pointer;
  • links to deeper docs.

AGENTS.md

Durable repository law for Codex and any tool that supports the convention. Keep the root file short enough to remain in working context. Use nested files only where a subtree truly has different rules.

Include:

  • source-of-truth documents;
  • architecture boundaries;
  • exact package manager and commands;
  • file ownership and import rules;
  • security and data rules;
  • generated-file policy;
  • migration policy;
  • UI/accessibility floors;
  • required verification;
  • restrictions on commits, deployment, or external writes.

The official Codex AGENTS.md guidance describes root instructions and more specific nested overrides. Test what the agent actually loaded when rules appear to be ignored.

CLAUDE.md

Claude Code uses CLAUDE.md and supports imports. Keep shared law in one place rather than maintaining two drifting constitutions:

@AGENTS.md# Claude Code notes- Project skills live in `.claude/skills/`.- Use plan mode for high-risk migrations and implementation mode for approved work.- Do not launch a deployment or send external messages without explicit authority.

Claude Code’s memory documentation explains the hierarchy and import behavior. If a tool does not read a shared convention directly, bridge it explicitly.

The deeper documents

FileOwns
docs/ARCHITECTURE.mdruntime topology, module boundaries, sync/async decisions, dependency direction
docs/BACKEND.mdrequest pipeline, services, persistence, jobs, idempotency, provider adapters
docs/DESIGN.mdvisual principles, tokens, typography, density, elevation, motion, exceptions
docs/COMPONENTS.mdowned components, variants, certified usage, gaps, provenance
docs/SECURITY.mdthreat model, tenant model, secrets, uploads, logging, incident paths
docs/TESTING.mdtest layers, required gates, fixture policy, browser matrix
docs/ACCESSIBILITY.mdkeyboard, focus, contrast, semantics, reduced motion, assistive-tech checks
docs/SEO.mdroute classes, canonicals, metadata, structured data, sitemap, measurement
docs/OPERATIONS.mdenvironments, deploys, rollbacks, backups, queues, alerts, recovery
docs/DECISIONS/short architecture decision records with context, trade, consequences, review trigger

Documentation should point to executable truth. If a component ledger claims all popovers share one motion system, an architectural test or demo matrix should make divergence visible.

19. Skills are procedures, not personality prompts

A repository skill is a focused instruction package for a recurring task: adding a migration, building a UI surface, reviewing auth, creating an API endpoint, running browser verification, preparing a release.

A good skill contains:

  • a precise trigger description;
  • required context and files;
  • ordered workflow;
  • commands or scripts to reuse;
  • stop conditions and prohibited shortcuts;
  • evidence required at completion;
  • examples only where ambiguity remains.

Keep the entry file concise and use progressive disclosure for detailed references or scripts. The official Codex skill guide recommends a discoverable description and focused instructions, with supporting resources loaded only when needed.

Do not create one giant “be a great engineer” skill. Broad taste belongs in durable design and architecture law. A skill should make a specific repeated operation safer and faster.

Useful early skills:

  • bootstrap-feature
  • add-api-route
  • add-database-migration
  • build-owned-component
  • render-and-review-ui
  • security-review
  • release-receipt
  • write-architecture-decision

Evaluate skills as products

A skill is a versioned operating artifact. “This prompt feels better” is not a promotion standard. Keep the current skill and a candidate side by side, run both against the same representative tasks, and promote only when the candidate produces better outcomes without a critical regression.

Use four separate scorecards:

  1. Deterministic validity: frontmatter, naming, file references, size, secrets, and path safety.
  2. Authoring quality: trigger specificity, completeness, concision, actionability, workflow clarity, and progressive disclosure.
  3. Activation quality: precision and recall across relevant, irrelevant, and overlapping prompts. A typography skill should not fire for every UI request.
  4. Outcome quality: paired baseline-versus-treatment execution in isolated repositories, scored for both method compliance and whether the artifact actually works.

Keep critical requirements non-compensatory. A beautiful result that breaks keyboard access, crosses a tenant boundary, invents an API, or edits a generated file does not pass because its aggregate score is high.

Prevent contamination: the baseline must not inherit the candidate from a global environment, the solver must not see the hidden scoring rubric, and the variants should differ only by the injected skill bundle. Prefer deterministic evidence—contrast calculation, import boundaries, static semantics, browser overflow, test output—before asking another model to judge subjective craft.

Finally, run important skills under both Claude Code and Codex. Their instruction loading differs, so use one canonical skill body with thin tool-specific discovery wrappers. Compare cross-version improvement separately from cross-model parity. Store immutable run artifacts, rubric versions, model snapshots, costs, and critical regressions so the next revision can be compared honestly.

20. Hooks turn recurring reminders into enforcement

If you repeatedly tell an agent the same thing, decide whether a hook, test, lint rule, or script can enforce it.

Hooks can observe lifecycle events and tool use. Exact configuration and event names differ between Codex and Claude Code, so use each product’s current documentation: Codex hooks and Claude Code hooks.

Good uses:

  • block edits to generated files and immutable vendor captures;
  • require a writer lock in a shared checkout;
  • reject direct imports that bypass owned UI adapters;
  • format touched files after edits;
  • remind the agent to update a component ledger when adapter files change;
  • run a targeted test after a sensitive module changes;
  • detect likely secrets before a commit;
  • require an evidence receipt before session stop.

Bad uses:

  • hundreds of milliseconds on every harmless read;
  • opaque policy with no remediation message;
  • shell commands that mutate unrelated files;
  • pretending a regex is a security boundary;
  • giving a project hook broad credentials merely because it is convenient.

Project hooks are code. Review them before trusting the repository.

21. MCP is capability, not judgment

Model Context Protocol servers let an agent reach systems such as GitHub, databases, design tools, browsers, issue trackers, and documentation. This can be transformative because the agent can inspect evidence and close work without copy-paste. It also expands the blast radius.

For every connector, write down:

  • what data it can read;
  • what state it can change;
  • which identity it uses;
  • whether writes require confirmation;
  • how credentials are stored and rotated;
  • what gets logged;
  • which environments it can touch.

Start read-only. Add narrow writes when the workflow is stable. Production database access, payments, email sending, DNS, and deployments deserve explicit approval and stronger isolation.

22. Prompt like a product owner and a staff engineer

The most reliable coding prompts have four sections:

## GoalImplement the smallest complete customer outcome.## Context- Read `AGENTS.md`, `docs/ARCHITECTURE.md`, and the linked issue.- The backend contract is `openapi/openapi.yaml`.- Reuse owned components before adding primitives.## Constraints- Preserve tenant isolation and current URL behavior.- Do not add a global store.- Do not deploy, commit, or contact external systems.- Stop if the contract requires a product decision not present in the issue.## Done when- Unit, integration, type, lint, and targeted browser checks pass.- Loading, empty, error, forbidden, and success states are rendered.- Return changed files, commands, results, remaining risks, and screenshots.

The prompt names an outcome, supplies local truth, limits authority, and defines proof. “Make it prettier,” “make it scalable,” and “clean this up” force the model to invent the evaluation function.

When you do not know the implementation, say what you can observe:

  • “The trigger and surface should read as one continuous object.”
  • “A user should be able to paste this URL and recover the same filters.”
  • “A user from workspace A must never infer whether workspace B has this record.”
  • “The request may be retried without sending two emails.”

Good product language is technically useful.

23. Require receipts, not confidence

An agent’s final sentence is not evidence. Ask for:

  • changed files;
  • exact commands and exit status;
  • test names and counts;
  • browser viewport and interaction path;
  • screenshots or computed evidence for visual claims;
  • migration and rollback notes;
  • source links for time-sensitive claims;
  • known gaps and unverified assumptions;
  • branch and commit state when handoff matters.

For a UI change, a green typecheck proves only that types compile. For a security change, a unit test around a mocked function does not prove the database policy. Match the proof to the claim.

A self-improvement flywheel from repeated friction through a fresh audit, corrected ownership, repository law, automated gates, and evidence receipts.

Open the full-size diagram · The durable output of a painful audit is a better system for the next session, not only a local patch.


Part V — What to do when the agents start fighting you

24. Assume the pain contains architectural information

When a workflow suddenly feels difficult, resist the urge to add five more sentences of emotional emphasis to the same session. Open a clean session and ask a diagnostic question:

What in this repository makes the requested behavior hard, inconsistent, or easy to implement incorrectly? Investigate without changing files. Map the relevant components, ownership boundaries, existing laws, tests, and current working-tree state. Distinguish root cause from symptoms and return evidence.

Fresh context matters. A long implementation session accumulates assumptions and defensive local decisions. A diagnostic session can inspect the system as evidence.

The usual causes are:

  1. The outcome was vague. The agent optimized a different definition of “better.”
  2. The model or tool was a poor fit. Some models are better at deep repository forensics; others are faster at bounded implementation or visual iteration.
  3. Repository law is wrong, missing, or contradictory. The agent is following a stale pattern more faithfully than your new instruction.
  4. The abstraction lives at the wrong layer. Shared behavior was attached to one component rather than the pattern it represents.
  5. The checkout is contested. Another agent or human is editing the same ownership boundary.

25. A representative frontend failure

Imagine several toolbar controls that should open with the same spatial continuity. Some feel correct. Two fade in as unrelated floating panels. Another action disappeared during a refactor.

The superficial fix is “make those two animate like the others.” A rigorous audit asks:

  1. Which semantic primitives power each surface?
  2. Which owned component actually contains the motion engine?
  3. Is the desired behavior visual, semantic, or both?
  4. Do the outliers need menu semantics or arbitrary popover content?
  5. What does the component ledger claim?
  6. Which tests prove the working implementation?
  7. Did the refactor change semantics without extracting shared behavior?
  8. Is a hot working tree making partial edits unsafe?

The root cause may be that a sophisticated measured morph—geometry, material, interruption, collision behavior, and reduced-motion support—was implemented inside the menu adapter. Rich-content surfaces correctly use a popover for focus and semantics, but the popover only has a basic reveal. The behavior was shared in the design language but not in the architecture.

The correct direction is not to force rich content into menu semantics. It is to extract the visual continuity engine behind owned semantic adapters.

Then the second review should challenge the proposed abstraction:

  • Footprint growth and material continuity are separate choices. A toolbar trigger may expand in layout for one surface and stay anchored for another.
  • Popover focus is harder. Closing while focus is inside must not strand or prematurely eject focus; opening content should not receive focus while visually unavailable.
  • A new API should replace the old boolean. Two overlapping configuration vocabularies recreate drift.
  • Import boundaries matter. Features may use owned adapters, not the internal motion engine directly.
  • Extraction is the moment to expose hidden state. A pure phase reducer, batched measurement, profiling, SSR coverage, and stable data-slot contracts are cheaper now than later.

This is the deeper lesson:

One implementation per pattern. Semantic adapters may differ; product behavior should have one true owner.

26. The audit sequence

Use this sequence for any painful frontend or backend inconsistency.

Step 1: Freeze mutation

Ask for source-only investigation. Record branch, working-tree changes, locks, and overlapping files. Do not debug a moving target by editing it.

Step 2: Inventory the visible surfaces

Create a matrix of each surface, route, state, semantic primitive, owned adapter, behavior, and exception. Include the “good” reference implementation.

Step 3: Trace downward

Follow imports from feature to system pattern to primitive to library. Locate where geometry, policy, network access, or state actually lives. Search for parallel implementations and direct primitive imports.

Step 4: Trace sideways

Read docs, ledgers, decision records, stories or demos, unit tests, browser tests, and recent changes. A divergence codified in documentation is more dangerous than an accidental one because future agents will preserve it.

Step 5: Read upstream contracts

Use primary documentation for the primitive, framework, or API. Confirm semantic responsibilities. A menu is not a popover merely because both float next to a button.

Step 6: State the root cause in one sentence

If you cannot, keep investigating. “The animation is inconsistent” is a symptom. “The shared popup behavior is owned by the menu adapter, so correct popover semantics cannot reuse it” is a root cause.

Step 7: Design the true ownership boundary

Separate semantic behavior, visual behavior, state, provider integration, and feature composition. Define a replacement API and delete the superseded path in the same migration.

Step 8: Adversarial review

Use a different model or fresh agent to verify load-bearing claims and look for omitted risks: focus, hydration, performance, data loss, migration compatibility, concurrency, and rollback.

Step 9: Implement in safe slices

First extract with no behavior change. Prove existing tests remain green. Add the new adapter and its edge-case tests. Migrate call sites. Delete old configuration. Update docs and demo evidence together.

Step 10: Prevent recurrence

Turn the finding into the lightest durable mechanism: an import-boundary test, component ledger row, skill, hook, demo matrix, or CI gate.

27. Audit the entire product by family, not by screenshot

Do not ask an agent to “review the whole frontend” as one shapeless task. Build a product-surface inventory, then audit families:

  • buttons, links, and press behavior;
  • menus, popovers, tooltips, dialogs, and sheets;
  • fields, validation, and form submission;
  • navigation, breadcrumbs, tabs, and URL state;
  • tables, lists, empty states, loading, pagination, and virtualization;
  • toasts, banners, status, and destructive confirmation;
  • typography, icons, color, density, borders, and shadows;
  • responsive composition and touch targets;
  • motion, interruption, reduced motion, and focus return;
  • errors, offline behavior, permission boundaries, and retries.

For each family, produce:

  1. source inventory;
  2. rendered matrix across representative routes and states;
  3. expected canonical implementation;
  4. justified exceptions;
  5. accessibility and keyboard results;
  6. performance observations;
  7. consolidation plan;
  8. prevention gate.

This is how design quality becomes infrastructure rather than a cleanup sprint.


Part VI — The agent capability ladder

28. Know which level you are operating

The word agent now describes everything from a chat window to a persistent process with payments and a schedule. Use a capability ladder.

A six-level agent capability ladder from chat and coding tools to governed teams, persistent runtimes, and bounded economic agents.

Open the full-size diagram · Every increase in autonomy adds leverage and blast radius; observability and permissions must mature at the same pace.

Each step adds leverage and blast radius. Earn the next level with boundaries and observability.

29. Claude Code and Codex: use both as engineering systems

Claude Code and Codex can inspect repositories, edit files, run commands, browse or connect to tools, verify work, and continue across large tasks. Their value comes from different model behaviors and independent perspectives as much as raw generation.

A practical division:

  • use one to perform the primary investigation or implementation;
  • use the other to challenge the plan, verify claims, or review the diff;
  • switch when a session becomes anchored to a bad assumption;
  • keep repository law tool-neutral where possible;
  • maintain small tool-specific bridges for instructions, skills, and hooks.

Do not bounce the same vague request between models and call disagreement insight. Give the reviewer the artifact, evidence, constraints, and a specific adversarial brief.

30. Subagents and parallel work

Parallelism helps when tasks are independent and ownership is explicit. It hurts when multiple agents touch the same files, shared state, or unresolved contract.

Good parallel lanes:

  • primary-source research;
  • read-only architecture audit;
  • independent test design;
  • frontend implementation in one isolated boundary;
  • backend implementation in another isolated boundary;
  • adversarial review after a shared-context barrier.

Bad parallel lanes:

  • two agents refactoring the same primitive;
  • one changing an API while another generates the client from the old schema;
  • simultaneous migrations without ordered dependencies;
  • multiple writers in one dirty checkout with no ownership ledger.

Use worktrees or isolated sandboxes for separate writers. Assign exact files or directories. Require each agent to report branch, base commit, changed files, verification, and integration assumptions.

31. tmux as a simple durable orchestration layer

You do not need a distributed control plane to supervise several long-running agents. tmux provides durable terminal sessions that survive a closed window or network interruption.

A tmux-based multi-agent topology with task contracts, isolated worktrees, a read-only reviewer, one integrator, and full CI.

Open the full-size diagram · Durable terminal sessions are enough for serious local orchestration when task ownership and integration remain explicit.

A robust local pattern includes:

  • one task contract per worker;
  • one worktree per writer;
  • deterministic session names;
  • a supervisor that can inspect liveness and recent output;
  • timeouts and explicit terminal states;
  • structured checkpoint files that survive context compaction;
  • cleanup for orphaned sessions and worktrees;
  • one integrator responsible for merging and resolving contracts;
  • reciprocal review between different model families where risk warrants it.

tmux solves session durability, not task correctness. Without file ownership and clean handoffs, it merely lets several mistakes run at once.

32. Persistent agent frameworks

Coding agents are repository-centered. Persistent agent frameworks add memory, schedules, communication channels, delegated subagents, and longer-running workflows.

Hermes Agent

Hermes Agent is an open-source personal agent with skills, memory, subagents, scheduled automation, multiple interfaces, and flexible model backends. It is attractive when you want a persistent, self-improving operator you can inspect and customize.

Evaluate its permission model, channel exposure, skill provenance, model costs, update process, and what long-term memory stores. Persistence means old context and credentials become part of the threat model.

OpenClaw

OpenClaw is another open personal-agent ecosystem centered on tools, skills, plugins, automation, channels, and subagents. It is useful for understanding what a personal operational agent looks like beyond an IDE session.

Treat community plugins as executable supply-chain dependencies. Start in a constrained environment, review installed skills, and avoid connecting sensitive company systems until logging, confirmation, and revocation are clear.

Vercel Eve

Vercel Eve approaches agents as deployable TypeScript systems with instructions, skills, tools, durable workflows, sandboxes, schedules, channels, connections, subagents, and evaluations. It is compelling when the agent itself is a product capability you need to develop, deploy, and observe like software.

The tradeoff is platform commitment. Durable workflows and managed primitives reduce infrastructure work, but you should understand runtime limits, portability, data handling, pricing, and how deeply business logic binds to the platform.

Natural and agentic payments

Natural is exploring infrastructure for agents to hold identity and use wallets, cards, payments, billing, and related financial rails with auditability. This is the experimental edge of the ladder, and it has only been lightly tested for the purposes of this field guide.

Economic agency should be bounded by:

  • an identified principal;
  • allowlisted merchants and action types;
  • per-action and period limits;
  • explicit approval thresholds;
  • immutable receipts;
  • revocable credentials;
  • dispute and recovery paths;
  • separation between test and real funds.

Do not grant an agent general purchasing authority because a demo transaction worked.

33. Version control is the safety net for autonomy

Use Git for code, documentation, prompts, infrastructure definitions, SQL, and other text-based operating artifacts. For binary files such as workbooks and PDFs, Git can still preserve snapshots, although diffs may need companion exports, structured data, or specialized tooling.

The principle is broader than the tool:

  • establish a known baseline;
  • make changes attributable;
  • preserve the ability to compare and recover;
  • let agents inspect prior attempts;
  • require small, intentional commits;
  • never use version control as an excuse to hand broad destructive authority to an unreviewed process.

The safest high-autonomy environment is isolated, observable, credential-limited, and easy to restore. Full local permissions can be productive for a trusted repository in a disposable environment. They are not a universal default for production systems, personal files, or unknown code.


Part VII — Bootstrap the first project correctly

34. Before touching the keyboard

Write five short artifacts:

  1. Customer: who has the problem, current workaround, urgency, and buying authority.
  2. Outcome: the one result the first release must create.
  3. Scope: what the walking skeleton includes and explicitly excludes.
  4. Risk: sensitive data, money movement, external actions, and irreversible operations.
  5. Proof: what observable behavior validates the product and the implementation.

The first vertical slice should cross the real system. For a workspace product, that might be:

A signed-in user creates a workspace-owned artifact, sees it in a list after refresh, cannot access another workspace’s artifact, and receives a stable error when validation fails.

That slice proves identity, tenancy, schema, migration, request validation, service boundaries, database policy, server rendering or client fetching, empty/loading/error/success states, and test infrastructure. A dashboard full of static cards proves none of those.

35. Day 1 — create a reproducible skeleton

Install the runtimes

Use a runtime manager and pin versions. Then scaffold:

bunx create-next-app@16.2.10 venture \  --typescript \  --tailwind \  --eslint \  --app \  --src-dir \  --import-alias "@/*"cd venturebun add --exact next@16.2.10 react@19.2.7 react-dom@19.2.7bun add --dev --exact typescript@6.0.3 @types/node@24 @types/react@19.2.17 @types/react-dom@19.2.3

If the scaffold’s options or peer requirements have changed, follow current official output rather than forcing this snapshot. Record the final exact versions.

Set:

{  "packageManager": "bun@1.3.14",  "engines": { "node": "24.x" }}

Add scripts for lint, format:check, typecheck, test, build, test:e2e, and one verify command that runs the required sequence. Commit the untouched scaffold. That commit is your recovery point.

Write the control plane

Create:

AGENTS.md
CLAUDE.md
README.md
.env.example
docs/ARCHITECTURE.md
docs/BACKEND.md
docs/DESIGN.md
docs/COMPONENTS.md
docs/SECURITY.md
docs/TESTING.md
docs/ACCESSIBILITY.md
docs/SEO.md
docs/OPERATIONS.md
docs/DECISIONS/0001-modular-monolith.md

Keep every document honest and short. “Not implemented” is useful truth. A fictional architecture is harmful context.

36. Day 2 — install the frontend foundation

Initialize shadcn for Base UI using the current shadcn documentation. Add only the primitives needed for the walking skeleton. Copying fifty unused components makes ownership less clear.

Define semantic tokens for light and dark themes. Establish:

  • background and elevated surfaces;
  • text hierarchy;
  • border and focus colors;
  • one core accent scale in OKLCH;
  • success, warning, danger, and information roles;
  • radii derived from component nesting;
  • a small shadow/elevation system;
  • typography roles and readable measure;
  • motion durations and easing;
  • reduced-motion behavior.

Build a tiny internal component page that renders every owned primitive in default, hover, focus, disabled, loading, error, and dark-mode states. This is not a public design system. It is an agent-visible proof surface.

Use shadcn Typeset for long-form content instead of hand-styling every Markdown element. Extend it through stable variables and a containing layout; avoid brittle selector overrides that make appended content unpredictable.

37. Day 3 — establish identity and the data boundary

Create the Supabase project and local development setup. Add environment validation that distinguishes public browser values from server secrets. Never import server-only configuration through a client module.

Create the first migration:

  • profiles or membership identity;
  • workspaces;
  • workspace members and roles;
  • the first tenant-owned artifact;
  • timestamps and relevant indexes;
  • RLS enabled;
  • explicit policies;
  • updated-at behavior only where needed.

Write policy tests for two tenants. Add a server-side client scoped to the user session and a separately named administrative client for the rare operations that need it.

Document the tenant invariant in SECURITY.md and the data ownership in BACKEND.md.

38. Day 4 — build the request and contract spine

Create:

  • a standard success and error response shape;
  • request identifiers;
  • Zod validation;
  • authentication and authorization helpers;
  • structured logging with redaction;
  • a thin route-handler wrapper;
  • one domain service;
  • one persistence repository;
  • the first real OpenAPI paths;
  • generated client and drift check.

Do not design forty theoretical endpoints. Specify the walking skeleton completely.

Add unit tests for validation and service behavior, integration tests for persistence and RLS, and contract tests for the handler. Make errors actionable for customers and traceable for operators without exposing internals.

39. Day 5 — finish the walking skeleton in the browser

Build the real UI with:

  • signed-out and forbidden behavior;
  • loading and optimistic behavior only where justified;
  • first-use empty state;
  • validation feedback connected to fields;
  • request error with retry where safe;
  • persisted success after refresh;
  • narrow phone layout;
  • keyboard-only operation;
  • light, dark, and system themes.

Add a Playwright test that creates an artifact, reloads, verifies it remains, attempts cross-tenant access, and captures screenshots at phone and desktop widths. Run axe on the rendered state.

At the end of Day 5, you have a small product system, not a large mockup.

40. Week 2 — add only the operational weight the product earned

Use customer and runtime evidence to add:

  • object storage and file policy when files exist;
  • Redis and BullMQ when work becomes slow or retryable;
  • email adapter and queue when a transactional message exists;
  • Stripe Checkout when a real entitlement can be sold;
  • an AI policy layer when a product job requires inference;
  • observability around actual failure paths;
  • backups and restore rehearsal before valuable data accumulates.

Each capability should arrive as a vertical slice with docs, tests, operations, and rollback—not a package installation followed by TODO comments.

A five-day timeline from a reproducible scaffold and repository law through UI foundations, identity and data policies, API contracts, and browser proof.

Open the full-size diagram · The first week proves one real vertical slice before adding the operational weight of queues, billing, files, or AI.

41. CI from the first pull request

Your CI should install from the frozen lockfile and fail in understandable layers:

  1. formatting and lint;
  2. typecheck;
  3. unit tests;
  4. generated-client and migration drift checks;
  5. integration tests with real database policies;
  6. production build;
  7. targeted browser tests and accessibility scan;
  8. dependency and secret scanning;
  9. container scanning if you ship containers.

A continuous-integration pipeline from frozen installation through static checks, behavioral tests, database policies, production build, browser evidence, and security review.

Open the full-size diagram · CI converts architectural promises into executable gates on every proposed change.

Optimize the fast path so agents run it often. Keep focused commands for a changed package or feature, but require the full gate before integration.

42. Deployment, observability, and recovery

Create separate local, preview, and production environments. Preview is not production and should not expose production data. Production changes require:

  • reviewed environment configuration;
  • migration ordering;
  • health checks;
  • structured logs with request/job IDs;
  • error capture and alert ownership;
  • deploy record;
  • rollback or roll-forward instructions;
  • database backups and a tested restore path;
  • worker queue visibility;
  • provider status and rate-limit handling.

Instrument customer outcomes, not only CPU. Measure signup completion, time to first value, job success and latency, payment conversion, retained use, and the failure point in important workflows.


Part VIII — Build for discovery and answer readiness

43. Public content is part of the product system

If a customer can discover, understand, or trust the company through a public page, that page deserves the same source-of-truth discipline as application code.

The useful loop is:

An answer-readiness loop from a real customer problem to useful public content, canonical pages, honest signals, earned references, and measured learning.

Open the full-size diagram · Public discovery compounds when first-hand usefulness, technical accessibility, evidence, and measurement reinforce one another.

Google’s current guidance for generative AI search is refreshingly unmagical: foundational SEO still matters, unique first-hand content matters, pages need to be crawlable and usable, and there is no special schema or llms.txt file that creates ranking advantage in Google Search.

Answer readiness means a page makes it easy for a person or retrieval system to determine:

  • the question being answered;
  • the direct answer;
  • the author or entity responsible;
  • the supporting evidence and primary sources;
  • the date and scope;
  • what is fact, recommendation, experience, or experiment;
  • what action the reader can take next.

Do not write robotic fragments for an imagined machine. Write the best answer for a capable human, structure it cleanly, and make the evidence accessible.

44. Create a route and claim registry

Classify every route:

  • public and indexable;
  • public but noindex;
  • private;
  • removed;
  • permanently moved.

Only canonical, successful, indexable URLs belong in the sitemap. Preview hosts should be noindex. robots.txt controls crawling behavior; it is not authorization. Private routes need real authentication.

Build canonicals from an allowlisted public origin, never an untrusted request host. Server-render titles, descriptions, main content, and relevant structured data. JSON-LD must describe content visible on the page; it does not grant truth by declaration.

For material public claims, keep a registry:

FieldPurpose
StatementExact public claim
StateDraft, verified, deprecated, prohibited
EvidencePrimary source or internal proof
OwnerPerson accountable for accuracy
Verified atLast evidence check
Review byExpiry or review date
Allowed surfacesPages, sales material, support, docs
Disallowed wordingOverclaim or legally risky variation

This prevents agents from copying an expired number or unsupported superlative across the entire site.

45. Performance, accessibility, and resilience are distribution work

A page that cannot be read on a phone, navigated by keyboard, loaded on a mediocre connection, or understood when JavaScript is delayed is less discoverable and less credible.

Make public routes:

  • server-rendered by default;
  • semantically structured with one clear h1;
  • readable before client hydration;
  • fast enough to meet Core Web Vitals in real field data;
  • explicit about authorship and update date;
  • stable at one canonical URL;
  • internally linked from relevant pages;
  • backed by primary sources;
  • free of modal walls that hide the actual answer.

Measure Search Console, referrals, qualified conversion, cited pages, customer language, and content decay. Do not optimize for impressions detached from the business.


Part IX — The operating doctrine

46. Ten rules to keep

  1. Validate the customer job before scaling implementation. Agents make it cheaper to build the wrong thing too.
  2. Choose the simplest architecture that preserves your real constraints. For most new SaaS products, that is a modular monolith.
  3. Make business operations part of the system. Identity, money, contracts, meetings, and records need owners and controls.
  4. Put truth in the repository. Architecture, design, security, tests, and decisions should be discoverable by humans and agents.
  5. Use one implementation per pattern. Keep semantics correct through adapters, but do not duplicate product behavior.
  6. Put contracts at real boundaries. Validate runtime data, generate clients, version jobs, and enforce tenancy in the database.
  7. Grant capability gradually. More tools and permissions increase leverage and blast radius together.
  8. Use independent review where failure is expensive. A fresh model should verify load-bearing claims, not merely admire the diff.
  9. Match proof to the claim. Render interfaces, exercise policies, retry jobs, replay webhooks, and restore backups.
  10. Convert every repeated pain into infrastructure. The output of a good audit is not only a fix; it is a law, skill, hook, test, or ownership boundary that makes the next fix unnecessary.

47. A paste-ready first prompt

Use this after the initial repository documents exist:

We are bootstrapping the first walking skeleton for a full-stack SaaS product.## GoalA signed-in member can create one workspace-owned record, see it after refresh,and receive an actionable validation error. A member of another workspace cannotread, infer, update, or delete that record.## Read first- `AGENTS.md` and `CLAUDE.md`- `docs/ARCHITECTURE.md`- `docs/BACKEND.md`- `docs/DESIGN.md`- `docs/SECURITY.md`- `docs/TESTING.md`## Constraints- Preserve the modular-monolith dependency direction.- The backend owns `openapi/openapi.yaml`; generate the browser client from it.- Enforce tenant scope in application code and Postgres RLS.- Use server state first and local UI state only where interaction requires it.- Reuse owned UI components. Do not import Base UI directly from features.- Implement loading, empty, validation, forbidden, request-error, and success states.- Do not add billing, queues, object storage, AI, or a global client store.- Do not deploy, push, or change external systems.- Stop and report if a missing product decision would change the schema or contract.## Workflow1. Audit the current scaffold and report any contradiction with the documents.2. Propose the thinnest vertical implementation and its tests.3. Implement after the plan is internally consistent.4. Run targeted checks, the full verification command, and browser proof at phone   and desktop widths in light and dark mode.## Done when- The real database policies pass a two-tenant test.- The generated client has no drift.- Lint, types, tests, production build, and browser checks pass.- Keyboard focus, labels, touch targets, contrast, and reduced motion pass.- Return changed files, commands and results, screenshots, remaining risks, and  the next smallest recommended slice.

48. The final perspective

The founders who gain the most from agents will not be the people who memorize the most framework trivia or discover the most theatrical prompt. They will be the people who can define a valuable outcome, make constraints explicit, give capable systems the right context and tools, inspect evidence without ego, and convert every lesson into durable operating leverage.

Your first repository is not merely where the code lives. It is the company’s earliest executable memory. Treat it that way from day one.


Reference shelf

Agent engineering

Application architecture

Business and discovery