How to Repair a Codebase Degraded by AI

TL;DR

Repair a deteriorating codebase by finding shallow modules, defining clear seams, and consolidating related behavior behind simple interfaces. An AI architecture skill can inspect the repository for weak locality and low leverage, propose deeper module shapes, discuss design decisions with a human, and turn the agreed refactoring plan into an issue for later implementation.

Transcript

You've probably seen the thousands of LinkedIn CEO posts saying that code is cheap and they can move faster than ever before. But what's happening is that AI has simply accelerated software entropy. In other words, code bases are falling apart faster than they ever have before. Because every time that you make a change that doesn't take into accoun... Read More

Key Insights

• AI can accelerate software entropy when generated changes do not account for the entire codebase. Each locally plausible modification may introduce inconsistencies or awkward structures, and these small problems can accumulate until the system becomes a difficult-to-change ball of mud.
• A module is a coherent unit of application behavior, such as a collection of React components forming a page, functions responsible for authentication, or a logging facility. Well-structured modules communicate through interfaces rather than requiring callers to understand their internal implementation details.
• An interface is everything a caller must know to use a module correctly. It can include callable methods, such as sign-in and sign-out operations, as well as documentation or other usage expectations that determine how callers should interact with the module.
• A deep module hides substantial implementation behind a comparatively simple interface. Its depth reflects how much behavior callers can exercise for each unit of interface they must learn, giving users greater leverage while shielding them from internal complexity.
• A shallow module exposes a complicated interface while providing relatively little implementation behind it. Codebases containing many shallow modules tend to offer poor leverage because callers must learn excessive detail for a limited amount of useful behavior.
• A seam is the location where a module's interface exists within the application. Seams are important architectural decisions because they provide natural places for unit or integration testing, including the insertion of mocks that isolate one module from its dependencies.
• An adapter is a concrete module that satisfies an interface at a seam. A real clock and a fake clock can implement the same interface, allowing production code to use actual time while tests avoid waiting for real periods to pass.
• High locality keeps related changes, bugs, and fixes concentrated within one module, while high leverage provides substantial capability through a small interface. The architecture skill searches for refactoring candidates that can improve these two properties through deeper, better-defined modules.

Questions & Answers

Q: How can you repair a codebase degraded by AI changes?

Start by examining the architecture for shallow modules, scattered responsibilities, duplicated implementations, and concepts without a single tested seam. Select one high-value candidate, inspect the concrete code on every affected side, and design a deeper module with a simpler interface. Discuss unresolved design decisions before implementation, then capture the agreed module shape and refactoring work in a tracked issue.

Q: What is software entropy in an AI-assisted codebase?

Software entropy is the gradual deterioration that occurs when changes make a codebase harder to understand and modify. AI can accelerate it by producing changes that work locally without accounting for the whole system. Each change may add a small inconsistency or unusual structure, and those problems can compound until the codebase resembles a large, difficult-to-reverse ball of mud.

Q: What is a deep module in software architecture?

A deep module provides substantial behavior through a relatively simple interface. Callers only need to understand a small set of methods, documentation, and usage expectations while the module hides its internal complexity. This arrangement increases leverage because callers gain more capability per unit of interface knowledge, and it reduces the amount of implementation detail spread throughout the rest of the application.

Q: What is the difference between an interface and an implementation?

An interface contains everything a caller must know to use a module correctly, including exposed methods and relevant usage expectations or documentation. The implementation is the internal behavior that runs when those methods are called. For an authentication module, sign-in and sign-out methods may form part of the interface, while the logic behind those operations belongs to the implementation.

Q: Why are seams important when refactoring a codebase?

Seams identify the locations where module interfaces live and where one part of the application interacts with another. Choosing these locations carefully creates clearer architectural boundaries and natural points for unit or integration testing. A test can place a mock or fake adapter at a seam, allowing one module to be exercised without depending directly on the real implementation of another module.

Q: How do adapters make software easier to test?

Adapters provide concrete implementations of an interface located at a seam. Production code can use an adapter connected to a real dependency, while tests can substitute a controlled fake that satisfies the same interface. For example, an application can use a real clock normally and a fake clock during testing, avoiding the need to wait for actual time to pass.

Q: What do locality and leverage mean in module design?

Locality means that related behavior, changes, bugs, and fixes are concentrated in one place instead of being scattered across multiple modules. Leverage means that a caller receives substantial capability for the amount of interface it must learn. Deep modules improve both qualities by gathering related implementation details together and exposing them through a comparatively small, clear interface.

Q: How does the architecture improvement skill guide refactoring?

The skill begins by exploring the repository and identifying opportunities to deepen modules, improve locality, or increase leverage. After the user chooses a candidate, it examines the relevant code and starts a discussion about the proposed solution. It suggests a module shape, asks questions about design decisions, verifies implementation details, and can produce a plan suitable for conversion into an issue for later work.

Summary & Key Takeaways

• AI-assisted changes can accelerate software entropy when each modification ignores the wider codebase. Small inconsistencies accumulate until future changes become difficult. The proposed remedy begins with established software design fundamentals, especially identifying modules, separating interfaces from implementations, and finding opportunities to replace scattered or shallow abstractions with deeper modules.

• A deep module hides substantial implementation complexity behind a relatively simple interface, giving callers more capability for less knowledge. Good module boundaries also improve locality by keeping related changes, bugs, and fixes together. Seams define where modules interact, while adapters provide concrete implementations of the interfaces located at those seams.

• The architecture skill first explores a repository and identifies deepening opportunities involving weak locality, low leverage, duplicated implementations, or missing seams. The user then selects a candidate and discusses a proposed module shape with the AI. After design questions are resolved, the resulting plan can become a tracked issue for implementation by another agent.