Development on NateBent.com

Zero to App with AI, Part 6: The App Taught Us What to Build

Nathan Bent — Sun, 19 Jul 2026 01:00:00 +0000

Everything up to here was built from imagination: what I thought logging a workout should feel like. Then I trained with it for real, phone in hand, chalk on fingers, rest timer running, and the roadmap got humbled. This part is about the highest-signal planning input the project ever had: actual use.

The friction list

After the first real gym sessions I dumped every annoyance into a list. Nine items, all of them things no amount of desk-testing had surfaced, because they only exist under gym conditions: tired, hurried, one-thumbed. The highlights:

Set grouping. A wall of individual sets is unreadable between exercises; sets want to cluster by exercise visually.
Post-hoc editing. Fat-fingered 135 as 125? There was no way to fix a set after saving. At a desk you’d never notice. At the gym it’s constant.
Smart defaults. The app made me re-enter the weight I just used. The previous set is almost always the best guess for the next.
Sort order, collapsible sections, calmer check-ins. The start-of-workout screen had grown enthusiastic; under time pressure you want it quiet and fast.
A Manage Plans page and plan archiving. Plans accumulate, and the picker shouldn’t scroll forever past experiments you’re done with.

None of these is clever. That’s the point. They’re obvious in use and invisible in theory.

Tip

Write the friction list in the moment or right after. These observations evaporate within hours, and once they’re gone you’re back to designing from imagination.

Steal like a product manager

Before turning the list into work, one session did something teams skip: surveyed the incumbents. Strong, Hevy, FitNotes, Jefit. What do apps with millions of gym-hours of accumulated feedback all agree on? The survey confirmed the friction list from the outside: auto-fill defaults from the previous set are table stakes everywhere, rest timers matter, set editing is universal.

When your dogfooding complaints and the market’s converged solutions agree, you can build without second-guessing. Where they diverge is interesting too: you either have a differentiator or a blind spot, and it’s worth a minute deciding which.

An ideation phase with no code

The friction list and the survey merged into a formal roadmap phase whose entire output was a document: a rated backlog, one line per idea, rated easy, medium, or hard, with just enough context to build from later, committed to the repo as docs/FEATURE-IDEAS.md.

Then the roadmap grew three implementation phases sorted by that rating: quick wins (the easy column, knocked out in one session), medium features, and the one genuinely hard interaction, supersets, which got a phase to itself rather than being wedged into a grab-bag.

This sounds like bureaucracy for a hobby app. It’s the opposite. It’s what let an AI-paced project stay aimed. When building costs hours instead of weeks, the scarce resource is knowing what’s worth building. A rated backlog in the repo means every future session picks from a priority queue instead of improvising, and, per the docs-as-memory principle from Part 1, it lives where the agent can actually see it: not in my head, not in chat history, not in a notes app.

The check-in lesson: features must earn their place in the flow

An earlier phase had added daily check-ins (sleep, mood) as cards when you start a workout, designed skippable from day one, on the principle that nothing stands between you and logging a set. Real use upgraded that principle from design guideline to law: even optional cards read as noise at 6 AM, which is why “calmer check-ins” made the friction list. The dopamine feature (“New PR!” celebrations) survived contact with reality. The earnest wellness features had to learn to whisper.

Interesting!

The flow you optimize is the one you’re in when you’re weakest: tired, rushed, low-patience. Design reviews happen at desks by people at their sharpest. Your users, even when that’s just you, are neither.

What I’d tell you

Ship to yourself early, then actually use it. The milestone “log a real workout from my phone” was in the roadmap from day zero, and everything after it was better-aimed than everything before it.
Write the friction list immediately, in the moment or right after.
Survey the incumbents once, deliberately. Where your complaints and their solutions agree, build with confidence. Where they diverge, you might have a differentiator, or a blind spot.
Make ideation a phase with a committed artifact. A rated backlog in the repo beats ideas in your head, in your chat history, or in a notes app the agent can’t see.
Rate by effort and let the easy column fund momentum. A session of quick wins after a heavy phase keeps the project fun, and fun is the actual fuel of side projects.

