The most expensive failure mode in an agent-augmented team is not the agent making mistakes. It is the team catching the same mistake over and over and never doing anything about it.
A reviewer reads the diff. They notice the agent reached into the wrong layer of the stack. They leave a comment. The author fixes it. The PR merges. Three days later, on a different feature, the agent does the same thing. A different reviewer catches it. A different comment. A different fix.
This is not a problem of agent capability. The team knows the rule. The agent does not. There is no path between the reviewer's brain and the agent's next session.
The flywheel is the path.
What a flywheel actually is
Every review comment is one of two things: a one-off ("you misnamed this variable") or a class of issue ("we never reach into the database from the controller layer"). The first kind is fine to handle in the PR and forget. The second kind is the entire population the agent will keep producing variations of, forever, unless the harness learns.
A flywheel is the loop that converts the second kind into durable change. It has three steps and they are all boring:
- A reviewer notices a pattern they have flagged more than once.
- The pattern is encoded as a rule, in the rules file the agent reads at the start of every session.
- The next agent run gets the rule in context and follows it.
Done. The reviewer never has to flag that specific thing again. The system absorbed the lesson.
The tooling matters less than the loop. Bridle ships a /bridle:learn command precisely to make step two cheap; you can do the same thing manually by opening the rules file and adding a sentence. What matters is that step two actually happens, in some predictable way, every time step one occurs.
Why most teams skip it
The flywheel is conceptually trivial. In practice, almost no one runs it consistently.
The usual reasons:
The reviewer is in flow on something else. Writing a comment takes ten seconds. Updating the rules file takes two minutes and requires opening a different file, picking the right section, and writing it in a way the agent will actually internalize. The marginal cost is small but it is exactly the cost that gets skipped under load.
Nobody owns the rules file. Everyone could edit it. So nobody does. The same pattern that turns shared documents into stale documents turns rules files into stale rules files.
The team is not sure the rule is general enough. "Is this a one-off or a class?" is a real question and the cautious answer is always "leave it for now." Cautious answers accumulate into a backlog of unencoded knowledge.
The rule already exists, in spirit, somewhere. The team has a wiki page that says something close. The CLAUDE.md mentions the principle. The senior engineers know it. None of that helps the agent unless the rule is in the file the agent loads.
What the ritual looks like
The shortest version of the practice that works:
When a reviewer leaves a comment that they have left before, on this PR or another, they commit a one-line note to the rules file in the same PR they are requesting changes from. Not later. Not in a follow-up. Same PR. The author of the PR can push back on the rule itself if they disagree, but the default is that the rule lands.
The rule should be the smallest concrete statement that would have prevented the diff under review. Not a principle ("we value clean architecture"). Not an essay. A sentence with a verb the agent can act on. "Controllers do not call repository methods directly; route all data access through the service layer." That kind of thing.
Once a week, somebody (rotating or assigned) reads the rules file end to end and prunes. Rules that turned out to be wrong get deleted. Rules that have been superseded by a linter or a type get deleted. Rules that nobody can remember the origin of get a link added back to the PR that spawned them, or they get deleted. The file stays alive because someone is keeping it alive.
That is the entire practice.
Bridle also has commands to make auditing both the code and the harness easy, as well as the ability to produce a debt map. This step does not have to be painstaking.
What the flywheel produces over time
The interesting property is that the file gets better with use, not worse. A team that runs the loop for six months ends up with a rules file that is essentially a compressed log of every mistake the agent has made in their codebase and the team's correction to it. New engineers, human or agent, inherit that history for free. The patterns the original team had to learn through painful review cycles become things the next session of the agent simply knows.
This is the same property that makes a mature deployment pipeline valuable. The pipeline is institutional memory enforced by automation. The rules file is institutional memory enforced by being loaded into context. Both work for the same reason: they do not depend on anyone remembering anything.
A team running the flywheel is, after a year, a meaningfully different team from one that is not. The drift is slow and the difference compounds. The team that fed the flywheel has a harness shaped to their codebase. The team that did not has the same generic harness it started with, plus a Slack channel full of recurring complaints.
Start tomorrow
If you want to start, the smallest move is this: the next time you leave a review comment that feels familiar (one you have left before, in any form) open the rules file and write one sentence that would have prevented it. Merge the rules update with the PR. Tell the rest of the team what you did and why.
That is the entire flywheel, running once. Do it twice next week. Do it five times the week after. The discipline is in the boring repetition; the rest of the value follows.
Top comments (0)