Website of Peter Westerman

Technical debt is not a sign of failure. It is the price of making speed-quality trade-offs. Those trade-offs are frequently the right call: getting to market faster, testing a hypothesis before over-investing in a perfect implementation, building something useful now rather than building something perfect later. The problem is not incurring technical debt — it is incurring it without a management plan, so that it accumulates unobserved until it breaks the practice.

Vibe coding generates technical debt faster than traditional development because it is optimized for velocity. Understanding this, naming it, and managing it explicitly is what makes vibe coding sustainable over years rather than impressive for twelve months and then unsustainable. This post is about the practical mechanics of that management.

What Technical Debt Looks Like in This Portfolio

Technical debt in the portfolio manifested in four specific and recurring patterns, each with different costs and different mitigations.

Inconsistent implementations: The same logical operation — making an API call, handling a form submission, querying the database — done slightly differently in different products. Not wrong in any individual case, but inconsistent in ways that make the codebase opaque to anyone who did not write each specific product’s code. The AI cannot infer from one product’s pattern how a different product handles the same operation, because the patterns differ in the details. This inconsistency cost is primarily a maintenance and debugging tax that grows with portfolio size.

Missing edge case handling: AI-generated code handles the happy path reliably. It handles the most common error cases when they are specified. It handles unusual edge cases only when those cases are explicitly included in the requirements brief. Fast-moving build cycles, where the focus is on the happy-path user scenarios, leave edge cases as untested paths through the code. They accumulate as unknown risks rather than known technical debt — failures that have not happened yet rather than failures that have been anticipated and handled.

Undocumented architectural decisions: Why is this database table structured with this specific schema? Why is this component a singleton when other similar components are not? Why does this API integration use this authentication approach rather than the more standard one? The code contains the decisions. Only the documentation contains the reasoning. When the documentation is sparse, the reasoning is lost. Future sessions — and future maintainers — must either infer the reasoning from context or risk reversing decisions that had good reasons behind them.

Dependency drift: External libraries, API versions, and platform compatibility targets that were current when a product was built and have since become outdated. In a twenty-product portfolio, each product with its own dependency profile, keeping everything current without a systematic approach is a real and growing operational burden.

The Debt Register

The most effective debt management tool is a visible register of known debt items. Not a complex system — a section in each product’s documentation listing things that are known to be imperfect, the trade-off that was made, and what the correct solution would be when time and priority allow.

The visible register serves three purposes. It moves debt from unconscious to conscious: known, named, documented debt is manageable because its scope and cost are defined. Unknown debt accumulates unobserved until it causes a production problem with no warning. It provides AI session context: “Here are the known debt items in this product; please work around them rather than extending them.” Without this guidance, an AI session building new features on top of known debt will extend the debt rather than contain it. And it provides a prioritized backlog for consolidation sessions — time specifically allocated to debt reduction rather than feature development.

A debt register entry requires only three elements: what the debt item is, what trade-off was made when it was incurred, and what the correct solution would be. One sentence each. Fifteen minutes to write initially. Updated when new debt is knowingly incurred.

Consolidation Sessions as a Standing Rhythm

The practice that most reliably prevented debt from compounding into a velocity drag: periodic consolidation sessions — sessions specifically focused on debt reduction rather than new feature development, on a standing schedule rather than triggered only by visible problems.

A consolidation session addresses items on the debt register, migrates product-specific implementations to the Shared Library, updates stale context files, improves error handling in high-traffic code paths, and updates dependencies that have drifted. It is maintenance work, not production work. It does not produce features. It maintains the conditions that make future feature production fast and reliable.

The cadence that worked across the portfolio: roughly one consolidation session for every four to five feature build sessions. Not a fixed schedule — a frequency calibrated to keep the debt register from growing. If it is growing across multiple products simultaneously, consolidation frequency is too low. If the register is consistently empty, it is likely not being populated honestly or consolidation frequency is excessive. The goal is a register that is visible, current, and shrinking on a reasonable timeline.

The Refactoring Trap

When significant debt has accumulated, the temptation is comprehensive refactoring: redesign the database schema, restructure the class hierarchy, normalize all the inconsistent implementations in one large session. This is almost always the wrong approach.

Large refactoring sessions produce large surface areas of change that need thorough testing before deployment. The AI generates the code changes quickly — that part compresses. The testing does not. A session that rewrites three major components in two hours requires testing those three components across all scenarios they participate in before the refactoring can be deployed safely. That testing often takes longer than the refactoring itself, and during that period the product is in a partially-refactored state with elevated regression risk.

Targeted, incremental debt reduction produces better outcomes: address one debt item at a time, test the targeted change, confirm no regressions before proceeding to the next item. Each individual change is small enough that the testing scope is bounded. The debt register shrinks steadily rather than through a single high-risk operation. The codebase remains deployable throughout rather than being frozen while a large refactoring is validated.

Documentation as Debt Prevention

