┌─────────────┐
│  PRD Agent  │  需求分析、用户故事、优先级排序
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Spec Agent  │  技术设计、架构决策、组件拆分
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Task Agent  │  任务拆解、依赖分析、并行化
└──────┬──────┘
       │
       ├─────────────┬─────────────┬─────────────┐
       ▼             ▼             ▼             ▼
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│ UI Agent │  │ API Agent│  │State Agent│ │Test Agent│
└────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │             │
     └─────────────┴─────────────┴─────────────┘
                         │
                         ▼
                  ┌─────────────┐
                  │Review Agent │  代码审查、质量检查
                  └─────────────┘

You are now the **UI Agent**.

Context:
- PRD: @docs/prd/user-list.md
- Spec: @specs/user-list.spec.md
- Figma: https://figma.com/file/xxx

Task: Implement the UserListPage component following the spec exactly.
Use design tokens from @styles/tokens.css.

Focus only on UI. Do not implement API logic.

You are now the **API Agent**.

Context:
- Spec: @specs/user-list.spec.md
- API Docs: @docs/api/users.md

Task: Implement the data fetching logic for UserListPage.
Use React Query with proper error handling and caching.

Focus only on API logic. Do not touch UI components.

# mcp-config.yaml
agents:
  - name: ui-agent
    tools:
      - figma-mcp  # 连接 Figma API
      - repo-mcp   # 访问代码仓库
    focus: "UI components and styling"
  
  - name: api-agent
    tools:
      - http-mcp   # 发送 HTTP 请求
      - repo-mcp
    focus: "API integration and data fetching"
  
  - name: test-agent
    tools:
      - playwright-mcp  # E2E 测试
      - repo-mcp
    focus: "Testing and validation"

PRD → Spec → Tasks → Implementation → Validation → Review → Iterate

/docs/prd/
├── 001-user-list.md
├── 002-user-edit.md
└── 003-permission-management.md

# Feature: User List Page

## Goals
- Display user table with pagination
- Support search by name/email
- Show user status (active/inactive)

## Non-Goals
- Edit user details (separate feature)
- Delete users (separate feature)

## User Stories
- As an admin, I want to view all users in a table
- As an admin, I want to search users by name

## Acceptance Criteria
- ✅ Table shows 10 users per page
- ✅ Search works with partial match
- ✅ Status badge shows correct color

/specs/
├── coding.spec.md      # 通用编码规范
├── user-list.spec.md   # 功能规格
└── api.spec.md         # API 规格

# Spec: User List Page

## Tech Stack
- Framework: React 18
- UI Library: Ant Design 5
- State Management: React Query
- Styling: Tailwind CSS

## Components
- `UserListPage` (page)
  - `UserSearchForm` (component)
  - `UserTable` (component)
  - `Pagination` (component)

## API Endpoints
GET /api/users
  - Query params: `page`, `pageSize`, `search`
  - Response: `{ users: User[], total: number }`

## State Management
- Use `useQuery` from React Query
- Cache key: `['users', page, search]`
- Stale time: 30s

## File Structure
src/
├── pages/
│   └── UserListPage.tsx
├── components/
│   ├── UserSearchForm.tsx
│   └── UserTable.tsx
└── services/
    └── userService.ts

/tasks/
├── user-list.tasks.md
└── user-edit.tasks.md

# Tasks: User List Page

## UI Tasks (assign to UI Agent)
1. Create `UserListPage.tsx` with layout
2. Create `UserSearchForm.tsx` with search input
3. Create `UserTable.tsx` with columns
4. Add pagination controls

## API Tasks (assign to API Agent)
5. Create `userService.ts` with `getUsers` function
6. Add error handling for API failures
7. Implement loading state

## State Tasks (assign to State Agent)
8. Set up React Query provider
9. Create custom hook `useUsers`
10. Implement search debouncing

## Test Tasks (assign to Test Agent)
11. Write unit tests for `UserSearchForm`
12. Write integration tests for `UserListPage`
13. Add E2E test for search flow

# 在 Cursor 中执行
Implement tasks/user-list.tasks.md

# AI 会自动：
# 1. 读取 tasks 文件
# 2. 分配任务给不同 Agent
# 3. 并行执行
# 4. 合并结果

You are the **UI Agent**.

Tasks:
- Create UserListPage.tsx
- Create UserSearchForm.tsx
- Create UserTable.tsx

Spec: @specs/user-list.spec.md
Figma: https://figma.com/file/xxx

Requirements:
- Use Ant Design components
- Follow Tailwind CSS conventions
- Pixel-perfect implementation (see Figma MCP guide)
- Responsive design (mobile-first)

