cấu hình tác nhân
File CLAUDE.md cấu hình cách các tác nhân AI tương tác với dự án 1thay. Nó định nghĩa bối cảnh dự án, quy tắc làm việc và tham chiếu lệnh mà tác nhân tải vào đầu mỗi phiên làm việc.
cấu trúc
| Mục | Mục đích |
|---|---|
| tổng quan dự án | 1thay là gì, công nghệ, nguyên tắc cốt lõi |
| quy tắc cốt lõi | Quy tắc làm việc bất biến: code-first, storybook trước astro, figma qua figma.md, tài liệu trước |
| cấu trúc dự án | Sơ đồ thư mục với chú thích |
| design tokens | Danh mục token, tiền tố, quy ước |
| cách thêm component/token | Quy trình từng bước cho tác nhân |
| figma | Vai trò của figma, hướng đồng bộ, quy tắc tương tác MCP |
| lệnh | Tất cả script npm kèm mô tả |
| quy ước đặt tên | Quy tắc đặt tên file/thư mục/token |
| thương hiệu | 4 chế độ thương hiệu với màu cơ bản và font chữ |
quy tắc cho tác nhân
Những quy tắc này là bất di bất dịch. Tác nhân phải tuân theo chính xác:
- code-first — component được xây trong storybook, token được định nghĩa trong tokens.css. không bao giờ hardcode giá trị.
- storybook trước astro — component được xây và kiểm tra trong storybook trước, sau đó dùng trong trang astro.
- figma qua figma.md — mọi tương tác figma MCP phải đọc figma.md trước. figma phản ánh code, không phải ngược lại.
- tài liệu trước — mọi quyết định xây dựng đều bắt đầu từ tài liệu. trước khi code, đọc các file tham chiếu liên quan. sau khi code, cập nhật tài liệu.
- nguồn chân lý duy nhất — tokens.css được import bởi cả astro và storybook.
- không viết tắt trừ khi là chuẩn ngành (ui, btn, sm/md/lg).
- đồng bộ số liệu — số lượng component, token, trang phải khớp nhau trong tất cả file .md.
file chính tác nhân cần tham khảo
| File | Đọc trước khi... |
|---|---|
AGENTS.md | bắt đầu bất kỳ tác vụ nào — chỉ mục trung tâm |
design.md | xây component — tham chiếu đặc tả |
design-tokens.md | làm việc với token — tài liệu token chi tiết |
storybook.md | xây story — quy ước story + danh mục |
astro.md | xây trang — kiến trúc site + quy ước |
figma.md | tương tác figma MCP — quy trình + quy tắc |
project-logs.md | hiểu bối cảnh — lịch sử quyết định |
cập nhật CLAUDE.md
Khi cấu trúc dự án, lệnh hoặc quy ước thay đổi, cập nhật CLAUDE.md để phản ánh trạng thái hiện tại. Đặc biệt chú ý đến:
- Số lượng component — xem trong storybook sidebar
- Số lượng token — chạy
npm run check-tokens - Số lượng thương hiệu (hiện tại 4)
- Tham chiếu lệnh
- Quy ước đặt tên