15KB
Context Engineering — Chapter-32: Teams: context as a repository asset
- Source: /library/Context Engineering/source-file.pdf
- PDF pages: 306–316
- Pages without text: none
Teams: context as a repository asset The pull request arrived on a Wednesday, with two new tests and clean lint. The colleague joined last month, took the first work-in task and handed back code that works: the front desk books the work-in, the system refuses it when the day is full, and the message comes out the same as the one in the spec. You approve it, and only in the next day’s review does somebody notice that the implemented limit is two, and that the clinic moved to three the Tuesday before last. Nobody got it wrong out of carelessness. The colleague cloned the repository, opened the agent and asked what the work-in rule was. The agent answered two, with the confidence of something it had read somewhere, because it had: in the context file the colleague wrote in their first week, copying what they found in the code at that moment. Their file never heard about the Tuesday before last, and had no way to hear. It lives on their machine. If you count the context files on your team, you will find one per person, all alike, none identical, and none of them in the repository. What the team shares is the code. What produces the code, each person wrote alone, and the divergence between those copies shows up nowhere until it becomes a pull request like this one. This chapter is about moving the context from the laptop to the repository, and doing it with the minimum process that works: a repository standard, one owner per artifact and an entry path for whoever arrives tomorrow.
What belongs to the repository One question draws the line: does this information hold for anyone who clones the repository? If it does, it belongs to the repository and it is versioned. If it holds only for you, it is yours and it stays out of version control. The URL of your test environment is yours. The domain vocabulary belongs to the repository. There is no third category, and most of what is in your personal file today falls on the repository side the moment you ask the question out loud. The good news is that the previous chapter already left the vehicle ready: the AGENTS.md at the root, with the one-line bridge for the tool that reads another name. What changes when it stops being yours and becomes the team’s is two paragraphs, and the file starts saying so about itself:
VilaSchedule
Appointment scheduling system for Vila Nova Clinic: one schedule per
provider in fixed intervals, regular appointments and work-ins.
This file belongs to the repository, not to you. It is versioned,
reviewed in the same pull request that changes what it describes and
has a named owner in docs/context-governance.md. What holds for you
alone goes in CLAUDE.local.md, which is in .gitignore.
[...]
What this file does not decide
The context specific to each feature lives next to its code, in an
AGENTS.md inside the feature folder. The work-in rules are in
src/features/workins/AGENTS.md, and this file does not repeat them:
two copies of the daily limit is exactly the problem the clinic
already had.
The anatomy is the one from chapter 12, with nothing new about
it: pointers to where the truth lives, rules that hold in every
session, commands. What chapter 12 could not give, because it
dealt with one person, is the two paragraphs above: the one that
declares ownership and the one that refuses to concentrate
everything in a single file.
The refusal matters more than it looks. A single file at the root
with all the rules of the system is the format any team writes on
the first try, and it breaks for two reasons at once: it costs
window space in every session, including the ones that have
nothing to do with work-ins, and it becomes the place where the rule gets duplicated, because the work-in code also needs it close by. The way out is the same way FOCUS Architecture (https://books.kodel.com.br/en/books/focus/) organizes code: the information lives next to the feature it belongs to. The nested AGENTS.md , which the previous chapter left inside the work-ins folder and which the agent in the integrated development environment (IDE), the agent in the terminal and the agent in continuous integration (CI) find when they work there, is the vehicle for that; where a tool does not read it, the same text becomes a rule by path pattern, and it goes on living in the feature folder. vilaschedule ├── .cursor │ └── rules │ └── migrations.mdc glob rule for the IDE agent ├── .github │ └── workflows │ └── pr-review.yml agent in CI, context all in a file ├── AGENTS.md repository context, versioned ├── CLAUDE.md one-line bridge: imports AGENTS.md ├── CLAUDE.local.md your preferences, in .gitignore [...] ├── docs │ ├── adr │ │ └── 001-fixed-intervals.md │ ├── agent-onboarding.md │ ├── context-governance.md │ ├── conventions.md │ └── scheduling.md living doc, verified in CI [...] └── src ├── features │ ├── scheduling │ │ ├── AGENTS.md [...] │ └── workins │ ├── AGENTS.md │ ├── day_limits.ts
[...] └── shared └── dates.ts It is the tree from chapter 13 with the context files visible, and with no new folder to accommodate them; even the configuration of the previous chapter’s tools is versioned, in the folder each one expects. Two choices in that tree are worth a comment. The first: providers and reports have no context file, because there is nothing to say there beyond what the code and the conventions already say. An empty context file costs window space and teaches nothing. The second: docs/context-governance.md is the only file in the repository that talks about people, and it is the subject of the next section. The reason the feature is the unit also comes from FOCUS Architecture, and it is not an aesthetic one. In the chapter about features, the argument against the folder per technical layer ends in a sentence that holds the same for context: a folder that belongs to everyone belongs to no one. A rules file at the root, describing work-ins, scheduling and reports, has the same disease: when the limit changes, nobody in particular is responsible for updating it, because it belongs to everybody. And there is a part of the team’s context that was already versioned before this conversation started. The feature spec, in the format of Spec Driven Development (https://books.kodel.com.br/en/books/sdd/) is what says what to build, and it has been going into the repository since chapter 8. What this chapter adds is the rest: the conventions, the architecture decision records (ADRs), the living documentation and the context files follow the same path, for the same reason.
One owner per artifact
Versioned context with no named owner ages exactly the way it
aged on your laptop, with the difference that now it ages for
everybody at once. The missing layer is short, and it fits in a
table:
| Artifact | Owner | Trigger |
|-----------------------------|-------------------|--------------------|
| AGENTS.md (root) | Cecilia Braga | pointer or command |
| docs/scheduling.md | Cecilia Braga | rule in production |
| docs/conventions.md | Rafael Lins | new convention |
| docs/adr/ | whoever proposes | decision made |
| src/features/*/AGENTS.md | the feature owner | feature rule |
| docs/agent-onboarding.md | Rafael Lins | the first day |
An empty cell does not exist. An artifact with no owner leaves the
repository or gets an owner in the same PR that brings it in.
The name in the table is a person’s, not a role’s and not a team’s. When the person leaves the team, reassigning their cells is the first line of the handover, the same day: a table with the name of someone who no longer works there is worse than no table, because it looks like somebody is watching. The second half of governance is a single rule, and it creates no new step: context changes in the pull request that changes the code it describes. Whoever reviews code reviews the context along with it, with a single question: after this merge, is any context file saying something false? In the case of the colleague in the opening, the answer would have been yes before the merge, and the work-ins feature file would have come in through the same pull request that changed the limit. The CI workflow of the previous chapter makes the enforcement cheap: the automated reviewer already receives the diff and the context files together, and the single question fits in its prompt. Here comes the most frequent objection, and it is fair: context governance turns into process bureaucracy. It does, when somebody turns it into a committee, a weekly ritual or a separate approval. My position is that the minimum viable version has exactly two items, a named owner per artifact and review alongside the code, and that any third item has to prove it is worth what it costs. If your context governance has a meeting, it has already failed. If it fits in a six-row table and one question at review, it survives the quarter. An agent’s first day The third axis is the easiest to forget, because it only shows up when somebody arrives. Agent onboarding is what a tool finds on its first run in the repository, before you explain anything, and the way to find that out is to ask:
The five first-day questions
Ask all five in the agent's session, without helping, and compare against the answer key. Each one checks a different file.
- How many work-ins does the clinic accept per day, per provider, and
where is that written? Answer: 3, in
src/features/workins/AGENTS.md. - What is the appointment scheduled outside the grid called in the
code? Answer:
WorkIn, the clinic's own word, perdocs/conventions.md. - Why does the schedule use fixed 30-minute intervals instead of
duration per procedure? Answer: ADR-001, in
docs/adr/. - Where would you create the file for a new cancellation rule?
Answer: inside
src/features/appointments/, never in a folder per
technical layer. 5. Can you rewrite the error message the front desk sees when a work-in past the limit is refused? Answer: no, it comes from the feature spec, copied literally. The checklist holds for the four classes of the previous chapter. In the terminal agent and in the IDE agent, you ask the questions in the first session; in the chat assistant, they test whether the pasted projection is current; in the CI agent, their version is the first test pull request, opened on purpose with one violation of each rule. The value of the checklist is not in the score but in the kind of mistake, and there are two kinds. Getting question 1 wrong means the feature file did not enter the session, and the problem is one of scope: the agent started in the wrong directory, or the tool does not read nested files, or the rule is in a file it ignores. Getting question 4 wrong means the opposite: the context entered and was not followed, and there the fix is in the text, not in the configuration. Almost always the rule was implicit, or said in two places with different words. Notice what that distinction settles. Without it, every wrong answer turns into the same reaction, pasting more text into the chat until the agent gets it right, which fixes today’s session and fixes nothing tomorrow. With it, half the mistakes become a scope adjustment and the other half become a context pull request, reviewed by the artifact’s owner. The same mistake for the same reason with two different people is the cheapest signal your team has that a file is badly written.
It is worth saying that this checklist is the same one for people. If the new agent cannot find out why the schedule uses 30-minute intervals, the new colleague cannot either, and neither of them is going to ask. The difference is that the agent answers wrong with confidence and in ten seconds, which turns your human onboarding, which nobody ever tests, into something you can measure in an afternoon. “Nobody is going to maintain this” The second objection is the strongest, and it almost always comes from someone who has seen it happen: nobody maintains team context; in three months it becomes an outdated file everyone has learned to ignore. The answer has two parts, and neither of them is optimism. The first is that chapter 12 already answered the technical part, with the maintenance triggers and the habit of never writing into the file anything with a short expiration date. A file written that way ages slowly, because almost everything in it is a pointer to places the code itself verifies. What was missing was a recipient: a trigger with no named owner is a reminder nobody receives. That is all this chapter adds, and it is why the six-row table is the centerpiece and not an ornament. The second part is about cost, and it is the objection that comes right after: writing and maintaining all this costs more than the benefit. For a one-off task, it does, and I recommend writing nothing. The return arrives the second time the same rule changes, which is when somebody has to find out where it lives, and it is the same argument FOCUS Architecture makes in favor of writing the specification before generating code. The first time, you type the context and get the result you would have gotten anyway. The second time, the work-in limit changes in one file,
the new colleague’s pull request already arrives with the right rule, and the cost you paid once stops being paid every week by the clinic’s front desk, calling to cancel the work-in the system accepted past the limit. This chapter assumes there is context to govern. Chapters 8 to 13 wrote the spec, the living documentation, the ADRs, the conventions and the project context file; without them, what this chapter produces is a maintenance process with no object, a table of owners for empty files. Governance does not improve bad context. It keeps good context from rotting and makes sure it reaches whoever joined yesterday. What happens when all of this meets a project You have the artifacts of Parts II and III, the techniques for fitting in the window, the number that says whether things are improving, the setup per class from the previous chapter and, now, the path for none of it to depend on your staying at the company. What is missing is the part no chapter on its own can show: how these pieces get in each other’s way in a real project, in what order they show up and what you do when the context fails in the middle of the implementation. That is what Part V does, in a single project, from preparing a new repository and a legacy one through the guided end-to-end implementation and the autopsy of what failed along the way, with the missing context named by name.