Part 7: the app grows up. Real multi-user auth, the migration that touched every table, and how “workout-tracker” became RepRepo.

References and further reading

Create custom subagents and How Claude remembers your project, Claude Code docs, if you’re wiring the ideation-phase pattern into your own repo: the backlog doc only works because the agent reads the repo.

Zero to App with AI, Part 5: Scaling Me, Not the AI

Nathan Bent — Fri, 17 Jul 2026 01:00:00 +0000

Around the middle of the project something flipped: the agent was no longer the bottleneck. I was. One session built a feature faster than I could specify the next one. Part 2 warned that multiplying agents multiplies cost. This part is about the places where parallelism and delegation genuinely paid, and the structures that kept it from becoming chaos.

Parallel phases in worktrees

The roadmap had independent phases queued up. Daily check-ins and a settings/themes page touched almost disjoint code. So they ran as separate sessions, simultaneously, each in its own git worktree, launched from pre-written, self-contained prompts.

If you haven’t used worktrees: git worktree add ../feature-x gives you a second working directory checked out to its own branch, backed by the same repository. No second clone, no stash juggling, and each parallel session gets a filesystem of its own to make a mess in. It is the difference between two people working on two copies of a document and two people fighting over one keyboard.

The mechanics that made this safe:

Independence first. Phases were picked for minimal overlap. The one predictable collision (both touching the main stylesheet) was flagged in advance as “expect a small merge conflict; resolve at merge time.” It was, and it was.
Self-contained prompts. Each parallel session got the full brief: read these docs, build this phase, end with /ship. No session depended on chat history from another.
The repo as the only communication channel.

Interesting!

Parallel sessions coordinate through commits and docs, never through shared conversational state. Which is exactly how human teams that work, work. If two sessions need to talk to each other, the thing they need to say belongs in a doc anyway.

Sub-agents with job descriptions

Claude Code lets you define sub-agents as little markdown files: a description of when to use them, which tools they may touch, which model they run on, and a system prompt as the body. Over the project these accumulated into a small staff:

code-reviewer: read-only tools (it literally cannot edit files, reviews report, they don’t meddle), pinned to the big model, briefed on this project’s specific bug habitat: PR-math edge cases, NULL weights, business logic leaking into the client.
docs-keeper: pinned to the small cheap model, allowed to edit, briefed to be terse and never rewrite history in the decision log.
And later, per-part specialists, which is where it gets interesting.

The job-description framing is the useful part. A sub-agent file answers “when should you call me, what am I allowed to do, and what do I cost,” which is the same information you’d want about a contractor. A clever one-off prompt answers none of those and is gone tomorrow.

Sub-projects: a plan doc plus a team

The best structure of the whole project emerged for a bigger feature (“exercise intelligence”: sectioned plans, a metadata-rich exercise database, a drag-and-drop builder, markdown import/export). Too big for a phase, it became a sub-project: one plan document splitting the work into parts A through D, and, this is the part I love, each part got its own scoped sub-agent defined in the repo: a schema-builder, an exercise-enricher, a UI-builder, a porter.

Each part then ran as its own session with its own specialist, against a shared written plan. The plan doc did for the sub-project what CLAUDE.md does for the repo: carried the intent, so no session had to be told twice. Part A (schema plus migration) shipped with a boot-time, idempotent migration that correctly upgraded the live server’s real database, old plans got a default section, exercises re-pointed, which I verified against production data before Part B started.

What stayed human

With all this delegation, the striking thing is what couldn’t be delegated:

Sequencing decisions. Multi-user was deliberately ordered after the fun features. It touches every table, so doing it last let one migration sweep everything (Part 7). An agent proposed the reasoning; choosing it was mine.
The test between phases. Every parallel stream still funneled through me using the app before the next phase started (Part 3’s rule).

Warning

Parallel building is safe. Parallel unreviewed shipping is how compound misunderstandings happen. The human reviewing at the merge seams is the thing that makes all of this safe to do at all; parallelize the work, never the judgment.

Anything requiring trust. Sudo passwords, firewall decisions, what goes on the public internet. The agent scripts around these boundaries respectfully; it doesn’t cross them.

