10 Design for Change, and for Agents

Learning objectives

After this chapter you should be able to:

1. Apply Parnas's information-hiding criterion to decompose a small system, and compare two designs with Ousterhout's depth test and a change-footprint count.
2. State the load-bearing assumption of design for change, apply the negation test to it, and explain why written design rationale becomes a precondition when agents maintain the system.
3. Summarize what has been measured, and what is only practice, about context limits and convention files.
4. Sort the lines of a convention file into preferences, mandatory procedures and cognitive strategies, and decide which belong in prose, in a build check, or nowhere.
5. Decide when duplication is acceptable, using the rule that separates interfaces from the inside of modules.
6. Write a convention file and a decision record, test one convention, and state what would overturn the verdict.

Opening case

A composite case, not a real engagement.

A logistics company's internal dispatch dashboard has been maintained for three years by a team of five. Job status is a string column, and the map, the notification sender, the reassign dialog, the daily report and the API each carry their own comparison of status strings.

The chapter continues from here.

What the chapter covers

1. 10.1 The classical method
   • 10.1.1 Why design for change
   • 10.1.2 Information hiding
   • 10.1.3 Extension and contraction
   • 10.1.4 Deep modules and the two causes of complexity
   • 10.1.5 DRY
   • 10.1.6 Where design knowledge lives
   • 10.1.7 A worked example: Dispatch
   • 10.1.8 What it got right
2. 10.2 The assumption it depends on
3. 10.3 What agents change
   • 10.3.1 A harder version of the same limit
   • 10.3.2 What is known about convention files, and what "fuller" means
   • 10.3.3 Written down is necessary, not sufficient
   • 10.3.4 What belongs in the file
   • 10.3.5 Duplication
4. 10.4 The verdict
5. 10.5 What replaces it: designing for agents as maintainers
   • 10.5.1 Deep modules with written interfaces
   • 10.5.2 The convention file
   • 10.5.3 The decision record
   • 10.5.4 Testing a convention
   • 10.5.5 The duplication rule
   • 10.5.6 These become the handoff package
6. 10.6 Lab: Convention file and ADR, tested
7. 10.7 What would make this verdict false

Lab and prediction

The lab tests this prediction from the working paper the book grows from (Smith 2026a):

• P8 Fuller (more complete, not longer) convention files and decision records at handoff predict lower comprehension hours for the inheritor

A result that contradicts a prediction, honestly reported, is a result. You are graded on accurate records and reasoned interpretation, not on agreeing with the book.

Summary

• Design for change (Parnas 1972, 1979; Ousterhout 2021) hides each likely-to-change decision in one module behind a small interface, so the change footprint of foreseen changes is one. DRY concerns knowledge, not text.
• Load-bearing assumption: maintainers can hold only part of a system in mind, so design knowledge must be localized behind interfaces. The secondary assumption that maintainers retain design knowledge is the one agents break, unless the harness persists context or memory.
• Evidence: context is limited and unevenly used (Liu et al. 2024); convention files help mainly for non-standard practices (Gloaguen et al. 2026); a pilot demonstration showed a written convention overridden on reflex, and its fix changed two things (Smith 2026b).
• Verdict: holds. The method does not change; writing the rationale down becomes a precondition.
• Replacement: deep modules with written interfaces, a short convention file with a Do Not section enforced by checks, ADRs, and tested conventions. "Short" and "fuller" coexist: fuller means complete on what an inheritor needs, not longer. These artifacts are the design half of the handoff package; P8 predicts they lower the inheritor's comprehension hours.

Key terms

Change footprint

the number of modules read or edited to make one change correctly.

Uses relation

A uses B if A's correct functioning depends on a correct B; a loop-free relation yields subsets.

Deep module

a module with a simple interface in front of substantial hidden functionality.

DRY

every piece of knowledge has one authoritative representation within a system.

Architecture decision record (ADR)

a short repository document recording one decision: title, status, context, decision, consequences.

Convention file

a repository file (AGENTS.md, CLAUDE.md) holding project guidance that an agent loads at the start of a session.Also used in 1, 8, 9, 11, 13, 14, 15, 17, 18

Do Not section

the part of a convention file listing prohibitions, each with a reason and an enforcement pointer.

Probe task

a small change where the model's habit and the written convention disagree, used to measure compliance.

Connections

Where this chapter and another point to each other most often.

• Chapter 2: The Assumption Audit: A Method That Outlasts the Tools
  Neither gives a probe design that varies how the agent is asked to decide, or tests convention files against a handoff. ## 10.4 The verdict Holds. This is my judgment, reached by the steps in Chapter 2.
• Chapter 6: Cost and Schedule Estimation After COCOMO
  An excerpt for Dispatch: Three Do Not lines come from defects in Chapter 6's opening case: the nonexistent dependency, the access check missing from the API, and tests written to accept a defect.
• Chapter 8: Coordination at Scale: Shared Context vs. Shared Messages
  For Dispatch, the job-state module, owned by the Routing agent of Chapter 8, hides the set of states (DD1) and the on-time rule (DD4).
• Chapter 14: Configuration Management When Agents Commit
  Unless the harness persists context or memory (Section 10.3.1), an agent begins each session without what the last one learned, and a persistent store the team cannot read or version is a hidden input (Chapter 14).
• Chapter 17: Coordination Without Communication: The Bound and the Leak Test
  P8 does. ### 10.3.3 Written down is necessary, not sufficient In a 200-round pilot on converge-or-split decisions (Chapter 17), a pair of agents with a written convention overrode it with the model's habit when they answered on reflex, and scored 26.5%, below chance.
• Chapter 18: Running the Whole Life Cycle: The Engineer as Manager of an Agent Team
  Copies are also lines to read: in the review term of Section 6.5.1, a 40-line routine copied into 12 places adds 480 lines to the review job, against 52 for one routine and 12 calls (Chapter 12). ### 10.5.6 These become the handoff package The convention file, interface documents and ADRs are the design half of the handoff package (Chapter 14; Chapter 18; Appendix C).

See it on the map

Further reading

• Parnas and Clements (1986). Why design documents should be written for the maintainer who comes later and record rejected alternatives; the ancestor of the ADR.
• Nygard (2011). Two pages that define the ADR and argue why a newcomer needs the reason.
• Ousterhout (2021), Chapters 2, 4 and 5: complexity, deep modules, information leakage.
• Naur (1985). The strongest objection to this chapter's replacement; read it before you decide how much a document can carry.
• Gloaguen et al. (2026). The first test of whether convention files help; read the method to see what counted as help.