Building This Site with Claude Code

Tooling note: this session ran on Claude Opus 4.8.

A category tag (Misconceptions and Myths) rendered with no color on the live site. The color definitions lived in a types file that the CSS build was never told to scan, so it stripped the classes used only there. Most tags survived by luck, because their exact colors also appeared elsewhere in the code. Adding that folder to the scan list brought the orange tag back and hardened the rest.

I moved the last two posts out of the codebase and into Firestore, so the whole blog is now managed in the admin. The public pages already read from the database, so the real work was deleting the hardcoded copies and pointing the leftover spots (the sitemap and the related-posts list) at the live source instead.

Editing a post and saving again could create a duplicate. After the first save the form never switched into edit mode, so a second save (Save Draft, then Publish) wrote a brand new copy instead of updating the first. Now the form tracks the saved post and updates it.

Finished by checking the draft workflow end to end: drafts stay hidden from the public site, and the security rules back that up. I added a preview so I can see a post exactly as it will render before publishing, and made the publish date set itself on the day a post goes live.

Tooling note, as usual: this session ran on Claude Opus 4.8. Performance work is a good fit for a high-effort model, because the fix is rarely the first thing you would guess.

The trigger was a feeling, not a number: pages took a beat too long, and I was hammering Cmd+Shift+R constantly to see whether my latest change had actually gone live. The temptation is to start "making things faster" immediately. We did the opposite first — we measured. A production build prints exactly how much code each page makes a visitor download, and reading that table told the story before we changed a single line: every page that talks to the database was carrying roughly two-and-a-half times the code of the one page that does not, and the home page was rebuilding itself from scratch on every single visit while still showing nothing until the browser did a second lap of work.

First problem: the slow part was happening in the wrong place. The home page was sending you an empty shell, and only then did your browser download a hefty database toolkit, connect, and ask three separate questions — two of which read the entire list of stories — before anything appeared on screen. That is the slowest possible order of operations. The fix was to move that work to the server, where it happens once, before the page is sent: now the very first thing you receive already has the stories, the headline stats, and the map dots baked in. Three database questions became one, and the loading shimmer is simply gone because there is nothing left to wait for.

Second problem was the hard-refreshing, and it was a completely different beast. When I approve a story or publish a post in the admin panel, that change goes straight to the database from my browser — which means the public site's cache never finds out anything happened. So it keeps serving the old version for a few minutes, and a hard refresh does not even help, because the staleness lives on the server, not in my browser. That is maddening when you cannot see your own work. The fix: after every admin action, the panel now quietly tells the site "that page changed, throw away your saved copy." Changes show up immediately, and I can stop abusing my keyboard.

Here is the part that earns this entry its place, because it is really about testing, not just speed. I did not take "it should be faster now" on faith. We started the real production site on my machine and looked at what it actually sends: confirmed the story text and the contributor count were now present in the very first response instead of arriving late, confirmed the page was now allowed to be cached, and then tried to abuse the new "refresh" button from the outside — once with no key and once with a fake one — to make sure it refused both. A performance fix that looks right in the code is not the same as one you have watched work. The difference between those two is the whole job.

This is the inspect-the-output philosophy pointed at speed instead of features. I cannot read a change and know in my gut that it shaved a second off the load; I can build the page before and after and watch the numbers move, and I can open the running site and see the content arrive sooner. Describe the outcome you want, then go verify the outcome — do not grade the implementation you never read.

A note on tooling, since people ask: Claude Fable 5 is still on limited access, so like recent sessions this one ran on Claude Opus 4.8 — this time at extra-high effort, which I have been leaning on for the trickier debugging. The encouraging part is that a single top-tier model at high effort has stayed comfortably within my usage limits at this project's cadence. I have not had to ration it to get real work done, which is exactly what you want to hear before you invite more people in.

First bug, and the most important: a real user tried to submit their story and got a generic "Something went wrong." It worked every time for me, which is the tell. The form sets blank optional fields to "undefined," and the database's browser library throws an error the moment you try to save an undefined value — and Name, an optional field, is the very first one. I had simply filled in every field during my own tests. The fix was to tell the database to drop undefined fields instead of choking on them, and to stop the form from silently swallowing the error so the next failure is actually visible.

