Every developer knows code review matters. It catches bugs, improves architecture, and keeps code maintainable. But when you're deep in a flow state—plan approved, implementation humming along, feature nearly complete—it's tempting to call it done and move on. The review gets skipped, deferred, or reduced to a quick skim. I built a system that makes skipping impossible.

Using Claude Code's hooks system, I created an automated gate that detects when a plan implementation session is complete and blocks the session from ending until a comprehensive code review has been performed. It's like having a senior engineer who never forgets to review the PR before it merges.

## The Problem: Review Fatigue After Implementation

If you've read my earlier post on [Plan Mode](/blog/power-of-plan-mode-claude-code), you know I'm a big believer in structured planning before writing code. Plan Mode ensures you think through architecture, edge cases, and user experience before a single line changes. But there's a gap in that workflow.

After a planning session produces a solid roadmap and the implementation is complete—sometimes spanning dozens of file changes across frontend and backend—the natural instinct is to wrap up. You've been collaborating with Claude Code for an extended session, the feature works, and you're ready to commit. The problem is that implementation mode is fundamentally different from review mode. When you're building, you're focused on making things work. When you're reviewing, you're asking whether things are built well. Those are two distinct mindsets, and context-switching between them at the end of a long session is exactly when quality slips.

## How Hooks Work

Claude Code hooks are shell commands or prompts that execute automatically in response to lifecycle events. You configure them in your settings file, and they run without manual intervention. The key events include things like `Stop` (when Claude is about to end its turn), and hooks can return `approve` to allow the action or `block` to prevent it.

The hook type I'm using is a `prompt` hook—rather than running a shell command, it sends a prompt back to Claude Code itself to evaluate the conversation and make a decision. This is powerful because the hook has access to the full conversation context to make intelligent, nuanced decisions.

## The Hook: An Automated Code Review Gate

