◈
What are we making?
Product shape determines almost every later decision.
FIELD GUIDE FOR AGENTIC BUILDERS
Build the system before you scale the agents.
A practical operating system for choosing architecture, controlling context, routing work to the right models, building UI, controlling cost, coordinating agent teams and deciding when “Done, boss” is actually done.
context → plan → gates
build → prove → ship
THE MAP
Thirteen decisions that shape the whole project.
The order matters: project intent first, agents second. Tools are downstream of product constraints.
01 · FOUNDATION
Healthy infrastructure starts before the first prompt.
Before stack, agents or CI, decide what you are building, who it is for, whether it is a hobby or a business, expected scale and the cost of failure.
◎
Who uses it?
Audience determines UX, accessibility, auth and support needs.
$
Hobby or business?
A weekend experiment and paid SaaS should not share the same risk budget.
↗
Expected users?
100 users and 100K users create different operational constraints.
⌘
What can go wrong?
Payments, private data and production actions need stronger boundaries.
1K
lean
moderate
INFRA PRIORITY
02
02 · ARCHITECTURE
Do not accept the first stack an AI suggests.
Models default to familiar, average choices. Your stack should fit traffic, budget, team skill, data model, deployment target and exit strategy.
DEFAULT-AI
“Use the popular stack.”
Reasonable on average. Possibly wrong for a tiny static product, a CPU-heavy converter, an offline app, a WordPress plugin or a zero-budget prototype.
CONSTRAINT-FIRST
Choose from requirements backwards.
Ask for three architectures: cheapest viable, balanced default and scale-first. Demand tradeoffs, free-tier limits, migration cost and operational burden.
01
Specification
Turn product intent into behavior, constraints and non-goals.
02
Architecture
Boundaries, ownership, data flow and shared primitives.
03
Delivery plan
Prefer incremental delivery: each slice should be usable, testable and reversible.
04
Agent boundaries
CI, linters, hooks, PR gates, Slopgate and tool blocking define what agents cannot bypass.
03 · LONG-RUNNING AGENTS
More autonomy needs stronger rails, not more trust.
Long tasks are powerful because agents can iterate, test and repair without babysitting. The same autonomy can also multiply a bad assumption across the repository.
Code pollution guardrails
- CI + required PR gates
- Linters + type checks
- Pre-commit / pre-push hooks
- Slopgate structural rules
- Small, reviewable task scope
Dangerous-action guardrails
- Block raw production/deploy commands
- Block ungoverned merge commands
- Keep secrets out of prompts/logs
- Use isolated branches/worktrees
- Require receipts before completion
04 · CONTEXT
Context is the agent’s working memory — and it gets dirty.
A project is much larger than one context window. The solution is not to paste everything; it is durable project instructions, searchable docs, explicit task scope and clean handoffs.
SESSION PRESSURE
38%
Project context lives outside the chatAGENTS/CLAUDE docs, specs, architecture maps, decision logs and tests survive session resets.
Keep each task narrowDo not make one session research, redesign, implement, deploy and audit an entire product unless the job truly requires it.
Start fresh before the session starts rationalizingA fresh session with a precise handoff often beats another 40K tokens of accumulated confusion.
05 · SESSION HYGIENE
Side questions can poison the main task.
Every unrelated discussion adds competing goals and facts to the same working memory. Keep detours separate: a side-channel command such as /btw, another thread, or a scratch agent lets the main task stay coherent.
Dirty session
Architecture task → restaurant question → pricing brainstorm → deployment bug → return to architecture. The model now has several unrelated objective functions in one conversation.
Clean session
Main task stays focused. Side questions move to /btw or another thread. Handoffs capture only durable decisions that matter to the project.
06 · MODEL ROUTING
Stop asking “which model is best?” Ask “best for what?”
Use models as roles. Route architecture, implementation, journey writing, CI and debugging to the behavior you want.
RECOMMENDED ROLE
07 · CI
CI is the referee that does not care what the agent claims.
GitHub reruns the project’s checks from a repeatable environment and turns “looks done” into a machine verdict. For CI implementation, use the model that stays goal-oriented instead of turning every task into an endless test loop.
Claude-family for CI architecture
Good at following repository policy, balancing build/test/deploy concerns and stopping when the requested gate is complete.
Codex-family for focused code tasks
Excellent when scoped tightly, but test-loving behavior can loop if the objective is vague. Give explicit gate boundaries and stop conditions.
08 · USER JOURNEYS
A user journey is the story the product must survive.
Do not start with test code. Start with a person, a goal, a starting state, actions, expected states, failure branches and the evidence that proves the journey worked.
1
Person + goal
Who is trying to do what?
2
Starting state
Account, permissions, data and prerequisites.
3
Actions + expected states
What they click/type and what must happen after each step.
4
Failure branches
Wrong password, no quota, timeout, expired plan, invalid input.
Model choice: OpenAI-family for journey specification and execution review
Long user journeys reward meticulous reading, exhaustive text and attention to small state changes. Use that strength, then keep the browser assertions deterministic.
09 · CODE HEALTH
Spaghetti code is future-agent tax.
When every screen invents its own colors, spacing, data access and helpers, every future task becomes harder. Shared tokens, components and primitives reduce both human and agent ambiguity.
Spaghetti
Copy-pasted UI, magic values, duplicate helpers, business logic inside pages, unrelated files importing each other.
Healthy structure
Design tokens, shared components, clear module boundaries, reusable primitives, one source of truth and automated structural guardrails.
10 · UI
Do not ask AI to “make it premium.” Give it visual evidence.
Collect screenshots from products whose layout, density and motion fit the project. Ask Claude to extract the design language, turn it into a design system and shared components, then move into visual iteration.
1
Collect references
Dribbble, product sites, screenshots of concrete patterns — not vague vibes.
2
Extract rules
Layout, spacing, typography, colors, surfaces, interaction states and motion.
3
Build the system
Tokens + reusable components before twenty one-off screens.
4
Visual iteration
Use Claude Design / visual workflow to assemble and refine screens on top of the system.
DESIGN TOKENS
Shared decisions stop style drift.
The exact prompt for screenshot → design language → design system belongs in the community repository.
Primary
Surface
Success
8 / 12 / 16 / 24
Radii: 12 / 18 / 28
Motion: 220ms
11 · COST
“It is only $5” is not architecture.
AI defaults optimize convenience. Development architecture should first ask what can stay local, open-source or inside generous free tiers — and what paying actually buys.
$0
Start free where it is rational
Local tools, open source, free tiers and temporary dev infrastructure often cover the whole build phase.
$
Pay for leverage
Pay when a service removes meaningful operations, adds required reliability or is cheaper than maintaining the alternative.
↗
Model the exit
Know the free-tier ceiling, ten-times-data cost, migration cost and lock-in before the architecture depends on it.
12 · TEAMS + PARALLELISM
The strongest agent can be a team — if the work does not collide.
Parallelism is task design. Two agents editing the same file or depending on contradictory assumptions do not give you twice the speed; they give you merge conflict and lost context.
FOREMAN · FABLE
Work manager
Plans tasks, dependencies, evidence and convergence.
SENIOR · OPUS
Senior engineer
Hard architecture, ambiguous problems and high-risk decisions.
JUNIOR · SONNET
Junior engineer
Well-defined implementation and bounded changes.
CODEX VIA CLODEX
Specialist
Focused code generation/repair while Claude Code keeps project instructions, tools and orchestration around it.
Single agent
Research→Plan→Build ABuild B→Converge→Gate
Hard rule: never assign two agents to the same file or to tasks that invalidate each other’s work.
13 · DONE, BOSS
“Done” is when the system asks for receipts.
A healthy project makes completion mechanical: the brief defines the outcome, architecture limits blast radius, CI checks the change and user journeys prove the product still works.
✓What changed
✓What user outcome is possible now
✓Which automated checks ran
✓Which user journeys ran
✓Skipped proof / remaining risk
✓Exact branch, revision and preview
Do not trust the agent more. Build a system that requires less trust.
COMMUNITY TOOLKIT
Package the pain so the next agent starts smarter.
The community repository is the durable layer: prompts, skills, guardrails, templates, presentations and working primitives.
Slopgate
Open guardrail for code health and new agentic slop.
CI Expert
Member skill: incident-derived CI rules plus reusable primitives.
UI Prompt Pack
Screenshot → design language → design system → components.
Clodex Workflow
Claude Code orchestration with Codex-family specialists inside the workflow.
OPERATING PRINCIPLE
Build the system before you scale the agents.
A practical field guide for agentic builders — not a computer-science course.