Agent Collaboration

Patterns for working effectively with AI coding agents — from component generation to test writing to design system adherence.

AI agents reflect the quality of your input and codebase structure. This page covers collaboration patterns that maintain design system integrity, accessibility, and code quality. For shared repos with human contributors, see Collaborative Repository Workflow.

In brief:

Define the interface first, then let the agent fill in the body
Constrain output: tokens only, server/client boundary, semantic HTML
Review everything — plausible-looking code fails on edge cases
"Vibe coding" produces UI that looks right but fails systematically

Agent Collaboration Principles

1. Define the interface first

Write the spec. Let the agent fill in the body.

Good: spec-first

// Prompt: Generate this Disclosure component
// 1. Props: { title: string, defaultOpen?: boolean, children: ReactNode }
// 2. Pattern: Compound — Disclosure, Disclosure.Button, Disclosure.Panel
// 3. A11y: button aria-expanded, panel aria-labelledby
// 4. Styling: design tokens via className, no inline styles
// 5. Framework: React + TypeScript, "use client"

Bad: guess-the-shape

// Prompt: Make me a disclosure component
// — Agent guesses every decision, likely wrong

2. Give the agent a reference

Point to an existing component as a style reference.

Read the Button at src/components/ui/button/button.tsx
Generate a Badge following the same patterns:
- Same file structure, CVA variant approach, comment style, a11y treatment

3. Constrain the output

Constraint	Example prompt suffix
Design tokens	"Use only tokens from globals.css — no inline colour values"
Server/client boundary	"Server Component — no useState, useEffect, or event handlers"
Accessibility	"Semantic HTML, aria-* attributes, keyboard navigation"
Framework conventions	"Next.js App Router conventions: app dir, layout.tsx, page.tsx"

4. Review everything

Agents produce plausible-but-wrong code. Always verify: prop types, edge cases (loading/empty/error), ARIA correctness, token usage (not hard-coded), composability with existing components.

The most dangerous AI code looks right at a glance but fails edge cases. Write tests first, then generate implementation — catches more than post-hoc review.

Phase-by-Phase Agent Patterns

Design & Architecture Phase

Requirements Analysis

Feature description: [your notes]

Generate:
1. 5-8 functional requirements (FR-XX format)
2. One non-functional requirement per category (perf, a11y, security)
3. 2-3 Gherkin acceptance criteria per functional requirement
4. Assumptions and open questions

Design System & Tokens

Generate a Tailwind v4 globals.css:
- Primary: #2563eb, Secondary: #64748b
- Neutral: zinc-50–zinc-950
- Type scale: Major Third (1.25), Spacing: 4px base
- Include: primitive tokens, semantic tokens, dark mode, @theme inline

Component Architecture

Generate "ProjectStatusBadge":
- Status: "active" | "paused" | "completed" | "archived"
- Size: "sm" | "md" (default "md")
- Each status → distinct colour + label

Output: component + tests + barrel export + JSDoc

Build Phase

Component Scaffolding — Define the pattern once, generate the rest.

Pattern: Label above input, error below, helper between, consistent padding/font/border.

Generate: [email, password, name, bio, website]

Data Fetching

Generate a Next.js data layer for "teams":
1. Route handler: GET (list) + POST (create with Zod: { name, description })
2. Client hook: useTeams() with SWR — loading, error, empty states
   useCreateTeam() with SWR mutation — optimistic update

Design System Integration — Tell agents which library to use.

Using shadcn/ui Button + Dialog, create "ConfirmDeleteDialog":
- Trigger: variant="destructive" size="sm"
- Cancel + confirm (also destructive) buttons
- Focus moves to cancel on open

"Use shadcn/ui Tabs" beats "make a tabbed interface" — which generates raw divs.

Quality & Polish Phase

Testing — Highest-ROI task to delegate.

Integration tests for LoginForm:
1. Validation errors on empty email/password
2. Error on failed login (401)
3. Calls onSuccess on success
4. Disables submit while loading
5. Rate-limit error after 5 failed attempts
Cover: loading, validation, success, API error, rate limiting

Accessibility Audits

Review for WCAG 2.2 AA: [component code]
Check: missing ARIA, heading hierarchy, focus management,
colour contrast, keyboard gaps, missing labels, aria-hidden on focusables

Deployment Configuration

GitHub Actions workflow: pnpm install --frozen-lockfile →
pnpm lint (no fail on warnings) → pnpm test → pnpm build →
deploy to Vercel (main branch). pnpm, Node 22.

Vibe Coding Pitfalls

"Vibe coding" — describe what you want, accept AI output without review — produces interfaces that pass first glance but fail systematically.

Pitfall	What happens	Prevention
Token drift	Agent inlines `#2563eb` instead of `--color-primary`	Require token-only styling; diff for hard-coded values
Responsive gaps	Beautiful desktop, broken below 768px	Include responsive requirements in every prompt
State blindness	Happy path only	"Generate all states: loading, empty, error, success"
A11y shortcuts	`<div onClick>` instead of `<button>`	Require semantic HTML; run axe-core in CI
Framework assumptions	React patterns that break in Server Components	Tag prompts "Server Component" or "Client Component"
Bundle bloat	Entire libraries for one utility	Review imports; ESLint import restrictions