How to give an AI agent a project memory: rules, linters, examples and evals instead of magic

When a team first runs an AI agent inside a repository, the same illusion almost always arises: if you give the model access to the code, it will figure it out. On a short demo, that looks true. The agent finds the file, edits the component, runs tests, writes a clear summary. But in a live project, it quickly becomes clear that the code base is not enough. It has something that has already been done, but there is almost no answer to the question of why it was decided and where the team cannot improvise.

On June 25, 2026, Vercel detailed its approach to this problem: it is important for agents not only to access files, but also a layer of project memory that stores product solutions, rules and verification methods. This is a good wording for the entire industry. The problem today is not how to “connect AI,” but how to make it a predictable participant.

## Why Accessing an Agent’s Code is Not Enough

The AI agent reads the project structure well. It can see folders, dependencies, existing components, tests, and even the style of past commits. But almost every serious repository contains a lot of implicit rules. Why can't you pull a new library for one form? Why should a particular screen use only one navigation pattern? Why does this service necessarily have a security review before UI polishing? The answers don’t usually live in the code, but in the team’s heads, in PR comments, in documents, and in perennial compromises.

Because of this, the agent often fails not at the level of syntax, but at the level of meaning. He can offer a technically working solution that breaks the team’s internal contract. For example, add a second state source because it is shorter. Or lay a direct call to the service bypassing the common client, because it is easier to complete the task. The code is formally compiled. In fact, a new layer of chaos appears in the project.

This is where the memory of the project begins. The agent needs not just file visibility, but access to reasons, limitations, and quality criteria. Otherwise, each of his actions turns into a guess with a beautiful interface.

## AGENTS.md is the front door, not the entire memory of the project

Wikivibe has already been discussing why AGENTS.md is needed. This is an important first step: the file actually works as a contract between the project and the agent. It helps to quickly explain the stack, boundaries, editing rules, and prohibitions that cannot be broken without separate approval. For a new project or for the first Codex integration, this is often enough to drastically reduce the number of random edits.

The problem begins when a team tries to fit everything into a single file. After a couple of weeks, it turns into a long sheet: there are rules on architecture, and bans on libraries, and product solutions, and pieces of design system, and half-broken checklists that no one updates. The agent reads such a document as a noise. The man, too.

Therefore, it is more useful to look at AGENTS.md as the front door. He must answer three questions: what kind of project is it, what routes the agent follows for the rules and in what mode to make decisions. And the rules themselves are better laid out deeper: by reference files, by surface-specific instructions, by linters, by test scenarios, by examples of decisions already made. Then the agent has not one heavy memo, but a clear map of the area.

## What in practice is the memory of the project

The most useful view of the project memory is this: it is not a document, but a system of several layers, each of which solves its own problem.

The first layer is rules and reference files. This is what explains to the agent how the team thinks about the code and the product. There are architectural constraints, naming conventions, boundaries between layers, rules for UI scenarios, security requirements, descriptions of acceptable patterns. It is important that these rules are not abstract but observable. Don’t “write carefully” and “don’t add a new state manager without approval.” Don’t “make good UX,” but “for two or three fixed options, use radio instead of select.”.

The second layer is linters and automatic checks. Anything that can be tested deterministically, it is better to give the machine. If the team cannot use arbitrary classes for the theme of the button, it should catch the linter, not a tired reviewer on Friday evening. If the modals cannot be embedded in each other, this should also be fixed by automatic verification. The memory of the project becomes stronger when part of the rules is not just described, but executed.

The third layer is exemplars and anti-exemplars. It is very useful for agents to see not only an abstract rule, but also an example of a solution that the team has already found successful. This can be PR, where the destructive flow is well implemented, or a screen where error processing is correctly arranged. Nearby, it is useful to keep bad examples: what already broke UX, what complicated support, what decisions had to roll back.

The fourth layer is coverage gaps and evals. If the team does not yet know how to standardize a part of the interface or process, it is better to fix this gap explicitly than pretend that the standard is already enough. Coverage gaps tell the agent that you can’t make too bold decisions. And evals allow you to check whether the behavior of the agent changes after updating the rules. This is especially important when the instructions seem to have improved, and the actual changes in the project have not improved.

## How MCP, tools, and project memory are related

There is often confusion at this place. Many people hear about MCP and think that it solves the problem of quality of agency work. In fact, MCP covers another part of the story. Model Context Protocol is needed so that the model can connect to tools, data and workflow in a standardized way: read documentation, access CMS, open internal services, search for artifacts, run safe actions.

This is a very important layer, but it does not replace the memory of the project. An MCP can give an agent access to a design, ticket, knowledge base, or CI. But he does not answer the question of how to use these tools in a particular team. Two projects can connect the same set of tools and get a completely different quality of the result, because in one place the agent has clear rules for making decisions, and in the other - only the right to call something.

Simply put, MCP leads to the tool cabinet. The project memory explains which tool to take, at what point, who then checks the result and what counts as a mistake. One without the other gives either a blind performer or a well-informed but helpless theorist.

## How to build such a system without bureaucracy

The good news is that you don’t need a separate agency architecture committee to get started. You can start with a very down-to-earth question: What comments does the team write over and over again? If this is the third time you explain that you can’t bypass a common API client in this project, this is the candidate in memory of the project. If designers and developers regularly argue about the same empty-state pattern, then the rule is not packaged where the agent can read it.

Then it is useful to move in small layers. First, build a short AGENTS.md, which routes the agent: where the architectural rules lie, where the UI restrictions are, where the security restrictions are, when you need to ask a person. Repeat decisions in separate reference files next to the code. After that, see what can be turned into a linter or a test. And only then add exemplars, anti-exemplars and evals, so that the system is not a set of declarations without feedback.

Another practical technique is to keep the rules as close as possible to the place of application. Do not put everything in one folder “docs about AI”, but keep the interface solutions next to the design system, the architectural solutions next to the backend diagram, and the restrictions on changes in the root router file. The museum does not look like a separate museum. It becomes part of the working repository.

## What mistakes do agent workflow break most often

The first mistake is believing in one magical file. The team writes a huge AGENTS.md, scores everything there and expects the agent to figure out which points are more important. Usually, the opposite happens: the useful signal dissolves in the text, and the document ceases to be supported after a couple of sprints.

The second mistake is irrelevant rules. An agent is especially dangerous where the instructions differ from the actual code. If a document says “only use one logging method” and the repository already has three, the model won’t know what to believe. It will begin to mimic the nearest example, and the team will assume that the problem is a model, although the problem is in a contradictory context.

The third mistake is to fully automate product solutions. Linters, skills and evals work well on repeatable rules, but do not replace engineering and product judgment. You can't just formalize everything important and keep people out of the process. As the product changes, the rules change. Therefore, the memory of the project should be a living system with owners, not an archive of wishes.

## What the team gets in the end

If done correctly, the effect is felt quite quickly. First, the number of strange AI edits that seem to work, but require a long manual parsing, drops. Second, the review becomes shorter and more meaningful: the discussion shifts from basic bans to real trade-offs. Thirdly, the agent begins to work more stable. Not because the model suddenly got smarter, but because it had good boundaries and a good map of the project.

For VibeCode, this is perhaps one of the major shifts of 2026. We used to talk about which model is better. Increasingly, we have to discuss what context the agent gets and how the team codes its own decisions. This is where the difference is born between a demo that impresses five minutes and an AI workflow that withstands a real product.

In the dry residue, the rule is simple: access to the repository gives the agent eyes and hands. The memory of the project gives it guidance. And the engineering process decides whether it turns into a useful assistant or another source of expensive surprises.