Rahul Garg closes his series on reducing friction in AI-assisted development on Martin Fowler’s site with a pattern he calls the feedback flywheel: a structured practice that captures what individuals learn from AI sessions and routes those learnings back into shared team artifacts. It sounds obvious stated plainly, but teams consistently fail to do it.
I’ve been building Discord bots with AI assistance for long enough to know exactly how this failure happens. One developer figures out that prefacing every command generation request with the bot’s interaction lifecycle model produces dramatically better output. That developer ships cleanly for weeks. Everyone else on the team keeps getting half-correct code and fixing it manually. Nobody connects the dots until someone mentions it offhand in a standup. That’s a knowledge problem, not a tooling problem, and Garg’s flywheel framing is the right way to think about fixing it.
What the flywheel is actually made of
A feedback flywheel for AI-assisted development has four components: a trigger to reflect, a practice of harvesting the insight, a shared artifact to encode it in, and a mechanism to inject it back into the next AI session.
The trigger is the tricky part. Most teams don’t build in any deliberate reflection on AI sessions. A developer finishes a task, the context disappears, and whatever they learned about getting the AI to produce good output lives entirely in their working memory. Without a trigger, the flywheel never gets a first spin.
The harvesting practice is simpler than it sounds. After a session where AI assistance was notably effective or notably frustrating, you write down one sentence: what was different this time. Effective: “Gave it the full type signatures for our custom Discord embed helpers before asking it to generate a new command.” Frustrating: “Asked it to modify a file it hadn’t seen; it invented method names.”
The shared artifact is where this gets concrete. In a repo using Claude Code, that’s CLAUDE.md. In a Cursor project, it’s .cursor/rules. GitHub Copilot has .github/copilot-instructions.md. Every major AI coding tool now has a first-class project-level context file, and the teams using these tools well are the ones treating those files as living documentation, not setup boilerplate.
Here’s the difference between a CLAUDE.md that gets maintained and one that doesn’t. The one that doesn’t looks like this:
# Project Overview
This is a Discord bot. Use TypeScript. Follow good practices.The one that does looks like this:
# Architecture Notes
Commands live in `src/commands/<category>/<name>.ts`. Every command must call
`interaction.deferReply()` before any async work; omitting this causes
interaction timeouts that are silent in dev but visible as errors in production.
Embed utilities are in `src/utils/embeds.ts`. Use `buildInfoEmbed()` and
`buildErrorEmbed()` instead of constructing EmbedBuilder directly.
## Common Generation Errors
- Claude often generates `require()` instead of `import`. This codebase is ESM only.
- Claude often checks `interaction.replied` but forgets `interaction.deferred`.
If deferred, use `interaction.editReply()`, not `interaction.reply()`.
- The `ClaudeClient` is a singleton in `src/services/claude.ts`. Never instantiate a new one.
## What Has Worked
When asking for new commands: provide the full type signature of any helpers the
command should use, and reference the nearest existing command as a style example.The second version is a direct transcription of team learning. Every entry came from a real session where someone noticed a pattern and wrote it down. The “Common Generation Errors” section alone is worth hours of debugging time for the next developer who encounters the same wall.
The injection mechanism closes the loop. When the AI tool reads CLAUDE.md at the start of every session, the accumulated team knowledge becomes the starting context. The next developer doesn’t rediscover the ESM import requirement by trial and error; they never encounter the problem because the AI has already been told.
Why this is harder than it looks
The parallel to other forms of institutional knowledge is exact. Architecture decision records have the same lifecycle problem: they get created enthusiastically, then ignored as the codebase diverges from what they describe, then forgotten because nobody trusts them anymore. Runbooks and onboarding docs follow the same curve.
What’s different with AI context files is the feedback loop is immediate. When you update CLAUDE.md with a new rule and the next prompt generates correct code on the first try, you know the artifact is doing work. That tight feedback sustains the motivation to maintain it in a way that “write down decisions for future engineers” rarely does. The beneficiary is you, next week, not some hypothetical future hire.
But there are still organizational dynamics working against it. AI context files are invisible work. Nobody gets credit for updating CLAUDE.md. The developer who spends twenty minutes distilling three weeks of learning into a clean, precise entry has done something valuable, but it shows up in no metric, no PR diff that anyone comments on, no ticket closed.
Garg’s framing addresses this by making the feedback practice a team habit rather than an individual act of generosity. If harvesting learnings is part of the session ritual, not an optional add-on, it stops depending on individual motivation. The retrospective equivalent isn’t “does anyone have notes from the last sprint” but a specific slot in every task completion: what did the AI get wrong, what context would have helped it get it right, does CLAUDE.md capture that yet.
This is related to a deeper problem in team knowledge management. Insights that are discovered in conversation stay in conversation. The move from ephemeral to persistent requires a deliberate act, and that act needs to be habitual rather than heroic. James Clear’s framing in Atomic Habits applies here: the goal isn’t to have good intentions about documentation, it’s to make the documentation act small enough that it happens at the moment of insight rather than later, when context has faded and motivation has dropped.
The compound effect
Teams that build this habit accumulate something real over time. A CLAUDE.md maintained through six months of active development isn’t just project documentation; it’s a precise record of how this codebase differs from the median codebase the model was trained on. It captures the gaps between what the AI assumes and what the project actually requires.
That specificity compounds. A new developer joining the project gets, in a few hundred lines of markdown, the distillation of hundreds of AI sessions. They don’t start from scratch with the model; they start from where the team currently is.
The broader argument in Garg’s series is that reducing friction in AI-assisted development is mostly about removing the invisible tax on each session: the time spent re-explaining context the AI should already know, fixing errors it made for reasons the team has already diagnosed, rediscovering prompting patterns that worked last month. The feedback flywheel is the mechanism that eliminates that tax systematically, rather than one developer at a time.
The tools already exist. CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, and equivalent files are first-class features of every major AI coding tool because the vendors understand this pattern. The teams using AI well aren’t the ones with the most sophisticated prompts; they’re the ones with the most disciplined practice of writing down what worked and making sure it shows up next time.