AI Agents Master Code but Ignore the Essence of Products

The Limits of AI Agents in Product Understanding

AI agents specialized in coding are capable of reading and analyzing the source code of applications. However, their ability to produce truly relevant results is often limited by their lack of understanding of the product's design context. This context includes essential elements such as the product's behavior, the specific interaction patterns it adopts or rejects, and the characteristics that define its unique identity. To address this gap, a skill called Claude Code has been developed. It aims to enhance the capabilities of AI agents by providing them with a more comprehensive and relevant framework.

Understanding the Product Beyond the Code

For an AI agent to truly understand a product, it must integrate seven distinct types of knowledge. These insights go far beyond what is typically recorded in a simple README file. They include:

• Architecture: This includes the services used, databases, authentication methods, data flows, as well as the strict constraints governing the system.

• Functionality: This pertains to end-to-end workflows, the domain entity model, and product surfaces.

• Technical Stack Conventions: This covers elements such as the use of yarn or pnpm, monorepo structure, pre-completion checks, and import rules.

• Brand Voice: The axes of tone, vocabulary for calls to action (CTA), text patterns, and anti-patterns fall under this category.

• Visual Identity: Includes fonts, weights, ray families, shadow hues, and color usage rules.

• Interaction Principles: These are the specific UX positions related to the product that generic agents might overlook.

• Positioning: This describes what the product is, what it is not, its differentiators, and the competitors it stands out from.

Together, these elements form the design context, a blurred boundary between design and engineering that the agent must understand to be effective.

The Limitations of a Traditional README

A README file typically serves as a map of the system, but it cannot capture the unique character of the product. While it is possible to describe the architecture or list entities in a README, it is challenging to include more subtle details such as token preferences, specific exceptions at breakpoints, or strict rules accumulated over time. These elements are crucial for an AI agent that needs to understand the product before it can effectively contribute to its development. Mature design systems, such as Shopify Polaris or Atlassian's design system, provide examples of documentation that go beyond simple technical specifications.

Developing the Claude Code Skill

To bridge this gap, the design context has been transformed into a Claude Code skill. This repository is automatically populated when you work on the product and contains several key files:

<product>-context/
├── SKILL.md                      # router
├── design.md                     # UI / UX / brand / visual / philosophy
├── pointers.md                   # index of referenced documents
├── quickref/
│   ├── component-map.md          # Figma → code index
│   ├── tokens.md                 # color/type/radius/shadow cheatsheet
│   └── commands.md               # pre-completion check rituals
└── references/
    ├── overview.md               # monorepo structure, application map, shared packages
    ├── functionality.md          # flows, entities, surfaces
    ├── system-analysis.md        # services map, authentication, data flows, constraints
    ├── typescript.md             # stack conventions
    ├── python.md                 # backend conventions
    ├── figma-component-mapping.md
    └── frontend/
        ├── ui-package.md
        ├── styles-package.md
        └── styles.md

The SKILL.md file acts as a router, determining which file should be loaded for a given task. For example, to write UI text, it refers to section 2 of design.md on brand voice. For functionality brainstorming, it directs to functionality.md and design.md. This router ensures disciplined use of the context.

Creation Process

The development of this skill did not happen all at once. The order of development was crucial.

First Step: Architecture and Functionality

These two aspects can primarily be derived from existing code. A sub-agent was directed to the code to draft an overview of the architecture, a services map, the authentication model, and data flows. Another sub-agent was used for functionality, focusing on end-to-end flows, the entity model, and surfaces. Each task took about two hours, followed by light editing.

Second Step: Technical Stack Conventions

The files typescript.md, python.md, and other frontend-specific documents were created. These are also primarily derivable from the code: which package manager is used, what linter is in place, and what rules must never be broken. The agent drafted a document based on existing configurations, which was then edited to include non-visible but essential rules.

Third Step: design.md, the Major Challenge

This part cannot be automatically generated by an agent. While the agent can list tokens, it cannot understand elements like the fact that the main CTA must be emphasized. The design.md file was written in layers:

• Tokens: Includes colors, typographic weights, spacings, radii, and shadows.

• UX Patterns: Empty state conventions, warning tips, etc., which exist in the code but are not obvious without labeling.

• Brand Voice: Axes of tone, CTA vocabulary, and anti-patterns. Each rule is anchored in a real chain of code.

• Aesthetics: Encompasses composition principles, color philosophy, and signature details.

• Explicit Anti-Patterns: Descriptions of what the product is not, with a self-validation test.

Tokens are readable by the agent, but the composition philosophy must be learned.

Fourth Step: The Router

The SKILL.md file is concise, with fewer than 150 lines. It uses YAML frontmatter with trigger phrases to guide the agent to the appropriate files based on the task at hand.