Book-Reader-Assist/library/Context Engineering/Chapter-14-Conventions/Chapter-14-source-text.md

Context Engineering — Chapter-14: Conventions

• Source: /library/Context Engineering/source-file.pdf
• PDF pages: 90–98
• Pages without text: none

---

Conventions The pull request that closes this story arrives on a Thursday. The front desk at Vila Nova Clinic asked for appointment cancellation with a mandatory reason, you handed the task to the agent with the spec in the window, the way chapter 8 taught, and the result works: the business rules are right, the tests pass, the behavior matches the acceptance criteria. Then you open the diff. The new type is called VisitCancellation , in a system where every type carries the name the clinic uses: Appointment , Provider , and WorkIn for the patient squeezed into a schedule that is already full. The tests landed in a brand new tests/ folder, when every other test lives beside the file it covers. The migration was generated from a schema diff and shipped with no rollback, in a project where every migration is written by hand and has its down , the rollback step, tested. And the model wrote its own error message for the front desk, polite and different from the one the spec laid down. Your review has nine comments and not one of them points to a bug; every one points to a difference. The sentence you type three times is the same: “that is not how we do it here.” Before you blame the model, go look for where those rules were written down. The cancellation spec says nothing about type names or test folders, and it should not: it records the intent of one change, not the way the house works. The living documentation describes what the system does, not how the code is arranged. The architecture decision records, the ADRs of chapter 10, hold the choices someone weighed and made, and nobody ever sat down and decided that tests live beside the file they cover; it happened, it became a habit, and a habit produces

no document. The rules the agent broke were written nowhere a context window can reach. You have known since chapter 1 what that means: for the model, they do not exist. There is something worse here than a random guess. Faced with the gap, the model fills it with the likeliest pattern from training, and the likeliest pattern is the very one your project decided against. Generic type names, a separate tests/ folder, generated migrations: each of those choices is the majority choice in the public repositories that trained the model. A team convention is, by definition, the set of points where your project departs from the statistical default; if it did not depart, you would need no rule. So the agent does not break your conventions by bad luck; it breaks them by construction: without the rule in the window, the expected behavior is the world’s default, never the house’s. And a correction typed into the chat, as you also know by now, lasts one session. Next Monday, another agent, another window, the same nine comments. Fewer decisions per task Treating the way the house works as an artifact has a classic formulation. In 2016, David Heinemeier Hansson published “The Rails Doctrine” (rubyonrails.org/doctrine), defending the pillar the framework made famous: convention over configuration. The argument is about attention. Every trivial decision the framework makes for you, the table name, the primary key, the folder layout, is a decision you no longer make on each task, which frees your attention for what is genuinely particular about your system. The convention is not the best possible choice case by case; it is a good enough choice, made once, that settles a thousand repeated arguments.

Read that argument with the vocabulary of this book and it changes audience without changing shape. For the developer, a convention saves a decision; for the model, a convention written in the window replaces a guess. The nine comments in your review are nine decisions the agent made alone because nobody had made them for it anywhere visible. And the cost is one round of rework, which chapter 6 taught you to count, multiplied by every future session, because the gap is still there. The answer, then, is not a smarter agent; it is the written rule. That is no invention of the agent era either: Google keeps its Google Style Guides public (google.github.io/styleguide), one per language, precisely because a convention that lives in people’s heads does not scale to a company of tens of thousands of engineers, let alone to a collaborator born without memory at every session, as chapter 3 showed. What 2026 changed is not that conventions get written down; it is that their most frequent reader is now a model. The conventions document This chapter’s artifact is the simplest in Part II. VilaSchedule keeps it in docs/conventions.md , and it opens by declaring its own scope, handing everything a tool can check to continuous integration (CI), the pipeline that runs on every push: Rules that apply to all new code in this project. Anything a tool can check does not live here: formatting, indentation and spacing belong to Prettier and EditorConfig, configured at the root of the

repository, and CI fails the build for anything that breaks them. This document holds only what no machine can check on its own. Hold on to that last sentence, because it is the bar for entry to the whole document, and I come back to it in the next section. First, look at what clears the bar. The names section answers the first comment in your review:

Names

• Domain terms match what the clinic says: Appointment, WorkIn, Provider, Block. No synonyms (Booking, Visit, Slot) and no generics (Item, Entity, Record).
• Technical terms with no business meaning keep the name the industry already gave them: Repository, Controller, parse, retry. An in-house replacement costs every reader a lookup and buys nothing.
• One concept, one name: before you coin a new term, check the vocabulary in the living documentation for scheduling.