Here's the Stop hook I configured:

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review the conversation transcript to determine if this stop follows a PLAN IMPLEMENTATION session..."
          }
        ]
      }
    ]
  }
}
```

The prompt instructs Claude Code to analyze the conversation and determine whether a code review is warranted. It should **approve** stopping (allow the session to end) if any of these are true:

- A code review was already completed in this session
- The session only involved questions, discussion, or file exploration
- Only a single small edit was made
- No plan was discussed or approved
- Changes were limited to configuration or documentation

It should **block** stopping only when **all** of these are true:

- A development plan was explicitly discussed and approved
- Multiple source code files were created or modified to implement the plan
- Claude indicated the implementation is complete
- No code review has been performed yet

When the hook blocks, it triggers a system message instructing Claude Code to spawn a specialized `code-reviewer` agent. This is a separate subagent—a distinct process with its own context window and its own set of instructions. It doesn't inherit the main agent's reasoning or biases from the implementation session. It reads the changed files fresh, evaluates them against its own review-focused criteria, and reports back its findings.

## Why This Design Works

### Smart Filtering, Not Blanket Rules

The most important design decision was making the gate conditional. A hook that forced a code review on every single session would be annoying—you don't need a full review when you're asking a question, exploring a codebase, or tweaking a config file. By scoping the trigger narrowly to plan implementation sessions with substantial code changes, the review only fires when it actually adds value.

### The Right Mindset at the Right Time

The code-reviewer is a separate agent with its own context and instructions—it doesn't share the main agent's conversation history or reasoning. This matters more than it sounds. The agent that just spent an hour implementing a feature has built up justifications for every decision it made. It's not going to second-guess itself. The reviewer agent has none of that baggage. It sees the code as-is, evaluates it against its own review-focused instructions, and flags concerns the implementation agent would rationalize away. This separation mirrors how human code review works best—the author builds, someone else reviews—except here it's enforced architecturally rather than by org chart.

### Zero Friction When Not Needed

If you're just chatting, reading files, or making a quick one-line fix, the hook evaluates the conversation, determines no review is needed, and approves the stop instantly. You never even notice it's there. The 30-second timeout ensures that even if the evaluation takes a moment, it won't hang your session.

## What the Reviewer Catches

The code-reviewer agent isn't doing a superficial lint check. It performs a comprehensive review covering:

- **Structural issues**: Components that are too tightly coupled, missing abstractions, or responsibilities in the wrong layer
- **Scalability concerns**: Patterns that work now but will break under growth—N+1 queries, unbounded loops, missing pagination
- **Maintainability**: Naming inconsistencies, duplicated logic, unclear interfaces that will confuse future developers
- **Pattern adherence**: Whether new code follows existing project conventions or introduces unnecessary divergence

In practice, I've found it catches things I would have noticed in a manual review the next day—but by then I've already committed and moved on. Getting that feedback immediately, while the context is fresh, means fixes are trivial instead of disruptive.

## Beyond Code Review: Other Hook Patterns

Once you see how this works, other applications become obvious:

- **Test verification**: Block stopping after implementation until tests pass
- **Documentation checks**: Require README or changelog updates when public APIs change
- **Security scanning**: Flag sessions that touch authentication or authorization code for extra scrutiny
- **Commit preparation**: Automatically stage and format a commit message summary when implementation is complete

The hooks system turns Claude Code from a reactive tool into a proactive workflow partner that enforces your team's quality standards automatically.

## Conclusion: Automate the Discipline

The best processes are the ones you don't have to remember to follow. By wiring code review into Claude Code's lifecycle, I've removed the decision of whether to review from the equation entirely. Every substantial implementation gets reviewed. Every time. No exceptions, no willpower required.

This hook has changed how I think about AI-assisted development. It's not just about generating code faster—it's about building guardrails that keep quality high even as velocity increases. Plan Mode ensures you build the right thing. The review hook ensures you build it well. Together, they create a development workflow where speed and quality aren't competing priorities.

If you're using Claude Code for anything beyond simple one-off tasks, I'd encourage you to explore hooks. Start with the code review gate described here, then layer on whatever quality checks matter most to your project. The few minutes of setup pay for themselves the first time the reviewer catches something you would have shipped.


How I built a Stop hook that automatically triggers a code review agent after every plan implementation session

Automated Code Review with Claude Code Hooks

When I started building [FreedomTrack](https://www.freedomtrack.io) — a financial independence tracking app — users entered their account balances manually. It worked, but nobody wants to log in monthly just to update their 401k balance. The obvious next step was pulling data directly from financial institutions through Plaid.

The integration turned out to be one of the more architecturally interesting pieces of the app. Plaid gives you access to balances, transactions, investment holdings, and recurring payment patterns — but how you model, sync, and present that data to users matters a lot more than the API calls themselves.

## How Plaid Link Works

The entry point is Plaid Link, a drop-in UI component that handles the entire bank authentication flow. Your app never touches bank credentials — Plaid's iframe handles login, MFA challenges, and account selection. The flow looks like this:

1. **Your server creates a link token** — this configures what products you want (transactions, investments, etc.) and what country/language to use
2. **The frontend opens Plaid Link** with that token — the user picks their bank and logs in
3. **On success, Link returns a public token** — a short-lived, one-time-use token
4. **Your server exchanges it for an access token** — this is the permanent credential you'll use for all future API calls against that institution

The access token is the critical piece. It represents a persistent connection to a user's accounts at a specific institution. One token can cover multiple accounts — a user's checking, savings, and credit card at the same bank all live under one token.

## Edge Function Architecture

I built the integration as a set of Supabase Edge Functions, each handling a specific concern:

- **`plaid-create-link-token`** — Generates the Link token with the right product configuration
- **`plaid-exchange-token`** — Swaps the public token for an access token and stores the institution connection
- **`plaid-sync-balances`** — Pulls current balances for all accounts under an institution
- **`plaid-sync-transactions`** — Uses Plaid's sync endpoint to incrementally fetch new, modified, and removed transactions
- **`plaid-sync-investments`** — Fetches investment holdings and their current values
- **`plaid-sync-recurring`** — Identifies recurring transaction patterns (subscriptions, regular bills)

Each function authenticates the request via JWT, verifies the user owns the Plaid item they're trying to sync, and handles Plaid API errors. The access tokens never leave the server — the frontend works with institution and account IDs only, and a database view strips the token column from any query results.

## Data Modeling: Keeping Plaid Separate from Your Domain

This was the most important architectural decision. Plaid data lives in its own tables, connected to the app's core domain through explicit links that users control.

```
plaid_items (institution connections)
  └── linked_accounts (individual bank accounts)
        ├── → assets (user links a brokerage account to a "Brokerage" asset)
        └── → liabilities (user links a mortgage account to a "Mortgage" liability)
