An AI product can have clean code and still be difficult to change safely. Behavior depends on model versions, prompts, retrieval, data, tools, policies, graders, and operator practices. If those dependencies are not versioned and tested, every release carries unknown regression risk.
Prompt and model debt
Unversioned prompts, undocumented provider settings, and model-specific workarounds create hidden coupling. Record behavior-changing configuration and maintain substitution evaluations.
Evaluation debt
A small static test set becomes stale as users and workflows change. Add production incidents, preserve critical slices, audit graders, and remove tests that no longer represent decisions.
Data and retrieval debt
Stale indexes, unclear source ownership, parser changes, permission drift, and weak deletion paths create quality and security risk. Operate retrieval as a data product.
Workflow and authority debt
Temporary manual reviews, broad credentials, unclear escalation, and unowned exceptions become permanent. Track them as product and operational debt with consequences and owners.
Track behavioral debt as a first-class liability
AI products accumulate stale prompts, undocumented evaluation gaps, brittle retrieval assumptions, provider-specific behavior, weak failure handling, and manual reviewer conventions. These may not appear in a code-quality tool, yet they make changes unsafe and outcomes hard to explain.
Record debt with an affected workflow, evidence, consequence, trigger, and remediation option. Separate deliberate tradeoffs from unknown weakness. A prompt that is simple but covered by strong tests may carry less debt than an elegant orchestration layer no one can evaluate.
Include data and operational debt: unclear source authority, unowned labels, missing deletion paths, incomplete traces, and review queues without capacity models.
Pay debt through the delivery cadence
Reserve capacity for evaluation coverage, dependency updates, incident follow-up, documentation, and simplification. Tie remediation to product changes that would otherwise amplify the exposure. Waiting for a separate cleanup quarter allows the debt to become architecture.
Use trend measures such as change lead time, regression escape, unexplained variance, manual exception rate, and time to reproduce a failure. The objective is not zero debt; it is keeping change understandable and reversible.
Executive decision record
The decision is which behavioral, data, platform, and code liabilities most threaten safe change and therefore deserve capacity now. Write that decision before selecting a model, vendor, framework, or implementation pattern. A written boundary keeps technical exploration connected to the operating outcome and makes it possible to explain why the organization advanced, revised, or stopped the work.
Approval should depend on debt records tied to workflow consequence, regression and incident trends, change lead time, exception burden, and remediation options. The evidence does not need to remove every uncertainty, but it should address the uncertainty capable of changing value, architecture, risk, or ownership. Record the baseline, assumptions, unresolved questions, and the person accepting the next stage.
Failure boundary and operating ownership
The central failure to guard against is tracking only code cleanliness while prompts, evaluations, retrieval assumptions, review conventions, and provider coupling become unmanageable. Treat that condition as a testable scenario. Define how the system detects it, what users experience, which action is prevented or reversed, and what evidence reaches the person responsible for recovery.
Long-term accountability sits with the product engineering team with explicit capacity and sponsor support to trade near-term features for sustainable change. Supporting specialists can provide platforms, research, review, or delivery capacity, but they cannot substitute for an owner who controls policy and operating change. Name that owner before production and include the ownership path in release evidence and incident procedure.
A practical 90-day application plan
During the first 30 days, convert debt records tied to workflow consequence, regression and incident trends, change lead time, exception burden, and remediation options into a bounded evidence plan. Assign each artifact to a named contributor, identify the representative inputs required, and agree on the comparison baseline before implementation expands. The objective of this period is to expose the assumption most likely to invalidate the work while the cost of changing direction is still low.
During days 31 through 60, build or instrument the smallest complete workflow that can support the decision about which behavioral, data, platform, and code liabilities most threaten safe change and therefore deserve capacity now. Include the real data and authorization path where feasible, record exceptions, and review difficult cases with the people who own the underlying process. Resist adding breadth until the team can explain the measured behavior of this narrow slice.
During days 61 through 90, test the boundary represented by tracking only code cleanliness while prompts, evaluations, retrieval assumptions, review conventions, and provider coupling become unmanageable. Exercise degraded dependencies, ambiguous inputs, recovery, and handoff rather than demonstrating only successful cases. End the period with a written advance, revise, or stop decision that cites evidence, residual exposure, expected operating cost, and the next authority boundary.
The review should be accepted by the product engineering team with explicit capacity and sponsor support to trade near-term features for sustainable change. That group should confirm not only that the system can work, but that ownership, support capacity, monitoring, and change control are credible. If those conditions are absent, the responsible outcome is another bounded learning stage rather than an unsupported production commitment.
Practical checklist
- Version prompts, models, and generation settings
- Maintain representative regression populations
- Track source and index lineage
- Audit tool scopes and human approvals
- Measure manual work and unresolved exceptions
- Assign debt by risk and operating consequence
- Fund reduction in the product roadmap
Continue reading
- [Production RAG architecture](/production-rag-architecture)
- [LLM evaluation framework](/llm-evaluation-framework-production)