Cognitive Debt: Keeping Your Codebase Understandable in the Age of AI


Greetings, traveler!

An iOS team ships a new account screen. The feature builds, the tests pass, and the initial release goes smoothly. An AI agent wrote most of the implementation, including the data-loading pipeline and its tests. The pull request was reviewed and approved.

A month later, customers report that their account details occasionally revert to older values. The engineer on call finds several layers between the screen and the network client: a coordinator, a generic pipeline, a cache policy resolver, and a set of error adapters. Each layer has a reasonable name. None makes it obvious which response is allowed to update the screen.

The team can ask an agent to investigate. Before accepting its proposed fix, someone still needs to determine whether the explanation matches the code and whether the fix preserves the intended behavior. That takes longer when the people responsible for the feature do not have a reliable picture of how it works.

The account screen is a hypothetical example, but the review and verification techniques apply to existing projects.

What cognitive debt looks like

Cognitive debt is a useful name for the future effort created when a team does not understand enough about the software it owns. That effort shows up when someone needs to change a behavior, diagnose an incident, review a security fix, or explain why a constraint exists.

The related term knowledge debt often describes the missing knowledge itself. The terms overlap, and teams do not need a strict distinction to use them. For this article, the focus is practical: what does the team need to reconstruct before it can safely act?

Technical debt and cognitive debt can reinforce each other. An overly generic caching layer is a design problem if it makes a change harder than necessary. If nobody knows which screens rely on its invalidation rules, there is also a knowledge problem. A straightforward implementation can have a knowledge gap too: a short function that encodes an undocumented financial rule may be easy to read and still difficult to change safely.

Neither kind of debt is unique to AI. Teams have always inherited code from former colleagues, rushed releases, and relied on undocumented decisions. AI changes the economics: a small team can produce and integrate changes faster than it can absorb them. When that happens, the gap between the code that exists and the behavior the team can explain may widen.

Passing tests are a starting point

A successful build tells us that the selected code compiled under a particular configuration. A passing test suite tells us that the executed checks passed. Both are valuable, and neither establishes that the suite covers every meaningful scenario.

Consider the account screen. Its tests may cover a successful request and a server error. They may also use a mock that returns immediately. That does not exercise two overlapping refreshes where an older request finishes last. A test can accurately verify its assertions while leaving that ordering untested.

Generated tests deserve the same scrutiny as generated implementation. If both encode the same mistaken assumption, they can agree with each other and still miss the requirement. Review the behavior the tests describe: what is controlled, which result is expected, and which cases remain outside the test. If an existing test disappears or its assertion becomes weaker, understand why before treating a green result as evidence of improvement.

Treat an agent’s explanation as a starting point. Ask it to identify the relevant call sites and tests, then check its claims against the code and observable behavior.

Follow one request through the system

Suppose the existing feature has this conceptual path:

Account screen
  → AccountViewModel
  → RefreshCoordinator
  → RequestPipeline
  → CachePolicyResolver
  → AccountRepository
  → API client

The names are illustrative. A real implementation may have good reasons for several of these boundaries: a shared cache, a reusable transport layer, or a compatibility boundary between modules. The audit begins by finding out what each layer actually contributes.

Choose one user action, such as pulling to refresh, and trace it to the visible result. For the account screen, record answers to these questions:

  • Where is the refresh task started, and who owns its lifetime?
  • Can two refreshes overlap? If they can, which result should appear?
  • Which object decides whether cached data is used?
  • Where is the screen state changed, and what isolation protects that state?
  • Which failures reach the user, and which are logged or ignored?
  • What happens when the screen disappears or the user signs out?

A call graph helps find the path, but it does not answer all of these questions. A task can outlive the call that created it, and a callback can re-enter through another object. Follow asynchronous work, cancellation, and state ownership as well as direct method calls.

When using an agent for discovery, give it a bounded assignment:

Trace the pull-to-refresh flow for AccountView.
Identify where tasks are created, how overlapping requests are handled,
and where the visible account state is updated.
Cite file paths and symbols for each claim. List anything you cannot verify.
Do not modify files.

Then inspect the cited code. If the agent says a request is cancelled on sign-out, find the cancellation and check whether the network operation and any later state update actually observe it. Use its output to navigate; keep uncertainty visible where the code or tests do not settle the question.

Simplify a boundary while preserving behavior

Imagine the audit reveals that RefreshCoordinator and RequestPipeline exist only for this screen. Their main job is to forward a request to AccountRepository; neither provides an independent policy. They are candidates for removal, subject to checking other call sites and contracts.

Before changing them, agree on the expected behavior. For this example, the product decision is that the most recently started refresh determines the visible result. A failed current refresh leaves existing account data visible and reports an error. A result from an older refresh must not replace it.

One possible implementation puts that rule close to the state it protects:

@MainActor
final class AccountViewModel: ObservableObject {
    @Published private(set) var account: Account?
    @Published private(set) var errorMessage: String?

    private let repository: AccountRepository
    private var refreshID = UUID()