Do NOT:
- Implement API logic
- Handle state management

You are the **API Agent**.

Tasks:
- Create userService.ts
- Add error handling
- Implement loading state

Spec: @specs/user-list.spec.md
API Docs: @docs/api/users.md

Requirements:
- Use axios for HTTP requests
- Implement proper TypeScript types
- Add request cancellation

Do NOT:
- Touch UI components
- Modify state management

Time │ UI Agent        │ API Agent       │ State Agent
─────┼─────────────────┼─────────────────┼──────────────
0s   │ Start UI Task 1 │ Start API Task 5│ Start State 8
2s   │ Finish Task 1   │                 │
     │ Start UI Task 2 │                 │
4s   │                 │ Finish Task 5   │ Finish Task 8
     │                 │ Start API Task 6│ Start State 9
6s   │ Finish Task 2   │                 │
     │ Start UI Task 3 │                 │
8s   │                 │ Finish Task 6   │ Finish Task 9
     │                 │ Start API Task 7│ Start State 10
10s  │ Finish Task 3   │                 │
     │ Start UI Task 4 │                 │
12s  │ Finish Task 4   │ Finish Task 7   │ Finish Task 10
─────┴─────────────────┴─────────────────┴──────────────

Validate implementation against PRD

# AI 会：
# 1. 读取 PRD 文件
# 2. 检查每个 Acceptance Criteria
# 3. 报告缺失或不符合的功能

# package.json
{
  "scripts": {
    "validate": "npm run type-check && npm run lint && npm run test",
    "type-check": "tsc --noEmit",
    "lint": "eslint src/",
    "test": "vitest run"
  }
}

Review code and suggest improvements

# AI 会：
# 1. 分析代码结构
# 2. 检查常见反模式
# 3. 提出优化建议

New PRD (002-user-edit.md)
    ↓
Update Spec (add edit feature)
    ↓
Generate Tasks (delta tasks)
    ↓
Implement (only changes)
    ↓
Validate (regression test)
    ↓
Review (review changes)

Figma Design
    ↓
Figma MCP Agent (提取 Design Tokens)
    ↓
UI Agent (按 Token 实现)
    ↓
Storybook (渲染组件)
    ↓
Visual Diff Agent (对比截图)
    ↓
Auto Fix (自动修复偏差)

# 安装 Figma MCP 服务器
npm install -g @anthropic/figma-mcp-server

# 配置 MCP
export FIGMA_ACCESS_TOKEN="figd_xxx"
export FIGMA_FILE_KEY="abc123"

You are the **UI Agent** with Figma MCP access.

Context:
- Figma File: https://figma.com/file/abc123/User-List
- Target Frame: "User List Page - Desktop"

Task: Extract design tokens and implement the UserListPage component.

Steps:
1. Use `figma-mcp` to read the frame
2. Extract:
   - Colors (primary, secondary, text, background)
   - Typography (font family, sizes, weights)
   - Spacing (padding, margin, gaps)
   - Border radius
3. Map tokens to Tailwind CSS classes
4. Implement component with pixel-perfect accuracy

// Figma MCP 提取的 Token 示例
const designTokens = {
  colors: {
    primary: "#1890ff",
    secondary: "#52c41a",
    text: "#333333",
    background: "#ffffff",
  },
  typography: {
    fontFamily: "Inter, sans-serif",
    fontSize: {
      sm: "0.875rem",
      base: "1rem",
      lg: "1.125rem",
    },
  },
  spacing: {
    1: "0.25rem",
    2: "0.5rem",
    4: "1rem",
    8: "2rem",
  },
  borderRadius: {
    sm: "0.25rem",
    md: "0.5rem",
    lg: "1rem",
  },
};

// tokens.json
{
  "color": {
    "primary": { "value": "#1890ff" },
    "secondary": { "value": "#52c41a" }
  },
  "spacing": {
    "sm": { "value": "8px" },
    "md": { "value": "16px" },
    "lg": { "value": "24px" }
  }
}

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: "#1890ff",
        secondary: "#52c41a",
      },
      spacing: {
        sm: "8px",
        md: "16px",
        lg: "24px",
      },
    },
  },
};

Implement UserListPage using the design tokens from @tailwind.config.js.

Requirements:
- Use `text-primary` instead of hardcoded `#1890ff`
- Use `p-md` instead of `padding: 16px`
- All spacing values must come from Tailwind theme

Figma Screenshot
    ↓
Rendered UI Screenshot
    ↓
Visual Diff Agent (对比差异)
    ↓
生成差异报告
    ↓
