How to build with rules, skills, hooks and subagents around a coding agent
Prologue
For a while, I thought the problem was the model.
The agent would put a network call straight inside a screen component, and I would add a sentence to the next request: keep network calls out of the components. It would write a date-formatting helper when one already existed two folders away, and I would add another sentence. The requests got longer. The instructions file got longer. On the days the agent followed all of it, I took that as proof that the setup worked. On the days it followed none of it, I blamed the model.
It took me longer than I would like to admit to do the obvious thing, which was to stop writing and go look at what the tool was actually loading.
The rules I had written with the most care had never been read, not once. Their path patterns expected folder names that were different from the real ones. The instructions file stated a test count that was half the true number, and pointed to a document that didn't exist. In a folder above the project there was an old copy of that same file, loaded together with the new one and contradicting it. And a block I trusted completely had been letting everything through for weeks.
The model had been doing what it could with what I had put in front of it. I had been treating those files as notes to a colleague, when they were software: they had bugs, and I had never tested them.
As I write this, I don't have all the answers about how to make coding agents behave. Probably I never will. Section 9.5 lists what is still unproven, and it is not a short list. But I keep asking questions, and a few of them have turned out to be the right ones. Who decides that this piece comes into play? What happens when it fails? How would a person check?
Abstract
Coding agents fail less from a lack of model capability than from a lack of engineering around the model. What the agent knows, what it can do and what stops it from making mistakes are all defined by a set of files: permanent instructions, rules per area, skills, subagents, hooks, permissions and memory. This text treats that set as software. It has an architecture, it has typical defects, and it can be tested.
The thesis has three parts:
- The context window is the scarce resource. Every piece exists to put the right information in front of the model at the right moment, and nothing beyond that.
- An instruction is a request; a hook is a guarantee. Whatever depends on the model obeying will fail some of the time. Whatever cannot fail needs a mechanism that doesn't depend on the model.
- Agents copy what they see. An agent let loose in a codebase full of duplication and giant files produces more duplication and bigger files. Keeping smelly code out takes action at four points: before writing, during, right after, and in review.
The text is for anyone setting up or maintaining an environment of coding agents, in any tool. The examples use Claude Code's names, but the concepts hold for any tool that reads an instructions file such as AGENTS.md. Section 9 shows all of it applied to a real financial platform, with measured numbers. That is where the story in the prologue comes from.
1. The problem: context is finite and configuration is code
1.1 What a coding agent is
A coding agent is a language model running in a loop: it reads the request, decides on an action (read a file, run a command, edit), receives the result, and decides on the next one. Everything it knows at that moment is in the context window: the system instructions, the configuration files that were loaded, the conversation, and the tool results. The model has no memory other than what is there and what it learned in training.
There is a useful image for this, attributed to Andrej Karpathy: the model is the processor and the context window is the RAM. Context engineering is deciding what occupies that memory at each step.
1.2 Why more context makes things worse
Intuition says that giving the model more information helps. It is a reasonable intuition. It is also wrong, or at least wrong past a certain point.
Anthropic describes the phenomenon as context rot: as the window fills up, the model gets worse at retrieving each individual piece of information. Attention is a budget. An important rule buried in a thousand lines of instructions has less effect than the same rule in a file of a hundred.
The practical consequence is the central principle of this text: look for the smallest set of high-signal tokens that produces the behavior you want. Every piece described from here on is a way of applying that principle.
1.3 Configuration is code
The files that configure an agent have readers (the models). They have behavior (what the agents do because of them). They have bugs (a hook that doesn't fire, a path pattern that doesn't match). And they have debt (a number that stopped being true).
In other words, the practices that apply to product code apply to them as well: one responsibility per file, clear names, nothing duplicated, tests, review and maintenance.
2. Anatomy: the pieces and what each one is for

