Code shows what a team delivered. It rarely shows why a behavior became the standard, why an exception was accepted, or which problem an interface set out to solve. While the work was done only by people who took part in those conversations, the gap could be covered by memory, review, and hallway questions.
With agents able to produce interfaces and code changes quickly, that compensation becomes more fragile. The agent finds components, names, and examples in the repository. If the reason for a decision stayed in a meeting, an old comment, or someone's head, it is not part of the context that guides the next change.
That is the central point of the experience Vercel describes: accepted product decisions are treated as code. They live in the repository, go through review, and are available to the agents working on that system. The consequence goes beyond documenting design. It turns product judgment into an explicit dependency of the delivery architecture.
Code preserves the pattern, not the intent
An agent can copy the look of a screen and reuse the right component. That does not mean it understands the reason for a choice. A short message may have been adopted because it removes a recurring doubt. A button may sit in a specific position because the flow needs to avoid an irreversible action. A seemingly redundant state may exist to guide recovery after a failure.
Without that explanation, the agent treats what exists as a collection of examples. It generalizes from the nearest case, even when visual similarity hides a difference in context. The implementation can compile, pass a visual snapshot, and still contradict a product decision that was already made.
The same applies to exceptions. A rule such as "use the confirmation component for destructive actions" is not enough if it does not record which actions were considered destructive, what information the user needs before confirming, and when the operation can be undone. The pattern helps execution; the decision explains the limit.
Versioned context is part of the architecture
Calling this material documentation can make it seem supplementary. In systems operated by agents, the distinction loses force. If the absence of a decision changes the result produced, that decision is part of the system that produces software.
There is no need to turn the repository into a long manual. Useful context is short and verifiable. For a decision, it is worth recording:
- the problem that needed to be solved;
- the chosen behavior and what was left out of scope;
- the reason that sets this choice apart from close alternatives;
- the signals that allow the decision to be revisited or retired.
That record can live next to the components, in a product decisions folder, or in a skill the agent loads. The location matters less than three properties: it has to be found by the workflow, it has to go through review, and it has to change when the product changes.
Vercel describes a setup with an agent skill, linters, and a review cycle that gathers evidence from Slack, Figma, and GitHub to propose updates to the guidelines. The operational detail can vary between teams. The architectural decision is the same: product context needs an owner, a source, and an update path.
The risk of freezing old decisions
Versioning a decision does not make it permanent. A repository can preserve patterns so efficiently that it also preserves choices that are no longer valid.
That is why each record needs to make its scope visible. A decision may apply only to one surface, to one type of user, or to a temporary integration constraint. Without that limit, the agent finds a rule that is true in one context and applies it as a general law.
Reviewing the context should also be part of the changes that consume it. If a new flow needs to open an exception, the pull request should not only change the interface. It should say whether the rule still holds, whether the exception is local, or whether the pattern needs to be rewritten. Review stops asking only "does the code work?" and starts asking "is the decision this code embodies still the right decision?".
What deserves to become context for agents
Not every design conversation needs to be archived. The most practical filter is to ask whether the absence of that information increases the chance of a plausible but wrong change.
First come the decisions that affect many paths: product vocabulary, error states, permissions, navigation patterns, required components, accessibility criteria, and boundaries between surfaces. Exceptions that seem to contradict a common rule also belong here. They are exactly what an agent cannot safely infer from an isolated example.
Cosmetic details and preferences without consequences do not need the same treatment. If a choice can change without affecting understanding, risk, or behavior, a shared token or component is probably enough context.
The decision for the team
Before asking agents to produce more screens, the team should list which product decisions today can only be recovered by asking a person. Then it can classify each one: coded pattern, documented decision, automatable rule, or judgment that still requires human review.
The goal is not to have the agent take part in every discussion. It is to reduce the space in which it has to guess. When the decision sits close to the code, the team gains speed without turning consistency into coincidence.
If your company is weighing something similar, reach me on LinkedIn or WhatsApp.