I looked briefly at the always-on assistant frameworks (the OpenClaw genre) for “have the AI run the whole pipeline itself.” Wrong tool for this job: those shine as persistent personal assistants across chat apps. For repo work, the native primitives, slash commands, sub-agents, parallel sessions, and worktrees, turned out to be all the orchestration a one-person project needs, with no extra moving parts to maintain.

What I’d tell you

Parallelize phases, not opinions. Two sessions building disjoint features: great. Two sessions with overlapping judgment calls: merge hell with extra steps.
Worktrees are the safety rail. Each parallel session gets its own checkout; the merge is explicit, reviewable, and yours.
Write job descriptions, not prompts. A sub-agent file that says when to use me, what I may touch, and what model I run on is reusable forever. A clever one-off prompt is gone tomorrow.
Big features want a plan doc and a team of specialists. The sub-project pattern (plan plus part-scoped agents plus one session per part) scales shockingly well.
Keep yourself in the merge. Scale your attention, don’t remove it.

Part 6 changes register entirely: what happened when I actually took the app to the gym, and how nine annoyances between sets became the most productive planning document in the repo.

References and further reading

git-worktree, git-scm.com. The full mechanics of linked worktrees.
Create custom subagents, Claude Code docs. The frontmatter format, tool allowlists, and delegation behavior.
Model configuration, Claude Code docs, for pinning models per sub-agent.

Zero to App with AI, Part 4: Shipping Is Still Sysadmin

Nathan Bent — Wed, 15 Jul 2026 01:00:00 +0000

By the end of Part 3 the app worked great, on my desk. This is the part where it had to run somewhere else, and where “AI writes the code” met “computers are still computers.” Spoiler: the app-side work was almost eerily smooth, and every single problem lived in the last mile of Linux plumbing. As the guy whose day job is networks, I found this both humbling and deeply familiar.

The app side: deliberately boring

Auth started as the simplest thing that genuinely locks a door: one password in an environment variable, an HMAC-signed httpOnly cookie, zero new dependencies, about 70 readable lines. Unset the variable and auth is off, so local dev is unchanged. Change the password and every device is logged out, which is the feature, not a bug. The decision log records why not the alternatives: proxy-level basic auth couples the app to the proxy and looks awful on a phone, and JWT libraries are dependency weight with no benefit at one user. It later grew into real per-user auth with bcrypt (Part 7), and the upgrade path was clean precisely because v1 was small.

Production shape: one process, one port. Express serves the API and the built client, with an SPA fallback. A /api/export endpoint dumps all your data as JSON. Never build a personal-data app without an exit door.

Backups use SQLite’s online backup API, stamped daily, pruned to fourteen, run by cron.

Caution

A naive file copy of a live SQLite database can catch it mid-write, especially in WAL mode where recent transactions live in a separate -wal file next to the main one. The copy looks fine, restores fine, and is quietly missing or corrupting data. The online backup API exists specifically to take a consistent copy while the database is in use.

The full local smoke test, no cookie 401s, wrong password rejected, login sets the cookie, export works, static app serves, SPA fallback falls back, passed 8-for-8 before anything left my machine.

The VM side: five sharp edges in one afternoon

Deploying to a fresh Ubuntu VM in the homelab produced, in order:

The invisible byte

First deploy script, piped over SSH: bash: line 1: #!/usr/bin/env: No such file or directory. The script had a UTF-8 BOM, three invisible bytes (EF BB BF) that Windows tooling loves to prepend, and bash tried to execute \xEF\xBB\xBF#!/usr/bin/env as a command. The shebang line was fine. The file just didn’t start with it.

The 700 house

useradd -m created the app user’s home directory with owner-only permissions, so the deploying user couldn’t cd into the directory it had just created. One chmod 755 later, the whole install script ran clean.

The firewall that was doing its job

App live on the VM, health check green on the VM, and total silence from my desk. UFW default-deny with only SSH allowed. This is the one I should have predicted before the agent did, given what it says on my resume. The fix wasn’t “open everything”; it was one rule allowing the app port from private-network addresses only.

The sudoers ordering trap