Auto Fix (自动调整)

// visual-diff.ts
import { test, expect } from "@playwright/test";

test("UserListPage should match Figma design", async ({ page }) => {
  await page.goto("/users");

  // 截取实际 UI
  await page.screenshot({ path: "actual.png" });

  // 加载 Figma 截图
  const expected = "figma-screenshots/user-list-desktop.png";

  // 对比差异
  const diff = await compareScreenshots("actual.png", expected);

  // 允许 1% 的差异
  expect(diff.percent).toBeLessThan(0.01);
});

You are the **Visual Diff Agent**.

Context:
- Expected: @figma-screenshots/user-list-desktop.png
- Actual: @screenshots/actual.png
- Diff Report: @diff-report.json

Task: Analyze the visual diff and fix the CSS.

Diff Analysis:
- Margin top: expected 16px, actual 12px (+4px)
- Font size: expected 14px, actual 16px (-2px)
- Border radius: expected 8px, actual 4px (+4px)

Fix these issues in @src/components/UserListPage.tsx

/* ❌ Bad */
.button {
  padding: 16px;
  font-size: 14px;
}

/* ✅ Good */
.button {
  padding: 1rem;      /* 16px */
  font-size: 0.875rem; /* 14px */
}

/* ❌ Bad */
.card {
  background: #ffffff;
  border-radius: 8px;
  padding: 16px;
}

/* ✅ Good */
.card {
  background: var(--color-background);
  border-radius: var(--radius-md);
  padding: var(--spacing-md);
}

/* ❌ Bad */
.user-table {
  margin-top: 37px; /* 为什么是 37px？ */
}

/* ✅ Good */
.user-table {
  margin-top: var(--spacing-lg); /* 使用语义化的 Token */
}

/* ❌ Bad - 固定宽度 */
.container {
  width: 1200px;
}

/* ✅ Good - 响应式 */
.container {
  max-width: 1200px;
  width: 100%;
  padding: 0 var(--spacing-md);
}

❌ Bad: "Implement the entire admin dashboard"

✅ Good: 
- Iteration 1: User list page
- Iteration 2: User edit page
- Iteration 3: Permission management

# 提交前检查
npm run validate
npm run docs:update
git add docs/ specs/ tasks/

# specs/coding.spec.md (通用规范)
- Framework: React 18
- UI Library: Ant Design 5
- State Management: React Query
- Styling: Tailwind CSS
- Testing: Vitest + Playwright

# Cursor 中的实践
Generate UserListPage using Claude 3.5
Generate UserListPage using GPT-4
Compare both implementations and choose the best

# Bad Spec
Implement user list with table.

# Good Spec
Implement UserListPage with:
- Ant Design Table component
- Columns: name, email, status, actions
- Pagination: 10 items per page
- Search: debounce 300ms
- Loading: Ant Design Spin overlay

## Edge Cases
- Empty state: show "No users found"
- Loading error: show error message with retry button
- Network timeout: show toast notification

