The Knowledge Trap in AI-Assisted Development and How to Escape It

Rahul Garg’s feedback flywheel article, the conclusion to his series on reducing friction in AI-assisted development, addresses something that has been gnawing at me for a while: the productivity gains from AI coding tools compound for individual developers but almost never compound for teams.

Here is what I mean. When you spend a month working with Claude or Copilot on a particular codebase, you develop a mental model of how to get useful work out of it. You learn which context to include in your prompts, what kinds of tasks the model handles well versus where it tends to drift, how to structure a multi-step request so it doesn’t get confused midway through, and which project-specific conventions you have to spell out explicitly versus which ones the model can infer from existing code. This knowledge is real, valuable, and hard to acquire. It also lives entirely in your head.

When your colleague starts working with the same tools on the same codebase, they start from scratch. They make the same mistakes you made in week one. They learn the same lessons the slow way. If you leave the team, that accumulated knowledge is gone.

This is not a new problem in software engineering, but AI tools make it particularly acute because the knowledge involved is procedural and contextual in ways that are awkward to document. Nobody writes a wiki page titled “how I learned to phrase refactoring requests so the model doesn’t also reformat the file.” But that kind of micro-knowledge accumulates into a significant productivity gap between new and experienced AI tool users on a team.

What a Feedback Flywheel Does

Garg’s proposal is to treat AI session learnings as raw material for team artifacts, rather than letting them dissipate. The flywheel works in cycles: developers have AI-assisted sessions, reflect on what worked and what didn’t, extract reusable patterns, and encode those patterns into shared documents that future sessions can reference. Those sessions then produce new learnings, which feed into another refinement cycle.

The mechanism is simple. The discipline required to maintain it is not. The gap between understanding a flywheel in principle and actually running one is mostly about two things: what artifacts you’re populating, and how you build the habit of populating them.

The Artifact Layer

The most concrete implementation of this pattern is the AI context file. In Claude-based workflows, this is often called CLAUDE.md. In Cursor, it’s .cursorrules. In both cases, the idea is the same: a version-controlled document in the repository that tells the AI tool things about the project that aren’t obvious from the code itself.

A minimal version of one of these files looks like:

# Project Context for AI Assistants

## Architecture
This service is a Discord bot. The bot process is long-lived; avoid suggesting patterns
that assume request/response lifecycles.

## Conventions
- All Discord event handlers live in src/handlers/
- Config is loaded once at startup from environment; never re-read it at runtime
- We use Zod for runtime validation at boundaries; don't add it elsewhere

## Known Footguns
- The job scheduler (src/scheduler.ts) is not thread-safe; don't suggest concurrent modifications
- Discord rate limits are handled in src/discord/client.ts; don't add rate limiting elsewhere

This file is the crystallized output of many AI sessions. Every bullet point in the “Known Footguns” section probably represents a moment where a developer got a confidently wrong suggestion from the model, figured out why it was wrong, and had enough presence of mind to write it down.

The feedback flywheel turns that final step, “had enough presence of mind to write it down,” from an occasional act of good citizenship into a structured team practice.

Beyond Context Files

Context files are the most obvious artifact, but they’re not the only one worth maintaining. Teams running this kind of flywheel tend to build several layers:

Prompt templates: Reusable prompt structures for common tasks. A template for “add a new slash command to this bot” that includes the right context pointers, the expected output format, and notes on what to verify afterward. These are most useful for onboarding, where new team members can’t yet infer what context the model needs.

Decision documents enriched with AI context: Architectural decision records (ADRs) have been around for years, but they become more valuable in an AI-assisted workflow when they explicitly note the constraints that AI tools tend to violate. Not just “we chose SQLite over Postgres because of deployment simplicity” but also “when asking AI tools to add persistence, you need to explain this constraint or they’ll suggest Postgres.”

Anti-pattern logs: A running record of suggestions the model made that seemed reasonable but were wrong for this codebase, with explanations of why. This sounds tedious, but even a short list prevents the same mistake from happening to five different team members.

The commonality across all these artifacts is that they encode knowledge that can’t be derived from reading the code, and that AI tools in particular tend to lack because they have no memory of the conversations that produced the code in its current form.

Why This Is Harder Than a Retrospective

Teams already have mechanisms for capturing lessons learned. Sprint retrospectives, postmortems, and engineering wikis all exist precisely because individual experience doesn’t automatically become team knowledge. So why does the feedback flywheel need to be a separate practice?

Because the knowledge involved is different in character. Retrospective learnings tend to be about process and collaboration: “our definition of done needs to include deployment” or “we need earlier code review on large features.” Postmortem learnings are about system behavior under failure conditions. Wiki pages capture stable reference knowledge.

AI session learnings are more like operational runbook entries: highly specific, contextual, and perishable. The insight that “Claude tends to over-abstract when refactoring this module” is specific to this codebase, this module, and possibly this version of the model. It has a different lifecycle than architectural decisions, and it needs a home that’s lower friction to update than a wiki and more structured than a Slack thread.

There’s also a tacit knowledge problem. The most valuable AI session learnings are often the ones developers don’t think of as learnings. The mental adjustment you make when you realize you need to specify the file path explicitly in prompts for this project isn’t something you’d normally write down, because it feels like common sense once you know it. A structured reflection practice, even a lightweight one, creates the pause in which that knowledge can surface and get recorded.

The Compounding Effect

What makes this worth the overhead is the compounding dynamic. A team that runs this flywheel for three months has AI context files that encode months of collective experience. A new developer joining the team in month four starts with that context already loaded. Their first AI-assisted sessions are more productive than they would have been, which means they’re able to contribute to the artifact layer sooner, which accelerates the flywheel for the next person.

This is the inverse of how individual AI tool productivity works. An individual developer’s effectiveness with AI tools plateaus as they internalize the relevant context. A team’s effectiveness can keep compounding as long as they’re disciplined about externalizing that context.

The analogy I find useful is the difference between a developer who knows where all the landmines are in a legacy codebase and a team that has mapped them in a shared document. The individual developer is more productive, but only while they’re there. The shared map survives turnover and scales across new team members.

Making It Stick

The failure mode for this kind of practice is familiar: it gets set up thoughtfully, maintained for a few weeks, and then gradually abandoned as delivery pressure increases. The teams that sustain it tend to do a few things differently.

They make the reflection lightweight. A five-minute end-of-session note is more sustainable than a formal writeup. “What context did I have to provide that wasn’t in the existing docs?” is a prompt that takes thirty seconds to answer if you do it while the session is fresh.

They assign ownership. The context files and prompt templates are owned by someone, the same way a runbook or a deployment guide is owned. That person reviews PRs that touch those files and ensures the artifacts don’t drift out of date.

They close the loop explicitly. When a piece of context in a shared artifact actually helps someone, that someone says so. This sounds trivial but it matters for sustaining the practice. People need to see that what they’re contributing is being used.

Garg’s series as a whole has been making the case that AI-assisted development has a friction layer that isn’t about model quality, it’s about the practices and tooling around how teams use models. The feedback flywheel is the most team-level of those practices, and probably the most underinvested. Individual prompt engineering gets a lot of attention. The organizational practice of turning individual prompt engineering into team infrastructure largely doesn’t. That asymmetry is worth correcting.