For unattended deploys I dropped a NOPASSWD rule into /etc/sudoers.d/99-deploy, and sudo kept prompting anyway.

Interesting!

Sudoers drop-ins load alphabetically and the last matching rule wins. A NOPASSWD rule early in the alphabet is silently overridden by any later file that matches the same user. My 99-deploy lost to an existing file further down the list; renaming mine zzz- fixed it.

Bonus discovery: this VM’s Ubuntu ships sudo-rs, the Rust rewrite of sudo that became the default in Ubuntu 25.10, and its error messages are just different enough from classic sudo to gaslight you mid-debug.

PowerShell’s CRLF ambush

The polished deploy pipeline piped the update script to the VM through PowerShell, which helpfully rejoins piped lines with Windows line endings. Bash met $'\r' and quit.

Tip

Fix the instance, then make the class impossible: stop piping (scp the file, strip \r on the far side) and add a .gitattributes pinning *.sh to LF forever, so a Windows checkout can never re-poison the scripts. Any time an OS boundary bites you, look for the one-line config that removes the whole category.

None of these are AI problems or AI solutions, but debugging them with an agent was genuinely faster: it read the error, named the BOM, knew the sudoers ordering rule, wrote the .gitattributes. What it couldn’t do was hold my sudo password, by design. The privileged bootstrap steps stayed human. Then a deliberately narrow permanent rule (run commands as the app user plus restart this one service, nothing else) let everything after be unattended.

/ship: the phase-ending word

All of it condensed into a slash command. Saying /ship at the end of any session now runs the checklist: update the docs (roadmap ticks, decision log entries), commit and push in logical chunks, deploy committed HEAD to the test server, verify from the outside, report. The deploy script runs the test suite first and refuses to ship red. It archives committed HEAD only. Uncommitted work deliberately doesn’t deploy, which quietly enforces the commit discipline I kept flunking in Part 3.

The target is a parameter, so “add a second test server” is an argument, not a new script. And because it’s a checklist in a file rather than a habit in a head, every future session, mine or the agent’s, ends phases exactly the same way.

What I’d tell you

Make v1 auth small enough to read in one sitting. You can grow it later. You can’t easily shrink a framework.
One process, one port, one SQLite file is a gloriously deployable shape for a personal app. Resist the urge to be web-scale.
Expect the last mile to be sysadmin, and let the AI pair on it. It has read more man pages than you have.
Keep privileged access narrow and boring. Broad temporary sudo for bootstrap, then a scoped permanent rule for the pipeline.
Turn your deploy into one word. If shipping takes a checklist you must remember, you’ll skip steps. If it’s a command, you won’t.

Part 5: the multiplier. Running phases in parallel sessions, scoped sub-agents with their own job descriptions, and where “more agents” actually earned its cost.

References and further reading

Using the SQLite Online Backup API, sqlite.org. Why a live database wants this instead of cp.
Adopting sudo-rs by default in Ubuntu 25.10, Ubuntu Discourse announcement.

Zero to App with AI, Part 3: The Phase Rhythm

Nathan Bent — Mon, 13 Jul 2026 01:00:00 +0000

Part 1 and Part 2 covered the setup: docs as memory, cost controls in config. This is the part where the app actually got built, a core logging loop, a plans system, and a PR detection engine, and where the working rhythm emerged that carried the whole project:

One phase per session. Review at every phase boundary. The human tests between phases.

That is the entire method. The rest of this post is what it looks like in practice and what it caught.

The loop

Each phase ran the same way:

Paste the kickoff prompt (pre-written at the end of the previous phase) into a fresh session.
The agent builds, explaining non-obvious choices as it goes. That is a CLAUDE.md rule, because I am learning web dev here, not just extracting code from a machine.
At the boundary, a review pass: read the diff, run everything, poke the edges.
I use the result for real, note what is off, and feed that into the next phase.

The phases were deliberately small. Phase 2 was “pick exercise, enter weight and reps, save set, see today’s session.” Phase 3 added workout plans, so “start Push Day” pre-populates the session. Phase 4 was the dopamine feature: PR detection with a “New PR!” celebration, and a progress chart per exercise. Each one fit comfortably in a single session, which Part 2 explained is also where the money is.

