diff --git a/content/posts/2025-09-08-from-accidental-discovery-to-agricultural-infrastructure-building-the-worlds-first-online-farmers-market-2002-2011.md b/content/posts/2025-09-08-from-accidental-discovery-to-agricultural-infrastructure-building-the-worlds-first-online-farmers-market-2002-2011.md index fed42fc9..3ea285b4 100644 --- a/content/posts/2025-09-08-from-accidental-discovery-to-agricultural-infrastructure-building-the-worlds-first-online-farmers-market-2002-2011.md +++ b/content/posts/2025-09-08-from-accidental-discovery-to-agricultural-infrastructure-building-the-worlds-first-online-farmers-market-2002-2011.md @@ -8,7 +8,7 @@ tags: - locallygrown categories: - locallygrown -lastmod: 2025-09-15T01:50:39.989Z +lastmod: 2025-09-22T20:54:42.989Z slug: locallygrown-origin-story --- @@ -237,6 +237,6 @@ _This is part one of a series documenting the creation, evolution, and rescue of 1. **From Accidental Discovery to Agricultural Infrastructure** ← _You are here_ 2. [The 23-Year Rescue Mission: Saving Agricultural Innovation from Technical Extinction](https://blog.kestrelsnest.social/posts/locallygrown-rescue-mission/) 3. [The Architecture Challenge: Translating 19 Years of Rails Logic to Modern SvelteKit](https://blog.kestrelsnest.social/posts/locallygrown-rails-svelte-migration/) -4. Crisis Response: When Launch Day Goes Wrong -5. Lessons from the Solo Developer Using Modern Tools +4. [The Reality of Production: When Hope Meets Live Users](https://blog.kestrelsnest.social/posts/locallygrown-reality-of-production/) +5. [Lessons from the Solo Developer Using Modern Tools](https://blog.kestrelsnest.social/posts/locallygrown-lessons/) 6. The Future: Building on Modern Foundations diff --git a/content/posts/2025-09-09-the-23-year-rescue-mission-saving-agricultural-innovation-from-technical-extinction.md b/content/posts/2025-09-09-the-23-year-rescue-mission-saving-agricultural-innovation-from-technical-extinction.md index bab7a320..447597be 100644 --- a/content/posts/2025-09-09-the-23-year-rescue-mission-saving-agricultural-innovation-from-technical-extinction.md +++ b/content/posts/2025-09-09-the-23-year-rescue-mission-saving-agricultural-innovation-from-technical-extinction.md @@ -8,7 +8,7 @@ tags: - locallygrown categories: - locallygrown -lastmod: 2025-09-15T01:50:22.702Z +lastmod: 2025-09-22T20:54:49.481Z keywords: - locallygrown slug: locallygrown-rescue-mission @@ -234,6 +234,6 @@ _This is part two of a series documenting the rescue and modernization of Locall 1. [From Accidental Discovery to Agricultural Infrastructure (2002-2011)](https://blog.kestrelsnest.social/posts/locallygrown-origin-story/) 2. **The 23-Year Rescue Mission: Saving Agricultural Innovation from Technical Extinction** ← _You are here_ 3. [The Architecture Challenge: Translating 19 Years of Rails Logic to Modern SvelteKit](https://blog.kestrelsnest.social/posts/locallygrown-rails-svelte-migration/) -4. Crisis Response: When Launch Day Goes Wrong -5. Lessons from the Solo Developer + AI Trenches +4. [The Reality of Production: When Hope Meets Live Users](https://blog.kestrelsnest.social/posts/locallygrown-reality-of-production/) +5. [Lessons from the Solo Developer Using Modern Tools](https://blog.kestrelsnest.social/posts/locallygrown-lessons/) 6. The Future: Building on Modern Foundations diff --git a/content/posts/2025-09-15-the-architecture-challenge-translating-19-years-of-rails-logic-to-modern-sveltekit.md b/content/posts/2025-09-15-the-architecture-challenge-translating-19-years-of-rails-logic-to-modern-sveltekit.md index 6e56d42b..308c1059 100644 --- a/content/posts/2025-09-15-the-architecture-challenge-translating-19-years-of-rails-logic-to-modern-sveltekit.md +++ b/content/posts/2025-09-15-the-architecture-challenge-translating-19-years-of-rails-logic-to-modern-sveltekit.md @@ -11,7 +11,7 @@ tags: - rails categories: - locallygrown -lastmod: 2025-09-15T02:22:37.194Z +lastmod: 2025-09-22T20:54:54.910Z keywords: - locallygrown - svelte @@ -974,6 +974,6 @@ Part 4 is the messy part: real users, real money, and the bugs that only show up 1. [From Accidental Discovery to Agricultural Infrastructure (2002-2011)](https://blog.kestrelsnest.social/posts/locallygrown-origin-story/) 2. [The 23-Year Rescue Mission: Saving Agricultural Innovation from Technical Extinction](https://blog.kestrelsnest.social/posts/locallygrown-rescue-mission/) 3. **The Architecture Challenge: Translating 19 Years of Rails Logic to Modern SvelteKit** ← _You are here_ -4. Crisis Response: When Launch Day Goes Wrong -5. Lessons from the Solo Developer + AI Trenches +4. [The Reality of Production: When Hope Meets Live Users](https://blog.kestrelsnest.social/posts/locallygrown-reality-of-production/) +5. [Lessons from the Solo Developer Using Modern Tools](https://blog.kestrelsnest.social/posts/locallygrown-lessons/) 6. The Future: Building on Modern Foundations diff --git a/content/posts/2025-09-17-the-reality-of-production-when-hope-meets-live-users.md b/content/posts/2025-09-17-the-reality-of-production-when-hope-meets-live-users.md new file mode 100644 index 00000000..0cb30cc4 --- /dev/null +++ b/content/posts/2025-09-17-the-reality-of-production-when-hope-meets-live-users.md @@ -0,0 +1,341 @@ +--- +title: "The Reality of Production: When Hope Meets Live Users" +description: Launching with 3,000 passing tests still led to two weeks of production bugs—fees, permissions, Stripe, email, and a thousand cuts. How I triaged 314 fixes, kept markets running, and what I’d change next time. +date: 2025-09-17T01:44:05.496Z +preview: "" +draft: false +tags: + - locallygrown + - svelte + - sveltekit + - rails +categories: + - locallygrown +lastmod: 2025-09-22T20:55:03.509Z +keywords: + - locallygrown + - svelte + - rails +slug: locallygrown-reality-of-production +--- + +_Three thousand passing tests don't mean your system works_ + +> **Note:** This is based on actual production issues from August 2025. These were the real bugs that affected real users running real businesses. + +--- + +## TL;DR + +I launched with 3,000 passing tests, weeks of manual checks on production data, and a two-month beta—and still hit two weeks of real-world bugs. DNS delays, fee miscalculations, role-permission gaps, Stripe edge cases, fragile email templates, and a thousand small cuts. I fixed 314 commits in 18 days and kept markets running. This is what broke, why, and what I’d do differently. + +--- + +## Launch Morning: The DNS Disaster + +August 14, 2025, Thursday morning. What should have been a five-minute DNS switch became a multi-hour nightmare. Years ago, I had set up Cloudflare for the domain, a detail completely forgotten after years of not needing to touch DNS. The changes I made weren't propagating. The "coming soon" page stayed up while I diagnosed what was happening. + +What should have been done by 3 AM dragged on past dawn. By the time I untangled the Cloudflare mess and got DNS propagating correctly, I was already exhausted. But finally, the new LocallyGrown.net was live. + +I'd taken two days off from my regular job, planning to relax, handle a few tech support requests, maybe squash a bug or two. Mostly relax. + +Instead, I got maybe eight hours of sleep total over the next four days. + +The first manager email arrived within hours. Then another. Then another. By evening, my inbox was a cascade of increasingly urgent discoveries: + +- Desktop views showing blank pages while mobile worked fine +- The three dollar flat fee disaster: every Stripe payment charging $3 instead of 3% +- Growers locked out of editing their own products +- Invoices no longer grouped by grower, breaking the physical workflow of how volunteers distributed food +- Some customers charged zero, others charged twice +- "Internal server error" when adding milk to cart +- Decimal amounts wouldn't save, so managers couldn't adjust balances for $12.50 worth of extras + +One manager was getting calls, texts, and emails from confused customers. By evening of the first day, she had only 7 orders when she usually had dozens. Customers were placing duplicate orders thinking the first hadn't gone through. Growers couldn't reactivate products after vacation mode. The harvest summary page showed negative quantities (-1 egg for -$5). + +But there was one bright spot: "The mobile checkout is so much better than before," one customer told their manager. At least something was working better. + +The real testing had just begun. + +--- + +## Bug Category #1: The Stupid Math Mistakes + +**The Most Embarrassing Bug:** + +Market credit card fees weren't being calculated as percentages; they were being added as flat amounts. + +```typescript +// What I wrote (wrong): +const surcharge = market.customerPercentage; // If 3%, adds $3.00 + +// What it should have been: +const surcharge = subtotal * (market.customerPercentage / 100); // 3% of subtotal +``` + +**How This Slipped Through:** + +My test data was too convenient: + +- \$100 order with 3% fee = $103 total ✓ +- Looked correct, but for entirely wrong reasons +- The three dollars was a flat fee, not 3% of $100 + +On real orders: + +- \$47.50 order with 3% fee = \$50.50 (wrong - added $3) +- Should have been \$48.93 (3% = $1.43) + +Markets were overcharging on small orders, undercharging on large ones. + +My Git logs from that first week are littered with fixes for math bugs. Markets can customize their pricing structure in an almost infinite number of ways, and even with thousands of tests I didn't capture everything I needed to. + +--- + +## Bug Category #2: Role-Based Permission Failures + +**What I Thoroughly Tested:** Manager accounts doing manager things. + +**What I Didn't Test Enough:** Grower-only accounts, volunteer-only accounts, customer-with-no-special-role accounts. + +The bugs were everywhere, all in the direction of being too restrictive: + +- Growers couldn't edit their own products (Aug 15) +- Volunteers couldn't access the volunteer functions they needed (Aug 28) +- Growers couldn't remove items from harvest lists (Aug 22) +- Non-grower admins couldn't add products (Aug 17) +- Growers couldn't access their Sales History (Aug 27) + +Root cause: I validated backend rules but missed UI visibility checks for non-manager roles. + +```svelte + +{#if user.isAdmin || user.isManager} + +{/if} + + +{#if user.isAdmin || user.isManager || (user.isGrower && product.growerId === user.growerId)} + +{/if} +``` + +My manual testing had a fatal flaw: I tried to test every kind of account, but I mostly spent my time viewing the site as a manager would. Managers can do everything. I ran out of time before I could test every kind of account with every button and control in the system. The back end logic was correct and tested, but that doesn't help when the button you need to click isn't even visible. + +--- + +## Bug Category #3: Payment Processing Disasters + +The Stripe integration broke in spectacular ways. The first disaster happened while we were still in the beta period, when I had created a whole set of safeguards that allowed for testing every aspect of the payment process but simulated the final step of charging the card. I'd accidentally left one path unguarded, and a manager charged several of her customers for copies of their real orders. It was painful, and we hadn't even launched yet. + +LocallyGrown’s payment flow is unlike typical e-commerce. When customers place their orders, often times the produce is still in the field. It's not unusual for orders to be received five days after they're placed, and there are many, many reasons why what gets delivered doesn't exactly match what was ordered. The simplest way to handle this is to verify the card, save it as a payment method tied to the customer, and then charge that card after the order is picked up and everything is verified and reconciled. + +Stripe allows me to do all this, though it's not their typical way of handling payments. On the old system, I was using an extremely early version of their APIs, but they have added a lot of complexity since then and that simplicity was not available to me. I tested everything I could, using the test environment they provide as well as running countless small real charges to my personal cards. It seemed as ready as it could ever be, but once the public started using the system, the bugs started appearing. + +Every time one was reported, it became the highest priority. It was imperative that I get a fix in place before anyone else was affected, and with many markets running cards on different schedules, I had to act quickly. Luckily there weren't many, but when they happened I had to drop everything and fix them. + +--- + +## Bug Category #4: Communication Breakdown + +My application sends thousands of emails every day. Customers need to be kept informed of what to expect when they receive their order. Growers need to know what to harvest. Managers expect a constant flow of information delivered to their inbox. All of this information is available in real time on the website, but when you're riding a tractor or setting up canopies in a parking lot, sometimes pulling up an email is the best way to get the information you need. + +I'd completely revamped the email system to be more flexible, to allow greater insight into deliverability, and to be friendlier in tone. It was a big change, and I was proud of it. But it also meant that I had to re-write all of the templates from scratch, include both plain text and formatted versions of each, and make sure they called the right variables in the right places. + +And of course I missed a few things here and there that looked good to my eyes but were noticed immediately when used by the markets. In a few places I used the old Rails variable names, so a gap appeared in an email instead of, say, a product name. Or in the process of changing the layout of a nicely formatted email I omitted a column so the growers didn't have the contact information for a customer they were used to seeing. + +None of these were major problems, and they were easy to fix. But, they piled up on top of everything else and became another thing for my customers to be frustrated with. + +--- + +## Bug Category #5: Death by a Thousand Cuts + +The Git history tells the rest: CSV exports with wrong columns. iPhone photos that wouldn't upload. Infinite scroll that wasn't infinite. Password resets that didn't reset. Bots flooding the logs so I couldn't see real errors. + +Every subsystem had issues. Every feature had edge cases. Every workflow had something I'd missed. + +--- + +## The Human Cost + +Market managers were drowning. One manager sent me 8 detailed bug reports in the first week alone. She was simultaneously: + +- Fielding calls from confused customers +- Helping growers who couldn't access their products +- Manually adjusting incorrect charges +- Trying to run a physical market with broken invoices + +The invoice bug wasn't just about data display. When items weren't grouped by grower, volunteers had to walk back and forth across the market instead of going down the line. Physical workflow, broken by code. + +The "can't use decimals" bug meant managers couldn't close out their markets. They literally couldn't mark orders complete because they couldn't enter $12.50 for extras, only $12 or $13. + +This wasn't just a website with bugs. This was dozens of live food systems, hundreds of growers, thousands of customers depending on me to keep their local food networks running. Real businesses. Real money. Real communities. + +--- + +## The Two-Week Bug Avalanche + +**The Numbers:** + +- **314 commits** from August 14 to September 1 +- **58 pull requests** merged +- **105 commits** with "fix", "bug", or "critical" in the first week alone + +Look at the PR names from August 18: + +- "morning bugs" +- "afternoon fixes" +- "evening bugs" +- "night bugs" + +I was naming my branches by time of day because there were too many to give them meaningful names. I was working quickly and fixing things as quickly as they were coming in, but they just kept coming. + +--- + +## My Personal Reality + +For the most part, my customers (the market managers) were understanding. They could see I was responding quickly and decisively. A few were angry at the surprise instability, and might still be angry. + +I was overwhelmed. My morale was at an all-time low. My disappointment in myself for not catching so many bugs that were obvious in hindsight was immense. Every bug report felt like a personal failure. Every "this used to work" comment cut deep. + +I've been in the software industry long enough to see many, many rollouts go horribly wrong. Goodwill can be destroyed overnight, and some large companies never recover. As a consulting developer, I've even been called in to help fix the messes caused by these disasters. I had to keep reminding myself that I've seen much worse, and even if it didn't go as planned I was capable of fixing it. + +And I was also determined to get it done. There was no rolling back, so I had to go forward. I had to dig my way out and redeem myself and the choices I made along the way. + +What kept me going was knowing this wasn't about me. It was about the communities depending on this system. + +--- + +## The Unsung Heroes + +The market managers became my QA team in production. They had every right to be furious. Instead, they sent detailed bug reports with screenshots, exact reproduction steps, and impact assessments. + +One manager's emails evolved into increasingly detailed technical reports: + +- Day 1: "The total amount due to growers is displaying incorrectly" +- Day 3: "When I export the checks .csv the amounts are correct but the display shows \$85 instead of $73.95 after the 13% fee" +- Day 5: "I can replicate this. It only happens when you select specific growers like 3C or BMB unless you also choose honey or baked goods category" + +They were debugging complex interaction patterns while running physical markets. They discovered edge cases I never would have found. They showed patience I didn't think possible. + +By Week 3, the emails changed tone. The bug reports became less frequent. The managers stopped apologizing for "all the emails." + +Success wasn't about the code being perfect. It was about the system becoming invisible again: managers could run their markets without fighting the software. + +--- + +## Lessons From The Bug Apocalypse + +### 1. Test Data Can Hide the Truth + +Using convenient test values (\$100 orders, 10% fees) hides calculation bugs. Real-world data is messy: $47.83 orders with 2.75% fees reveal rounding errors immediately. I had an extensive library of test data, but most of the products had nice round numbers that were easy to verify but hid the bugs. + +Seed fixtures with non-round prices and odd percentages; add randomized totals to catch rounding errors. + +### 2. Your Primary Account Blinds You + +Testing mainly with your admin account means you'll miss most permission bugs. You need test accounts for every role combination, and you need to use them repeatedly, even when you just change a single button. + +Automate smoke flows per role; assert on control visibility, not just API responses. + +### 3. Mock APIs Aren't Reality + +Stripe test mode worked perfectly with clean test cards. Production Stripe used with real cards and long-standing accounts worked differently. I needed to better understand the newer APIs and how they differed from the old simple ones I was using. + +Mirror prod settings in a staging account; record/replay webhooks and handle retries/duplicate events. + +### 4. The Correct Backend + Broken Frontend = Broken System + +A single wrong Svelte condition can make perfect backend logic useless. + +Add component tests for visibility conditions and null/“unlimited” states. + +### 5. Email Templates Are Code + +They need testing. They need error handling. They need to handle missing data gracefully. "Hello undefined" is not acceptable. + +Snapshot test rendered templates with missing fields; fail builds on “undefined” placeholders. + +### 6. The Frontend Testing Gap + +My backend had 3000 tests. Rock solid. But Svelte 5's testing story in 2025? Still evolving. + +@testing-library/svelte had experimental Svelte 5 support with known bugs. The `mount()` function threw "not available on the server" errors in jsdom. Testing `$derived` runes didn't detect reactivity changes. Cypress and Playwright worked for basic flows but couldn't properly test Svelte 5's new reactive primitives. + +Ideally, I'd have automated tests running as manager, grower, volunteer, and customer accounts at various screen sizes. More critically, these would have caught the permission-based bugs where essential buttons and controls were hidden from the very users who needed them: growers who couldn't edit their own products, volunteers locked out of their tools. That's still the goal. But with the testing tools available and the Rails system dying, I had to choose: wait for the ecosystem to mature, or launch with manual testing only for the frontend. + +I chose to launch. + +Until tooling stabilizes, lean on Playwright smoke suites across roles and screen sizes; treat them as gate checks. + +### 7. Edge Cases Aren't Edge Cases + +Products with unlimited inventory, markets with 0% fees, users with multiple roles. These aren't edge cases. They're Tuesday. When I offer near-unlimited flexibility, I'm taking on the responsibility to keep the freedom I've given working. + +Promote “edge” scenarios to first-class test data and UX checks. + +### 8. Beta Testing Has Limits + +The handful of managers who beta tested provided invaluable feedback. But they weren't a representative sample. I set up perfect copies of every market with real data, gave two months of access, sent regular updates. Still, most managers (including those with the most complex customizations) waited until launch day. + +The lesson: Beta testing helps, but it's a self-selecting sample. The users with the most complex workflows are often too busy to test until they have no choice. + +Identify high-risk markets and schedule guided sessions; don’t rely on opt-in. + +### 9. Launch and Fix > Wait for Perfect + +The old Rails system was dying. Every day I delayed was another day it might fail completely. Launching with bugs I could fix was better than not launching at all. + +Pair fast rollback-like mitigations (feature flags, circuit breakers) with rapid patch cadence. + +--- + +## Where We Are Now + +It's been four weeks since launch. I fixed more bugs last night. Reports are still coming in, but it's a trickle now instead of a flood. + +But here's what matters: The system works. Markets are running. Orders are flowing. Communities are getting their local food. + +Yes, it was messier than I'd hoped. Yes, I made mistakes. But I also: + +- Successfully migrated 23 years of Rails code to modern infrastructure +- Kept dozens of markets running without any data loss +- Fixed 314 commits worth of bugs without breaking production +- Maintained trust by responding quickly and transparently + +I'm not in crisis management mode anymore. I'm able to think about (and even implement) new features. The system is stable enough that I can look forward, not just fix what's broken. + +The migration isn't complete, but we're getting there. And more importantly: we're still here. + +--- + +## What's Next: How One Developer Used Every Tool Available + +From day one of this migration, I used the current generation of programming tools to accomplish what would have been impossible alone. Enhanced IDE autocomplete, AI-powered code generation, groups of specialized agents I created and orchestrated. These weren't crutches; they were force multipliers. + +But let's talk about that loaded term: "AI." Like "farming," it's a broad term that covers both the exploitative and the ethical. Most food comes from factory farms that destroy communities and environments. But LocallyGrown.net exists to support the farmers who grow food responsibly. Similarly, many AI companies are built on stolen art and exploited resources. But there are also thoughtfully-created development tools that learned from code developers explicitly shared to help others. + +I was the architect, the decision maker, the one who read and understood every line of code before it was committed. But I typed with more than just my fingers, using tools that amplified rather than replaced my expertise. + +**Part 5 will cover:** + +- Why "AI" (like "farming") isn't a monolith, and why that distinction matters +- How modern development tools made a solo migration of 23 years of code possible +- The reality of being the human in the loop: reviewing, correcting, and owning every line +- The ethics of using AI tools while opposing AI exploitation +- Building a workflow that let me multiply my efforts without losing control + +This is the story of using every available responsible tool to save a system that feeds communities. Not because I couldn't code, but because I could code smarter, and because sometimes the right tool for the job happens to use machine learning. + +--- + +_This is part four of a series documenting the rescue and modernization of LocallyGrown.net._ + +### The Series + +1. [From Accidental Discovery to Agricultural Infrastructure (2002-2011)](https://blog.kestrelsnest.social/posts/locallygrown-origin-story/) +2. [The 23-Year Rescue Mission: Saving Agricultural Innovation from Technical Extinction](https://blog.kestrelsnest.social/posts/locallygrown-rescue-mission/) +3. [The Architecture Challenge: Translating 19 Years of Rails Logic to Modern SvelteKit](https://blog.kestrelsnest.social/posts/locallygrown-architecture-challenge/) +4. **The Reality of Production: When Hope Meets Live Users** ← _You are here_ +5. [Lessons from the Solo Developer Using Modern Tools](https://blog.kestrelsnest.social/posts/locallygrown-lessons/) +6. The Future: Building on Modern Foundations diff --git a/content/posts/2025-09-22-lessons-from-the-solo-developer-trenches.md b/content/posts/2025-09-22-lessons-from-the-solo-developer-trenches.md new file mode 100644 index 00000000..15f9c821 --- /dev/null +++ b/content/posts/2025-09-22-lessons-from-the-solo-developer-trenches.md @@ -0,0 +1,1159 @@ +--- +title: Lessons from the Solo Developer Using Modern Tools +description: How I used code-aware tools to multiply my reach (tests, docs, audits) while keeping humans in charge of architecture, business logic, and quality. +date: 2025-09-22T20:15:51.108Z +preview: "" +draft: false +tags: + - devtools + - locallygrown + - rails + - solodeveloper + - stripe + - svelte + - testing + - agents +categories: + - locallygrown +lastmod: 2025-09-22T21:35:02.057Z +keywords: + - locallygrown + - svelte + - rails + - claude +slug: locallygrown-lessons +--- + +_Advanced Developer Tools, Real Tradeoffs_ + +> **Note:** This isn't about the "AI" that generates blog spam or copies artists' styles. This is about a new generation of developer tools that understand code structure, maintain consistency, and amplify human expertise rather than replacing it. + +--- + +## TL;DR + +I didn't use "AI" to write my app. I used code-aware tools to multiply my reach by researching options, generating tests and docs, and catching patterns. I stayed the architect and quality gate. + +**What worked:** Test generation, documentation, technology research, code review +**What failed:** Following architectural rules, understanding business logic, knowing when to stop +**What made it safe:** Specs first, human review always, specialized agents for audits, hard CI/CD guardrails + +--- + +## Lessons Quick Navigation + +* [The Starting Point](#the-starting-point) — Rails-to-SvelteKit rewrite and the impossible solo deadline +* [The Evolution of Our Working Relationship](#the-evolution-of-our-working-relationship) — From architecture analysis to rule-breaking intern +* [Page-by-Page Migration](#week-4-5-page-by-page-migration) — Password upgrades, pixel-perfect clones, and CSS survival +* [Claude Learns to Drive](#month-3-claude-learns-to-drive) — Puppeteer testing and theme validation +* [Reimagining the Back Office](#month-4-reimagining-the-back-office) — Modern tools for managers with sub-agent Ray +* [Building a Team of Specialized Code Analyzers](#building-a-team-of-specialized-code-analyzers) — Human-named agents and the orchestra effect +* [The Parallel Universe Gambit](#the-parallel-universe-gambit) — Running legacy and modern front-ends side by side +* [What Claude Excels At](#what-claude-excels-at) — Boilerplate, testing, review, documentation +* [What Claude Struggles With](#what-claude-struggles-with) — Business logic, refactoring, debugging +* [The Two-Week Launch Gauntlet](#the-two-week-launch-gauntlet) — Structured audits, blockers, and the go/no-go ritual +* [Lessons Learned](#lessons-learned) — How to keep ML tools safe, useful, and human-centered +* [A Critical Warning](#a-critical-warning-the-vibe-coding-disaster-waiting-to-happen) — Why “no-code AI SaaS” launches are dangerous +* [What’s Next](#whats-next-the-future-of-development) — Building on stable foundations for 20+ years ahead + +--- + +## The Starting Point + +March 2025: Day one of the Rails-to-SvelteKit rewrite. I knew from the start I'd need the latest generation of developer tools: + +- 23 Rails controllers, 23 models, 173 view templates, and 23 helpers to convert +- All the business logic embedded in those views and models +- 27 database tables to migrate with all their relationships +- Payment system to completely rebuild for modern Stripe +- Authentication to reimplement in TypeScript +- 23 years of accumulated features and edge cases to preserve (Rails since 2006) +- Documentation to write from scratch +- Test coverage at 0% +- Launch deadline: August 14, 2025 (5 months away) + +I was one person trying to rebuild my own 23-year-old platform in a completely new framework while keeping the existing one running for thousands of users across dozens of markets. I needed tools that could help me plan work, organize tasks, document designs, write tests that match those designs, and review code for compliance. + +I started with Cursor, an IDE with advanced code completion and pattern recognition. But after a few weeks, I switched to Claude Code. Unlike the "AI" that floods the internet with generic articles and stolen art styles, Claude Code is closer to what we used to call machine learning. It's trained on programming patterns, not creative works. It understands code structure, can trace logic flows, and most importantly, helps maintain consistency across thousands of files. + +I chose Claude Code for its code-aware workflow and Anthropic's published emphasis on safety; that alignment mattered to me. + +That decision to go all-in with Claude transformed everything. What started as smart autocomplete evolved into something unexpected: a programming partner that could hold the entire codebase in context. + +--- + +## The Evolution of Our Working Relationship + +### Day 1-7: The Architecture Phase + +Before writing a single line of production code, I had Claude analyze the entire Rails application: + +``` +Me: "Here's my Rails schema and Gemfile. I'm moving to SvelteKit. + What's the modern equivalent stack?" + +Claude: "Looking at your ActiveRecord usage, consider these ORMs: +- Prisma: Most popular, good DX but heavy +- Drizzle: Lightweight, SQL-like, perfect for your use case +- TypeORM: Familiar if coming from ActiveRecord + +For your use case with complex queries and performance needs, +I'd recommend Drizzle because..." + +Me: "What about replacing Paperclip for image uploads?" + +Claude: "Modern options: +- Uploadthing: Simple but locked to their service +- Local storage + Sharp for processing +- S3 + CloudFront for scale + +Given your farmer's market context and need for simplicity, +local storage with Sharp gives you full control..." +``` + +We spent the first week evaluating every gem's modern equivalent: + +- **ActiveRecord → Drizzle ORM** (after comparing Prisma, TypeORM, and others) +- **Paperclip → Sharp for processing + S3/CloudFront for serving** (scalable image handling) +- **Prawn → PDFKit** (for label generation) +- **Geokit → Custom distance calculations** (simple haversine formula) +- **gmaps4rails → OpenStreetMap/Leaflet** (privacy-respecting) +- **will_paginate → Custom pagination** (simpler with Drizzle) +- **delayed_job → BullMQ** (modern job queues with Redis) +- **Stripe gem → Stripe SDK for Node** (official, well-maintained) + +### Week 2-3: The Documentation and Testing Foundation + +Before writing any Svelte code, I had Claude help me create a complete blueprint of the existing system: + +``` +Me: "Let's document the User model. Here's the Rails code. + Create a TypeScript service that replicates every method." + +Claude: "I'll create UserService with type-safe equivalents: +```typescript +// Replicating User.find_by_email_and_market +static async findByEmailAndMarket(email: string, marketId: number): Promise { + // Exact behavior from Rails, now in TypeScript +} +```" + +Me: "Now write tests that verify this matches Rails behavior exactly" + +Claude: "Creating comprehensive test suite: +```typescript +describe('UserService.findByEmailAndMarket', () => { + it('returns empty array when no user found', async () => { + // Test matches Rails: User.find_by_email_and_market('nonexistent', 1) => nil + const result = await UserService.findByEmailAndMarket('nonexistent', 1); + expect(result).toEqual([]); + }); + + it('handles multiple users with same email in different markets', async () => { + // Documenting Rails edge case behavior + }); +}); +```" + +Me: "Perfect. Now document this in markdown with examples" + +Claude: "Creating comprehensive documentation: +```markdown +## UserService.findByEmailAndMarket + +Finds users by email within a specific market context. + +### Rails Equivalent +`User.find_by_email_and_market(email, market_id)` + +### Behavior Notes +- Returns array (Rails returned single record or nil) +- Case-sensitive email matching (preserves Rails behavior) +- Used in authentication flow and order assignment +```" +``` + +Another important output of this process was the **CLAUDE.md file** that emerged, containing rules for the codebase: + +``` +Me: "We keep having to repeat these patterns. Let me document the rules." + +// Early CLAUDE.md entries: +- NEVER make database calls outside service files +- ALL database logic goes in /src/lib/server/services/ +- Use camelCase for variables, PascalCase for types +- Every service method needs error handling +- Always return typed objects, never raw database rows + +Me: "Claude, you JUST made a DB call in a route handler. AGAIN. + The rules are RIGHT THERE in CLAUDE.md!" + +Claude: "You're right, let me fix that and use the service layer..." + +Me (next day): "Another DB call in a route. Are you even reading CLAUDE.md?" + +Claude: "I apologize, I should have used the UserService..." +``` + +If Claude were a human intern, I'd have fired them for repeatedly ignoring the CLAUDE.md rules: DB calls in routes, inconsistent naming, bypassed service layers. But as a research assistant, test generator, and documentation writer? The value far outweighed the frustration of constantly correcting architectural violations. + +By the end of week 3, we had: + +- **27 TypeScript services** matching Rails models +- **500+ unit tests** documenting exact Rails behavior +- **100+ pages of markdown** explaining every method +- **CLAUDE.md** - our collaboration constitution +- **Zero UI code** - but complete confidence in the foundation + +### Week 4-5: Page-by-Page Migration + +We started converting the Rails application one page at a time, beginning with authentication: + +``` +Me: "We need to support the old Rails password hashes. I can't force + thousands of users to reset passwords simultaneously." + +Claude: "Rails uses bcrypt with a specific salt format. We could..." + +Me: "Right, but these are OLD Rails hashes. Some might be MD5 from 2006." + +Claude: "Interesting challenge. We could implement a versioning system..." +``` + +This led to one of my favorite solutions: a seamless password migration system. + +```typescript +Me: "Here's my idea: detect the hash version, validate using the old + algorithm, then after X successful logins, silently upgrade them + to modern Argon2." + +Claude: "That's elegant. Let me help implement: + +class PasswordService { + // Detect hash version + static getHashVersion(hash: string): 'legacy_md5' | 'legacy_bcrypt' | 'modern_argon2' { + if (hash.startsWith('$2a$')) return 'legacy_bcrypt'; + if (hash.startsWith('$argon2')) return 'modern_argon2'; + return 'legacy_md5'; + } + + // Validate with appropriate algorithm + static async verify(password: string, hash: string): Promise { + const version = this.getHashVersion(hash); + switch(version) { + case 'legacy_md5': return this.verifyMD5(password, hash); + case 'legacy_bcrypt': return bcrypt.compare(password, hash); + case 'modern_argon2': return argon2.verify(hash, password); + } + } + + // After successful login, maybe upgrade + static async maybeUpgrade(userId: number, password: string, loginCount: number) { + if (loginCount >= 3) { // After 3 successful logins + const newHash = await argon2.hash(password); + await UserService.updatePasswordHash(userId, newHash); + } + } +}" + +Me: "Perfect! And we'll set a deadline 6 months out for forced reset + if they haven't hit the threshold." +``` + +This wasn't a real discussion. Claude doesn't truly understand the human impact of forcing password resets on farmers at 5 AM trying to print harvest sheets. But the rubber ducking process (and yes, rubber ducking with actual rubber ducks works for a reason) helped me think through an elegant solution. + +The result: **Zero support tickets** about passwords during migration. Users never knew their security was being upgraded behind the scenes. + +### Month 2: The Methodical Page-by-Page Clone + +This phase wasn't glamorous, but it was crucial. Every market had custom CSS, and breaking their styling would destroy trust: + +``` +Me: "We need to match the HTML structure EXACTLY. Same IDs, same classes, + same nesting. Markets have 19 years of custom CSS depending on this." + +Claude: "So we're creating a pixel-perfect clone in Svelte?" + +Me: "Exactly. My 2007 design looks ugly as sin now, but that's not the point. + This is about trust and continuity." +``` + +We developed a methodical routine for each page: + +``` +Me: "Here's the Rails orders/index.erb view. Let's break it down." + +Claude: "I see several role-based sections: +- Admin sees all orders with edit buttons +- Growers see only their products +- Customers see only their orders +- The HTML structure uses #order-list > .order-item > .order-details" + +Me: "Right. And notice how the classes change based on order status?" + +Claude: "Yes: class='order-item status-#{order.status}' +We'll need to replicate that exact pattern." + +Me: "Here's what the page.server.ts needs to fetch..." + +Claude: "Based on the view, we need: +- User's orders with items and products +- Market configuration for display options +- Grower details if user is a grower +- All maintaining the exact div structure" +``` + +Page after page, we followed this pattern: + +1. **Examine Rails views**: understand every conditional, every loop +2. **Document data requirements**: what the server needs to fetch +3. **Map role-based variations**: how admins/growers/customers see differently +4. **Match HTML exactly**: same IDs, classes, structure +5. **Test with real market CSS**: ensure their customizations still work + +```svelte + +
+ {#each orders as order} +
+
+ + {#if userRole === 'admin'} +
...
+ {/if} +
+
+ {/each} +
+``` + +By the end of Month 2, we had a complete visual clone. It looked exactly like the 2007 design: dated, clunky, but **perfectly familiar to every user**. + +I couldn't test every single market's custom CSS. There wasn't time. But I had a secret weapon: a collection of themes from a Tennessee designer who'd gotten out of the web business years ago, selling me his LocallyGrown theme collection as he exited. These themes varied widely in style and gave me a solid baseline for testing. I knew if I could make these work, I'd have a foundation for helping individual markets adapt their custom CSS later. + +Some markets had gone far beyond these themes with their own deep customizations. They'd need tweaks post-launch. But having those baseline themes working meant the core structure was solid. The IDs and classes were right, the nesting was correct. Markets could adapt their CSS as needed rather than having everything break at once. + +This wasn't the exciting rewrite I'd imagined, but it was the right approach. Trust first, modernization later, and realistic about what could be tested before launch. + +### Month 3: Claude Learns to Drive + +Everything changed when Claude stopped reading screenshots and started driving the browser itself. We integrated Puppeteer, letting Claude use a browser directly: + +``` +Me: "I'm tired of taking screenshots for you. Here's Puppeteer access. + Drive yourself to the dev server and look for issues." + +Claude: "Navigating to https://localhost:3000/orders... + Taking screenshot... + I can see the order table is missing the status column for growers. + Let me check if it's a CSS issue or missing data..." + +[Claude navigates to inspect mode, checks elements] + +Claude: "The data is there but hidden. The CSS class .grower-view is + overriding .status-column with display:none" + +Me: "Finally! I've been staring at this for an hour." +``` + +This changed everything. Claude could now: + +- **Self-verify fixes**: Make a change, navigate to the page, confirm it worked +- **Test user flows**: Click through multi-step processes like checkout +- **Compare Rails vs Svelte**: Open both versions side-by-side, spot differences +- **Hunt for visual bugs**: Systematically visit every page looking for issues + +``` +Me: "Check if all the theme variations work with the new order page" + +Claude: "I'll test all 12 themes: +[Switches theme] +- Theme 1: ✓ Order table displays correctly +[Switches theme] +- Theme 2: ✓ Working +[Switches theme] +- Theme 3: ✗ ISSUE: Order totals overlapping with sidebar + The float:left on .order-summary conflicts with .sidebar-right +[Continues through all themes] + +Found issues in themes 3, 7, and 11. Here are the fixes..." +``` + +### Month 4: Reimagining the Back Office + +After achieving the visual clone, I realized an opportunity: market manager pages didn't need customer-facing branding. These were tools, not storefronts. + +``` +Me: "The manager pages (order management, product admin, reports) + only managers see these. They don't need their market's CSS. + We could make these actually modern, mobile-first." +``` + +This coincided perfectly with Anthropic introducing sub-agents to Claude Code. That same day, I created **Ray**, named after legendary designer Ray Eames. + +``` +Me: "Ray, you specialize in modern responsive design philosophy. + We're reimagining back-office pages that have been stuck in 2007. + They need to work on phones, tablets, and desktops." + +Ray: "I'll establish design principles first: +- Mobile-first breakpoints (320px base, enhance upward) +- Touch-friendly targets (minimum 44px) +- Information hierarchy over decoration +- Consistent spacing system (8px base unit) +- Accessible color contrast (WCAG AA minimum) + +For the order management page, instead of a cramped table, +consider cards that stack on mobile and grid on desktop..." + +Claude: "I'll bring Ray in whenever we're working on these pages. + She can establish patterns we'll reuse." +``` + +Ray created a cohesive design system for the back office: + +```css +/* Ray's spacing system */ +:root { + --space-xs: 0.5rem; /* 8px */ + --space-sm: 1rem; /* 16px */ + --space-md: 1.5rem; /* 24px */ + --space-lg: 2rem; /* 32px */ + --space-xl: 3rem; /* 48px */ +} + +/* Mobile-first responsive grid */ +.admin-grid { + display: grid; + gap: var(--space-md); + grid-template-columns: 1fr; +} + +@media (min-width: 768px) { + .admin-grid { + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); + } +} +``` + +The result: Market managers finally got modern tools. They could manage orders from their phones at the farmers market. They could update inventory from tablets in the field. The ancient tables and tiny form fields were gone, replaced with touch-friendly, responsive interfaces. + +Customer-facing pages kept their familiar 2007 look. Manager tools entered 2025. + +--- + +## Building a Team of Specialized Code Analyzers + +### The Sub-Agents Revolution + +By month three, I discovered Claude's most powerful feature: specialized sub-agents. Instead of one generalist tool, I could spawn focused code analyzers with specific expertise: + +``` +Me: "I need a comprehensive security audit of our authentication system" + +Claude: "I'll use the security-focused agent for this task..." + +SecurityAgent: "Beginning authentication audit. Checking: +- Session management +- CSRF protection +- Authorization boundaries +- SQL injection vectors +- XSS vulnerabilities +..." +``` + +### Our Developer Tools Roster + +Over time, I assembled a team of specialized agents, each trained on different aspects of software engineering: + +**1. Ray - The Design Systems Expert** (First agent, created Month 4) + +```typescript +// Named after Ray Eames, pioneering designer +"Create responsive, mobile-first design system for admin pages" + +Ray: "Establishing design tokens: +- 8px spacing grid +- Touch targets minimum 44px +- Mobile-first breakpoints: 320px, 768px, 1024px +- Consistent typography scale" +``` + +**2. Erma - The User-Facing Text Consistency Expert** + +```typescript +// Named after Erma Bombeck, humorist who made the everyday relatable +"Review all user-facing text for consistency and clarity" + +Erma: "Analyzing user-facing content: +- Standardized 47 inconsistent error messages +- Unified tone across 23 email templates +- Simplified checkout flow language +- Added helpful context to 18 form fields" +``` + +**3. Diderot - The Documentation Synchronizer** + +```typescript +// Named after Denis Diderot, encyclopedist who organized knowledge +"Update documentation to reflect the new payment flow" + +Diderot: "Analyzing recent changes... +- Updated PaymentService.processStripeWebhook() +- New error codes added: PAYMENT_METHOD_DECLINED, INSUFFICIENT_FUNDS +- Updating API docs, error handling guide, and integration tests" +``` + +**4. Maya - The Marketing Tone Specialist** + +```typescript +// Named after Maya Angelou, poet who knew how words make people feel +"Create welcoming, inclusive marketing copy for the homepage" + +Maya: "Crafting messaging that resonates: +- Hero: 'Fresh from your neighbors, delivered to your door' +- Value prop focuses on community, not just convenience +- Farmer stories highlight real people, not statistics +- Call-to-action: 'Join your local food community'" +``` + +**5. Agatha - The Security Auditor** + +```typescript +// Named after Agatha Christie, master of finding what others miss +"Examine data flow between server and client for security leaks" + +Agatha: "Found 3 critical issues: +1. User objects expose internal IDs in /api/users endpoint +2. Password reset tokens visible in logs +3. Market admin can access other markets' data via direct API calls" +``` + +**6. Ada - The Performance Optimizer** + +```typescript +// Named after Ada Lovelace, first to see computing's true potential +"Profile the market homepage and optimize load time" + +Ada: "Performance analysis complete: +- Initial load: 3.2s (target: <1s) +- Largest Contentful Paint: 2.8s +- 47 database queries (18 are duplicates) +- Recommendations: + 1. Implement query batching + 2. Add Redis caching for product lists + 3. Lazy load images below fold" +``` + +**7. Carver - The Payment Integration Expert** + +```typescript +// Named after George Washington Carver, who transformed simple inputs into valuable systems +"Implement subscription management with Stripe" + +Carver: "Designing subscription architecture: +- Webhook handlers for subscription lifecycle +- Proration for mid-cycle changes +- Grace periods for failed payments +- Automatic retry logic with exponential backoff" +``` + +### Why Human Names Matter + +Most guides recommend technical names for sub-agents like "css-design-agent" or "auth-flow-agent." I deliberately chose to name mine after real people, and this decision shaped the entire development experience. + +First, it was my way of acknowledging gratitude. Every time I worked with Ray, I remembered Ray Eames and the design revolution she helped create. When Agatha found security holes, I thought of Agatha Christie's meticulous attention to detail. These names kept me grounded, aware that I stand in a long line of innovators and problem-solvers. + +More importantly, human names constantly reminded me who this platform serves. This isn't a faceless SaaS product. It's a community platform. My market managers are people with names and stories. The farmers wake up at 4 AM to harvest vegetables. The customers are neighbors feeding their families. I am a person, building tools for people. + +```typescript +// This feels different: +"css-optimizer-agent: Reduced bundle size by 47KB" + +// Than this: +"Ada: I found 18 duplicate queries slowing down checkout. + These farmers deserve faster tools. Let me fix this." +``` + +In an age of increasing automation, these human names became my north star. Every feature, every optimization, every bug fix serves real people building real communities around local food. The internet makes it easy to forget that. My named agents never let me. + +### The Orchestra Effect + +The real power came from using multiple agents in parallel: + +```typescript +Me: "We're adding a new feature: recurring subscriptions for CSA boxes. + Analyze all aspects." + +// Agents working simultaneously: +Agatha: "Security review: Need to encrypt stored payment methods..." +Ada: "Performance impact: Subscription checks will add 50ms to each request..." +Erma: "User messaging: Need clear subscription terms and renewal notices..." +Carver: "Payment flow: Implementing Stripe subscriptions with webhooks..." +Diderot: "Documentation needed: API changes, user guides, webhook reference..." + +// 2 hours later: Complete implementation plan with no gaps +``` + +--- + +## The Parallel Universe Gambit + +**Mobile was killing us.** Markets were leaving LocallyGrown because customers couldn't use their phones to shop. With my agent orchestra as a safety net, I attempted something audacious: building a completely modern front-end alongside the legacy-compatible one. + +### The Problem That Demanded a Solution + +Our legacy system required pinch-zooming on phones. Market customizations made responsive design impossible. But forcing markets to abandon their customizations would break trust. I had to solve mobile without breaking anything. + +### Building Two Platforms in One + +I created a parallel front-end that broke free from market customization constraints: + +```typescript +// Legacy route (preserves market CSS): +/market/products → old HTML structure, custom styles work + +// Modern route (new theming system): +/shop/products → mobile-first, responsive, beautiful +``` + +The new theming system expanded beyond "anything goes" CSS: + +```typescript +interface MarketTheme { + season: 'spring' | 'summer' | 'autumn' | 'winter'; + palette: 'earth' | 'ocean' | 'prairie' | 'mountain'; + accent: 'vibrant' | 'subtle' | 'warm' | 'cool'; +} + +// Generated 12 distinct, professional themes +// Each one tested on devices from iPhone SE to desktop +``` + +### Progressive Rollout Strategy + +Market managers could enable modern views by role: + +```typescript +marketSettings: { + modernViews: { + admin: true, // Try it yourself first + volunteers: true, // Then your helpers + growers: false, // Then your vendors + customers: false // Finally, everyone + } +} +``` + +This meant markets could migrate at their own pace. No forced transitions, no angry customers confused by sudden changes. + +### The Complexity Explosion + +This decision nearly broke me. The two months before launch became a complexity nightmare: + +- Duplicate Svelte server code for parallel routes +- Double the testing surface +- Context switching between legacy and modern patterns +- State management across two UI paradigms + +I mitigated this with a robust API layer: + +```typescript +// Instead of duplicating business logic: +// Legacy: +page.server.ts calls ProductService +// Modern: +page.server.ts calls ProductService + +// I created: +// Legacy: +page.server.ts → /api/products → ProductService +// Modern: +page.server.ts → /api/products → ProductService +``` + +### The Agent Safety Net + +Without my agents, this parallel development would have failed: + +```bash +Me: "I need to duplicate the checkout flow for modern UI" + +Ray: "I'll ensure consistent responsive design across all new pages" +Agatha: "I'll verify both flows have identical security checks" +Ada: "I'll monitor performance - no flow should be slower" +Diderot: "I'll track which APIs serve both versions" +Erma: "I'll ensure error messages match between versions" + +# 4 hours later: complete parallel checkout with zero security gaps +``` + +### The Price of Innovation + +Almost every bug in the frantic two weeks after launch traced back to this parallel UI period. Not because the tools failed, quite the opposite. The agents caught hundreds of potential issues. But the sheer complexity of maintaining two parallel systems while racing toward launch introduced edge cases even our vigilant orchestra couldn't predict. + +```typescript +// Real bug from launch week: +// Modern UI: Displayed product edit button for growers +// Legacy UI: Also displayed the button +// Backend: Correctly validated grower could edit their own products +// Frontend: {#if user.isAdmin || user.isManager} - forgot grower check +// Result: Growers couldn't see button to edit their own products +``` + +### No Regrets + +Despite the complexity and the post-launch firefighting, this parallel approach proved essential: + +- 15 markets opted into modern UI within first week +- Mobile usage noticeably increased in first month +- Markets reported some customer confusion, but it was minimal +- Gradual migration path preserved trust + +The modern front-end fixed LocallyGrown's biggest weakness while respecting its greatest strength: each market's unique identity. Without the agent orchestra giving me confidence to attempt this parallel universe approach, we'd still be forcing markets to choose between mobile usability and their customizations. + +--- + +## What Claude Excels At + +### 1. Boilerplate and Patterns + +Claude wrote 80% of our API endpoints. They all follow the same pattern: + +```typescript +// I'd write: +"New endpoint: POST /api/markets/{id}/announcement +- Validate user is market manager +- Create announcement +- Notify all market users +- Return created announcement" + +// Claude generates complete endpoint with: +- Input validation +- Authorization checks +- Error handling +- TypeScript types +- Transaction wrapping +- Logging +``` + +### 2. Test Generation + +``` +Me: "Generate comprehensive tests for OrderService pricing calculations" + +Claude: +- "should charge only fixed fees when no products are delivered" +- "should maintain pricing consistency across spot and regular calculations" +- "should handle mixed delivery scenarios correctly" +- "changing product price after order creation does not affect order item price" +- "calculates spot price correctly when all items are missing" +``` + +### 3. Automated Code Review with BugBot + +Even as a solo developer, I maintained professional workflows: proper branching, full pull requests, code reviews. Both Claude and Cursor's BugBot automatically reviewed PRs as they were created. + +``` +PR #287: "Fix order calculation for spot prices" + +Claude: "The logic looks correct, but consider adding a test for + when all items are marked as missing." + +BugBot: "⚠️ Potential issue in line 147: + - Missing validation: what if orderItem.delivered is negative? + - Edge case: calculateSpotPrice doesn't handle null deliveredQuantity + - Error handling: division by zero when market.growerPercentage is 100" + +Me: [Adds validation, handles edge cases, prevents division by zero] +``` + +BugBot became my most valuable reviewer. While Claude had fresh context and could see things differently from the session that created the code, BugBot consistently caught: + +- Uncovered edge cases +- Incomplete validations +- Unhandled error conditions +- Security implications I'd missed + +I've long since stopped using Cursor to write code, but BugBot remains essential for automated review. It's like having a paranoid QA engineer who never sleeps and loves finding problems. + +### 4. Documentation + +Claude wrote most of my documentation by analyzing code: + +```typescript +/** + * Calculates the final order total including all adjustments + * + * @param order - The order entity with items + * @param market - Market configuration for fees + * @param user - User for membership and credits + * + * @returns OrderTotal with breakdown of all components + * + * @throws InvalidOrderError if order contains invalid items + * @throws InsufficientCreditsError if user credits don't cover total + * + * @example + * const total = await calculateOrderTotal(order, market, user); + * // Returns: { subtotal: 50.00, fees: 5.00, credits: -10.00, total: 45.00 } + */ +``` + +--- + +## What Claude Struggles With + +### 1. Business Logic Consistency + +``` +Claude Monday: "Membership fees should be charged when expired" +Claude Wednesday: "Membership fees should be charged after trial period" + +Me: "We discussed this Monday. The rule is: charge when expired AND + after trial period." +``` + +### 2. Large-Scale Refactoring + +Claude can't hold enough context to safely refactor across 20+ files. I learned to break refactoring into smaller chunks: + +``` +Me: "Step 1: List all files importing the old UserService" +Claude: [Lists files] +Me: "Step 2: Update just the authentication methods in these 5 files" +Claude: [Updates those files] +``` + +### 3. Debugging Complex State + +When bugs involved multiple services, queues, and timing issues, Claude would often fixate on the wrong area: + +``` +Claude: "The issue is in the email service" +Me: "Actually, I found it. The queue processor was using the wrong timezone" +Claude: "Ah yes, that would cause this exact symptom because..." +``` + +## The Two-Week Launch Gauntlet + +### The Go/No-Go Framework + +For two weeks before launch, I treated each day like an airline cockpit checklist: systematic, comprehensive, no shortcuts. Each day, I'd run the entire agent orchestra through production readiness checks, categorizing every finding: + +```markdown +# LAUNCH READINESS AUDIT - T-14 Days + +## Issue Categories: +🚨 LAUNCH BLOCKERS - Must fix or launch fails +⚠️ CRITICAL - Fix within 24 hours +🔶 HIGH PRIORITY - Fix before Day 3 post-launch +🔷 MEDIUM - Fix within first week +🟢 LOW - Can wait for regular development + +## Launch Decision Matrix: +- 0 Launch Blockers = GO +- 1-2 Launch Blockers (<12 hours to fix) = CONDITIONAL GO +- 3+ Launch Blockers OR any >12 hours = NO GO (postpone) +``` + +Each agent had specific focus areas and delivered structured reports: + +``` +Ada (T-72 hours): "Performance Audit Complete +🔴 CRITICAL: Severe Page Load Performance + - First Contentful Paint: 27.0s + - Largest Contentful Paint: 46.7s + - Time to Interactive: 47.2s + - Root cause: 325KB JavaScript chunks, no code splitting + +🔴 Database Connection Pool Risk: + - Production: 100 connections (67% of DB capacity) + - Risk: Multiple batch operations could exhaust pool + - Mitigation: Emergency cleanup functions exist ✅ + +🟠 Bundle Size: 16MB total, needs optimization + +Launch Recommendation: CONDITIONAL - Can launch but needs immediate attention" + +Agatha (T-72 hours): "Security Audit Complete +🚨 LAUNCH BLOCKERS: NONE IDENTIFIED ✅ + +All critical security components properly implemented: +✅ Modern password hashing (Argon2 with proper salts) +✅ Legacy password migration (MD5/bcrypt → Argon2) with deadlines +✅ Redis-backed sessions with secure cookies +✅ Rate limiting (3 attempts/24h for password resets) +✅ Multi-level authorization framework +✅ Market isolation with subdomain-based context + +Launch Recommendation: GO from security perspective" +``` + +The audit wasn't just about finding problems. It tested actual user journeys with production data, verified every integration, and simulated failure scenarios. By T-24 hours, each agent would produce a 10-page markdown report with metrics, evidence, and specific remediation steps + +### Day 14: First Audit (July 31, 2025) + +``` +Me: "Full system audit. Are we ready to launch?" + +Agatha: "BLOCKER: SQL injection possible in search endpoint + BLOCKER: User sessions don't expire + BLOCKER: No rate limiting on API" + +Ada: "BLOCKER: Homepage takes 8 seconds to load + WARNING: No database connection pooling" + +Claude: "BLOCKER: 0% test coverage on payment system + WARNING: Only 22% overall coverage" + +Recommendation: NO-GO (Confidence: 95%) +Blockers must be resolved before launch. +``` + +### Day 10: Progress Check + +``` +Me: "Re-audit with focus on blockers from day 14" + +Agatha: "Previous blockers RESOLVED + New issue: CORS configuration too permissive + Status: CONDITIONAL-GO" + +Ada: "Homepage load: 2.1s (acceptable) + Database pooling implemented + Status: GO" + +Claude: "Payment system: 78% coverage + Overall: 45% coverage + Status: CONDITIONAL-GO (minimum viable)" + +Recommendation: CONDITIONAL-GO (Confidence: 70%) +Can launch with monitoring for remaining issues. +``` + +### Day 7: Cutting Scope to Ensure Stability + +``` +Me: "Agents are flagging Paraglide build warnings. Review needed." + +Claude: "Build warnings from internationalization library: +- Paraglide/inlang throwing compilation errors +- Not breaking builds but creating noise +- Library for future multi-language support" + +Me: "We're 7 days from launch. This is for future features. + Ripping it out completely. Multi-language can wait." + +[Removes entire i18n library and dependencies] + +Me: "Better to launch with solid English-only than risk + instability from unused future features." + +Recommendation: GO +Reduced scope = reduced risk. Focus on what matters now. +``` + +### Day 3: Final Systems Check + +``` +Me: "Final comprehensive audit before launch" + +Team Consensus: +- Security: 14 issues fixed, 2 low-priority remaining +- Performance: All pages <2s load time +- Testing: 67% coverage, critical paths covered +- Documentation: API docs complete, user guides updated +- Payments: Fully functional with error handling + +Recommendation: CONDITIONAL-GO (Confidence: 75%) + +Remaining items (non-blocking): +1. Add rate limiting to search endpoint +2. Implement Redis caching for product lists +3. Add monitoring for payment webhooks +``` + +### Day 1: Launch Eve Audit (August 13, 2025) + +``` +Me: "Final go/no-go decision needed" + +All Agents: "Analyzing 2,847 files, 50,000+ lines of code..." + +Results: +✅ Authentication: Secure +✅ Authorization: Market isolation verified +✅ Payments: Stripe integration stable +✅ Performance: <2s page loads +✅ Data integrity: No corruption paths found +✅ Error handling: All critical paths covered +⚠️ Test coverage: 87% (acceptable for launch) +⚠️ Documentation: 85% complete (acceptable) + +Recommendation: GO (Confidence: 82%) + +Agatha's final note: "No critical vulnerabilities. Ship it." +Ada's final note: "Performance acceptable. Monitor after launch." +Erma's final note: "User messaging is clear and helpful. Ready for real users." +``` + +### The Launch Day Reality Check + +The reports created by my agents were detailed enough that I could see where I needed to focus my attention. The issues they flagged as non-blocking remained non-blocking. The systems they certified as ready performed flawlessly. When the crisis hit (as described in Part 4), it wasn't in any of the areas they'd audited. It was in the simple things: math errors in calculations, UI buttons hidden from the wrong roles, invoices not grouping by grower, and input fields that couldn't accept decimal values. + +--- + +## Lessons Learned + +### 1. These Are Tools, Not Developers + +Claude Code doesn't understand business requirements, can't make product decisions, and won't catch when it's solving the wrong problem. The human is still the architect, product manager, and quality gatekeeper. + +### How to Keep ML Tools Safe in Production + +✅ **Write specs first**: Markdown in-repo. Tools get the what; you keep the why. +✅ **Enforce architecture with lint rules + CI**: e.g., "no DB calls in routes" +✅ **Require tests for every business logic change**: No exceptions +✅ **Security agent + human review** for auth, payments, data exports +✅ **Treat generated code like a junior dev's PR**: Review, annotate, refine +✅ **Maintain a "red file"** of irreversible actions (deletes, refunds) with extra checks +✅ **Monitor metrics**: If an endpoint is 10x slower, investigate + +### 2. Trust but Verify + +Every piece of machine-generated code needs review. The agents sometimes flag false positives, like when they reported "missing" deployment automation that had been tested for weeks, or build warnings that weren't actually breaking anything. Human oversight catches both their mistakes and their over-caution. + +### 3. Context Is Everything (Documentation as Specification) + +The more context you provide, the better the output. I learned to document specs and implementation plans in markdown files that become part of every prompt: + +```markdown +# Feature: Order Refunds +## Requirements +- Partial and full refunds supported +- Audit trail for all refund actions +- Email notifications to customer and grower +## Implementation +- Use PaymentService.refundOrder() +- Store refund records in orderRefunds table +- Queue email via RefundNotificationJob +``` + +This markdown becomes Claude's blueprint. No ambiguity, no guessing. + +**CLAUDE.md** serves as a readily consulted set of rules and standards for the entire project. When Claude remembers to check it, it helps enforce patterns like "use the service layer" and "follow our error handling conventions." When it forgets, at least the rules are documented for me to reference. + +### 4. Specialized Agents > General Purpose + +One Claude trying to do everything is good. Five specialized agents each doing what they're best at is transformative: + +- Security audits need security focus (Agatha) +- Performance needs profiling mindset (Ada) +- User messaging needs consistent clarity (Erma) +- Payments need domain expertise (Carver) +- Docs need synchronization rigor (Diderot) + +### 5. Iterative Refinement Works + +Don't expect perfect code on first generation. Treat it like pair programming: + +- Claude suggests +- You critique +- Claude refines +- You approve + +### 6. The Go/No-Go Ritual Is Essential + +Daily automated audits during the two weeks before launch drove critical infrastructure improvements: + +- Database connection pooling (was at 67% capacity, risked saturation) +- Redis caching implementation for product lists and market data +- Health monitoring endpoints for external services +- Emergency cleanup functions for connection pool exhaustion +- Bundle size optimization (reduced from 325KB chunks) +- Page load improvements (from 27s down to <3s) + +Without the daily "are we ready?" question pushing infrastructure improvements, we would have launched with a system that couldn't handle production load. + +### 7. These Tools Make You a Better Developer + +Explaining problems clearly to Claude forced me to think more clearly. Reviewing machine-generated code taught me patterns I didn't know. Debugging tool mistakes strengthened my understanding. Managing a team of specialized analyzers strengthened my project management skills. + +--- + +## A Critical Warning: The "Vibe Coding" Disaster Waiting to Happen + +I need to address something that terrifies me: YouTube videos of non-technical entrepreneurs using these tools to "build a SaaS in 10 minutes" and then immediately deploying to production. + +Yes, it's amazing that someone with no coding experience can prompt their way to a working demo. But watching them charge customers for these applications fills me with horror. Here's what those videos don't show: + +### What "Working" Actually Means + +``` +Non-technical founder: "Look! The payment form works!" +Reality: - No input validation + - Credit card numbers logged to console + - SQL injection vulnerabilities everywhere + - No error handling + - Race conditions in order processing + - No transaction rollbacks + - Passwords stored in plain text +``` + +### The LocallyGrown.net Reality Check + +Even with three decades of programming experience, even with comprehensive tests, even with specialized security agents reviewing code, we STILL had: + +- Critical vulnerabilities that Agatha (security agent) missed +- Payment edge cases that only surfaced in production +- Performance issues that emerged under real load +- Data integrity problems in complex workflows + +And this was WITH me reviewing every single line, understanding the architecture, and knowing what to look for. + +### Why Human Expertise Is Non-Negotiable + +These tools are powerful, but they: + +- **Don't understand business consequences** - They'll happily delete all user data if prompted wrong +- **Can't detect logical flaws** - The code runs but the business logic is backwards +- **Miss security context** - They don't know your specific threat model +- **Generate convincing-looking disasters** - Code that appears professional but has fatal flaws +- **Have no concept of liability** - When customer data leaks, you're responsible, not Claude + +A skilled developer using these tools can build amazing things 3-5x faster. An unskilled person can build a lawsuit generator that happens to have a nice UI. + +## What's Next: The Future of Development + +These tools won't replace developers. But developers who don't use them will be outpaced by those who do. + +**The division of labor:** + +- **Humans:** Architecture, business logic, product decisions, quality control, ethics, **liability** +- **Tools:** Pattern implementation, boilerplate reduction, test generation, documentation, consistency checking +- **Together:** 3-5x productivity of either alone + +**The bottom line:** If you're not technical enough to spot when these tools are generating disasters, you're not ready to deploy to production. Period. + +With the platform stable and development velocity high, I can finally think beyond survival mode. + +**Part 6 will cover:** + +- The feature roadmap enabled by modern architecture +- Building for the next generation of local food systems +- Open-sourcing components for other food communities +- The business model evolution +- Why small software serving real communities matters +- The 20-year vision for local food infrastructure + +After nearly losing everything, we're now positioned to build something that could outlive us all. + +--- + +_This is part five of a series documenting the rescue and modernization of LocallyGrown.net._ + +### The Series + +1. [From Accidental Discovery to Agricultural Infrastructure (2002-2011)](https://blog.kestrelsnest.social/posts/locallygrown-origin-story/) +2. [The 23-Year Rescue Mission: Saving Agricultural Innovation from Technical Extinction](https://blog.kestrelsnest.social/posts/locallygrown-rescue-mission/) +3. [The Architecture Challenge: Translating 19 Years of Rails Logic to Modern SvelteKit](https://blog.kestrelsnest.social/posts/locallygrown-architecture-challenge/) +4. [The Reality of Production: When Hope Meets Live Users](https://blog.kestrelsnest.social/posts/locallygrown-reality-of-production/) +5. **Lessons from the Solo Developer Using Modern Tools** ← _You are here_ +6. The Future: Building on Modern Foundations