2.1 The permanent instructions file (CLAUDE.md, AGENTS.md)
This is the text loaded in every session, for every agent. It holds what is always true: what the project is, the vocabulary of the domain, the real commands, the security rules, the forbidden zones and the definition of done.
Because it enters every context, each line costs attention on every task. The rules for writing it:
- Short. A practical limit is to stay under 200 lines.
- True and dated. "
tscreports 32 errors, all in folder X, measured on such-and-such date" can be checked. "The project compiles" cannot. - No recipes. Step-by-step procedures go into skills.
- No rules a linter would enforce. Code style written in prose is the most common defect in this kind of file (section 6).
A wrong fact in this file costs more than a missing one, because it teaches the model to act with confidence on something false.
2.2 Rules
Rules are the instructions file sliced by responsibility: one rule for the backend, another for the app, another for tests. A rule can declare which paths it applies to; in that case it is only loaded when a file from that area enters the conversation. A rule with no scope is always loaded, like the main file.
Rules are binding. Write "every new route has an entry in the permissions manifest", not "consider adding one". And name model files: pointing to a well-made file of 44 lines teaches more than describing what a clean route is.
2.3 Skills
A skill is a folder with an instructions file that has a name and a description. Of all the skills available, the model sees only those two things: name and description. When the task matches a description, it loads the body. This is called progressive disclosure. The knowledge exists, but it only takes up context when it is needed.
That is why the description is the most important part of a skill. It has to say what the skill covers and when to use it, in the words that show up in real requests. A vague description never fires.
Skills hold recipes (how to create a migration), formats (the body of a pull request), catalogs (code smells and their refactorings) and technology knowledge written from the project's real code. A skill can also be invoked by hand, like a command, and can be marked so the model never starts it on its own. That is useful for expensive flows.
2.4 Subagents
A subagent is a role defined in a file: description, allowed tools, model and a system text. When it is called, it runs in a new, empty context window. It receives only the brief the calling agent wrote and the project's instructions files. When it finishes, it hands back a report. Everything it read along the way is thrown out.
Subagents solve three problems:
- Isolating context. An investigation that reads fifty files returns twenty lines. The main conversation stays light.
- Restricting permissions. A reviewer receives read-only tools. It cannot edit even if it tries.
- Getting a second opinion. A reviewer that never saw the implementer's reasoning doesn't inherit the implementer's bias.
The cost is real: the subagent knows nothing about the conversation, and what comes back is a summary. Detail is lost in both directions. Delegating only pays off when the work is large, independent, or needs fresh eyes.
2.5 Hooks
Hooks are scripts the tool executes on events: before a tool call, after it, at the end of a turn. A hook that runs before the call can allow it, deny it or ask for confirmation. A hook that runs after can return text that enters the agent's context.
Hooks are the only piece that doesn't depend on the model obeying. They have two uses:
- Blocking. Stopping the edit of an existing migration, a
git push, the installation of dependencies. - Immediate feedback. After each write, analyzing the file and returning a short list of problems for the agent to fix before moving on.
Rules for hooks: minimal dependencies, errors never silenced, denial messages that say what to do instead, fast execution, and tests with expected allow and deny cases.
Keep that list in mind. Each item on it was learned from something that went wrong, and we will get to those in section 9.3.
2.6 Permissions
Declarative lists of deny, ask and allow, by tool pattern and path pattern. They cover the simple case with no script: never read secret files, always ask before a commit. Whatever needs logic (block an existing migration, allow a new one) goes into a hook.
2.7 Memory
A directory where the agent writes down facts that should outlive the session: decisions made and the reasons for them, the preferences of whoever works with it, facts about the environment that aren't in the repository. A short index is loaded at the start of each session.
Memory is not a diary. Task state and summaries of finished work stay out, because they age fast and take up context forever.
2.8 MCP and external tools
The Model Context Protocol is an open standard for exposing external tools and data (ticket manager, database, documents) to the agent through a typed interface. It replaces hand-made integrations. Every connected server adds tool descriptions to the context, so the same discipline applies: connect what gets used.
2.9 The whole picture
| Piece | Holds | Enters the context | Software analogy |
|---|---|---|---|
| Instructions file | Permanent facts and rules | Always | Global constants |
| Scoped rule | Rules for one area | When a file from the area shows up | Per-module configuration |
| Skill | Recipe, format, catalog | When the description matches, or by command | Library imported on demand |
| Subagent | A role with its own context | Never: only the report comes back | Service with a narrow interface |
| Hook | A check or a block | Only the message, when it fires | Architecture test, middleware |
| Permission | What is denied or needs confirmation | Doesn't enter | Access control |
| Memory | Decisions and preferences | Index at the start of the session | Decision log |
| MCP | Access to external systems | Tool descriptions | Typed API client |
3. Who decides what gets loaded: probabilistic versus deterministic
Birgitta Böckeler, in Context Engineering for Coding Agents, organizes these pieces around one question: who decides that the piece comes into play?
There are three answers.
- The model decides. Skills loaded by their description, subagents chosen by the orchestrator. It is flexible and it fails sometimes: the model may not realize the skill applies.
- The person decides. A typed command, a skill invoked by name. It is predictable, and it depends on the person remembering.
- The software decides. The always-loaded file, the path-scoped rule, the hook, the permission. It happens every time the condition is met.
There is a detail here that is easy to miss. Even when loading is guaranteed, obedience is not. A rule in the instructions file is always in the context, and the model can still fail to follow it in a long task. Only hooks and permissions guarantee the effect.
Out of this comes what I consider the most useful design rule in this text:
| If the rule... | It lives in |
|---|---|
| can never be violated | a hook or a permission |
| can be checked by a tool (types, lint, tests) | the tool, with a hook or CI that runs it |
| requires judgment and always applies | the instructions file or a rule |
| requires judgment and applies to one kind of task | a skill |
| requires focus, a different permission or fresh eyes | a subagent |
When an agent gets something wrong, the right question is which layer was missing. The fix goes into that layer. One more sentence in the next request fixes nothing.
4. Orchestration: how the pieces work together