Second bug: a tester who lives in Bowie, Maryland showed up on the world map as a dot in Texas. The submission form only asked for City and Country, and "Bowie" exists in several U.S. states, so the geocoder confidently picked the wrong one. There is no clever lookup that fixes this — the answer is more information. We added an optional State / Region field so the lookup becomes "city, region, country," and built an admin control to correct any pin after the fact, either by re-geocoding from a fixed location or by typing coordinates by hand. Automated geocoding will never be perfect, and I already review every story, so giving myself a ten-second override beats chasing accuracy I cannot guarantee.

Third bug came wrapped in a feature. We had just enriched responses — commenters can now add a LinkedIn link, and the admin panel can finally view and delete every response on a story. While testing that, a comment saved fine and appeared in the admin panel but not on the public story page. The public page asks the database for "this story's approved comments, newest first," and that particular question needs a database index that had never been created. The query was failing, and the failure was being swallowed, so the page just looked empty. Adding the index fixed it instantly, and again, we stopped hiding the error.

The thread connecting all three is the point of this whole project: these are the bugs only a real, unpredictable person finds. In my own testing I fill in every field, type a city I know is unambiguous, and post a single comment. Real people leave fields blank, live in towns that share a name with four other towns, and do things in an order I never scripted. As more people join, that loop only gets stronger — every new contributor is also, for free, a fuzz-tester. Scaling a project built this way turns out to be less about the code and more about widening the feedback loop and fixing fast when it talks back.

A quick note before the work: Fable 5 was unavailable today, so this session ran on Claude Opus 4.8 with High Effort. Same workflow, different engine.

First problem: a cover image linked from Google Drive would not show up. The instinct is to blame the file type, but the PNG was never the issue. A Google Drive "share" link points at a viewer web page, not the raw image, so the browser gets HTML back instead of a picture. On top of that, the site blocks remote image hosts unless you explicitly allowlist them. The clean fix was to stop fighting it: drop the image in the project's public folder, which our own domain then serves as a real, shareable URL. No new service to sign up for.

Second problem: the home page was not showing posts written through the /admin tool. The home page only read the posts hardcoded in the codebase, while posts created in the admin live in a database. The blog index already merged both sources; the home page did not. We added a small piece that merges them the same way, so the latest post now appears everywhere it should.

Third problem, and the most interesting: a freshly published post returned "Page not found," even though it existed and showed up fine on the blog index. The cause was a database security-rules mismatch. The rules only permit a query that is guaranteed to return published posts. The index asks for "published == true" and is allowed; the single-post page asked only by its name (slug), which the rules reject outright. That rejection was being quietly turned into a 404. Constraining the lookup to published posts fixed it and lined the two queries up.

Fourth problem: sharing a post to LinkedIn showed the generic site card instead of the post's own image and headline. Social crawlers read tags rendered on the server, but admin posts were only being fetched in the browser, so the server had nothing post-specific to offer. We taught the page to fetch the post on the server when it builds those tags. LinkedIn's own inspector confirmed the per-post card afterward.

Last problem, and the one I most wanted to rule out as serious: a post dated June 14th displayed as June 13th. That is exactly the kind of thing that makes you worry the data got saved wrong. It did not. The date was stored correctly; the display code read a plain calendar date as midnight UTC and then re-rendered it in a US timezone, sliding it back a day. Telling the formatter to interpret the date in UTC put it right, with nothing to repair in the data.

I gave Fable 5 one paragraph describing what I wanted: a new tab where people could follow along with how I use Claude Code to build this site. No wireframe, no spec, no component list. It read the existing codebase, matched the blog page's design patterns, created a content file so future entries are easy to add, wired the page into the navigation and sitemap, and wrote the first draft of these entries by reading the project's own git history.

That last part is what struck me. I never told it what happened on May 18th or May 31st. It reconstructed the story of this project from the commit log, which is a record Claude Code itself wrote over the past month. The project is now documenting itself.

With more capable models, my role shifts even further toward editor and quality inspector. I read this page the way you are reading it now, checked the dates against what I remember, and asked for revisions where the tone was off. I did not review the React code line by line. I reviewed the result.

Until this point the admin page had no login, which was fine while the site was a prototype on my laptop and a known launch blocker the moment it went public. I asked Claude Code to ship the production checklist in one pass: lock down /admin, remove the fake demo stories and placeholder content, add story reactions and sharing, and give me a real admin experience.

