Giảng dạy thiết kế sản phẩm tác nhân tại Vercel

Tác nhân mã hóa có thể tạo ra giao diện người dùng hoạt động nhanh, nhưng điều khó hơn là hình dạng khác. Họ có thể sao chép kiểu dáng sản phẩm của bạn, làm cho phù hợp với mẫu mã của nó và cố gắng tuân theo các quy ước của nó. Điều họ không thể làm là hiểu tại sao những khuôn mẫu đó tồn tại. Mã hiển thị cho tác nhân những gì được vận chuyển chứ không phải tại sao một thành phần, cụm từ hoặc tương tác lại trở thành tiêu chuẩn của bạn. Lý do đó tồn tại trong các bài đánh giá thiết kế, nhận xét PR, chủ đề Slack và với những người có mặt trong phòng. Đối với một tổng đài viên, ngữ cảnh không có trong cơ sở mã sẽ không tồn tại.

Vercel là một đội gốc tác nhân. Chúng tôi xử lý các quyết định về sản phẩm được chấp nhận như mã, lưu giữ chúng trong kho lưu trữ, xem xét các thay đổi đối với chúng và cung cấp chúng cho mọi tác nhân làm việc ở đó.

Cách chúng tôi thực hiện điều này là thông qua thiết kế sản phẩm. Đó là một hệ thống gồm ba phần:

Một kỹ năng của tác nhân cung cấp cho tác nhân mã hóa bối cảnh đằng sau các quyết định yêu cầu phán đoán về sản phẩm hoặc cơ sở mã.

Linters thực thi các quy tắc rõ ràng một cách tự động.

Vòng đánh giá thu thập bằng chứng từ Slack, Figma và GitHub, sau đó chuẩn bị các bản cập nhật hướng dẫn để xem xét.

Bất kỳ nhóm nào cũng có thể xây dựng cấu trúc tương tự theo tiêu chuẩn của riêng họ.

Bên trong kỹ năng thiết kế sản phẩm

Kỹ năng này tồn tại bên trong kho lưu trữ cùng với mã mà nó quản lý. Đây là một cái nhìn đơn giản về cấu trúc của nó:

kho lưu trữ/├── AGENTS.md├── .agents/│ └── Skills/│ └── sản phẩm-design/│ ├── AGENTS.md│ ├── SKILL.md│ ├── tài liệu tham khảo/│ │ ├── sản phẩm-judgment.md│ │ ├── giao diện-chất lượng.md│ │ ├── khả năng phục hồi.md│ │ ├── bề mặt.md│ │ ├── bề mặt-{surface}.md│ │ ├── copy.md│ │ ├── Rules.md│ │ ├── bảng thuật ngữ.md│ │ ├── mẫu.md│ │ └── vùng phủ sóng-gaps.md│ └── mẫu/│ └── pr-{name}.md└── tooling/ └── scripts/ └── evals/ ├── Fixture.json ├── Rules-checklist.json └── <cố định>/ ├── trước/ └── sau/

Cấu trúc kỹ năng thiết kế sản phẩm bên trong kho lưu trữ.

Kho lưu trữ AGENTS.md cho các tác nhân mã hóa biết thời điểm tải kỹ năng. AGENTS.md kỹ năng cục bộ xác định thứ tự tải, xác thực và quản trị. SKILL.md sở hữu quy trình làm việc thời gian chạy.

tham chiếu/lưu trữ phán đoán sản phẩm, chất lượng giao diện, khả năng phục hồi, bản sao, tên sản phẩm chuẩn, mẫu tương tác và các quyết định theo bề mặt cụ thể.

các ví dụ/ghi lại các quyết định đáng được lặp lại từ các yêu cầu kéo đã được vận chuyển, cùng với những sai lầm cần tránh. vùng phủ sóng-gaps.md liệt kê các khu vực mà chúng tôi chưa có tiêu chuẩn.

copywriting-eval/tests sao chép và hành vi ngôn ngữ giao diện. Nó không đánh giá quy trình thiết kế sản phẩm rộng hơn.

Lộ trình kỹ năng như thế nào