Tests first, but only where bugs hide

We did not test everything. We tested the one module most likely to have subtle bugs, a rule written into CLAUDE.md on day zero: the PR math. Weight PRs, rep PRs at a given weight, estimated 1RM (the Epley formula, whose accuracy falls off as reps climb, so the app’s 12 rep cutoff is part of the spec, not an implementation detail), and session volume records.

The tests were written against the rules in DATA-MODEL.md before the route existed, each one running against a fresh in-memory SQLite database. And they immediately forced real decisions the prose spec had glossed over. Does a bodyweight set (NULL weight) break a weight PR? No, it is its own “reps at bodyweight” bucket. Does the first set you ever log count as a PR? No, “broken” implies something existed to break. Does a heavy warm-up set the bar? Never. Warm-ups are excluded, and there is a test proving a 500 lb warm-up can’t.

Every one of those edge cases would have been a quiet production bug. Instead they are one-line test names.

What review actually caught

The end-of-phase reviews earned their keep with real finds, not style nits. Highlights, in ascending order of how much they would have annoyed me in production:

Dormant features. Review noticed the warm-up exclusion logic was beautifully tested and completely unreachable. The UI had no warm-up checkbox yet, so the flag was always false.

Interesting!

Nothing about “all tests green” tells you a feature can’t be triggered. Tests prove the logic is correct if reached. Only tracing the path from the UI proves it is reachable.

The over-celebrating PR banner. Session volume PRs originally fired on every set after your session total passed the old record, so on a good day, sets five through ten would each yell “New PR!” at you. Celebration inflation. The fix: only fire on the set that first crosses the record, with a regression test so it stays fixed.

The evening-workout timezone bug. The client resumed “today’s session” by comparing a UTC timestamp’s date prefix to the local calendar date. Which works fine, until you train after 7 PM in a UTC-minus timezone, when the UTC date rolls over and a page refresh mid-workout would silently create a duplicate session instead of resuming.

Caution

This is the classic shape of a timezone bug: no error, no crash, just quietly wrong data, and it only reproduces in the evening, so it survives every daytime test you run. The fix (compare Date objects, not string prefixes) landed with a comment explaining the trap for whoever touches that code next.

The mistake I kept making

Every phase, the same finding at review time: the work wasn’t committed. At one point two entire phases, around eight hundred lines of the best code in the project, existed only in the working tree, one bad git checkout away from oblivion. This despite “small commits, one feature per commit” sitting right there in CLAUDE.md since day zero.

The lesson generalizes. An agent optimizes for the thing you are asking about right now (the feature), and the standing rules (commit discipline) quietly lose priority. It is the same failure mode as a junior engineer who nails the change but skips the change ticket, and the fix is the same: not scolding, structure. Commit-and-push became part of an end-of-phase checklist that runs as a single command. Structure beats intention, for AIs exactly as for humans. That checklist became /ship, which gets its own war story in Part 4.

The human is the test between phases

The most valuable QA in the whole project cost nothing: I used the app. Logged sets from my phone. Noticed the exercise dropdown was miserable with 52 entries, which became a type-to-search picker. Noticed starting a workout felt bare, which became check-in cards (sleep, mood) that are deliberately skippable, because nothing is allowed to stand between you and logging a set.

Later, real gym sessions generated a nine-item friction list that became an entire ideation phase (that is Part 6).

Tip

None of that feedback is producible by an agent, however good, because it comes from squinting at your phone between sets with chalk on your hands. Be the field test. Your friction list is the roadmap’s best input.

What I’d tell you

Size phases to one session. If the kickoff prompt doesn’t fit in a paragraph, the phase is too big.
Concentrate tests where the subtle bugs are, for us the PR math, and let curl checks cover the plumbing.
Review at boundaries, not continuously. Batch review at the phase edge caught everything worth catching, cheaper.
Make the standing rules structural. Anything you find yourself repeating at review time (commit! update docs!) should become a checklist the agent executes, not advice it remembers.
Use the thing between phases. Real use finds what tests can’t.