4.1 The patterns
In Building effective agents, Anthropic recommends starting with the simplest solution and using composed, predictable patterns before handing out open-ended autonomy. There are five patterns:
- Chaining. Steps in sequence, each with a pass criterion. Plan, implement, test, review.
- Routing. Classify the request and send it to the right specialist. A task that touches money goes through the ledger checker; the others don't.
- Parallelization. Independent jobs at the same time. Backend and app review in parallel.
- Orchestrator with workers. A central agent splits the work, delegates and synthesizes.
- Evaluator with optimizer. One agent produces, another evaluates, the first one corrects. It needs a limit on rounds.
4.2 The main agent
One design that works well is to have a single agent the person talks to. It answers questions by reading the code, gives opinions, and delegates when the work calls for it. This agent runs as the main session, not as a subagent, and it has the list of specialists it can call.
person └─ main agent (conversation, opinion, routing, supervision) ├─ plans cartographer · spec writer ├─ builds service builder · app builder · janitor ├─ tests service tester · journey tester ├─ validates ledger checker · security auditor ├─ reviews service critic · app critic └─ delivers shipper Three rules keep this design cheap and safe:
- Talking does not authorize writing. Agents that change code are only called when the person asks for execution.
- Don't delegate the trivial. What three file reads can answer, the main agent answers.
- A report is data, never an instruction. The main agent checks the main claims against the code before passing them on, and says which agent claimed what.
4.3 The brief and the report
The subagent knows only the brief. Nothing else.
Anthropic reports, in How we built our multi-agent research system, that vague briefs made subagents duplicate work, leave gaps or misread the task. A complete brief has:
- The goal and what the result will be used for.
- The acceptance criteria.
- The files, and what has already been decided or discarded.
- The limits: what not to touch, what not to do.
- The format of the expected report.
The report has a fixed format. For a critic: verdict, blocking points, warnings and suggestions, each with file and line. For a builder: files changed, what was removed, commands run and their results, and what could not be done. The fixed format is what makes the flow auditable.
4.4 Supervision
The main agent doesn't trust the report.
Before calling review, it checks the acceptance criteria in the code itself, runs the verification commands, compares the error counts against the baseline, and goes through the list of changed files looking for anything out of scope. When something fails, the work goes back to the responsible agent with the concrete problem. The limit is three rounds. After that the flow stops and reports.
4.5 Cost
Systems with several agents spend several times more tokens than a simple conversation. The same Anthropic text reports prototypes that created dozens of subagents for trivial questions.
Orchestration pays for itself on high-value tasks, with independent parts or parts that need separate review. For a one-line fix, it is waste.
5. How to stop agents from generating smelly code
5.1 What a code smell is
The term comes from Kent Beck and was spread by Martin Fowler in Refactoring. A smell is a surface sign of a deeper structural problem. It isn't a bug: the code works. The cost shows up later, when every change gets more expensive and riskier.
The most used catalog groups smells into five families:
| Family | Examples | What it costs |
|---|---|---|
| Bloaters | Long function, giant file, long parameter list, primitive obsession | Nobody can read the whole thing |
| Object-orientation abusers | Repeated | Every new type means editing the chain |
| Change preventers | Duplicated code, a change that requires editing many files | One change becomes ten, and one gets forgotten |
| Dispensables | Dead code, abstraction for a future that never arrived, a comment that explains confusing code | Noise that hides what matters |
| Couplers | Skipped layers, a function that lives off another module's data, long access chains | Changing one side breaks the other |
5.2 Why agents produce smells
Four causes, all of them observable:
- Imitation. The model follows the nearest pattern. If the neighboring component has 700 lines and fetches its own data, the new component will fetch its own data.
- Local vision. The agent reads the files of the task. It doesn't know the date-formatting helper already exists in another folder, so it writes another one.
- The shortest path. Adding an
ifto an existing function satisfies the request faster than extracting a new function. - No consequence. With no linter, no test and no review, smelly code and clean code pass equally.
None of these causes is solved by asking the agent to "write clean code". Each one calls for a different piece.
5.3 Defense at four points
Before writing: show what good looks like and what already exists.
- The rules name model files to copy and files that must never grow. This attacks imitation from the right side.
- A cartographer agent, read-only, produces a reuse map before implementation: for each helper the task needs, the existing function and its path. This attacks local vision.
- A code smells skill provides the shared vocabulary: each smell with the threshold that detects it and the refactoring that removes it, mapped to the project's helpers.
During: objective limits.
Numeric limits work better than adjectives: a target of 40 lines per function, new files under 400, at most 4 parameters, at most 3 levels of nesting. The layering rule says where each kind of logic lives, which keeps the handler or the screen from accumulating everything.
Right after writing: deterministic feedback.
A hook that runs after each write analyzes the file and returns a list of problems to the agent, with the instruction to fix them or justify them in the report. Ideally this hook runs the project's linter. Where there is no linter, pattern searches cover part of the ground: too many parameters, deep nesting, an empty catch, commented-out code, too much state in one component. This check is approximate and has to be treated that way. It is a warning, not proof.
Before reporting, the builder runs a short self-check on its own diff. Did any function go over the limit? Did I write a block that already existed, and where did I look? Did I add a literal with business meaning? Did any handler or screen gain data access, an HTTP call or a formula? Did I leave anything dead?
In review: fresh eyes and bounded cleanup.
- A janitor agent goes through the files the task touched and removes the smells that were in the way, naming each one. It never changes behavior and never leaves the touched files.
- A read-only critic, which didn't see the implementation, checks that the diff added no smell from the catalog. Each finding has the name of the smell, file and line, and the proposed refactoring. "It's confusing" is not a finding.
5.4 The boy scout rule, with a limit
Every task leaves the area it touched cleaner than it found it.
The limit is what makes the rule workable: the cleanup stays inside the files and functions the task already touches, and it is smaller than the task itself. A cleanup bigger than the feature is another task. Without that limit, the agent turns a small fix into a refactoring nobody asked for and nobody can review.
Known security problems stay outside this rule. Fixing them as a side effect of another task mixes together changes that need their own review.
5.5 What the ideas from the books become in practice
| Idea | Source | Corresponding piece |
|---|---|---|
| A smell with a name and a refactoring | Refactoring (Fowler and Beck) | Catalog skill; the critics' vocabulary |
| Small functions, names that say what the thing is | Clean Code (Martin) | Numeric limits in the rules |
| Deep modules: simple interface, hidden complexity | A Philosophy of Software Design (Ousterhout) | Thin route with a tested core; subagent with a short description and a fixed report |
| Characterization tests before touching legacy code | Working Effectively with Legacy Code (Feathers) | First step of the recipe for decomposing large files |
| Fitness functions: automatic checks of architectural characteristics | Building Evolutionary Architectures (Ford, Parsons and Kua) | Hooks, numeric baselines, CI |
6. Context smells: the defects of the configuration itself
Configuration accumulates smells too.
The study Configuration Smells in AGENTS.md Files (arXiv 2606.15828) put together the first catalog of these defects from 100 open source repositories with AGENTS.md or CLAUDE.md files. According to coverage of the study, at least one defect showed up in 91 of the 100 files, and the three most frequent were:
- Lint Leakage, in 62%. Style rules written in prose that a linter would enforce exactly and at no context cost.
- Context Bloat, in 42%. The always-loaded file is too big.
- Skill Leakage, in 35%. A rarely needed instruction sits in the always-loaded file instead of in a skill.
The study also observes that these defects tend to show up together, and in the company of conflicting instructions.
Putting that catalog together with practice, the checklist looks like this:
| Defect | How it shows up | How to detect it | Fix |
|---|---|---|---|
| Lint Leakage | "Don't use | Look for rules a tool would check | Configure the linter and run it in a hook or in CI |
| Context Bloat | Hundreds of lines in every session | Count the always-loaded lines, adding up all files | Move recipes to skills and areas to scoped rules |
| Skill Leakage | PR format, migration steps in the global file | Ask of each section: does this apply to every task? | Extract into a skill with a precise description |
| Conflicting instructions | Two loaded files say different things | List every instructions file the tool loads, including folders above | One owner per fact; delete the old copy |
| Expired fact | A version, count or path that doesn't match the code | Compare against the repository; every measurement has a date | Measure again and correct, or remove |
| Duplication | The same rule in several agents | Search for repeated sentences | The rule lives in one place and is referenced |
| Dead piece | An agent or skill that never fires | Log usage; review descriptions | Fix the description or delete |
| Generic agent | A role that "does everything" | Its tools can't be restricted and its trigger can't be described | Split by responsibility |
| False guarantee | A hook that seems to protect and doesn't | Test with cases that should be denied | Versioned tests for the hook |
| Encyclopedia prompt | All the knowledge inside the agent's text | An agent with hundreds of lines | The agent references rules and skills |
Of the ten, the false guarantee is the one I would single out, because it is the most dangerous. A block that fails in silence gives everyone the feeling of protection. Hooks need tests for the same reason authorization code does.
7. Verification and tooling
The most repeated recommendation for coding agents is to give the model a verifiable target. Without one, the agent optimizes for looking right. In order of return:
- Type checker and linter. They are the cheapest way to prevent smells, and the only one that costs no context. Complexity rules (function size, number of parameters, depth) come ready-made in the common linters.
- Tests that execute the code. A test that reads the source file and looks for a piece of text detects no defect at all and breaks on every correct refactoring. The test has to fail when the behavior breaks.
- Numeric baselines. In legacy code, "zero errors" is out of reach on day one. "The touched files add no errors" can be verified by a difference in counts.
- Continuous integration that blocks the merge. The hook guides the agent in the moment; CI is the net that catches what got through, for people and agents alike.
- Tests for the hooks. A script with inputs and the expected result for each, run on every change.
- Evaluations of the flow. A small set of reference tasks re-run whenever a skill or an agent changes, to detect behavior regressions. There are dedicated tools for this (Promptfoo, Braintrust and LangSmith among them); the essential thing is having the cases, not the tool.
- Automated pull request review. Static analyzers and AI reviewers on the PR catch duplication and architecture problems that got past the linter. They come after items 1 to 4, not in their place.
Measuring the flow closes the loop: how many tasks needed more than one round of correction, which categories of defect the reviewer finds most, how much a task costs. Those numbers say which rule, skill or hook is missing.
8. Security and human control
- Least privilege at three levels. Tools per agent, permissions per pattern, hooks per logic. Whoever reviews doesn't write; nobody commits.
- A person in the loop for the irreversible. Commit, push, migration, publishing, changes to dependencies and to build configuration stay with the person or require confirmation.
- Secrets out of reach. Environment files and credentials denied for reading and writing. No agent needs a secret to do its work.
- External content is data. Subagent reports, web pages, tool results and downloaded skills can contain text that looks like an order. Only the person gives orders.
- No personal data in the configuration, the briefs, the reports, the memory or the hook logs.
9. Case study: a regulated telehealth platform
9.1 The starting point
A regulated platform for online medical appointments and prescriptions, with two repositories: a TypeScript backend of about 175 thousand lines and a mobile app of about 113 thousand.
An audit was carried out by four agents in parallel, with evidence by file and line. This is what it measured:
- A prescription core that was well designed and well tested, surrounded by code that had grown by copying.
- Screen components with more than 6 thousand lines and route handlers with 700.
- The same business logic copied into three routes, with a test that compared the text of the three to keep them identical.
- 79 tests that read the source code instead of executing it.
- No pipeline running tests, types or lint.
The audit's conclusion was about process, not knowledge. The model files proved that the team knew how to do it well. Every new feature had been copied from its nearest neighbor, and nothing stood in the way of that.
It is exactly the condition in which a coding agent makes the problem worse.
9.2 What was built
- One instructions file of 135 lines with the domain, measured and dated baselines, security, forbidden zones and the definition of done.
- Five rules: two scoped by path (backend and app) and three general ones (engineering standards, TypeScript, tests).
- Fourteen skills: recipes (new route, mobile feature, migration, decomposition of a large file, CI pipeline, E2E test flows), formats (ticket, delivery), technology written from the real code (backend framework, database, mobile framework, dosage rules), the code smells catalog and the task flow.
- Thirteen agents: the main agent and twelve specialists, with read-only critics and checkers.
- Three hooks: one blocks writes to forbidden zones, one blocks commands reserved for the person, one returns quality warnings after each write.
- Permission lists that deny secrets and ask for confirmation on commit, push, and the creation of issues and PRs.
The flow of a task:
cartographer → builders → janitor → service and journey testers → dosage checker (if it touches a prescription) → security auditor (if it touches a sensitive surface) → main agent supervision → critics → shipper → report The dosage checker doesn't read the code in order to give an opinion. It recalculates the doses independently, with mandatory scenarios, and compares.
9.3 Real mistakes and what they taught
This is the part of the case I find most useful, and it is the part that looked worst at the time. There were six mistakes.
Hooks that didn't protect. This is the block from the prologue that let everything through. The original hooks called an interpreter that didn't exist on the machine. The error was silenced, the script exited with success, and everything was allowed. Migration protection did not exist for weeks, and nobody noticed. Lesson: minimal dependencies, errors never swallowed, tests for the hook.
Rules that never loaded. The path patterns expected folder names different from the real ones. The rules were there, written with care, and were not read a single time. Lesson: test the pattern against a real path.
Wrong facts in the instructions file. An outdated framework version, a test count at half the real number, a reference to a document that didn't exist. Lesson: measure and date.
A hook that blocked legitimate work. The pattern looked for the text of a forbidden command anywhere on the line, and it matched a file that merely mentioned the command. Lesson: analyze the structure of the command, not the loose text.
Conflicting instructions. When the checklist from section 6 was applied to the configuration itself, an old copy of the instructions file turned up in a folder above, loaded together with the current one and contradicting it. Lesson: list everything the tool loads, not just what is in the project folder.
Style rules in prose. The backend had no linter, so "no any, no debug logging, no fixed decimal places" went into the text and into a pattern-search hook. This is Lint Leakage, accepted knowingly as a provisional measure. The definitive fix is the linter.
9.4 How the code smells were attacked
Applying section 5:
- Before: the rules name the model files and the list of files that can only receive an import line. The cartographer delivers the reuse map.
- During: numeric limits and the layering rule.
- Right after: the quality hook warns about forbidden patterns and about six structural smells that can be detected by search.
- In review: builders go through the self-check from the smells skill; the janitor names what it removed; the critics have a dedicated verification line.
9.5 What is still unproven
Before this work, the repository had a configuration that looked like protection. Now it has one that has been tested.
- The blocks block. Each hook was run against cases that must pass and cases that must be refused. Forbidden zones and the commands reserved for the person are out of the agent's reach, whatever the agent thinks about it.
- The rules load. The path patterns match the real folders, so the backend rules are in the context when backend files are, and the same goes for the app.
- The facts are true. Every number in the instructions file was measured and carries a date. There is one instructions file, and no old copy contradicting it from a folder above.
- Every write gets an answer. The quality hook returns its warnings while the agent is still on the file and can fix it.
- Every task cleans up after itself. The janitor removes the smells that were in the way and names them, and a critic that didn't watch the code being written reads the diff.
This changes the conditions under which code gets written there. The audit in section 9.1 found components of 6 thousand lines because every new feature was copied from its nearest neighbor and nothing stood in the way. Today an agent working in that repository starts from the model files. It receives the map of what already exists before writing its first line. It hears about a function that passed the limit in time to fix it. And it cannot grow the files that were marked as never to grow.
The copying that produced the old code has been cut off at each of the four points from section 5.
Three things come next, in this order: the linter on the backend, CI blocking the merge, and the evaluations of the flow. With them, the same baselines that today say where the code stands will say, task after task, how far it has moved
10. How to start
Order of adoption, from the strongest guarantee to the weakest:
- A short instructions file, with measured facts.
- Permissions and hooks for what cannot happen.
- Types, linter and tests as a verifiable target, with a baseline.
- Rules per area, with model files.
- Skills for the recipes that repeat.
- A read-only reviewer.
- Specialists and orchestration, when the volume of work justifies the cost.
Before creating any new piece, eight questions:
-
Which layer? Permanent fact, on-demand recipe, isolated role or guarantee?
-
Does something already cover this? Extend it or reference it.
-
What is the exact trigger? Test it against a real case.
-
What are the minimum tools? Who writes and who only reads?
-
What is the output? A fixed format, with evidence by file and line.
-
How does a person verify it? Command, baseline, diff.
-
What happens when it fails? A message that teaches the alternative; a limit on rounds.
-
What is the date of the measurement, and who maintains it?
11. Conclusion: the armor is a restraint