SKILL.md trước tiên giải quyết chế độ yêu cầu: định hình, triển khai, xem xét, sao chép hoặc củng cố. Điều này giúp các cuộc kiểm tra không trở thành các chỉnh sửa và các bản sao chép chuyển sang thiết kế lại. Nó bỏ qua công việc chỉ phụ trợ, đo từ xa, lỗi bảng điều khiển, tệp được tạo và kiểm tra mà không có tác động đến giao diện người dùng.

Các tuyến kỹ năng đến các nguồn kinh điển thay vì sao chép chúng. API thành phần, quy tắc hệ thống thiết kế, tiêu chí trợ năng và hướng dẫn tương tác vẫn thuộc quyền sở hữu của chủ sở hữu.

Định tuyến dành riêng cho cả nhiệm vụ và bề mặt. Thay đổi vật liệu sẽ tải đánh giá sản phẩm và chất lượng giao diện trước tiên. Sao chép, thành phần, bố cục, tương tác, khả năng truy cập và khả năng phục hồi hoạt động theo từng tuyến đường đến các tài liệu tham khảo tập trung. Một phương thức tải các mẫu hành động phá hoại và các động từ chuẩn. Biểu mẫu cài đặt tải nhãn, xác thực, tiết lộ lũy tiến và hướng dẫn về tên có thể truy cập.

Bạn có thể sử dụng cấu trúc đơn giản hóa này làm điểm bắt đầu và thay thế các đường dẫn cũng như tiêu chuẩn bằng cấu trúc của riêng bạn:

1---2tên: sản phẩm-design3description: >-4 Điểm truy cập duy nhất cho thiết kế sản phẩm và triển khai sản phẩm hướng tới người dùng5 trong ứng dụng/vercel-site. Sử dụng bất cứ khi nào công việc thay đổi những gì người dùng nhìn thấy, hiểu,6 lựa chọn hoặc thực hiện: định hình các yêu cầu và quy trình; xây dựng hoặc thiết kế lại7 trang và thành phần; xem xét các URL, ảnh chụp màn hình, điểm khác biệt hoặc các phát hiện của Vercel Agent8; cải thiện bản sao sản phẩm, kiến ​​trúc thông tin, lựa chọn thành phần,9 Tuân thủ Geist, phân cấp, bố cục, tương tác, khả năng truy cập, hành vi đáp ứng10 và các trạng thái tải, trống, lỗi, cấp phép, thanh toán hoặc phá hoại11. Kích hoạt về thiết kế, UX, UI, khả năng sử dụng, quy trình, triển khai, cài đặt, 12 trang tổng quan, xây dựng, cải tiến, sửa lỗi, kiểm tra, đánh giá, đánh bóng, đơn giản hóa hoặc 13 yêu cầu sẵn sàng sản xuất. Cũng sử dụng khi hành vi phụ trợ thay đổi a14 kết quả mà người dùng có thể nhìn thấy. Không dành cho công việc chỉ phụ trợ mà không có hiệu ứng mà người dùng có thể nhìn thấy,15 thử nghiệm không có tác động đến giao diện người dùng, công việc chỉ đo từ xa, tài liệu hoặc16 nội dung tiếp thị.17---18
19 # Thiết kế sản phẩm Vercel20
21Tạo giao diện chính xác cho người dùng, sản phẩm và Vercel. Mã làm việc thôi là chưa đủ: hãy chọn sự tương tác phù hợp, làm rõ phạm vi và hậu quả, bao quát thực tế ngoài con đường hạnh phúc và xác minh kết quả được hiển thị.22
23##Hợp đồng điều hành24
25- **Bắt đầu với công việc, không phải pixel.** Xác định ai đang hành động, họ đang cố gắng hoàn thành điều gì, đối tượng sản phẩm liên quan và hệ thống sẽ thay đổi điều gì.26- **Xác định kết quả trước khi xuất ra.** Thiết lập vấn đề người dùng hiện tại, hành vi mong muốn, tín hiệu thành công và các mục tiêu không phải trước khi chọn bề mặt hoặc thành phần.27- **Sử dụng bằng chứng, không phải hương vị.** Theo dõi các quyết định đối với hành vi sản phẩm, hướng dẫn kho lưu trữ chuẩn, quyết định thiết kế được chấp nhận hoặc mẫu liền kề đã được xác minh.28- **Tách biệt các dữ kiện từ các quyết định.** Đánh dấu các giả định và lựa chọn sản phẩm chưa được giải quyết một cách rõ ràng; không giấu chúng bên trong các chi tiết triển khai.29- **Coi mã được vận chuyển như bằng chứng chứ không phải tiền lệ tự động.** Nó chứng minh những gì tồn tại chứ không phải tại sao nó đúng. Kiểm tra nó dựa trên các thành phần hiện tại, hoạt động của sản phẩm và hướng dẫn rõ ràng.30- **Chọn biện pháp can thiệp mạch lạc nhỏ nhất.** Xem xét các mặc định, hành vi hoặc sử dụng lại tốt hơn trước khi thêm giao diện người dùng. Không giải quyết một công việc bằng cách tạo các cài đặt hoặc trừu tượng không liên quan.31- **Quyết định trước khi trang trí.** Giải quyết kiến ​​trúc thông tin, ngữ nghĩa thành phần, tương tác và hành vi trạng thái trước khi tạo kiểu hoặc viết lại bản sao.32- **Thiết kế mọi trạng thái có thể truy cập.** Chỉ bao gồm các trạng thái mà sản phẩm thực sự có thể nhập nhưng không dừng lại ở trường hợp thành công đã được điền sẵn.33- **Xác minh bề mặt thực.** Kiểm tra nguồn thiết lập hành vi; giao diện được hiển thị sẽ thiết lập chất lượng hình ảnh và tương tác. Không bao giờ yêu cầu xác minh trực quan chỉ từ mã.34- **Giữ một điểm vào hướng về phía người dùng.** Gọi `product-design`; định tuyến nội bộ tới các nguồn chuẩn bên dưới.35
36## Chế độ yêu cầu37
38Giải quyết chế độ từ động từ và tạo tác của người dùng trước khi hành động.39
40| Chế độ | Yêu cầu điển hình | Hành vi bắt buộc |41| --------- | ---------------------------------------------------------------------------------- ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |42| Hình dạng | "Thiết kế quy trình này", "Quy trình này hoạt động như thế nào?", tóm tắt tính năng không có giao diện người dùng cố định | Đưa ra vấn đề và bằng chứng, so sánh các lựa chọn thay thế quan trọng, sau đó xác định quy trình, trạng thái, tiêu chí chấp nhận, rủi ro và quyết định mở. Không chỉnh sửa trừ khi được yêu cầu. |43| Thực hiện | "Xây dựng", "sửa chữa", "cải thiện", "tuân thủ" hoặc "chạy thiết kế sản phẩm trên mọi thứ" | Giải quyết các quyết định quan trọng về sản phẩm, sau đó thực hiện thay đổi toàn diện nhất quán nhỏ nhất trong phạm vi. Không tiếp thu các kết quả đánh giá không liên quan.                      |44| Đánh giá | "Kiểm toán", "phê bình", "có chuyện gì vậy?", đánh giá mã | Kiểm tra nguồn và bằng chứng được đưa ra, sau đó báo cáo những phát hiện được ưu tiên. Không chỉnh sửa trừ khi được yêu cầu.                                                                      |45| Sao chép | "Sửa bản sao", "viết lại các lỗi này" | Chỉnh sửa ngôn ngữ hướng tới người dùng, tên có thể truy cập và chỉ JSX được yêu cầu trực tiếp. Báo cáo các trình chặn cấu trúc mà không âm thầm mở rộng phạm vi.                             |46| Làm cứng | "Đánh bóng", "sẵn sàng sản xuất", "xử lý các trường hợp cạnh" | Duy trì hướng sản phẩm đã ổn định trong khi khắc phục các lỗi về trạng thái, khả năng phục hồi, khả năng phản hồi, khả năng tiếp cận và hoàn thiện.                                                  |47
48Khi ý định không rõ ràng, hãy sử dụng chế độ hẹp nhất được động từ hỗ trợ. URL, ảnh chụp màn hình, tuyến đường hoặc thành phần xác định phạm vi; bản thân nó không cho phép chỉnh sửa.49
Quyết định quan trọng 50A thay đổi nhiệm vụ, mặc định, phạm vi, hậu quả, điều hướng, bề mặt tương tác hoặc trạng thái có thể truy cập của người dùng. Cơ chế sao chép, thay thế mã thông báo và thay thế thành phần đã được thiết lập thường không phải là vật chất.51
52## Cơ quan ra quyết định53
54Giải quyết xung đột theo thứ tự sau:55
561. Mục tiêu và ràng buộc rõ ràng của người dùng.572. Bằng chứng người dùng/sản phẩm đã được xác minh và sự thật của hệ thống.583. Hướng dẫn chuẩn về kho lưu trữ: `AGENTS.md`, API thành phần Geist, `packages/geist/STYLE_GUIDE.md` và kỹ năng định tuyến.594. Các quyết định và ví dụ về sản phẩm/thiết kế được chấp nhận với bằng chứng ổn định.605. Đã xác minh các mẫu vận chuyển liền kề trong cùng khu vực sản phẩm.616. Giao diện chung heuristic.62
63##Quy trình làm việc64
65### 1. Đặt phạm vi và chế độ66
67Đặt tên cho bề mặt mục tiêu và chế độ yêu cầu trong kế hoạch làm việc hoặc ghi chú xem xét.68
69### 2. Tải ngữ cảnh sản phẩm70
71Trước khi đề xuất giao diện người dùng, hãy đọc chuỗi `AGENTS.md` hiện hành, các bản tóm tắt và thiết kế được cung cấp cũng như logic sản phẩm xác định các đột biến, quyền, xác thực, lỗi và tác dụng phụ.72
73### 3. Làm mẫu cho quyết định về sản phẩm74
75Đối với Hình dạng, Triển khai, Củng cố, Đánh giá đầy đủ hoặc bất kỳ thay đổi quan trọng nào về sản phẩm/luồng, hãy đọc `product-judgment.md` và viết một bản tóm tắt nội bộ nhỏ gọn bao gồm người dùng, công việc, hành vi hiện tại, kết quả mong muốn, tín hiệu thành công, không phải mục tiêu, đối tượng, phạm vi, hành động, hậu quả, khả năng đảo ngược, quyền và quyết định mở.76
77### 4. Lập bản đồ bề mặt và các trạng thái78
79Điểm vào kho, vùng hiển thị, lớp phủ, chuyển tiếp, thoát và đường dẫn quay lại. Chỉ lập bản đồ các trạng thái có thể truy cập bao gồm các biến thể đang tải, trống, thưa thớt, đông dân, xác thực, lỗi, quyền, bị vô hiệu hóa, lạc quan, cũ, phá hoại và phản hồi.80
81### 5. Tải các tài liệu tham khảo đã định tuyến82
83| Cần | Tải |84| ---- | ---- |85| Quyết định về sản phẩm/dòng/thành phần | `product-judgment.md` + `thành phần-hướng dẫn` |86| Triển khai, thay đổi hình ảnh nội dung hoặc đánh giá đầy đủ | `giao diện-chất lượng.md` |87| Sao chép hoặc truy cập tên | định tuyến `copy.md` + `surfaces.md` |88| Bố cục, kiểu chữ, màu sắc, khoảng cách, API Geist | `design-guidelines` + `packages/geist/STYLE_GUIDE.md` |89| Bàn phím, tiêu điểm, biểu mẫu, cảm ứng, hoạt ảnh, trạng thái URL, hiệu suất | `hướng dẫn giao diện web` |90| Tràn, bản địa hóa, dữ liệu cực đoan, khả năng phục hồi mạng/lỗi | `khả năng phục hồi.md` |91
92### 6. Quyết định rồi thực hiện93
94Đối với mỗi thay đổi phi máy móc, có thể trả lời: điều này giải quyết được vấn đề gì của người dùng, tại sao thành phần này phù hợp, giao diện phải truyền đạt hậu quả gì, bằng chứng nào hỗ trợ cho quyết định và thay đổi mạch lạc nhỏ nhất là gì?95
96### 7. Xác minh97
981. Xác nhận công việc chính và tiêu chí chấp nhận.992. Chạy kiểm tra tìm lỗi mã nguồn của kho lưu trữ.1003. Kiểm tra các khung nhìn nhỏ gọn và rộng có liên quan.1014. Thực hiện mọi trạng thái có thể tiếp cận được thay đổi đáng kể.1025. Xác minh thứ tự bàn phím, chuyển động tiêu điểm, hành vi tải và mục tiêu con trỏ/chạm.1036. Kiểm tra nội dung dài, giá trị lớn, độ rộng bị hạn chế và rủi ro bản địa hóa/RTL.1047. Tải `review-design-system` để biết những thay đổi về cấu trúc có thể nhìn thấy được.105
106## Tiêu chuẩn thiết kế sản phẩm107
108- Làm cho nhiệm vụ chính và hành động chính của người dùng không thể nhầm lẫn.109- Bảo toàn mô hình tinh thần và bối cảnh hiện tại của người dùng trừ khi việc thay đổi nó giải quyết được vấn đề đã được xác minh.110- Đặt tên chính xác đối tượng, phạm vi và hậu quả của các hành động quan trọng.111- Sử dụng các thành phần điều hướng cho các thành phần điều hướng và hành động cho hành động.112- Chọn tính bền vững bề mặt để phù hợp với tầm quan trọng.113- Thích tiết lộ nội tuyến trước khi thêm một phương thức.114- Hiển thị các điều khiển nâng cao khi cần mà không đặt mặc định đường dẫn mang tính phức tạp của chúng.115- Ưu tiên các mặc định mạnh mẽ và hành vi trực tiếp hơn là thêm cấu hình mà người dùng phải tìm hiểu và duy trì.116- Sử dụng các thành phần Geist ngữ nghĩa và API của chúng trước HTML hoặc kiểu dáng tùy chỉnh.117- Sử dụng phân cấp, khoảng cách và căn chỉnh trước khi thêm vùng chứa.118- Bảo toàn dữ liệu đầu vào của người dùng thông qua xác thực và các lỗi có thể phục hồi.119- Giữ nhãn kiểm soát tải ổn định; sử dụng khả năng tải/bận của thành phần.120- Thực hiện các hành động phá hoại tương ứng với tác động và cung cấp tính năng hoàn tác khi hệ thống có thể hỗ trợ nó một cách trung thực.121- Không thêm tính mới trang trí, chuyển động hoặc sao chép trừ khi nó làm rõ cấu trúc, trạng thái hoặc mục đích của thương hiệu.122
123## Xem lại kết quả124
125Dẫn đầu với các phát hiện, sắp xếp theo tác động của người dùng:126
127- **P0:** chặn tác vụ chính, tạo ra lỗi truy cập nghiêm trọng hoặc có thể gây hại cho người dùng không thể khôi phục.128- **P1:** có thể là lỗi tác vụ, hậu quả sai lệch, thiếu trạng thái quan trọng hoặc lỗi phản hồi/khả năng truy cập chính.129- **P2:** xung đột có ý nghĩa, sự không nhất quán, hệ thống phân cấp yếu hoặc vấn đề về khả năng phục hồi.130- **P3:** cải thiện tính nhất quán hoặc thủ công nhỏ.131
132Đối với mỗi phát hiện bao gồm: tệp/dòng hoặc vị trí được hiển thị, trạng thái xác minh, nguồn chính tắc, hậu quả của người dùng và bản sửa lỗi cụ thể nhỏ nhất.133
134## Tính chính trực của kỹ năng135
136- Chỉ thêm hoặc thay đổi quy tắc sau khi xác minh nguồn hiện tại và sự chấp nhận của con người.137- Ghi lại phạm vi, lý do, bằng chứng, ngoại lệ và ví dụ xấu/tốt.138- Ưu tiên đích đến hẹp nhất: nguồn chuẩn, tham chiếu được định tuyến, mẫu, kiểm tra lint/eval hoặc khoảng trống phạm vi.139- Giữ các kiểm tra xác định một cách máy móc. Đưa ra phán quyết bằng văn xuôi với bằng chứng và mức độ tự do của nó.140- Không bao giờ quảng cáo một ảnh chụp màn hình, một tệp được gửi hoặc một nhận xét của người đánh giá thành một quy tắc chung.

SKILL.md thiết kế sản phẩm. Chế độ định tuyến, hợp đồng điều hành và quản trị.

Định tuyến chỉ là một phần khiến kỹ năng này trở nên hữu ích. Phần còn lại là cách các phát hiện vẫn có thể theo dõi được sau khi kỹ năng tạo ra chúng.

Làm cho các phát hiện có thể theo dõi được

Quy tắc sao chép có ID ổn định và trỏ đến các nguồn chuẩn của chúng: