The Codebase Your Successor Will Thank You For
The Codebase Your Successor Will Thank You For
Imagine inheriting a codebase. Not a bad one — it works. Orders process. Users authenticate. The test suite is passing and CI is green. But it was built over two years by two developers who used AI heavily and were always in a hurry, and the codebase reflects that.
There are no ADRs. There are no requirements files committed to the repo. The commit history is full of messages like "fix," "update," "changes," and "WIP — cleaning up." The PR descriptions say things like "guest checkout is done" and "refactored the order service." There is no business intent document. There is no implementation plan. The AI generated most of the code, and the decisions it made are visible in the output but not explained anywhere.
You need to add a new feature. Not a big one — just extend the guest checkout flow to support multi-address shipping. But you can't tell why the orders collection is structured the way it is, or what would break if you added a shippingAddresses array to the Order model, or whether there's a query somewhere that assumes a single address field. You don't know what was decided, why, or what constraints are load-bearing.
So you spend three days reading code before you write any.
This is the hidden cost of speed-first AI development. Not the initial feature. The fifth feature. The tenth feature. The new developer six months after the original team left.
The ANN SDLC is optimized for that person — not because they matter more than the original developer, but because the original developer becomes that person. Two months after shipping, you're the new engineer on your own codebase. You've forgotten what you decided and why. The ADR is the note you wrote to yourself before you forgot. The PR description is the explanation you gave yourself while you still understood it.
Speed-first development feels fast because the cost is paid later. The cost of building with no structured artifacts is paid in every debugging session, every new feature that has to reverse-engineer the previous one, every onboarding that takes three weeks instead of one. The cost is real. It's just deferred.
Step 10 is where the ANN SDLC closes the loop on all of it.
The checklist is short, but each item is a category of failure it prevents.
Health checks pass. The feature is live in production and the system is healthy. Not just CI green — production healthy. Metrics. Error rates. Response times. The definition of "healthy" was written in the business intent as "success looks like." If the system is healthy by the measures that mattered before the feature was built, it's healthy.
Business acceptance complete. The product owner or client confirms the feature matches what was asked for. This is not the same as "the acceptance criteria passed." Acceptance criteria are engineering artifacts — they describe the feature in technical terms. Business acceptance is the human answer to "is this what you wanted?" Sometimes those align perfectly. Sometimes the client sees the feature and realizes they described it wrong. Better to find this out at Step 10 than from a support ticket.
Documentation synced. Any user-facing documentation that references or is affected by this feature is updated. Any internal documentation that references the old behavior is updated. The change log is updated. The ADR is amended if the implementation deviated from it in any meaningful way. The living documentation reflects what was actually built.
Process metrics recorded. How long did this feature take from business intent to ship? How many gate failures? How many rework cycles? Which gate caught the most issues? These numbers are not for performance reviews — they're for process improvement. For guest checkout, the team records: eight days total, two gate failures at Gate 2 (the button and the missing GDPR handler), zero Gate 3 blocks. Over twenty features, this log shows exactly where time is consistently lost. A team that doesn't record it is always guessing whether the process is improving.
The ADR amendment at Step 10 is the most commonly skipped item, and the most important one.
Not every feature touches an existing ADR. But when it does — when the implementation reveals something the ADR didn't anticipate, or when the gate reviews identified a consequence the original decision didn't foresee — the ADR needs to be updated before the feature is considered done.
For guest checkout, Step 10 surfaces a consequence that ADR-012 didn't document: when a guest creates an account post-purchase, the order attachment query needs special handling for the case where the guest email matches multiple prior guest orders. This is the edge case that appeared in the bug report six months later in the opening scenario.
At Step 10, before anyone has forgotten the feature, the ADR gets an amendment:
ADR-012: Guest orders stored in unified orders collection
[Amendment — post-ship, added at Step 10]
Additional consequence identified during Step 10 review:
When a guest creates a post-purchase account and their email matches
multiple prior guest orders, the order attachment query must handle
the multi-match case explicitly. See REQ-CHECKOUT-00020 for the
post-purchase account creation specification. The attachment logic
must run as a transaction to prevent partial attachment.
That amendment is available to the engineer who inherits the codebase. They find it while reading the ADR before building the multi-address shipping extension. They understand immediately why the attachment query works the way it does. They don't repeat the edge case. The three-day reverse-engineering exercise doesn't happen.
The codebase built with the ANN SDLC looks different from the outside.
Every significant decision has an ADR. Every feature has requirements committed to the repo, with acceptance criteria that describe the feature in terms a human can verify. Every PR description traces back to the plan that governed the implementation. Every commit references the requirements and ADRs that drove it. The ADRs have amendment trails that record what was discovered post-ship.
This doesn't make the code more complicated. The code is simpler, because every decision was made once, by a human, and the AI was given the decision as a constraint rather than being left to decide on its own. The code is also more maintainable, because the reasoning is visible alongside the implementation — in the same repository, in the same commit history, permanently available to anyone who reads it.
The new developer joins the team. They spend their first week reading ADRs and requirements. By day five, they understand why the orders collection is structured the way it is, what alternatives were rejected, and what constraints govern every query that touches it. They start contributing in week two.
The engineer assigned to the bug opens git log. They read the commit. They find the ADR. They understand the constraint. The fix takes two hours.
The client asks for multi-address shipping. The developer reads ADR-012 and finds the amendment. They know exactly what to change and what to leave alone. The impact analysis takes one day, not three.
The AI is a capable builder. It generates correct code at speed when given the right constraints. The failure isn't the AI — the failure is what happens when the AI works without structure, makes the decisions humans didn't make, and leaves no record of why the output looks the way it does.
The ANN SDLC is the structure. Ten steps, four phases, three gates. Business intent before requirements. Requirements before ADRs. ADRs before plans. Plans before generation. Human verification before commit. Gate review before merge. Health checks before close. Each step exists because something goes wrong when it's skipped.
The codebase your successor will thank you for isn't the one with the fewest bugs. It's the one where every decision left a trace — where the reasoning is as permanent as the code, and the next person who has to change something can understand not just what was built, but why it was built the way it was.
That's the codebase the ANN SDLC builds. Not faster than working without structure — faster than working without structure and then spending three days every time something needs to change.
The full process is documented at anntech.dev/docs/ai-sdlc.