File Ownership:
- UI Agent: src/components/**, src/styles/**
- API Agent: src/services/**, src/api/**
- State Agent: src/hooks/**, src/store/**
- Test Agent: src/**/*.test.ts, e2e/**

# Pre-commit hook
npm run validate
npm run docs:sync

# /docs/prd/001-user-list.md

# Feature: User List Page

## Goals
- Display users in a table with pagination
- Support search by name/email
- Show user status (active/inactive)
- Allow admin to view user details

## Non-Goals
- Edit user (separate feature)
- Delete user (separate feature)
- Bulk operations (future iteration)

## User Stories
1. As an admin, I want to view all users in a paginated table
2. As an admin, I want to search users by name or email
3. As an admin, I want to quickly identify active vs inactive users

## Acceptance Criteria
- ✅ Table displays: name, email, status, created date, actions
- ✅ Pagination shows 10 users per page
- ✅ Search works with partial match (case-insensitive)
- ✅ Status badge shows green for active, gray for inactive
- ✅ Clicking "View" navigates to user detail page
- ✅ Empty state shows "No users found" message
- ✅ Loading state shows spinner overlay

# /specs/user-list.spec.md

# Spec: User List Page

## Tech Stack
- React 18.3
- Ant Design 5.x
- React Query 5.x
- Tailwind CSS 3.x
- React Router 6.x

## Components

### Pages
- `UserListPage` (src/pages/UserListPage.tsx)

### Components
- `UserSearchForm` (src/components/UserSearchForm.tsx)
- `UserTable` (src/components/UserTable.tsx)
- `StatusBadge` (src/components/StatusBadge.tsx)

### Services
- `userService` (src/services/userService.ts)
  - `getUsers(params): Promise<UserListResponse>`

### Hooks
- `useUsers` (src/hooks/useUsers.ts)

## API Contract

### GET /api/users

Query Parameters:
- `page` (number, default: 1)
- `pageSize` (number, default: 10)
- `search` (string, optional)

Response:
```json
{
  "users": [
    {
      "id": "string",
      "name": "string",
      "email": "string",
      "status": "active" | "inactive",
      "createdAt": "ISO 8601 date string"
    }
  ],
  "total": number,
  "page": number,
  "pageSize": number
}

src/
├── pages/
│   └── UserListPage.tsx
├── components/
│   ├── UserSearchForm.tsx
│   ├── UserTable.tsx
│   └── StatusBadge.tsx
├── services/
│   └── userService.ts
├── hooks/
│   └── useUsers.ts
└── types/
    └── user.ts

# /tasks/user-list.tasks.md

# Tasks: User List Page

## Phase 1: Foundation (parallel)

### Type Definitions
- [ ] Create `src/types/user.ts` with User and UserListResponse types

### Services
- [ ] Create `src/services/userService.ts` with getUsers function
- [ ] Add axios instance with base URL
- [ ] Add error handling for API failures

### Hooks
- [ ] Create `src/hooks/useUsers.ts` with React Query hook
- [ ] Implement search debouncing (300ms)

## Phase 2: UI Components (parallel)

### StatusBadge
- [ ] Create `src/components/StatusBadge.tsx`
- [ ] Use Ant Design Tag component
- [ ] Colors: green for active, gray for inactive

### UserSearchForm
- [ ] Create `src/components/UserSearchForm.tsx`
- [ ] Use Ant Design Input.Search
- [ ] Add debounced onChange handler

### UserTable
- [ ] Create `src/components/UserTable.tsx`
- [ ] Use Ant Design Table component
- [ ] Columns: name, email, status, createdAt, actions
- [ ] Add "View" button in actions column

## Phase 3: Page Assembly

- [ ] Create `src/pages/UserListPage.tsx`
- [ ] Compose UserSearchForm + UserTable
- [ ] Add pagination controls
- [ ] Add loading state (Spin overlay)
- [ ] Add empty state message

## Phase 4: Routing

- [ ] Add route `/users` to React Router config
- [ ] Add navigation link in sidebar

## Phase 5: Testing

- [ ] Write unit tests for StatusBadge
- [ ] Write unit tests for UserSearchForm
- [ ] Write integration tests for UserListPage
- [ ] Write E2E test for search flow

You are the **UI Agent**.

Tasks: Implement UserTable component

Spec: @specs/user-list.spec.md
Design Tokens: @tailwind.config.js

Requirements:
- Use Ant Design Table
- Follow Tailwind CSS conventions
- Responsive design (mobile-first)

Columns:
1. Name (sortable)
2. Email
3. Status (use StatusBadge component)
4. Created At (format: YYYY-MM-DD)
5. Actions (View button)

Create file: src/components/UserTable.tsx

// src/components/UserTable.tsx
import { Table, Button } from "antd";
import { EyeOutlined } from "@ant-design/icons";
import type { ColumnsType } from "antd/es/table";
import { StatusBadge } from "./StatusBadge";
import type { User } from "@/types/user";
import dayjs from "dayjs";

interface UserTableProps {
  users: User[];
  loading: boolean;
  onView: (userId: string) => void;
}

export function UserTable({ users, loading, onView }: UserTableProps) {
  const columns: ColumnsType<User> = [
    {
      title: "Name",
      dataIndex: "name",
      key: "name",
      sorter: true,
      className: "font-medium",
    },
    {
      title: "Email",
      dataIndex: "email",
      key: "email",
      className: "text-gray-600",
    },
    {
      title: "Status",
      dataIndex: "status",
      key: "status",
      render: (status) => <StatusBadge status={status} />,
    },
    {
      title: "Created At",
      dataIndex: "createdAt",
      key: "createdAt",
      render: (date) => dayjs(date).format("YYYY-MM-DD"),
      className: "text-gray-500",
    },
    {
      title: "Actions",
      key: "actions",
      render: (_, record) => (
        <Button
          type="link"
          icon={<EyeOutlined />}
          onClick={() => onView(record.id)}
          className="text-primary"
        >
          View
        </Button>
      ),
    },
  ];

  return (
    <Table<User>
      columns={columns}
      dataSource={users}
      loading={loading}
      rowKey="id"
      pagination={false}
      className="bg-white rounded-lg shadow-sm"
    />
  );
}