Part 4 is the deploy story: auth in one file, a homelab VM, and the five sysadmin sharp edges that no amount of AI polish saved me from.

References and further reading

How Claude remembers your project, Claude Code docs, on CLAUDE.md rules and why standing instructions still need structural enforcement.
Validation of the Brzycki and Epley equations for 1RM prediction, if you want the actual research on where 1RM estimation formulas hold up and where they don’t.

Zero to App with AI, Part 2: Keeping It Cheap

Nathan Bent — Sat, 11 Jul 2026 01:00:00 +0000

The dirty secret of AI-assisted development is that the naive way to do it, one enormous chat session, the biggest model, all day, is expensive out of proportion to what you get. Before writing much code for RepRepo, I set up cost controls. The interesting part is that almost none of them rely on me remembering to do anything, which turns out to be the whole trick.

If you missed it, Part 1 covered the docs-as-memory setup this all builds on.

The routing table

My docs/AI-WORKFLOW.md starts with a table that says which model does which job:

Task	Model	Why
Day-to-day coding, CRUD, UI, tests	Mid-tier (Sonnet)	Great at it, cheap
Architecture, schema review, stuck bugs	Big model, one focused session	Deep reasoning is worth paying for occasionally
Doc updates, checkbox-ticking, bookkeeping	Small model (Haiku)	It’s bookkeeping
Commit messages, fake seed data, “what is middleware?”	Local LLM (free)	Iteration costs nothing

The rule of thumb that emerged: the big model is for decisions, the mid model is for code, the small model is for chores, and the free model is for anything where “okay” is good enough.

If you have ever done QoS design, this will feel familiar. You are not trying to give everything the best treatment. You are trying to make sure the expensive queue only carries traffic that deserves it.

Config beats discipline

A routing table you have to remember is a routing table you will ignore by Tuesday. So the routing went into configuration:

Sub-agents carry their own model. In Claude Code, a sub-agent is a markdown file with YAML frontmatter, and one of the frontmatter fields is model. My code-reviewer agent is pinned to the big model in its config file, and my docs-keeper agent is pinned to the small one. When a review runs, the right model runs. Nobody chooses.
Slash commands carry their own model too, via the same model frontmatter field. /wrap-up, the end-of-session command that ticks roadmap checkboxes and drafts decision log entries, runs on the small model, always.
A git alias handles commit messages for free. git aimsg pipes the staged diff through a code-tuned model on my home server’s Ollama instance and prints a conventional commit message. Costs nothing, runs on hardware I already own.

Quotedocs/DECISIONS.md

Cost control that relies on remembering to switch models fails; encoding it in config makes the cheap path the default path.

That entry from my own decision log says it better than I can in prose. The pattern shows up in networking all the time: policy that lives in muscle memory drifts, policy that lives in config holds.

The free tier is better than you think

I run Ollama on a homelab box with a decent GPU, with a browser chat UI for me and a raw API for scripts. The models on it (a 14B code model, a couple of general models in the 14B to 24B range) are nowhere near frontier quality, and it does not matter, because I only send them work where mediocre is fine: commit messages, learning questions (“explain Express middleware like I’m new”), rubber-ducking, and generating fake seed data.

The first time I tested the pipeline, the local model confidently explained that OLLAMA stands for “Online Learning and Language Acquisition for Mathematics and Arithmetic.” It does not stand for anything. That hallucination was clarifying rather than alarming: this is the tier where confident nonsense is acceptable, because everything it produces is either checked by me in two seconds (a commit message) or purely educational scaffolding I will verify against real docs anyway. Route accordingly.

Session hygiene: the biggest lever isn’t a tool

Here is the thing that actually dominates cost: every message you send re-sends the whole conversation. The API is stateless, so your entire history rides along with each new message. Caching softens this (Claude Code caches your session automatically, so previously processed history is re-read at a steep discount instead of full price), but the history still gets re-read and billed on every turn, so a long meandering session still gets more expensive per message the longer it runs. The fix is structural, not heroic:

