Handing Over an AI-Built Codebase

Handover is on Thursday and there are files in this repository you have never opened. They work, the tests pass, the client is happy with the demo, and in a fortnight every one of those files becomes somebody else's problem with your name attached.

That is the specific hazard of agent-built work. You understand the code less deeply than if you had typed it, the gap is invisible while you are shipping, and handover is the moment it becomes visible to other people.

The audit you owe yourself

Read every file you have not read. All of them. On a project this size that is an afternoon, and it is the cheapest afternoon of the engagement. You are looking for four things.

Dead code. Modules nothing imports, exported helpers nothing calls, a second implementation of something you already had. npx knip or ts-prune finds most of it; grep the symbol before you pull the trigger.

Abandoned half-implementations. The agent's signature artefact, and worse than dead code because they look alive. A retryWithBackoff that is defined, tested, and never called.

Stray secrets and placeholders. A real key in .env.example. const ADMIN_EMAIL = "test@example.com". // TODO: validate this properly above the one input that reaches the database. Check the git history, not just the working tree.

Dependencies you did not choose. Agents reach for a library the way you reach for a keyboard shortcut. A full date library imported for one format string, a utility package for a single groupBy, two HTTP clients because two sessions made two decisions. Each is a maintenance obligation you handed over without discussing it.

Deleting is the highest-value task

An AI-built codebase has more surface area than it needs, and the reason is structural rather than careless. Ask for a function and you get the function, a wrapper, an options interface, a types file, and tests for the wrapper. Every generation is locally reasonable. Nothing in the process ever removes anything.

Surface area is what the next developer pays for. Leave a utils/ directory exporting forty things of which nine are used and you have handed over thirty-one traps.

So: if I cannot say where a thing is used, it either gets a one-line comment explaining why it exists or it goes.

Documentation somebody will actually read

Three documents. No more, because a fourth will not be read and its staleness will discredit the other three.

A README that gets a new developer from clone to running in under fifteen minutes. Prerequisites with versions, the exact commands in order, what the seed data contains, the login for the development admin account. Test it in a fresh directory, not in the repo where things work because of state on your machine.

An architecture note that explains decisions rather than restating the code. They need to know why sessions live in Redis rather than a JWT, and why there is no queue — volume is two hundred bookings a day and a minutely cron was sufficient.

A runbook: deploy, roll back, where the logs are, how to rotate a key, what to do when the nightly job fails. This is the document that decides whether they ring you at nine on a Sunday.

docs/
  README.md          # clone to running in under fifteen minutes
  architecture.md    # why it is shaped this way
  runbook.md         # deploy, rollback, incidents, contacts

Hand over the agent configuration too

Your project rules file, your hooks, your scripts. These are part of the deliverable. Whoever maintains this will almost certainly use agents, and forty lines telling their agent that migrations are generated and never hand-edited is worth more than another page of architecture prose.

Strip your own setup out first. Machine paths, API keys, MCP servers pointing at your accounts, hooks that fire your notification script, references to other clients' repositories. And read the prose — you may have written something impatient about their legacy system at one in the morning.

Licences and provenance, handled plainly

Run pnpm licenses list or npx license-checker --summary and read the output, because you did not pick these packages by hand. You are scanning for copyleft and source-available terms: AGPL, SSPL, BUSL, anything with a commons clause. A transitive AGPL dependency inside an internal tool is usually a non-event. The same one in something the client intends to sell is a conversation you want now rather than during their due diligence.

On ownership, do not pretend to certainty you lack. Your contract should assign the intellectual property on final payment, and you assign whatever rights you hold. The copyright status of AI-generated output is unsettled and varies by jurisdiction, so say so and point them at their own solicitor.

Tell them in writing, before handover

Take the clear position: the client should be told the codebase was built with AI assistance, in writing, before the code changes hands. Not after. Not if asked.

Frame it as a maintenance-relevant fact, because that is what it is: it affects how they staff the maintenance and what tooling the next developer wants.

For your records, and because it is relevant to how you maintain this: the codebase was built with heavy use of AI coding agents, with every change reviewed and tested by me. The agent configuration I used is included in the repo under .claude/, so whoever picks this up next can work the same way and will get moving faster for it.

One sentence, no apology, no salesmanship.

The alternative is a reputational time bomb. It surfaces from the commit history, or from the next contractor who mentions it casually in a meeting. The moment it emerges after the fact, the question stops being "is this good software" and becomes "what else did they not tell us". You lose the reference, which in independent work is the only asset that compounds.

A fixed window beats open-ended goodwill

Open-ended goodwill sounds generous and behaves badly. It has no end date, so the cost is unbounded and unbilled, and the client cannot tell a defect from a change, so every request arrives labelled as a bug.

Defects — behaviour that differs from the agreed specification — will be
corrected at no charge for 30 days from the date of handover. Requests
that add to or change agreed behaviour are not defects and will be
quoted separately. After the 30-day period, support is available at
£550 per day, half-day minimum, subject to availability.

That day rate is my own read of what the market bears for maintenance on a system you already know, not a survey figure; £450 to £700 is the band I would work within. The window gives the client a deadline, and nothing surfaces real bugs like a team that knows the free period closes on the thirtieth.

The handover call

Forty-five minutes, recorded, with whoever will maintain the thing in the room — not only the person who signed the cheque.

Do not demonstrate the features; they have seen those for three weeks. Demonstrate the operations, live: clone the repo into an empty directory and get it running while they watch, deploy a trivial change, roll it back, show where the backups are and restore one.

The clean clone is deliberately exposing, and that is the point. If it fails, it fails in front of you both rather than at nine the following Tuesday.

Before that call, work through the list.

• Every file read at least once by you.
• Dead code, orphaned helpers and abandoned half-implementations deleted.
• No secrets in the tree or in the history; .env.example contains only placeholders.
• No TODOs, placeholder emails, stubbed senders or lorem text in shipped paths.
• Dependency list reviewed and trimmed; licences checked and any copyleft flagged.
• README verified by a clean clone in a fresh directory.
• Architecture note and runbook written.
• Agent configuration included and scrubbed of anything personal.
• Deploy and rollback both performed at least once from the documented steps.
• Access transferred: repository, hosting, domain, database, email sender, error monitoring, and any third-party account created in your name.
• Disclosure sentence, warranty window and post-warranty rate all stated in writing.
• Final invoice raised.

The discomfort of reading files you did not type is useful information. It is the honest distance between having produced software and understanding it, and handover is the day that distance gets priced. Spend the afternoon and it closes. Skip it and you find out how wide it was nine months later, from a developer who has questions.