There is a gap that most developers do not think about until it causes a problem.
The AI you use every day has been trained on enormous amounts of React code. It knows the patterns. It knows the hooks. It knows how components should be structured, how TypeScript integrates, how state management libraries work, what the common anti-patterns are and how to avoid them.
It is genuinely knowledgeable about React as a technology. More knowledgeable than most developers who use it.
And it knows absolutely nothing about your React project specifically.
Not how you structure features. Not what naming conventions your team has settled on. Not where state belongs in your architecture. Not what your component boundaries look like. Not what patterns you have deliberately chosen and which ones you have deliberately avoided. Not the decisions that took months of iteration to arrive at and that define how this particular codebase works.
Every session starts with the same AI that knows everything about React and nothing about yours. And then it generates code. And then you wonder why the output does not quite fit.
The difference between knowing React and knowing your project
React knowledge is general. It applies to every React project that has ever existed or will ever exist.
Project knowledge is specific. It only applies to this codebase, this team, this set of decisions, this particular way of solving the problems this product has.
A developer who knows React but not your project can still write good React code. It just will not fit your project without guidance. You would onboard them. You would explain the architecture, the conventions, the decisions that define how things are done here. You would give them the context they need to make their general React knowledge useful in your specific situation.
The AI gets no such onboarding. It shows up with all its general React knowledge and starts generating based on that plus whatever it can infer from the files around the current work. Which is never enough to substitute for actually knowing the project.
The result is React code that is technically correct and contextually wrong. Code that follows best practices for React as a technology while ignoring the specific practices of your particular project.
What the AI is actually doing when it generates
When the AI generates a component for your project it is making decisions.
Where does this state belong? What should this be named? How should this component be structured? What is the right way to handle this type of interaction given the patterns I can see around me?
These are not trivial decisions. They are exactly the kinds of decisions that experienced developers on your team make quickly because they have internalized the project's standards. They know the answer before they have to think about it because the answer has been established over months of building together.
The AI does not have that internalized knowledge. It has general React knowledge and whatever it can read in the immediate context. So it makes the best decision it can with what it has. Which is often a reasonable React decision that is not your project's decision.
Every session. Every component. Every hook. Every time it names something or decides where something belongs or chooses how to structure a piece of logic, it is working from general knowledge in the absence of specific rules.
And the output reflects that. Not because the AI is bad at React. Because nobody told it how your project works.
What your project knowledge actually consists of
Most developers do not think of their project knowledge as something that can be written down and transferred. It feels too embedded, too contextual, too much like intuition built up over time.
But when you look at what actually constitutes project-specific knowledge for an AI, it breaks down into surprisingly concrete things.
Architectural decisions. Where does logic live? What is the layer structure? What goes in a hook versus a service versus a component? These are not vague preferences. They are decisions your team made and has been following. They can be written as rules.
Naming conventions. What are event handlers called? How are hooks named? What is the pattern for boolean props? What domain language does this project use? These are specific and writable.
Component boundaries. When does a component get split? What is the maximum scope of a single component? What makes something presentational versus container? Again, specific and writable.
Import and module structure. How are features organized? What can import from what? Where do shared utilities live? How are public APIs defined for each feature? Completely writable.
Patterns to use and patterns to avoid. What has your team tried and rejected? What approaches work well in this codebase specifically? What does good look like here, beyond what good looks like in React generally? Writable.
None of this is too contextual or too intuitive to write down. It just has never been written in a form the AI can use before a session starts.
The gap between what the AI knows and what it needs
The AI's React knowledge is genuinely comprehensive. It knows what it knows about React deeply and accurately.
The gap is not in its React knowledge. The gap is in everything that is specific to your project that cannot be derived from general React knowledge alone.
Think about the last time you corrected AI output. What was the correction? Was it a React mistake, something that violated React best practices or introduced a technical error? Or was it a project mismatch, something that was technically fine React but not how things are done in your codebase?
For most developers it is almost always the second category. The AI knows React. What it does not know is your project's specific application of React. And that is the gap that rules close.
Here is what closing that gap looks like in practice:
Project-specific rules that the AI cannot derive from React knowledge alone:
1. Features are self-contained modules. Each feature has its own components, hooks, services, and types folder. External access goes through the feature's index file only. No direct cross-feature imports.
2. State scope is determined before writing any code. Local state stays in the component or a dedicated local hook. Shared state only moves to a global store when two independent features genuinely require it. Auth state is local to the auth feature unless another feature explicitly needs it.
3. Component names reflect what they render, not where they are used. UserCard, not ProfileUserCard. ProductList, not ShopPageProductList. The name travels with the component, not with the page.
4. All API responses are transformed in the service layer before they reach a hook or component. UI components receive domain objects, not API shapes. If the API changes, only the service layer changes.
5. Loading, error, and empty states are defined before building the happy path. No component ships without explicit handling for all three. The pattern for each is consistent across the codebase.
These five rules are not derivable from React knowledge. They are specific to how your project has decided to apply React. Written down and given to the AI before a session starts, they close the gap between what the AI knows about React and what it needs to know about your project.
What changes when the gap is closed
The most immediate change is in the corrections.
The category of correction that accounts for most of the time spent steering AI output — the project mismatch corrections — disappears or shrinks dramatically. The AI is no longer making decisions based on general React knowledge in the absence of specific rules. It is making decisions based on your project's specific application of React.
The components look like they belong. The naming matches what is already there. The structure follows the pattern. The state ends up where you would have put it. The imports follow the module rules.
This is not the AI getting better at React. It is the AI finally having the project knowledge it needed to apply its React knowledge correctly.
Beyond the immediate sessions, something more significant changes over time. The codebase starts to accumulate consistent decisions instead of varied ones. New features look like existing features because the same rules that governed the existing ones governed the new ones. The project develops a coherence that is hard to achieve when every session is working from general knowledge alone.
The session is not the problem. The missing project context is.
Most attempts to improve AI output focus on the prompt. Better descriptions. More detailed instructions. More context included in each request.
These help at the margins. A better prompt produces better output for that specific request. But it does not solve the underlying problem, which is that the AI does not know your project and has to guess at every session-specific decision it makes.
Rules solve the underlying problem. They give the AI the project knowledge it cannot derive from its React training. They close the gap between knowing React and knowing your React project.
Write them before the session. Not in the prompt. In a system that applies them to every session, every developer, every request. And stop spending session after session teaching the AI things it should have known before it started.
The prompt does not matter. The rules do.
Your AI knows React. That knowledge is real and valuable and it makes your sessions faster than building without AI would be.
What your AI does not know is your project. And without rules that transfer that project knowledge, every session is working from general knowledge in a specific context. The output reflects that. Every time.
Write the rules. Give the AI the project knowledge it needs. And close the gap between knowing React and knowing your React project.
Want to find where your React project knowledge is missing from your AI setup?
I built a free 24 point checklist that helps you find exactly that. The specific project decisions that your AI is currently guessing at because nobody wrote them down as rules.
→ Get the React AI Clean Code Checklist — free
→ Avery Code React AI Engineering System
The prompt doesn't matter. The rules do.
© Avery Labs — Avery Code
Top comments (0)