One session, one task, then end it. Start a session, build the phase, run the wrap-up, close. The next session starts fresh, and because of the docs-as-memory setup from Part 1, it starts fresh with full context, for free. CLAUDE.md and the docs folder carry everything between sessions. Chat history carries nothing but cost.

This is also why the phase structure matters financially, not just organizationally. A phase is sized to fit comfortably in one session. “Scaffold the client” is a session. “Also fix that bug and discuss deployment strategy” is a second one.

The counterintuitive one: automation isn’t cheaper

When I first asked “can we automate this more?”, the honest answer I got, and later verified, was that most automation increases spend.

Caution

Multi-agent orchestration, agents controlling agents, parallel everything: these burn several times the tokens of a single focused session, because every agent carries its own copy of the context. The bill scales with the number of contexts, not the amount of work done.

The economical version of automation is boring: pinned models, one-keystroke commands for repetitive prompts, a local model for the free tier, and docs that eliminate re-explanation. Fancy orchestration has its place (Part 5 covers where parallel sessions genuinely earned their cost), but as a default it is a bill, not a feature.

What I’d tell you

Write the routing table down, then push it into config, per-agent models and per-command models, so the cheap path is the default path.
Stand up a free tier. Even a modest local model absorbs a surprising amount of work once you are honest about which tasks tolerate “okay.”
Treat sessions like transactions. Open, do one thing, commit, close. Long sessions are where money goes to die.
Let the repo be the memory. Every fact in a doc is a fact you never pay to re-explain.
Distrust automation that multiplies contexts. More agents does not mean more productivity per dollar. Usually the opposite.

Next, Part 3: the actual build. The phase rhythm, what end-of-phase reviews caught (including a timezone bug that would have eaten my evening workouts), and the one mistake I kept making anyway.

References and further reading

Model configuration, Claude Code docs. Covers the model frontmatter field for sub-agents and commands.
How Claude Code uses prompt caching, Claude Code docs. Why long sessions cost what they cost, and what invalidates the cache.
Prompt caching, Claude API docs, if you want the underlying mechanics.

Zero to App with AI, Part 1: Write the Docs Before the Code

Nathan Bent — Thu, 09 Jul 2026 01:00:00 +0000

This is a different kind of post for this blog. Less BGP, more JavaScript.

I built and shipped a real app, RepRepo, a workout tracker, essentially over one weekend, working with an AI coding agent (Claude Code, in my case, though most of this translates to any of them). Not a todo list demo either. It has a plans system, PR detection with unit tests, multi-user auth, security hardening, nightly backups, and tagged releases deployed by CI, and it is running on the public internet where I actually use it at the gym.

I should be clear about my starting point, because it matters for how you read this series. I am a network engineer. I can script, I can read code, and I run a homelab full of self-hosted services, but I had never built a web application. The agent wrote nearly all of the code. My job was direction, review, testing, and the sysadmin work at the end. Whether that counts as “building an app” is a philosophical question I will leave to the comments section I do not have.

This series is the honest write-up: what worked, what bit me, and what I would tell anyone starting the same experiment. Part 1 is about the counterintuitive first step, the one hour that made everything after it possible.

The empty folder

Day zero looked like this:

workout-tracker/
├── README.md
├── CLAUDE.md
├── docs/
│   ├── ROADMAP.md
│   ├── DATA-MODEL.md
│   ├── DECISIONS.md
│   └── AI-WORKFLOW.md
└── .claude/agents/

No code. Not one line. Just markdown.

That felt backwards. Every instinct says start with npm create vite and get pixels on screen. But AI-assisted development changes the economics of documentation completely, for one reason.

Interesting!

The docs are the agent’s memory. An AI coding session starts from zero every time. Anything you don’t write down, you will re-explain every session, forever, at token prices. Write it down once and every future session starts already knowing the project.

This is not a metaphor. A coding agent does not remember yesterday’s session, your preferences, or why you chose SQLite. Chat history dies when the session ends, and while it is alive it costs money to carry, because it rides along with every message you send. The repo, on the other hand, is free, permanent, and versioned. So the docs are not documentation in the usual sense, written after the fact for some hypothetical future reader. They are load-bearing infrastructure, consumed by the agent at the start of every single session.