```

A `plaid_items` table stores each institution connection — the access token, institution name, and sync cursors. A `linked_accounts` table stores individual accounts within each institution — account name, type, subtype, and current balance.

These connect to the app's `assets` and `liabilities` tables via optional foreign keys. When a user links their Vanguard brokerage account to a "Brokerage" asset in FreedomTrack, syncing balances automatically updates that asset's value. But the user explicitly creates that link — connecting an institution doesn't automatically overwrite anything.

This separation means users can unlink an account at any time and go back to manual entry without losing data. Plaid is a data source, not the source of truth.

## Transaction Staging: Don't Auto-Import Everything

Transactions were the trickiest piece to get right. The naive approach would be: sync transactions from Plaid, dump them into the user's expense tracker, done. But bank transactions are messy. Transfers between your own accounts show up as both a debit and a credit. Pending transactions can change amounts or disappear entirely. Categories from Plaid don't always match how a user thinks about their spending.

Instead, I built a staging pattern:

1. **Sync** — Transactions land in a `plaid_transactions` table using Plaid's sync endpoint, which gives you added, modified, and removed transactions incrementally (no need to re-fetch everything)
2. **Review** — Users see their transactions in a review UI where they can categorize, annotate, or skip them
3. **Import** — Selected transactions get pulled into the app's expense/income tables

This keeps users in control. They see everything Plaid gives them but choose what enters their financial picture. The sync endpoint's cursor-based approach means each sync only fetches what's changed since last time — efficient even for accounts with heavy transaction volume.

## Investment Holdings: More Than Just Balances

For a financial independence app, investment data is where Plaid really shines. Beyond just the total account balance, you get:

- **Individual holdings** — each position with its ticker, quantity, and current value
- **Cost basis** — what the user originally paid, enabling gain/loss calculations
- **Security metadata** — whether it's a stock, ETF, mutual fund, cryptocurrency, etc.

I sync this into a `plaid_holdings` table linked to the account. The app can then show a user's total investment allocation, track individual positions over time, and calculate how close they are to their financial independence target — all without the user lifting a finger after the initial connection.

## Handling the Rough Edges

Plaid's sandbox environment is excellent for development, but there are quirks to watch for:

**Account selection behaves differently across environments.** In sandbox, you get all accounts from the test institution. In development and production, users can select which accounts to share. Your UI needs to handle a user connecting an institution but only sharing two of their five accounts.

**Webhooks vs. polling.** Plaid recommends webhooks for transaction updates, but for a smaller app where users trigger syncs manually, polling via the sync endpoint works fine and avoids the infrastructure complexity of webhook receivers. I went with user-initiated sync — they click a refresh button, the edge function calls the sync endpoint, done.

**Token expiration and re-authentication.** Access tokens can break when a user changes their bank password or their bank's connection with Plaid has issues. You need an "update mode" flow where users can re-authenticate through Plaid Link without creating a new connection. The link token creation endpoint accepts an existing access token for this purpose.

**Rate limits and error handling.** Plaid returns specific error codes for different failure modes — `ITEM_LOGIN_REQUIRED` means re-authentication is needed, `INSTITUTION_NOT_RESPONDING` means try again later. Handling these gracefully in the UI is important for trust — users get nervous when bank connections show errors.

## Security: Earning the Trust

When users connect bank accounts to your app, you're accepting serious responsibility. A few things I implemented beyond the basics:

**Column-level encryption** for access tokens using pgcrypto and Supabase Vault. Even if someone gained database access, tokens are unreadable without the Vault key. The encrypt/decrypt functions are restricted to the service role.

**Row Level Security** on every Plaid-related table. The `auth.uid() = user_id` pattern ensures users can only ever see and sync their own connections. No admin endpoint accidentally leaks another user's bank data.

**Audit logging** for sensitive operations — linking accounts, removing connections, syncing data. A simple table that records who did what and when.

**MFA support** — Plaid requires this for production access, and frankly any app touching bank data should have it. Supabase Auth supports TOTP natively, so it was mostly a matter of building the enrollment UI.

Getting production access from Plaid also requires data deletion capabilities, a privacy policy, and documentation of your security practices — reasonable requirements that push you toward building a more trustworthy product.

## Lessons Learned

**Choose infrastructure that handles the hard parts.** Supabase gave me Row Level Security, built-in auth with MFA, Vault for secrets, and pg_cron for scheduled jobs. On a more barebones stack, I'd have spent weeks building what amounted to configuration changes.

**Keep the integration loosely coupled.** The separation between Plaid tables and domain tables paid for itself immediately. When I changed how assets worked, the Plaid integration didn't need to change. When Plaid changed their transaction schema, the app's expense tables didn't care.

**Let users stay in control.** The staging pattern for transactions and the explicit linking for balances both serve the same principle: connected data should inform the user's financial picture, not dictate it. Users trust the feature more when they feel in control of it.

**Start with fewer Plaid products and expand.** I started with just balances, got that working end-to-end, then added transactions, then investments. Each product has its own sync patterns, error modes, and data models. Trying to build them all at once would have been a mess.

---

The Plaid integration took [FreedomTrack](https://www.freedomtrack.io) from a manual spreadsheet replacement to something that genuinely saves users time. The API itself is well-documented and straightforward — the real engineering work is in the data modeling, sync patterns, and UX decisions around how automated data coexists with user control.

_If you're building a product that needs financial data integrations or other complex API work, I'd love to chat. Hit the "Get in Touch" button below or connect on [LinkedIn](https://linkedin.com/in/awwester)._


Architecture decisions, data modeling, and sync patterns behind integrating Plaid into a financial independence app

Building Bank Account Sync with Plaid

Every SaaS product has an onboarding flow, and most of them have historically looked the same: a multi-step form wizard with progress bars, radio buttons, and input fields. You pick a goal from a predefined list, enter some numbers, click Next five times, and land on a dashboard. It works, but it's the digital equivalent of filling out paperwork at a doctor's office before anyone has talked to you.

I recently replaced the entire onboarding wizard in [FreedomTrack](https://www.freedomtrack.io) — a financial independence tracking app I built — with a conversational AI agent. No more steps. No more radio buttons. Just a chat where you describe your financial situation in plain English, and the agent creates your records, explains FI concepts along the way, and gets your dashboard populated in a couple minutes.

Here's how I built it, the pitfalls I hit along the way, and why I believe this pattern applies to far more products than just mine.

## What Was Wrong with the Wizard

FreedomTrack's original onboarding was a 5-step form:

1. **Welcome** — Pick your financial goal from a list, select how you found us
2. **Personalize** — Enter your age, target FI age
3. **Expenses** — Enter a total monthly expense number
4. **Income** — Add income sources one by one
5. **Review** — See a summary, optionally add an asset

It wasn't broken, but it had clear problems:

**It assumed users already understood FI concepts.** When someone sees a field labeled "yield rate" during onboarding, they either guess, skip it, or leave. The form had no room to explain _why_ a yield rate matters or what a reasonable value would be for their 401k.

**It forced a rigid structure.** Some users want to talk about their investments first. Others want to start with debt. A form wizard forces everyone through the same sequence regardless of what's on their mind.

**It captured the minimum.** The wizard got a total expense number and maybe one or two income sources. A conversation naturally surfaces more detail — "I spend about 2k on rent, 400 on groceries, 200 on subscriptions" gives you three expense records instead of one lump sum.

**It felt like a chore.** Five steps with a progress bar signals "this will take a while." A chat with an opening question signals "just tell me about yourself."

## The Architecture

The replacement has three pieces: an edge function that talks to Claude, a React hook that manages conversation state, and a set of chat UI components.

### The Edge Function

The edge function is a Supabase Edge Function that acts as a proxy between the frontend and the Claude API. It authenticates the user, builds the Claude request with tools, and executes tool calls against the database.

The key design decision is the **tool loop**. When Claude decides to create a record, the edge function executes the database insert and feeds the result back to Claude as a tool result. Claude might then create another record, ask a follow-up question, or summarize what it did. This loop continues until Claude responds with just text (no more tool calls), at which point the function returns.

![Edge Function tool loop diagram](/images/blog/edge-function-tool-loop.svg)

The tools available to Claude mirror the app's data model:

- `create_asset` — investments, retirement accounts, property
- `create_liability` — mortgages, loans, credit card debt
- `create_income` — salary, freelance, side income
- `create_expense` — rent, groceries, subscriptions
- `update_profile` — goals, age info
- `complete_onboarding` — marks onboarding done, writes a summary

Each tool inserts directly into the database with the authenticated user's ID. By the time the conversation is done, the user's dashboard is fully populated with real data.

### The System Prompt

The system prompt is where the domain knowledge lives. It teaches Claude the FI concepts that matter for the app:

- The 25x rule (FI number = 25x annual expenses)
- What yielding assets are and why they matter
- How savings rate is calculated
- Reasonable yield rates and growth rates for common asset types

It also defines conversation flow guidance — start with goals, then expenses, income, assets, debts — but explicitly tells Claude to be flexible and adapt if the user volunteers information in a different order.

One important behavioral rule: **confirm before creating records.** The agent should say "I'll create a $4,200/month expense record for your total monthly expenses" before actually calling the tool. This gives the user a chance to correct mistakes before data hits the database.

### Conversation History

The first version sent only the text content of previous messages to Claude on each request. This meant Claude had no memory of its own tool calls — it didn't know what records it had already created. The result: duplicate records.

The fix was to return the **full message chain** from the edge function, including the raw tool_use and tool_result message blocks. The frontend stores these in a ref and sends them back as conversation history on each subsequent request. Claude sees its own prior tool calls and their results, so it knows exactly what's been created.

The display messages (what the user sees in the chat) remain simple — just text and created record cards. The API conversation history is a separate, richer data structure that preserves the full tool interaction chain.

### The Frontend

The chat UI is straightforward: a message list with auto-scroll, a text input, and a header with a "Skip to Dashboard" button. Messages are styled as bubbles — user messages right-aligned, assistant messages left-aligned. When the agent creates a record, a compact card appears below the message showing the record type, name, and value.

The hook manages two parallel data structures:

- `messages` — the display state (simple text + record cards)
- `apiHistoryRef` — the full API conversation history (tool calls included)

On completion, the agent calls the `complete_onboarding` tool, the response includes an `onboardingComplete` flag, and the UI swaps the input for a "Go to Dashboard" button.

## What Makes This Better

**Natural language parsing removes friction.** "I make about 120k" becomes a $10,000/month income record. "We spend maybe 4k a month total" becomes an expense record. Users don't need to think about which field to put a number in or what format to use.

**Concepts get explained in context.** When the agent asks about investments, it can naturally explain yield rates: "For a broad index fund, a yield rate around 2% and growth rate around 7-10% would be typical." This happens in conversation, not as a tooltip the user has to hover over.

**The flow adapts to the user.** If someone opens with "I have $200k in student loans and I want to get out of debt," the agent starts with liabilities instead of forcing them through a goal-selection step first. The conversation goes where the user takes it.

**More data gets captured.** In the wizard, users entered a single total expense number. In conversation, they naturally break things down — rent, car payment, groceries, subscriptions — which gives the dashboard much richer data to work with.

**Skip still works.** The "Skip to Dashboard" button is always available. Any records created during the conversation persist even if the user skips partway through. There's no all-or-nothing commitment.

## Where Else Does This Apply?

I built this for a financial tracking app, but the pattern fits anywhere you have a multi-step form and a domain where users need guidance:

- **Health & fitness apps** — "I run three times a week and do yoga on Sundays" beats picking from dropdowns
- **Project management setup** — describe your team and workflow instead of configuring boards and columns
- **Insurance or lending applications** — complex forms with conditional logic are natural conversations
- **Any product with domain-specific jargon** — if users Google your field labels, a conversational agent will onboard them better than a form

The ingredients are simple: a clear data model that maps to tool definitions, a domain where users benefit from explanation, and a flow where rigid ordering adds friction rather than clarity. Most onboarding flows check all three boxes.

The conversational approach isn't just a UI change — it fundamentally changes what data you collect. When you let users describe their situation in their own words, you get richer, more accurate data. And when the agent can teach concepts while collecting that data, users start their experience with understanding rather than confusion.

Onboarding is just the starting point. For FreedomTrack, I'm already building out additional agents — a Data Management Agent for natural language updates to your finances, a Monthly FI Review Agent that proactively analyzes your progress, and a Scenario Advisor Agent for exploring "what if" questions about your FI path. Once the pattern clicks, you start seeing agent-shaped opportunities everywhere in your product.

---

Want to see this in action? Try the conversational onboarding at [FreedomTrack.io](https://www.freedomtrack.io) — it's free, and you'll have your FI dashboard populated in a couple minutes.

_If you're looking at your own product's onboarding (or any workflow that could benefit from conversational AI) and thinking "this could work for us" — I'd love to chat. I build these kinds of agentic integrations for teams. Hit the "Get in Touch" button below or reach out on [LinkedIn](https://linkedin.com/in/awwester)._


How I replaced a 5-step form wizard with a conversational AI agent that collects richer data while teaching users along the way

Replacing Onboarding Forms with an AI Conversational Agent

We've all been there: you ask an AI coding assistant to implement a feature, and it immediately starts making changes across multiple files. Halfway through, you realize it's heading in the wrong direction, making assumptions that don't align with your architecture. Now you're faced with a frustrating choice—spend time fixing a tangled mess of changes, or just revert everything and start over.

There's a better way. Today, I want to share how Claude Code's Plan Mode prevents this scenario entirely by establishing a clear roadmap before any code gets written.

## The Challenge: Adding a "Remix" Feature

Recently, I worked on adding a new "Remix" feature to an application that processes YouTube videos and creates content based on that video, such as a news summary article. The requirement was to allow users to enhance existing generated content by incorporating additional source materials like PDF reports or web articles. This required API changes, service changes for parsing files or URLs to gather data to pass into LLM for remixing the content, database considerations, frontend form components with validation, frontend service for managing the request/response, file upload handling for multiple formats, integration with existing content generation pipelines, and UI/UX implementation.

## The Tale of Two Approaches: With and Without Plan Mode

To truly appreciate the value of Plan Mode, it's helpful to contrast what this development process would have looked like without it.

### Without Plan Mode: Direct Implementation

In Claude Code without Plan Mode—where there's minimal upfront discussion and the AI jumps straight into implementation—here's how this remix feature would have unfolded:

1. **Initial Analysis**: Claude Code would receive the requirements ("add a remix feature") and perform some quick analysis based on its understanding
2. **Assumptions Made**: It would make assumptions about implementation details—perhaps assuming we should reuse the existing "regenerate" function which starts from scratch, or assuming we need storage for the source files provided
3. **Immediate Implementation**: Development would begin immediately based on these assumptions
4. **Mid-Development Surprises**: Halfway through coding, we'd discover that reusing the regenerate function doesn't preserve the original content for remixing, or that we don't actually need persistent storage for the source files
5. **Course Corrections**: This would lead to refactoring, redesigning, and potentially scrapping work already done
6. **Iterative Fixes**: Multiple rounds of "let me fix this" and "actually, let's try this approach instead"

The result? A meandering development process with false starts, wasted effort, and potentially a final implementation that addresses the immediate need but creates technical debt.

### With Plan Mode: The Structured Approach

Plan Mode completely transforms this dynamic:

1. **Collaborative Planning**: Claude Code presents a comprehensive, step-by-step plan covering all aspects of the feature, breaking it down into phases and sub-tasks
2. **Feedback Loop**: I can review the plan, spot potential issues, and provide feedback before any code is written or any file is changed
3. **Shared Understanding**: We align on implementation strategy, architectural decisions, and user experience considerations upfront
4. **Informed Execution**: Development proceeds with confidence in a structured way because the approach has been validated
5. **Smooth Integration**: Each implementation step builds logically on the previous ones because the interfaces and dependencies were planned in advance

### The Key Difference: Collaboration vs. Assumption

The fundamental difference isn't just about planning—it's about **collaboration**. Without Plan Mode, Claude Code has to make educated guesses about my intentions and preferences. With Plan Mode, we have a conversation about the approach before committing to it.

This dynamic mirrors the relationship between a product manager and an engineer. The PM provides requirements and context, the engineer proposes a technical approach, they discuss trade-offs and alignment, then the engineer executes with confidence. Plan Mode transforms Claude Code from a "guess and implement" tool into a collaborative partner that seeks alignment before action.

## Planning Prevented These Problems

Plan Mode forced us to step back and analyze the full scope before any code was written. What seemed like "just adding a button" revealed multiple layers of complexity that could have derailed the implementation:

**Over-Engineering the Database**: Initially, we considered creating a new remix_sources table to store uploaded materials. Planning revealed this was unnecessary complexity—the remix functionality only needed source material during processing, not for long-term storage. Without planning, we might have built and later removed an entire database layer.

**UI Chaos**: We were going to add the new Remix button alongside existing Regenerate, Edit, Copy, and Delete buttons. Planning helped us realize this would create a cluttered interface. Instead, we designed a clean dropdown menu that consolidates all content actions. This prevented shipping a poor user experience and then having to refactor it later.

**Component Architecture**: Rather than cramming functionality into existing components, we planned a clean separation: RemixContentForm for form logic, RemixContentDialog for dialog state, and ContentProductActionsDropdown for the consolidated UI. This upfront architecture decision prevented messy, tightly-coupled code.

**File Processing Strategy**: We decided upfront to support only PDF and DOCX files with a structured approach that makes adding new file types trivial. Without planning, we might have built a rigid solution that would require significant refactoring to extend.

Each of these decisions made during planning prevented expensive mid-development course corrections and potential reverts.

## The Implementation Journey: Staying on Track

With our plan in place, the implementation became a series of well-defined, manageable tasks: Backend Foundation File processing utilities with proper validation, new API endpoint with multipart support, and enhanced content generation logic to handle remix scenarios. Frontend Polish Reusable form components following established patterns, dialog components with both controlled and uncontrolled modes, and clean dropdown interface replacing button chaos. Integration Points Service layer updates with proper error handling, React Query hooks for state management, and real-time updates via existing WebSocket infrastructure. Each step built logically on the previous ones, and because we had planned the interfaces upfront, integration was smooth.

## Key Lessons Learned

### 1. Planning Reveals Hidden Complexity

What seemed like a simple feature request revealed multiple layers of complexity that only became apparent through thorough planning. Without this upfront analysis, we would have discovered these complexities during implementation—when they're much more expensive to address.

### 2. Architecture Decisions Have Lasting Impact

The decision to use a dropdown menu instead of multiple buttons, or to process files in-memory rather than storing them, had implications throughout the entire feature. Making these decisions during planning, when the cost of change is low, is infinitely better than making them during implementation.

### 3. User Experience Should Drive Technical Decisions

Planning forced us to consider the user experience first, which then informed our technical approach. The dropdown menu decision is a perfect example—it was driven by UX concerns but had positive technical implications as well.

### 4. Consistent Patterns Accelerate Development

By planning to follow existing patterns (React Hook Form, shadcn/ui components, TanStack Query), we avoided reinventing the wheel and maintained consistency across the application.

## The Results

The final implementation was clean, well-structured, and user-friendly: robust backend file processing with proper validation and error handling, intuitive frontend dropdown interface with comprehensive form validation, seamless integration with existing content generation pipelines, and maintainable code that follows established patterns and is easy to extend. Most importantly, the feature shipped without major revisions or refactoring needs because the planning phase had identified and addressed the key challenges upfront.

Perhaps most remarkably, this entire feature took under 3 hours to complete, when in the past—before AI assistance was a thing—a similar feature could have taken a full week.

## Conclusion: Plan Mode is Your Friend

In our fast-paced development world, it's tempting to skip planning and jump straight into implementation. But as this example demonstrates, taking time for proper planning—especially for complex features—pays dividends throughout the development process. Plan Mode in Claude Code isn't just about organizing thoughts; it's about revealing hidden complexity before it becomes expensive, making architectural decisions when they're cheap to change, ensuring user experience drives technical implementation, and creating a roadmap that keeps development focused and efficient. The next time you're faced with a feature request that feels complex, resist the urge to start coding immediately. Fire up Plan Mode, think through the implications, and create a roadmap. Your future self (and your users) will thank you.

The remix feature described in this article demonstrates how proper planning can transform a potentially chaotic development process into a structured, successful implementation. While the specific domain was content generation from YouTube videos, these planning principles apply to any complex feature development.


Discover how Plan Mode transforms complex development tasks through collaborative planning

The Power of Plan Mode in Claude Code

## From Single Agent to Specialized Teams

The shift from using a single AI coding assistant to orchestrating specialized agent teams has fundamentally changed how I approach software development. After years of building products—from initial MVPs to scaling production systems—I've learned that the same principles that make human development teams successful apply to AI agents as well.

The traditional approach has been heavily reliant on human labor, but if you haven't heard, that landscape is changing rapidly.

Over the past couple months, I've been using Claude Code to handle my coding changes. I've thoroughly enjoyed how it breaks out prompt requests into a set of tasks, and then allows you to review the code along the way and help guide it into the proper direction. For technical users, it provides benefits over some of the earlier code editors which tend to be better for non-technical users (cursor, windsurf, co-pilot).

That being said, there still is a lot of human oversight required to build products, especially if you want it to be quality work that is easily maintained and expanded upon. Until now, I had been using a single agent (just the built-in claude code, co-pilot, cursor, windsurf, etc) in my IDE to work through coding changes. However, in the past few days I found the /agents command in claude code.

## The Vision: Specialized Agents, Unified Goal

Traditional development teams succeed because of specialization. You have frontend developers who live and breathe React, backend engineers who architect robust APIs, QA specialists who think in edge cases, and DevOps engineers who understand infrastructure at scale. My intended approach with Claude Code mirrors this structure, but with AI agents filling each role.

Currently, I've built agents for my projects that specialize in:

- **React Development**: Handles component architecture, state management, and modern frontend patterns
- **Supabase Operations**: Database design, real-time subscriptions, and authentication workflows
- **Django REST Framework**: API design, serialization, and backend architecture
- **Quality Assurance**: Test planning, edge case identification, and validation strategies
- **Code Review**: Standards enforcement, security audits, and optimization suggestions

Each agent operates with instructions that encode years of my product development experience. When a React agent consistently produces components with poor structure or continually repeats state management code, I update its prompt to emphasize proper standards which lead to a maintainable system. When the QA agent creates flaky tests for trivial edge cases, I enhance its testing methodology to focus more on actual usage cases that won't easily break with non-breaking code changes.

The problem with the single agent approach is that the instructions file becomes far too large and broad. It gets split up into several sections, however there is too much context scope for a single agent to handle everything and that in turn results in more extensive human reviews and more guidance required.

## The Orchestration Challenge

Right now, I serve as the conductor of this orchestra. I formulate task requirements, determine which agents need to collaborate, and sequence their work to avoid conflicts. A typical workflow might involve:

1. The Supabase agent creating the database migration and updating the frontend types
2. The React agent building the service layer and components that consume the API
3. The QA agent creating tests for the new coverage
4. The Code Review agent auditing everything to ensure project standards are met

This orchestration role mirrors what I've been doing manually previously—analyzing requirements, sequencing development phases, managing dependencies, and ensuring quality at each step. The difference now is scale and consistency. What once required weeks of careful coordination can now happen in hours, with the same attention to detail and best practices I've developed through years of product development.

## The Self-Serving Future

The natural evolution is automating the methodology I've developed over years of building products. I'm currently developing a project that will deploy this entire agent ecosystem as a self-serving system—essentially codifying my entire product development methodology into an automated pipeline. Imagine describing a product idea and watching as the system automatically applies all the lessons, patterns, and quality standards I've learned through hands-on experience:

- Breaks down requirements into specialized tasks
- Assigns work to appropriate agents
- Manages inter-agent communication and dependencies
- Deploys the final product

The technical challenges are significant, but the challenge is good. I'm able to build this incrementally, one step at a time, driving closer to making myself obsolete and my team of agents more useful in building products. Agent coordination requires sophisticated workflow management, shared context understanding and proper oversight for improvement. These are rapidly evolving concepts that the entire industry is still figuring out, so there is much evolution taking place constantly.

*Building with AI agents has fundamentally changed how I approach software development. If you're experimenting with similar workflows or would like to build a product together, I'd love to see if we can collaborate.*


Building collaborative AI agent systems that work together to build products

Building Products with Specialized AI Agent Teams

## Discovering AI-Generated Code

A couple of months ago, I decided to switch from standard VS Code to Windsurf. I had been using VS Code since about 2015, although since Copilot autocomplete came into the picture a couple years ago, coding became much easier. The autocomplete feature finished my thoughts, and I could even write a docstring for a class or function and Copilot would give me a usable solution, most of the time.

And then came editors that used the entire codebase as context and were able to generate full projects. I decided to try out Windsurf and see what happened. Within an hour I had a full Django REST framework server foundation ready for a stock trading application. This was no basic implementation—it contained authentication, interactive documentation, and was fully tested.

The next day I built out a personal finance application that I had in my head for years, but had never built. As opposed to the day before, this time I built out both the frontend and the backend. Everything was working great, and I built it in a day. What would have taken months of traditional SaaS development—user authentication, subscription management, admin dashboards—was scaffolded and functional in hours.

This is incredible, I thought. And my career is toast.

## The Fundamentals Haven't Changed

A client of mine sent me a message. Through his code editor, he had accidentally terminated the entire production environment, including the database. He'd been experimenting with an AI coding assistant, got confident with the rapid development speed, and made a destructive command. Here's the thing—AI is super confident, and if something doesn't work, one idea to get to its goal is to terminate your environment.

The recovery took a few days, and served as a stark reminder that while AI can accelerate development, it doesn't replace the fundamental need for proper development practices, staging environments, and human intervention (at least for now).

Even though I was able to build these projects with incredibly different timelines than before, that didn't mean that anyone could. The speed of AI-assisted development can mask the complexity of the decisions being made. When you can generate a working solution in minutes, it's easy to skip the critical thinking about whether it's the right solution. You still need to review the code, and know when something smells wrong.

The core process remains unchanged: understand requirements, build, gather feedback, and iterate. What's transformed is the speed and efficiency of execution, particularly in that crucial "build" phase, but the other phases remain important.

## Wearing Many Hats Just Got Easier

Throughout my career, I've always juggled multiple roles—product manager understanding user needs, project manager coordinating timelines, and as an engineer implementing solutions. This wasn't by deliberate choice; as a consultant working with startups and growing companies, wearing multiple hats was simply necessary. My business background has always driven me to approach solutions from a strategic perspective, focusing on what creates real value rather than just what's technically interesting.

What's fascinating is how AI code generation has shifted the balance of these responsibilities. The engineering portion, which used to consume about 90% of my time on a project, has become dramatically more efficient. I can now stand up complete SaaS applications in weeks instead of months, prototype business ideas in hours instead of days, implement complex features in days instead of weeks.

But here's the key insight: this efficiency gain doesn't make the other roles less important—it makes them more critical.

## Fast Code, Wrong Direction

The "build" phase is undeniably faster now. I can describe a component, API endpoint, or a database migration, and have working code in minutes. Features that would have taken me a full day to implement—like setting up user authentication, subscription billing, or admin dashboards for a SaaS product—can now be scaffolded and functioning in an hour.

However, this speed comes with a significant caveat: you must know what you're building and why. AI is incredibly powerful at execution, but it will enthusiastically code you into a corner if you're not providing clear direction.

I've watched AI dig deeper and deeper into architectural rabbit holes, creating increasingly complex solutions to problems that didn't need solving. Without experience to recognize these patterns, it's easy to end up with a codebase that works but is unmaintainable.

The key is finding the right balance on the spectrum of human involvement. On one extreme, you could write every line of code manually, gaining complete control but sacrificing the enormous efficiency gains AI offers. On the other extreme, you could create a completely autonomous coding agent, give it broad directives, and let it make all implementation decisions before pushing directly to production. Both approaches miss the sweet spot.

The optimal approach lies somewhere in the middle: leveraging AI for rapid implementation while maintaining human oversight of architectural decisions, code quality, and strategic direction. You want to be involved enough to catch problems early, but not so involved that you're micromanaging every function the AI writes.

## The Product Management Mindset

What I've discovered is that successful AI-assisted development requires thinking like a product manager creating requirements for a very capable but literal team member. Instead of thinking in terms of "how do I implement this function," I'm now crafting detailed product requirements to relay to my AI agent for accurate implementation.

The shift is fundamental: I'm no longer building the solution directly—I'm defining the problem and success criteria so clearly that the AI can build it correctly. The questions I ask now are:

- What exactly should this feature accomplish for the user?
- What are the specific acceptance criteria and edge cases?
- How should it behave in different scenarios?
- How does this integrate with existing functionality?

These detailed requirements aren't just helpful—they're essential. The more precise and comprehensive my "product brief" to the AI, the better the resulting code. I've learned that vague instructions lead to elegant solutions to the wrong problems, while clear requirements lead to exactly what I need.

## What This Means for Developers

For developers early in their careers, my advice is to focus on building solid engineering fundamentals alongside your product sense. You still need to recognize bad patterns when AI applies them, understand how to debug issues properly, and know when the code "smells" wrong. AI can generate code quickly, but you need the technical foundation to evaluate whether that code is maintainable, performant, and follows good practices.

For experienced developers, embrace the efficiency gains but double down on your strategic thinking. Use the time saved on implementation to better understand your users and market. To improve your efficiency, you must expand into more of a product perspective, or else your role might be not needed in the near future.

For organizations, recognize that while development speed has increased dramatically, the need for experienced technical leadership hasn't diminished—it's evolved into something more strategic and product-focused. This is especially critical for SaaS companies where rapid iteration and market validation are essential for success.

## Looking Forward

We're still in the early days of this transformation. AI tools will continue improving, and development will become even more efficient. But the fundamental skills of product thinking and strategic decision-making will only become more valuable.

This added efficiency creates new opportunities. When you can build SaaS products in days instead of weeks, the ROI calculation changes dramatically. Ideas that were previously too expensive or risky to pursue become viable. Prototypes that would have cost thousands can now be built for hundreds. This opens up entirely new categories of business models and makes validating SaaS concepts exponentially more affordable.

The future belongs to developers who can effectively orchestrate AI tools while maintaining a clear vision of what they're building and why. We're transitioning from being primarily implementers to being primarily strategists—and that's an exciting evolution.


Adam's Tech Blog

Automated Code Review with Claude Code Hooks

Building Bank Account Sync with Plaid

Replacing Onboarding Forms with an AI Conversational Agent

The Power of Plan Mode in Claude Code

Building Products with Specialized AI Agent Teams

The AI Coding Revolution Is Here