    init(repository: AccountRepository) {
        self.repository = repository
    }

    func refresh() async {
        guard !Task.isCancelled else { return }

        let requestID = UUID()
        refreshID = requestID
        errorMessage = nil

        do {
            let updatedAccount = try await repository.fetchAccount()
            guard requestID == refreshID, !Task.isCancelled else { return }
            account = updatedAccount
        } catch is CancellationError {
            return
        } catch {
            guard requestID == refreshID, !Task.isCancelled else { return }
            errorMessage = "Could not refresh the account."
        }
    }

    func invalidateRefresh() {
        refreshID = UUID()
    }
}

This sketch assumes Account and AccountRepository are existing types and that fetchAccount() has isolation and concurrency guarantees appropriate for the project’s Swift settings. The identifier prevents an earlier invocation from applying its result after a newer one has begun executing on the main actor. It does not cancel the earlier network request.

The example uses a latest-started policy: if B starts after A and B is then cancelled, A remains obsolete. The previous account stays visible until another refresh succeeds. An invocation that is already cancelled at the first check returns without invalidating A. A cancellation arriving after that check is cooperative; Task.isCancelled can change immediately after any check. The code handles CancellationError separately, while other errors from a cancelled task are ignored when cancellation is observed. A repository that represents cancellation with another error needs an explicit, documented mapping.

When a lifecycle event must prevent an in-flight response from updating the screen, the owner calls invalidateRefresh() on the main actor, for example when signing out or changing accounts. The owner must also cancel any task it controls if it wants to request that the underlying work stop. Invalidation and the final state update are serialized on the main actor: a response cannot commit after invalidation has executed. A response committed before invalidation is not undone; clearing account state on sign-out is a separate responsibility. Merely cancelling a task does not provide that ordering guarantee.

After confirming that the two forwarding layers have no other callers or side effects, the hypothetical team can remove them. The path becomes AccountViewModel → AccountRepository → API client. The latest-started rule lives beside the visible state, while any real cache policy remains with its existing owner. A reviewer can now trace one flow, inspect the ordering check, and find its tests without following two forwarding types. Compare that trace before and after the change; do not treat the number of deleted files as proof of improved maintainability.

Before removing a real layer, check its consumers, analytics, retry behavior, and module contracts. Preserve any required policy and verify it independently.

Verify the behavior you intend to preserve

For the hypothetical refresh change, start with tests at the boundary where the behavior matters: the view model’s visible state. A controllable repository can suspend individual requests until the test releases them. That lets the test choose completion order without relying on arbitrary delays.

A useful set of checks would cover:

  1. A successful current request updates the account.
  2. A failed current request keeps the previous account and exposes an error.
  3. Request A starts, request B starts, B completes, then A completes. The screen still shows B.
  4. A task cancelled before it starts does not replace the active request identifier or clear the error.
  5. If B starts after A and B is cancelled, A cannot update the account. A later refresh can succeed.
  6. A repository CancellationError and an observed task cancellation do not produce a generic error.
  7. Invalidation runs before a suspended request resumes; its result cannot update the account. Separately verify the project’s sign-out and account-switch behavior.

Write the ordering test before the refactor when feasible. If it fails against the old implementation, investigate whether that is a defect or an undocumented behavior the product actually expects. A characterization test can preserve what the old code does, but it cannot decide what it should do.

Run the relevant tests and build against the final changes. Record the command, configuration, result, and any checks that were not run. If the screen’s loading or error presentation changed, inspect it in the simulator as well. Unit tests for state transitions do not establish that a user can see or understand the resulting interface.

A refactor can reduce the effort required to trace a flow without proving that every regression has been eliminated. Keep the scope small enough to review, and preserve the evidence needed to revisit the decision later.

Choose where understanding matters most

No engineer can keep an entire application in working memory. A team needs to decide where deeper understanding is worth the time, and where it is sufficient to know the interface and whom to ask.

Give more attention to code whose failure has serious consequences, whose behavior crosses many boundaries, or whose recovery is difficult. In a mobile application, that might include authentication, payment state, data migration, synchronization, or the handling of sensitive information. A frequently changed navigation component can also deserve attention because many features depend on it.

Depth of understanding can vary. A developer using a stable image-loading library may only need to know its integration contract and failure behavior. The team responsible for account synchronization should be able to explain conflict handling, data ownership, and recovery from a partial failure. For critical areas, distribute that understanding across more than one person when team size permits.

Abstraction is not inherently a source of debt. A clear boundary can hide implementation details and reduce the amount a caller must know. It earns its place when its contract is meaningful, its ownership is clear, and the complexity it hides remains manageable. Be wary of abstractions that introduce configuration, generic types, or indirection without a current use that justifies their cost. Equally, do not remove validation or error handling merely because it makes the code longer. Check the input boundary and the consequences of failure first.

Use review to build shared understanding