Once that clicked, spending the first hour on markdown stopped feeling like procrastination and started feeling like configuring the router before plugging in the clients.

The four files that matter

CLAUDE.md is the file Claude Code reads automatically at the start of every session (other tools have equivalents: rules files, instructions files, whatever your agent auto-loads). Mine is short and rule-dense: the stack, the architecture rules (“ALL business logic lives in the server, the client renders and calls /api”), workflow rules (“small commits, one feature per commit”), and cost rules (Part 2 is entirely about those). The guidance from the Claude Code docs is to treat it as the place you write down whatever you would otherwise re-explain, and to keep it concise, because shorter instruction files get followed more reliably.

One sentence in mine paid for itself fifty times over: “The developer is learning, explain non-obvious choices briefly as you go, and prefer simple, readable code over clever code.” Every session, every explanation, calibrated to me, for free. If you are using a project like this to learn a stack, put a line like that in on day zero.

docs/ROADMAP.md breaks the project into phases with checkboxes. Phase 1: foundation. Phase 2: core logging loop. Phase 3: plans. Phase 4: PRs and progress charts. Each phase is small enough for one focused session, and each ends with its checkboxes ticked. This file became the heartbeat of the whole project, which is Part 3’s story.

docs/DATA-MODEL.md is the schema, written in SQL, before any code existed. Five tables, and, crucially, the business rules in prose: how PR detection should work, what the Epley 1RM formula is and where it stops being trustworthy, what a “workout” even is. Code can tell you what the app does. Only a doc can tell you what the app is supposed to do, which is exactly the distinction an agent needs when it writes tests.

The file ended with a section called “Open questions (answer these before Phase 2)”: lbs or kg? Track RPE? How do bodyweight exercises work? I answered them inline like a form. That ten minute exercise surfaced decisions I would otherwise have made accidentally, mid-implementation, three phases deep, and at least one of them (bodyweight exercises) would have meant a schema migration if I had discovered it late.

docs/DECISIONS.md is a decision log with a rigid little format, three lines per entry:

Decision: <what we chose>
Why: <the reason, one or two sentences>
Alternatives: <what lost, and why>

It started with two entries. It now has over forty, and it is the file I would rescue from a fire. When a fresh session asks “why is weight stored in lbs only?” the answer is in the repo, dated, with the alternatives that lost. Future me does not do archaeology, and the agent does not re-litigate settled questions. If you have ever kept a change log for a firewall, this is the same instinct pointed at software decisions.

Day one, measured

With the docs in place, day one went: install Node, git init, resolve the open data-model questions, then paste a kickoff prompt (pre-written at the bottom of the roadmap) that scaffolded the Express + SQLite server. Schema, a seed script with 52 exercises, and the first three API routes. The agent tested everything with curl before calling it done, including the failure cases: bad exercise IDs got clean 400s, not stack traces.

By evening there was a working API with validated inputs. The next morning there was a React client. The docs took about an hour of that. Everything else in this series runs on the rails laid in that hour.

What I’d tell you

Write CLAUDE.md first, or whatever your tool’s auto-loaded context file is. Rules you write once are rules you never repeat.
Put the schema and the business rules in a doc, not just in code. Code says what. The doc says why, and what counts as correct, which is exactly what an agent needs to write real tests.
Keep a decision log with a format. Decision, why, alternatives considered. Three lines per entry. It compounds.
Answer the open questions before building. Make the doc ask you questions. The ten minutes I spent answering “how should bodyweight exercises work?” saved a schema migration later.
Pre-write the next kickoff prompt. Ending each phase by writing the prompt that starts the next one means zero cold-start cost.

The pattern under all five: move context out of your head and out of the chat history, into the repo. Chat history dies with the session and costs money to carry. The repo is free, permanent, and versioned.

Next up, Part 2: how I kept the whole thing cheap. Model routing, running the boring work through a local LLM on the homelab, and why more automation usually means a bigger bill.

References and further reading

How Claude remembers your project, Claude Code docs. Covers CLAUDE.md loading behavior and what belongs in it.
Claude Code overview, the official starting point if the tool is new to you.