Claude Code: refactor with a codebase architecture skill

Matt Pocock demonstrates his Improve Codebase Architecture skill in Claude Code as a way to plan refactoring with a coding assistant. He argues that AI can make code harder to maintain when individual changes ignore the wider application.

The tutorial explains deep modules: substantial behavior behind a small interface. Pocock distinguishes the interface from the implementation, then introduces seams where modules meet and adapters that satisfy those interfaces. A real clock and a fake clock for tests illustrate how adapters work. He frames the benefits as locality, where related changes stay together, and leverage, where callers get more capability with less interface to learn.

The practical example uses his course video manager, a React Router application that uses effect.ts. With auto mode disabled, Claude Code explores the repository and proposes six opportunities to deepen modules. Pocock selects duplicated insertion and ordering logic in the frontend and backend, then discusses a shared module and its TypeScript interface.

The demonstration reaches a proposed design rather than a completed refactor. Pocock explains that the plan can become a GitHub issue for an AI agent to implement later. He stresses that the skill requires programmer judgment and recommends tests around clear module boundaries before changing legacy code.