Notice that each line names the default it forbids. “No synonyms” is there because varying the word is what generated text does by nature. “No generics” is there because a generic name is where the model lands once the synonym is closed off, and a name that fits any system describes none. A good convention rule looks like this: it draws the exact line between the world’s default and the house’s, and shows an example of both sides. The next sections close the remaining comments in the review:

Tests

• Every test lives beside the file it covers, with the _test suffix (workin.ts and workin_test.ts in the same folder). There is no separate tests/ folder.
• The test name describes the business rule, not the method: “refuses the third work-in of the day,” never “tests createWorkIn”.

Migrations

• A database migration is written by hand, never generated from a schema diff; every migration has its rollback (down) written and tested.
• Name in the NNN-verb-object.sql format, as in 014-create-workin.sql. The whole file keeps that tone and fits on one page: two more short sections, commits and error messages, and a closing “what this document does not cover” that points to Prettier, to the ADRs and to the living documentation, the same cross-reference pattern chapters 9 and 10 used to keep each artifact small. With the file in the window, run Thursday again: same agent, same spec, and the diff comes back with AppointmentCancellation , the test beside the file, the migration written by hand. The review shrinks from nine comments to zero, and the model did not get better. Those nine decisions were no longer the model’s to make. Conventions that run in CI What is left is to defend the bar for entry, because that is where the classic objection lands. You propose the document to the team and someone who has seen this movie before answers: “a style guide becomes a dead letter; nobody reads it, nobody follows it, and every six months somebody reopens the holy war over semicolons.” The objection describes something real, and the answer has two parts.

The first: anything a tool can enforce stays out of the document and goes into CI. In 2026 the tooling for that is mature. EditorConfig (editorconfig.org) fixes indentation, charset and line endings in a file almost every editor respects, and Prettier (prettier.io) formats the whole codebase with very few options, on purpose. The Prettier home page sells exactly that: the end of the holy war, because a formatter with fixed opinions ends the style debate by removing anything left to debate. An executable convention, to my mind, is the best shape a rule can take. Nobody has to read it, remember it or agree with it; the build rejects anything that breaks it, and that holds the same for code typed by a person and code generated by an agent. It is chapter 9’s move again, where living documentation traded promised discipline for installed machinery. The second part answers the “dead letter.” What is left in the document, once everything delegable has been delegated, is short and dense: at VilaSchedule, a single page where every line forbids a default from the model’s training. And that remainder has a property the style guides of 2015 never had, which is a guaranteed reader. The agent that receives the document in its window applies it in that same session, in every file it writes, with none of the fatigue and none of the forgetting that killed the old guides. Chapter 10 gave that a name: a document with a reader and an effect is context, never bureaucracy. The dead letter was a problem of audience, and the audience changed. Where each kind of information lives With this chapter, the four artifacts that open Part II are on the table, and each one answers a question: what are we changing and under which rules, the spec; what is true in the system today, the living documentation; why the system is the way it is, the ADR; how we do things here, the convention. Test the split

against a real case, because concrete cases are where it creaks. The VilaSchedule team uses the version 7 universally unique identifier (UUID v7), whose first bits are a timestamp, as the primary key in every new table. Where does that live? It depends on what you want to keep, and the test is this: a decision with context and consequences calls for an ADR; a rule that applies over and over, to every new file, calls for a convention. The why of UUID v7, what it gained over the random v4, what was accepted as a cost, what would overturn the choice later, is a decision taken once, with alternatives that lost. That is an ADR, immutable like the ones in chapter 10. Whereas “every new table uses UUID v7 as its primary key” is a rule the agent has to apply in every migration it writes, without reopening the discussion: a convention, one line in the migrations section that points to the ADR for whoever wants the why. The same information appears in both artifacts with different jobs, and that boundary is gray anyway. I would rather accept the overlap and settle it by cross-reference than chase a pure taxonomy. When in doubt, ask what the reader in the window needs: if it needs to obey, a convention; if it needs to understand before touching, an ADR. The four artifacts exist, they are short, and they cite each other without duplicating each other. But notice a weakness this chapter inherited from the previous ones and did not solve: in every scene where an agent found the living documentation, the ADR or the conventions, it found them because it searched the repository and the files had good names. Being found depends on a search: one that can fail, that costs tokens in every session, and that depends on the agent choosing to look before it acts, which is exactly what it did not do on the Thursday at the top. The 2026 tools offer a shortcut: a file loaded into the window at the start of every session, with no search and no luck involved, the natural place to point to the four artifacts of this part and to hold the few

rules that have to be present at all times. Writing that file well, and keeping it from turning into a dumping ground, is the subject of the next chapter.