Vercel teaches AI agents the reasoning behind product decisions, not just how to copy code

Vercel has published a detailed description of its product-design system, a toolkit that helps AI agents not just copy style and patterns, but understand why a given component, phrase or interaction became the standard in the product.

Agents don't understand the "why"

Modern coding agents get tasks done fast: they write working UI, copy visual style and repeat patterns from the repository. The problem lies elsewhere: they don't understand the reasons behind those decisions. The logic of a specific component, wording or interaction usually sits in Slack threads, design review comments, PR replies and the memories of the people who were in the meeting. For an agent, that context doesn't exist: it works only with what made it into the codebase.

Vercel took a radical approach to the problem: all product decisions now live in the repository alongside the code. They go through review when they change and are automatically available to any agent working in the project.

What's inside the system

The system has three components.

The skill lives in `.agents/skills/product-design/`, right next to the code it governs. It has two key sections. `references/` contains documentation on product decisions, interface quality, resilience and copywriting, a glossary of terms, and `coverage-gaps.md`, a list of areas where no standard has been established yet. `exemplars/` documents decisions from past PRs worth repeating, and mistakes to avoid.

Linters automatically check everything that can be verified by machine. Anything that can be checked without a human should be checked without one.

The update loop gathers signals from Slack, Figma and GitHub, aggregates them and prepares guideline updates for the team's final approval.

How the skill routes tasks

SKILL.md works as a router. First it determines the request mode: shape, implement, review, copy or harden. This matters: an audit should not turn into editing, and a copywriting task should not grow into a redesign. The skill also skips tasks with no visible UI impact: backend-only logic, telemetry, generated files.

Once the mode is set, the skill routes to the right sources based on the task type and the specific surface:

• Changes to interface materials load `product-judgment.md` and `interface-quality.md`
• Work on text leads to `copy.md` and the product's canonical verb forms
• A modal window brings in destructive-action patterns and canonical verbs
• A settings form brings in labels, validation, progressive disclosure and accessible-name guidance

The skill does not duplicate sources: Component API, design-system rules and accessibility criteria stay with their owners, and the skill only links to them.

"Code shows agents what was shipped, but not why this particular component or interaction became the standard," from

Vercel's documentation.

What this means

Vercel has shown a concrete method for scaling product knowledge in teams that work with AI agents. Instead of counting on an agent to "guess" the intentions of designers and managers, the company codified them and made them part of the repository, with change history, review and automated checks. According to the authors, any team can build the same structure around its own standards.