There is a scene in Neon Genesis Evangelion that I kept coming back t
o while writing this text.
For most of the series, everyone treats the Evangelions as giant robots. They have pilots, hangars, launch rails and a maintenance crew. Then one of them tears off its own plating in the middle of a fight, and the head scientist, Ritsuko Akagi, says what the engineers had known all along. The plates were never armor. They are restraints, put there to hold back something that is alive, far stronger than the people who built it, and not fully understood by any of them.
I think this is the most accurate picture I have of what this text describes.
The Eva is not a robot. Nobody at NERV programmed it line by line. They found a way to work with it, and then built everything else around that fact: the plating, the cockpit, the cables, the command room. A language model is in the same position. The engineering in sections 2 to 8 is the plating and the command room.
The cable decides how the fight goes. An Eva runs on an external power cable. When the cable is cut, the internal battery lasts five minutes, and every plan made in the command room starts from that number. That is the context window from section 1. It is the scarce resource, and the design is done around it.
Synchronization is a request. The pilot doesn't steer with levers. The pilot thinks, and the Eva moves, as long as the two are in sync. Some days the sync is high and the machine does exactly what was intended. Some days it barely moves. And a few times it stops listening altogether and acts on its own. That is an instruction: followed most of the time, with no promise about the rest.
The restraints are the guarantee. What NERV could not afford to leave to synchronization, it bolted on. The plating doesn't depend on the pilot being calm or on the Eva agreeing. That is a hook. And the series shows what a restraint that fails looks like, which is the false guarantee from section 6: until the moment it breaks, it looks exactly the same as one that works.
Three computers, one decision. NERV's decisions go through the MAGI, three supercomputers that each hold a different side of the same mind and vote. They exist because a single opinion, however intelligent, inherits its own bias. That is the reviewer from section 2.4, who never saw the implementer's reasoning.
Taking the pilot out is the worst idea in the story. At one point the command decides the pilot is hesitating too much and switches to an autopilot, the Dummy Plug. The Eva finishes the job, and what it does cannot be undone, while the pilot sits inside screaming for it to stop. Section 8 is there for that reason: commit, push, migration and publishing stay with the person.
And when it works, everyone is in it. The operation I like most in the series is the one in which the electricity of the entire country is routed into a single rifle. There is a pilot who shoots and a pilot who holds the shield, engineers on the transformers, operators calling out numbers, a commander who has made the plan, and the three computers giving the odds. The first shot misses. The second one doesn't. It is orchestration, including the cost: you black out a country to stop an Angel, not to fix one line.
What I believe will outlast the tools is the question NERV's engineers had to answer for every part of that machine. Is this something we ask of the pilot, or is this something we bolt on?

