Vercel Teaches AI Agents to Understand Product Decisions, Not Just Copy Code

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

Agents don't understand "why"

Modern coding agents handle tasks quickly: they write working UI, copy visual styles, repeat patterns from the repository. The problem lies elsewhere — they don't understand the reasoning behind these decisions. The logic of a specific component, wording, or interaction is usually stored in Slack threads, design review comments, remarks in PRs, and in the memory of people who were in that meeting. For an agent, this context doesn't exist: it works only with what made it into the codebase. Vercel approached the problem radically: all accepted product decisions now live in the repository alongside the code. They undergo review when changed and are automatically available to any agent working on the project.

What's inside the system

The system consists of three components. The skill lives in `.agents/skills/product-design/` right next to the code it governs. Inside are two key sections. `references/` contains documentation on product decisions, interface quality, resilience, copywriting, a glossary of terms, and `coverage-gaps.md` — a list of areas where the standard hasn't yet formed. `exemplars/` documents decisions from past PRs worth repeating, and mistakes to avoid. Linters automatically check everything that can be machine-verified. Everything that can be checked without human involvement should be checked without it. The update cycle collects signals from Slack, Figma, and GitHub, aggregates them, and prepares guideline updates for final team approval.

How the skill routes tasks

SKILL.md works like a router. First it determines the request mode: shape, implement, review, copy, or harden. This is fundamental — an audit shouldn't turn into editing, and a copywriting task shouldn't expand into redesign. The skill also skips tasks with no visible UI impact: backend-only logic, telemetry, generated files. After determining the mode, the skill routes to the appropriate sources based on task type and specific surface:

• Changes to interface materials load `product-judgment.md` and `interface-quality.md`
• Work with text leads to `copy.md` and canonical verb forms of the product
• Modal window — patterns for destructive actions and canonical verbs
• Settings form — labels, validation, progressive disclosure, accessible-name guidance

The skill doesn't duplicate sources: Component API, design-system rules, and accessibility criteria remain with their owners — the skill only references 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 demonstrated a concrete methodology for scaling product knowledge in teams with AI agents. Instead of relying on the 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 automatic checks. According to the authors, any team can build the same structure around their own standards.