A code review is an opportunity to transfer knowledge while the change is still fresh. For a significant AI-assisted change, the author should be able to describe the behavior being introduced, the main design choice, and the checks performed. They can use an agent to prepare that explanation, but they need to verify it before presenting it as their own understanding.

Reviewers can ask concrete questions that expose assumptions:

  • Which existing behavior could this change affect?
  • Why does this boundary exist, and who else uses it?
  • What happens if this operation finishes twice or finishes after the user leaves?
  • Which test would fail if the central requirement stopped holding?
  • What would someone inspect first if this failed in production?

Not every pull request needs a walkthrough. For a critical or unfamiliar change, tracing one representative flow together can reveal more than a long list of generic comments. Limit the size of changes when possible so reviewers have enough context and attention to examine them. If a large migration cannot be split into independently deployable pieces, still consider reviewable stages with explicit dependencies.

Automated review can surface potential defects and suggest questions. Its output needs assessment against the actual requirements and codebase. Reject a suggested abstraction if it solves no present problem; investigate a suspected race if the reported execution path is plausible. Treat both acceptance and rejection as engineering decisions, not a vote on whether the suggestion sounds sophisticated.

Keep decisions close to the work

Documentation helps when it captures information that is expensive to recover from the implementation. For a critical flow, a short note in the repository might contain:

Account refresh

Entry point: AccountViewModel.refresh()
Visible state owner: AccountViewModel, isolated to MainActor
Ordering: the latest started refresh may update visible state
Failure: retain existing data and show a refresh error
Cancellation: caller owns task cancellation; lifecycle owner invalidates pending results
Relevant tests: AccountViewModelRefreshTests
Open question: confirm behavior when the active account changes

This is an example of a working note, not evidence that those files or tests exist in your project. Link the actual symbols, tests, and decisions in your own repository. If a statement remains uncertain, mark it as an open question instead of turning a guess into documentation.

Keep the note short enough to update during a related change. Review it when the contract changes and assign ownership for resolving open questions. A generated description can provide a first draft, but it should be checked against the code and maintained by the team. Stale documentation can send an incident investigation in the wrong direction.

Practice an incident without depending on one tool

A useful way to assess operational understanding is to rehearse a plausible failure. For the account screen, imagine a report that values changed back after the user refreshed twice. Give the team the symptom and access to its usual repository, logs, test tools, and runbooks. Ask how it would narrow down the cause, contain customer impact, and verify a fix.

For part of the exercise, assume the AI service is unavailable. This is not a test of whether someone remembers every symbol. Engineers can search the code, read documentation, consult a colleague, and use ordinary debugging tools. The exercise checks whether the team has enough information and access to move forward when one aid is missing.

A reasonable investigation might start with the refresh entry point, correlate timestamps in available logs, reproduce overlapping responses in a controlled test, and inspect the code that updates the view model. If logs do not distinguish requests, that is a useful finding. Add suitable observability only after considering privacy and the project’s logging policy; account data or credentials should not be included merely to make a rehearsal easier.

The exercise may end with an unresolved question rather than a fix. Record what was missing: a reproducible scenario, access to logs, an owner, or an explanation of a state transition. Assign follow-up work based on the potential impact and likelihood of needing that knowledge.

Notice the debt before an incident

Cognitive debt cannot be measured precisely with a single score. Teams can still look for signals during normal work:

  • A reviewer cannot trace the main behavior without asking the agent to explain every layer.
  • Different engineers give conflicting answers about an important rule.
  • A change repeatedly requires rediscovering the same dependency or undocumented decision.
  • Only one person can safely modify a critical component.
  • An incident requires extensive reconstruction before anyone can identify a safe mitigation.
  • Tests cover methods in isolation, but the team cannot identify which user behavior they protect.

These are prompts for investigation, not automatic proof of poor code or an individual performance problem. A complex domain may be difficult because the underlying rules are difficult. A new team member will naturally need time to learn. Consider whether the team can recover and share the necessary knowledge at a cost proportionate to the risk.

Teams can track a few practical observations over time: how long a realistic investigation takes, whether another engineer can locate the relevant behavior, how often important documentation is found to be wrong, and whether a critical component has an available backup owner. These are contextual signals. They can be distorted by task difficulty, staffing, and reporting habits, so use them to guide discussion rather than rank individuals.

Make room for understanding

Every safeguard has a cost. Detailed documentation can become stale. Extra reviewers can slow delivery. A broad cleanup can introduce regressions into stable code. Even an incident exercise takes time away from feature work. Match the investment to the component’s risk and the team’s actual ability to maintain the practice.

Start with one area that the team changes often or would struggle to recover during an incident. Trace a representative flow, identify the behavior that must hold, and check whether the existing tests demonstrate it. If a layer adds useful protection, document its contract. If it adds indirection without a clear responsibility, consider a small, verified simplification.

AI can help throughout that work: it can locate callers, summarize competing explanations, draft tests, and identify questions for review. The team retains the responsibility to check those outputs and decide what knowledge needs to remain accessible. The goal is a codebase that the people on call can change and repair, whether or not the tool that helped create it is available.