All courses / AI Developer / Module 2 / Chapter 12
Learning objectives
After the lesson the participant can:
- Compare what the sources on code health in AI-assisted codebases measured and where each stops
- Explain the five things a legacy migration needs before any generated translation
- Classify documentation by its three jobs and say which an assistant can draft
- Draft a code-ownership record and plan a yearly ownership review
Key concepts
- Programming as theory building
- Naur's argument that a program is not its source text but a theory the programmers hold of how it relates to the world and why it is built as it is. Documentation derived from code can say what the code does; the reasons are carried by people and decision records.
- Five things before a migration
- An owner by name, an oracle that does not come from the generator (characterisation tests of the old system's behaviour), a scope in which the tool may act, a way back, and the knowledge captured before it retires. Both profiles keep migrate at Level 0 Advisory.
- Debt as a flow
- Technical debt is the accumulated cost of choices that made change easier then and harder now. The chapter's rule is to track it as a flow and not a stock, because debt accumulates in the sum of changes and the sum needs an owner and a measure.
- Deletion as stewardship
- The counterweight to cheap generation. Deletion works when a signal of use, a human reviewer, an exception list and a way back are in place.
- Code-ownership record
- The artefact OWN: owner and deputy, scope, tests and who owns the oracle, decisions, revert method, and the evidence age of the Understand and Revert tests. It is a tool for the owner and the team, not a means to rank or appraise named developers.
Interactive exercises
Do them here and get feedback at once. Choose a card and then where it belongs, or drag it.
Interactive exercise 1 · Match
What each code-health source measured
Match each source in the chapter's evidence table to what it measured.
Interactive exercise 2 · Scenario
The repository whose owner has left
Apply the practical guide for the yearly ownership review.
Teaching plan
| 15 min | Lecture on Table 12.1 and the three statements that survive the limits of the evidence on code health. |
| 15 min | The teacher presents the public migration reports and their shared pattern (bounded, mechanical, repeated work), then the five things a migration needs first. |
| 10 min | Reading of the two ownership records OWN-NR-2030-04 and OWN-HM-2030-07: why a vacant deputy is a finding and why the deputy for the oracle differs from the deputy for the code. |
| 25 min | Exercise: participants write an ownership record for the module whose loss of its last explainer would hurt most. |
| 10 min | Plenary: each participant names the first recorded conversation with an explainer they would put in the calendar. |
Discussion
- The public reports describe bounded, mechanical, well-tested migrations. What makes the COBOL estate of Hansa Mutual or the case system of Nordvik Region a different kind of problem?
- Why does the chapter ask that the ownership inventory is reported as counts with dates, and what would an undated figure hide?
- Adding code is visible and rewarded; deleting it is not. What would have to change in your organisation for deletion to count as work?
Written exercise
Exercise · 25 minutes
An ownership record for one module
Choose the module in your estate whose last explainer you would miss most, or the COBOL settlement module of Hansa Mutual. Write its ownership record: the owner and a deputy by name, what the module is and does, where its tests and decisions are and who owns the oracle, how it is reverted, and the review trigger: a date at most a year ahead and the events that bring it forward, such as the owner leaving or the tool changing. Record when the Understand test was last run, by asking the owner to explain a recent change without the assistant, and when the Revert was last rehearsed. Mark every vacancy as a finding.
Deliverable: A code-ownership record with owner, deputy, scope, oracle owner, revert method, test dates, review triggers and marked findings.
Self-test
Choose an answer to see whether it is right, or open the answer below each question.
What did the randomised trial by Borg and others, in which 75 developers evolved code without AI, find?
Show the answer
C. No significant difference for the next maintainer, whether or not an assistant was used
The trial asked whether code written with an assistant costs the next maintainer more, and found no significant difference in a small task. The other figures come from the Cursor study and the GitClear report.What sequence do both organisations arrive at for legacy modernisation?
Show the answer
A. Owner first, oracle second, knowledge captured third, translation last
The chapter concludes that both reach the same sequence from different directions: owner first, oracle second, knowledge captured third, translation last. It also notes that the conversations that capture knowledge are put on the calendar first, because that knowledge cannot be recovered later.What does the practical guide say about using ownership records to count the modules a named developer owns for appraisal?
Show the answer
D. It treats it as a monitoring use that the record is not meant for
The record is a tool for the owner and the team. The guide says that using it to rank or appraise named developers is a monitoring use, which belongs to the agreements treated elsewhere in the book.