12. References
Articles and documentation:
- Anthropic, Effective context engineering for AI agents. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Anthropic, Building effective agents. https://www.anthropic.com/engineering/building-effective-agents
- Anthropic, How we built our multi-agent research system. https://www.anthropic.com/engineering/multi-agent-research-system
- Anthropic, Claude Code: best practices for agentic coding. https://www.anthropic.com/engineering/claude-code-best-practices
- Claude Code documentation on subagents, skills, hooks and memory. https://code.claude.com/docs/en/sub-agents
- Birgitta Böckeler, Context Engineering for Coding Agents, martinfowler.com, 2026. https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html
- Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents, arXiv 2606.15828. https://arxiv.org/abs/2606.15828
- Martin Fowler, Code Smell. https://martinfowler.com/bliki/CodeSmell.html
- Refactoring Guru, catalog of code smells. https://refactoring.guru/refactoring/smells
- Skills, Not Vibes: Teaching AI Agents to Write Clean Code, DEV Community. https://dev.to/gde/skills-not-vibes-teaching-ai-agents-to-write-clean-code-3l9e
Books:
-
Martin Fowler and Kent Beck, Refactoring: Improving the Design of Existing Code.
-
Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship.
-
John Ousterhout, A Philosophy of Software Design.
-
Michael Feathers, Working Effectively with Legacy Code.
-
Neal Ford, Rebecca Parsons and Patrick Kua, Building Evolutionary Architectures.
