I Cleaned Up My Messy Code… It Got Worse

Key Concepts

• Agentic Coding: A development methodology where AI agents are used to perform tasks, refactor code, and manage tool execution.
• Monorepo Architecture: A single repository containing multiple projects (CLI, server, shared packages) that requires careful wiring to avoid code duplication.
• Registry Pattern: A centralized design pattern used to manage tool definitions, schemas, and runtimes, ensuring a single source of truth.
• Compile-Time Safety: Using TypeScript features (like satisfies and explicit type maps) to ensure that missing or incomplete tool implementations trigger errors during development rather than at runtime.
• Code Smell: Indicators in the codebase (e.g., excessive any types, ad-hoc casting, scattered wiring) that suggest poor architectural design.
• Vibe Coding vs. Engineering: The distinction between blindly accepting AI-generated code ("vibe coding") and actively guiding the AI to build maintainable, deterministic, and modular systems.

1. The Problem: Architectural Debt

The instructor identifies a critical issue in their monorepo: tool-calling logic is scattered across three distinct areas (the tools package, the server agent, and the CLI chat screen).

• The Pain Point: Adding or renaming a single tool requires manual updates in three to four files across three packages.
• The Risk: Because the wiring is not centralized or strictly typed, it is easy to leave a tool "half-finished" without the IDE throwing a compile-time error.
• The Goal: Consolidate all AI-related logic (tools, chat hooks, system prompts, and agent construction) into a single packages/AI directory.

2. Methodology: Iterative Refactoring with AI

The instructor demonstrates a step-by-step process for refactoring, emphasizing that the goal is not to follow the exact steps, but to recognize the patterns of "bad" architecture.

• Step 1: Planning: Use the AI agent in "Plan Mode" to map out the current state versus the desired state.
• Step 2: Registry Consolidation: Move all tool definitions, schemas, and runtimes into the packages/AI directory.
• Step 3: Type Safety Enforcement: Replace "magical" schema-derived types (which were overly complex) with an explicit internal type map.
• Step 4: Compile-Time Validation: Use TypeScript’s satisfies operator to ensure that if a developer adds a new tool but forgets to register it in the client or server, the IDE reports an error.

3. Key Arguments and Perspectives

• On AI Models: The instructor notes that different models have different strengths. Claude Opus 4.7 is praised for its ease of communication, while GPT-5.4 is highlighted for its superior ability to handle strict, complex type systems.
• On "Minimal Change" Constraints: The instructor admits that forcing the AI to make "minimal changes" can sometimes lead to more complex, "hacky" code. Relaxing this constraint to allow for a more explicit, readable structure is often a better trade-off.
• On Determinism: A core argument is that developers must impose determinism on non-deterministic AI tools. By creating a rigid, explicit registry, the developer ensures the AI cannot create "spaghetti code."

4. Real-World Application: Debugging the "Queued" Bug

During the refactor, the instructor encountered a bug where tool calls remained in a "queued" state.

• The Cause: The refactor introduced an await on submitToolOutput within the client-side tool handler. Because the AI SDK’s onToolCall is blocking, awaiting the output created a deadlock (the UI was waiting for the tool to finish, but the tool was waiting for the UI to process the queue).
• The Fix: Removing the await on the tool output submission resolved the deadlock, demonstrating the importance of testing even when the code "looks" correct.

5. Notable Quotes

• "I want to show you the reality of coding... I want to show you 1 hour of pure refactoring using agentic coding."
• "The simpler the architecture is, the sooner will an LLM understand it."
• "This is you can see how drastically different this is from vibe coding... I can guarantee you not a single vibe coder is spending this much time brainstorming architecture."

6. Synthesis and Conclusion

The module concludes that successful agentic coding requires the developer to act as an architect, not just a prompter. By consolidating tool wiring into a single package and enforcing strict compile-time contracts, the instructor transformed a fragile, scattered codebase into a modular, maintainable system. The key takeaway is that AI is an amplifier of skill; when guided by clear architectural principles and a willingness to backtrack and refactor, it can produce high-quality, professional-grade software.