Bạn yêu cầu một AI agent xây dựng một biểu mẫu đăng ký (signup form). Kết quả bạn nhận về là một đống hỗn độn: màu sắc ngẫu nhiên, khoảng cách không đồng đều, các mã CSS inline tùy tiện, và các thành phần (components) thậm chí còn không tồn tại trong mã nguồn của bạn. Sau đó, bạn phải mất cả giờ đồng hồ để điều chỉnh liên tục: “Hãy dùng button từ thư viện của chúng ta.” “Màu đó không nằm trong bảng màu.” “Padding 16px chứ không phải 20px.” Vấn đề không nằm ở AI agent. Vấn đề là bạn chưa từng nói cho nó biết các quy tắc.
Vấn đề thực sự
Hệ thống thiết kế (Design systems) đã giải quyết bài toán đồng nhất cho các đội ngũ nhân sự trong nhiều năm qua. Các nhà thiết kế và lập trình viên luôn đồng bộ với nhau. Nhưng chúng ta xây dựng hệ thống đó là để cho con người đọc — các token thiết kế trong mã nguồn, các component trong Figma, tài liệu hướng dẫn trong Storybook.
Các AI agent (LLM) không đọc theo cách đó. Chúng tự “suy diễn”.
Nếu không có các thông số kỹ thuật rõ ràng, một AI agent khi tạo giao diện (UI) sẽ không biết:
❌ Component nào thực sự tồn tại trong dự án của bạn
❌ Màu sắc nào là hợp lệ
❌ Cách kết hợp các khoảng cách (spacing)
❌ Mỗi component được sinh ra để làm gì
Vì vậy, nó tự phát minh ra. CSS inline. Mã màu hex ngẫu nhiên. Padding tùy ý. Mỗi câu lệnh (prompt) lại bắt đầu từ con số 0. Không có bộ nhớ. Không có tính nhất quán. Không có hệ thống.
Hệ thống thiết kế truyền thống
Các hệ thống thiết kế gồm có ba lớp. Chắc hẳn bạn đã biết điều này:
Tokens (Các biến) — Màu sắc, khoảng cách, kiểu chữ. Thay đổi primary: #007AFF thành #0066FF và mọi component ở khắp mọi nơi sẽ tự động cập nhật.
Components (Các khối xây dựng) — Button (Nút), Input (Ô nhập liệu), Card (Thẻ), Modal (Hộp thoại). Mỗi khối đi kèm với các props, các biến thể (variants) và các trạng thái (states).
Rules (Quy tắc) — Khi nào thì sử dụng chúng. Nút bấm chính (Primary button) chỉ dành cho các hành động chính. Biến thể nguy hiểm (Danger variant) chỉ dành cho các hành động mang tính xóa/hủy. Tối đa một nút chính trên mỗi màn hình.
Luồng làm việc thông thường: Figma → Storybook (tài liệu) → Code. Mọi thứ luôn đồng bộ vì nó được xây dựng một lần và được tham chiếu ở mọi nơi. Hệ thống này hoạt động hoàn hảo. Chỉ là AI agent không thể nhìn thấy nó.
Bước đột phá: Hai file đơn giản
Cách khắc phục cực kỳ đơn giản: mở rộng hệ thống của bạn bằng 2 file markdown để nói chuyện trực tiếp với các AI agent.
File 1: design.md — Những gì đang tồn tại
Đây thuần túy là các thông số kỹ thuật. Các Token. Các Component. Các Props. Tất cả các giá trị hợp lệ. Không cần suy diễn.
## Design System Tokens
## Colors
- primary: #007AFF
- secondary: #5E5CE6
- danger: #FF3B30
- success: #34C759
- warning: #FF9500
## Spacing
- xs: 4px | sm: 8px | md: 16px | lg: 24px | xl: 32px
## Typography
- heading-1: 32px, 700
- heading-2: 24px, 700
- body: 16px, 400
- caption: 12px, 400
---
## Components Available
### Button
- variant: "primary" | "secondary" | "outline" | "danger"
- size: "sm" | "md" | "lg"
- disabled: boolean
- loading: boolean
### Input
- type: "text" | "email" | "password"
- error: boolean
- placeholder: string
### Card
- elevation: 0 | 1 | 2
- padding: "sm" | "md" | "lg"
Xong. Đó là tài liệu tham chiếu của bạn — sự thật để máy móc có thể đọc được.
File 2: claude.md
Khi nào và như thế nào. Các khuôn mẫu (Patterns). Các ràng buộc. Những gì bị cấm.
# Button rules
- primary → CHỈ dành cho hành động chính (submit, confirm, send)
- secondary → hành động thay thế (back, cancel)
- danger → chỉ dành cho hành động xóa/hủy (delete, remove)
- ⚠️ Tối đa MỘT nút primary trên mỗi màn hình
# Input Rules
- error={true} khi xác thực dữ liệu (validation) thất bại
- Tuyệt đối không dùng custom styling (phong cách tùy biến ngoài hệ thống)
# Spacing Rules
- Giữa các khối: md (16px) hoặc lg (24px)
- Bên trong các component: sm (8px)
- ⚠️ Không bao giờ sử dụng các giá trị pixel tùy ý
# Common Form Pattern
<Card padding="md">
<Input type="email" placeholder="Email" />
<Input type="password" placeholder="Password" />
<Button variant="primary">Sign Up</Button>
</Card>
# What's Forbidden (Những điều bị cấm)
- Không dùng inline styles: style={{}}
- Không dùng màu tùy biến: chỉ sử dụng các giá trị token có sẵn
- Không dùng margin/padding bên ngoài các props của component
- Không dùng các component lạ không có trong danh sách
Bây giờ, hãy đưa chúng vào AI Agent
Bạn là một nhà phát triển frontend đang xây dựng các component bằng React. Bạn BẮT BUỘC chỉ được sử dụng các component và quy tắc dưới đây. Không có style tùy biến. Không ngoại lệ.
[paste nội dung design.md]
Hãy xây dựng một modal xác nhận cho việc xóa tài khoản người dùng. Chỉ vậy thôi.
Sự khác biệt rõ rệt
❌ Khi KHÔNG CÓ thông số kỹ thuật rõ ràng:
JavaScript
<div style={{ padding: '20px', border: '1px solid red', backgroundColor: '#FF0000' }}>
<p style={{ color: '#FF0000', fontSize: '18px' }}>Delete this?</p>
<button style={{background: '#00FF00'}}>OK</button>
<button>Cancel</button>
</div>
❌ Inline styles ở khắp mọi nơi
❌ Các màu sắc không tồn tại trong hệ thống
❌ Không sử dụng các component chuẩn
❌ Sai ngữ nghĩa (semantics)
✅ Khi CÓ design.md + claude.md:
JavaScript
<Modal title="Confirm Delete" size="md">
<Alert type="warning" title="Are you sure?">
<Button variant="danger">Delete</Button>
<Button variant="secondary">Cancel</Button>
</Alert>
</Modal>
✓ Các component được cấu trúc chuẩn chỉnh
✓ Sử dụng đúng các token thiết kế
✓ Đúng ngữ nghĩa
✓ Tự động tuân theo các quy tắc
Tại sao các LLM lại phản hồi tốt với cách này
Các LLM không giỏi đoán mò. Chúng chỉ đưa ra dự đoán tốt dựa trên các ràng buộc chính xác. Khi bạn cung cấp cho chúng:
Specification (Thông số kỹ thuật – những gì đang tồn tại)
Rules (Quy tắc – khi nào thì sử dụng)
Forbidden patterns (Các khuôn mẫu bị cấm – những gì không bao giờ được làm)
Chúng sẽ ngừng tự suy diễn linh tinh. Chúng sẽ mặc định hướng tới sự nhất quán. Tuyệt vời hơn nữa: hệ thống này có thể mở rộng khi hệ thống thiết kế của bạn phát triển. Bạn vừa thêm một component mới vào Storybook? Hãy cập nhật nó vào design.md và claude.md. AI agent sẽ sử dụng nó ngay trong câu lệnh tiếp theo. Không cần đào tạo lại mô hình. Không cần hướng dẫn đặc biệt. Nó cứ thế hoạt động.
Các bước triển khai
Bước 1: Tạo tệp design.md: Kiểm kê lại mọi thứ. Tất cả token, component, props và các giá trị hợp lệ. Hãy làm thật chi tiết.
Bước 2: Tạo tệp claude.md: Viết ra các quy tắc. Khi nào dùng Button thay vì Link. Các khuôn mẫu phổ biến (Form, Modal,…). Những gì bị cấm. Hãy đưa ra quan điểm rõ ràng.
Bước 3: Đưa vào ngữ cảnh của AI Agent: Dán cả hai tệp này vào phần System Prompt (Câu lệnh hệ thống).
Bước 4: Cải tiến tệp claude.md theo thời gian: Nếu kết quả đầu ra có xu hướng bị lệch hướng, hãy tinh chỉnh lại các quy tắc. Thêm các ràng buộc và làm rõ các khuôn mẫu.
Bước 5: Luôn giữ đồng bộ: Khi bạn cập nhật hệ thống thiết kế của mình, hãy cập nhật cả hai tệp này. Chúng chính là “nguồn chân lý” (source of truth) dành cho các AI agent.
Giá trị cốt lõi thu về
Hệ thống thiết kế luôn là giải pháp cho sự đồng nhất của các đội ngũ con người. Giờ đây, đây là giải pháp cho các AI agent. Hai file. Một file cho những gì tồn tại: design.md. Một file cho cách sử dụng: claude.md. AI agent sẽ ngừng ảo tưởng. Kết quả đầu ra trở nên dễ dự đoán. Bạn sẽ nâng tầm từ việc “sửa từng câu lệnh” sang “tinh chỉnh các quy tắc”. Sự chuyển dịch chỉ đơn giản là vậy. Khi hệ thống thiết kế kết hợp với các AI agent, mọi thứ bỗng nhiên trở nên hoàn hảo và đồng bộ.