The cheapest form of debt management is documentation maintained in real time. An architectural decision documented at the time it is made costs thirty seconds. The same decision reconstructed from code three months later costs fifteen minutes — if it can be reconstructed accurately at all. Decisions that cannot be reconstructed become recurring sources of inconsistency, as future sessions make different choices without access to the reasoning that motivated the original decision.

The context file update discipline — five minutes at the end of every session, capturing the decisions made in that session — is debt prevention rather than documentation overhead. The code captures what was built. The context file captures why it was built that way. Both are necessary for intelligent maintenance of a codebase over time. The code is a record of decisions; the documentation is a record of reasoning. Reasoning without code is speculation. Code without reasoning is archaeology. The combination is a maintainable, understandable system.

The Sustainable Practice Defined

Vibe coding at full speed, with no debt management discipline, produces impressive results for six to eighteen months before hitting a wall. The codebase becomes too inconsistent to extend reliably. Context files too stale to be useful. The maintenance burden of accumulated debt exceeds the capacity to address it while continuing to build new products. Velocity drops as each session must first reconstruct the context that systematic maintenance would have preserved.

Vibe coding with appropriate discipline — the four quality gates, the debt register, the consolidation sessions, the context file maintenance — is sustainable over years. The velocity remains high because the infrastructure is maintained. The debt remains manageable because it is addressed regularly. The codebase remains coherent because conventions are documented and followed. The overhead of this discipline is real — approximately twenty to twenty-five percent of total session time. The return is a practice that works at scale and over time, not just in the first year of enthusiasm.

The Consolidation Session Agenda

A specific, practical consolidation session agenda that worked consistently across the portfolio:

First fifteen minutes: review the debt register for each active product. Identify the three to five highest-priority items based on a combination of maintenance cost (how often is this debt causing extra work?) and risk (how likely is this debt to produce a production failure?). Select the one or two items to address in this session.

Next forty-five to sixty minutes: address the selected debt items. For each: open the product, load the context file, describe the debt item to the AI with the context of why it exists and what the correct solution is, build the fix, test it against the primary user scenarios affected by the change, update the debt register to reflect the resolution, update the context file to reflect any architectural change the resolution involved.

Final fifteen minutes: identify any new debt incurred since the last consolidation session and add it to the relevant product’s debt register. Update any context files that have become stale since the last update. Identify the objective for the next session — whether feature development or another consolidation.

This agenda takes approximately ninety minutes. It keeps the debt register current and shrinking. It keeps context files accurate. It prevents the silent accumulation of debt that would eventually require a large, disruptive consolidation effort rather than consistent small ones.

When to Accept Debt Deliberately

Not all technical debt is incurred accidentally. Sometimes the right decision is to accept known debt deliberately — to choose a faster, imperfect implementation now with explicit acknowledgment that the better solution will be implemented later. This deliberate debt incurrence is acceptable and sometimes correct; what makes it acceptable is the explicitness and the plan.

The pattern that works: when choosing a faster implementation over a better one, immediately add the debt item to the product’s debt register with the correct solution described. “Using WordPress transients for caching here rather than a proper object cache because the object cache setup would take an additional session. This will not scale beyond approximately 1000 concurrent users. The correct solution is to migrate to Redis object cache when traffic approaches that level.” One entry. Takes three minutes. Makes the debt visible, bounded, and actionable when the time comes.

Debt that is incurred deliberately and documented immediately is managed debt. Debt that accumulates through a hundred small shortcuts that were never documented is unmanaged debt. The difference between them, measured in maintenance overhead and debugging time over a twelve-month period, is substantial. Deliberate debt is a tool. Unmanaged debt is a liability.

How Recent AI Innovations Change This Picture

Technical debt management in AI-generated codebases involves the same challenges as in human-written codebases, with some additional dynamics specific to how AI generates and modifies code. Recent innovations change both the accumulation rate and the remediation tools available.

Checkpoints are the most directly relevant new tool for technical debt management. In the methodology described here, the discipline against taking shortcuts was partly enforced by the knowledge that undoing shortcuts was expensive — you had to manually reverse the work rather than revert to a previous state. Checkpoints change this economics: you can checkpoint before a hacky quick fix, try the fix, verify it works, and then either accept the technical debt or roll back and take the time to do it right. The reversibility of decisions reduces the cost of trying the right way first.

The 1-million-token context window changes how debt can be analyzed. Comprehensive technical debt assessment previously required multiple focused sessions — looking at one module at a time, identifying issues, compiling findings across sessions. With a context window large enough to hold the entire codebase, a single “technical debt audit” session can review the full codebase simultaneously, producing a consistent, prioritized debt register rather than a piecemeal picture assembled across multiple sessions.

Extended thinking changes the quality of refactoring plans. The technical debt remediation plans described in this post required careful human judgment about sequencing — what to fix first, how to avoid breaking dependencies, how to migrate incrementally. Extended thinking lets Claude reason through refactoring sequences systematically before producing a plan. The human still validates and directs the plan, but starts from a more thoroughly reasoned baseline, which reduces the iteration required to arrive at a sequencing that avoids hidden dependency problems.