The part I could not have done quickly on my own was the blog admin UI. I described it as "I want to write and publish posts without redeploying the site," and Claude Code built a Firestore-backed editor that merges with the hardcoded posts on the public blog page. When the Subscribers tab did not show up in the section switcher, I just described the symptom and it found and fixed the wiring.

My testing process for all of this was behavioral: log in, log out, try to reach admin without auth, publish a draft, unpublish it, check the public page. I never opened the auth code. I attacked the door instead of reading the blueprint for the lock.

This was the first time the project faced a real-world security event rather than a theoretical one. A CVE advisory landed for React Server Components, the exact architecture this site is built on. Instead of spending my evening reading the advisory and diffing changelogs, I brought it to Claude Code and asked two questions: are we actually exposed, and what is the safest minimal fix?

It walked me through which parts of the advisory applied to our setup, upgraded the affected dependencies, and we shipped the fix through a proper pull request that I merged after the preview deployment checked out. The workflow felt less like patching software and more like consulting a security engineer who could also do the work.

For a solo builder this matters a lot. CVE response is exactly the kind of work that gets skipped on side projects because it is urgent, unfamiliar, and unrewarding. Lowering the cost of doing it right means it actually gets done.

Day two was less about architecture and more about the hundred small things that separate a prototype from a real site. Claude Code generated the SEO layer in one shot: metadata, sitemap, robots.txt, social sharing images. Each change took a sentence to request and a minute to verify.

The email work was the instructive part. HTML email is notoriously hostile, and the newsletter logo and unsubscribe links rendered wrong in actual inboxes in ways no code review would have caught. My feedback loop was: send a test email to myself, screenshot what looked wrong, describe it, and let Claude Code adjust the template. Three or four rounds of that and the emails were clean.

This is the purest version of the workflow I keep describing: I cannot evaluate HTML email markup by reading it, and I do not need to. The inbox is the test suite.

This is where Claude Code stopped feeling like a code generator and started feeling like a DevOps partner. Building the bi-weekly newsletter pipeline meant touching Google Cloud for the Gemini API, Gmail for sending, Vercel for deployment config, and Upstash Redis for subscriber storage. Each of those has its own CLI, its own auth dance, and its own naming conventions.

The real debugging story from this day: subscriber writes to Redis were silently failing in production. Claude Code traced it through layers I would have spent hours on. The environment variable names Vercel auto-creates for its KV integration did not match what the code expected, and client-side writes needed to move behind a server-side API route. Two commits, problem solved.

It also handled the model churn for me. We started on one Gemini model, and when newer versions released, switching was a one-line conversation. The pipeline itself never changed.

A community site that accepts public submissions is an open database with extra steps if you get the security rules wrong. So the second session of day one was a security review of the first session. I asked directly: what would you attack about what you just built?

The answers were concrete. The example environment file with config hints came out of the repository. Firestore got rules that let anyone submit a story but only let approved stories be read publicly, with moderation writes restricted. Then came the genuinely educational part: the rules were initially too strict and broke legitimate queries. Watching Claude Code debug the difference between document-level and query-level permissions in Firestore (resource.data versus request.query) taught me more about Firestore's security model than the documentation ever did.

I verified the result the way an attacker would: tried to read unapproved stories from the browser console, tried to write to collections I should not be able to touch. The rules held.

This project started as a description, not a design document. I told Claude Code what the site was for: a place for real people to share real AI stories, with a world map showing where they come from, and an editorial blog alongside it. From that, it scaffolded the entire platform: Next.js 14 with the App Router, Tailwind, Firestore for data, Leaflet for the map.

The commit log from that first day reads like a time-lapse: initial build, newsletter wiring, story feed, map pins, geocoding, story detail pages. Eighteen commits. Each one was a short conversation: I described what I wanted or what looked wrong, Claude Code made the change, I checked the running site.

Here is the part I want to be honest about, because it is the whole reason this page exists: I did not read most of this code. I am an experienced builder, but my role in this project is deliberately different. I inspect outputs, not implementations. I click through the site, try to break the forms, check the data landing in Firestore, and judge the result. The question this project is testing is whether that is enough to ship something real. So far the answer is yes, with the caveat that knowing what to inspect is itself an expert skill.