Một Prototype Notes Skill chuyên dành cho HTML Demo và các dự án frontend.
Gần đây, tôi ngày càng quen với việc để AI trực tiếp tạo các trang nguyên mẫu và mã frontend.
Trang được tạo ra rất nhanh, nhưng một vấn đề mới cũng xuất hiện:
“Sau khi nhấp vào nút này cần xác nhận lần hai.”
“Hình ở đây chưa đẹp, hãy đổi sang cách thể hiện khác.”
“Khi chuyển danh mục trong bảng, dữ liệu bên dưới cũng phải được lọc đồng thời.”
Những ý kiến này nên được viết ở đâu?
Gửi ảnh chụp màn hình, vẽ khung đỏ, viết tài liệu, bổ sung một câu trong nhóm chat, rồi đội phát triển lại phải mất rất lâu để tìm đúng vị trí trên trang. Khi trang thay đổi, ảnh chụp cũ lại mất hiệu lực; khi có quá nhiều ý kiến, ngữ cảnh trong nhóm chat cũng rất dễ bị thất lạc.
Vì vậy tôi đã tạo một Skill: Prototype Notes (Chú thích nguyên mẫu). Nó thêm một lớp công cụ chú thích độc lập vào nguyên mẫu HTML hoặc môi trường phát triển frontend, để yêu cầu và ý kiến chỉnh sửa được lưu ngay tại vị trí phát sinh trên trang.
Nó thực sự dùng để làm gì?
Nói đơn giản, nó giống như lắp một lớp “ghi chú tại chỗ” lên trang web.
Sau khi bật chế độ chú thích, nhấp chuột phải vào bất kỳ vị trí nào trên trang để chọn thêm hai loại nội dung:
Mô tả yêu cầu: dành cho quản lý sản phẩm, dùng để mô tả yêu cầu mới hoặc thay đổi yêu cầu; có thể đặt mức độ ưu tiên, trạng thái và thêm nhiều nội dung mô tả.
Ý kiến chỉnh sửa: dành cho người đánh giá, dùng để đưa ra đề xuất trong quá trình review; cần điền tên người đưa ý kiến nhưng không cần đặt mức độ ưu tiên hay trạng thái.
>Sau khi bật chế độ chú thích, nhấp chuột phải để chọn loại chú thích cần thêm
Sau khi gửi, phần mô tả sẽ thu gọn thành một biểu tượng nhỏ trên trang. Đội phát triển chỉ cần nhấp vào biểu tượng để xem ngữ cảnh, không còn phải đoán “nội dung trong ảnh chụp đang nói đến vị trí nào”.
Tính năng chính
01 Tách riêng mô tả yêu cầu và ý kiến review
Yêu cầu sản phẩm và đề xuất review vốn là hai loại thông tin khác nhau. Skill không cố nhồi chúng vào cùng một biểu mẫu, mà đã phân biệt rõ ngay từ điểm truy cập bằng chuột phải.
>Mô tả yêu cầu: nhiều nội dung, mức độ ưu tiên, trạng thái thêm mới hoặc thay đổi, thời gian lưu
>Ý kiến chỉnh sửa: điền tên người review, trực tiếp ghi lại đề xuất đánh giá
02 Một đánh dấu có thể chứa nhiều nội dung mô tả
Không cần trải kín một hàng biểu tượng cho các yêu cầu liên quan tại cùng một vị trí. Một đánh dấu yêu cầu có thể tiếp tục thêm nhiều mô tả yêu cầu, một đánh dấu ý kiến chỉnh sửa cũng có thể thêm nhiều ý kiến, đồng thời hiển thị số lượng bằng huy hiệu.
03 Có thể di chuyển cả đánh dấu và cửa sổ nổi
Khi vị trí đánh dấu chưa chính xác, có thể trực tiếp kéo để định vị lại; cửa sổ nổi cũng có thể được kéo sang chỗ khác để không che nội dung trang đang xem. Đánh dấu sẽ ghi lại vị trí tương đối, nhờ đó vẫn cố gắng bám theo phần tử mục tiêu khi trang cuộn hoặc kích thước thay đổi.
04 Có thể dán hình ảnh trực tiếp vào phần mô tả
Khi chỉ dùng chữ vẫn khó diễn đạt, hãy sao chép ảnh chụp màn hình rồi dán trực tiếp vào phần mô tả hiện tại. Hình ảnh sẽ được tự động nén và lưu cùng dữ liệu chú thích, đồng thời có thể xóa riêng.
05 Chế độ không chú thích hoàn toàn chỉ đọc
Trong quá trình xem thông thường, nội dung không thể bị sửa nhầm và thao tác nhấp chuột phải bình thường cũng không bị can thiệp. Chỉ sau khi chủ động bật chế độ chú thích, người dùng mới có thể thêm, chỉnh sửa, di chuyển, nhập hoặc xóa đánh dấu.
>Chế độ xem thông thường: có thể xem mô tả nhưng không có thao tác chỉnh sửa và xóa
06 Tự động lưu vào JSON trong kho Git
Dữ liệu chú thích được lưu tại:
.prototype-notes/annotations.json
Sau khi lưu, di chuyển, nhập hoặc xóa, môi trường phát triển sẽ tự động ghi lại tệp này. Sau khi thành viên trong nhóm commit lên Git, chú thích có thể đi cùng dự án để được luân chuyển, review và lưu giữ lịch sử. Tính năng nhập và xuất thủ công vẫn được giữ lại như một phương án khôi phục khi có sự cố.
07 Bản build chính thức không chứa mã chú thích
Đây không phải là công cụ giả vờ an toàn bằng cách “nhấp để ẩn”. Dự án Vite chỉ tải runtime trong chế độ phát triển, API lưu cũng chỉ được gắn trên máy chủ phát triển; với dự án HTML tĩnh, có thể thực hiện thao tác gỡ bỏ trước khi đưa lên mạng. Mục tiêu của bước kiểm tra phát hành là: bản build production hoàn toàn không chứa runtime chú thích và nội dung chú thích.
Một vài chi tiết nhỏ tôi khá thích
Biểu tượng tài liệu màu xanh và biểu tượng ý kiến màu cam. Không cần mở cửa sổ nổi cũng có thể nhận ra đây là yêu cầu sản phẩm hay ý kiến review.
Chỉ tiếp quản thao tác nhấp chuột phải trong chế độ chú thích. Bình thường không làm phiền thao tác của trang web; chỉ bật lên khi cần ghi chú.
Mỗi nội dung mô tả đều có thời gian lưu mới nhất. Đội phát triển có thể biết nội dung mình đang xem có phải phiên bản vừa được cập nhật hay không.
Bộ nhớ đệm cục bộ làm phương án dự phòng. Khi ghi tự động thất bại, bản nháp trong trình duyệt sẽ không lập tức bị mất, đồng thời thanh công cụ sẽ hiển thị “đồng bộ thất bại”.
Tích hợp dấu hiệu nguồn. Phiên bản hiện tại hiển thị “泥嚎的AI实验室”, đồng thời giữ lại một dấu hiệu thống nhất có thể kiểm chứng trong runtime, công cụ phát triển và JSON đã xuất.
Nó giải quyết vấn đề gì?
Thứ nhất, giảm thất lạc ngữ cảnh yêu cầu. Yêu cầu không còn tách rời khỏi trang để trôi nổi riêng trong lịch sử trò chuyện hoặc tài liệu.
Thứ hai, giảm chi phí định vị giữa sản phẩm và phát triển. Chú thích được gắn vào thành phần cụ thể, mở trang lên là biết cần sửa ở đâu.
Thứ ba, tách riêng yêu cầu sản phẩm và phản hồi review. Ai đưa ra, thuộc loại nào, có thể phân biệt ngay.
Thứ tư, đưa nguyên mẫu AI thực sự vào quy trình lặp. AI phụ trách tạo nhanh, lớp chú thích phụ trách đưa phản hồi tiếp theo trở lại cho AI hoặc đội phát triển.
Thứ năm, không đánh đổi an toàn khi phát hành. Chú thích chỉ thuộc về môi trường phát triển và review, không trở thành tính năng của sản phẩm chính thức.
Sử dụng trong các tình huống khác nhau
Tình huống 1: HTML Demo một trang do AI tạo
Yêu cầu AI sử dụng Prototype Notes Skill để cài đặt lớp chú thích và khởi động máy chủ phát triển cục bộ đi kèm. Bộ phận sản phẩm nhấp chuột phải trên trang để viết yêu cầu; sau khi lưu, dữ liệu sẽ tự động được đưa vào JSON của dự án. Sau khi xác nhận hoàn tất, gỡ runtime rồi phát hành trang tĩnh.
Tình huống 2: Dự án frontend Vue / React + Vite
Skill sẽ đặt runtime vào thư mục công cụ phát triển và cài đặt plugin lưu chỉ chạy trên máy chủ phát triển. Chỉ cần chạy lệnh phát triển thông thường của dự án là có thể sử dụng; khi build chính thức, runtime chú thích sẽ không được tải.
Tình huống 3: Quản lý sản phẩm và đội phát triển cộng tác trong cùng một kho Git
Sau khi bộ phận sản phẩm lưu đánh dấu và commit annotations.json, đội phát triển chỉ cần lấy mã nguồn là có thể xem chú thích trên trang gốc; sau khi hoàn tất chỉnh sửa thì tiếp tục commit. Git phụ trách phiên bản, hợp nhất và lịch sử; công cụ chú thích phụ trách thể hiện ý kiến ngay tại vị trí trên trang.
Tình huống 4: Review thiết kế hoặc nghiệp vụ
Người review chọn “thêm ý kiến chỉnh sửa”, điền tên rồi ghi lại đề xuất. Yêu cầu sản phẩm sẽ không bị nhầm lẫn với ý kiến review, và đội phát triển cũng biết ý kiến đến từ ai.
Tình huống 5: Buổi review chỉ có quyền trình bày
Sau khi tắt chế độ chú thích, người tham gia vẫn có thể nhấp vào biểu tượng để xem nhưng không thể chỉnh sửa; cũng có thể ẩn tất cả đánh dấu bằng một lần nhấp để trang trở lại trạng thái trình bày thuần túy.
Cài đặt và gọi Skill như thế nào?
Skill này hiện chưa được phát hành mã nguồn mở. Nếu bạn muốn trải nghiệm:
Theo dõi “泥嚎的AI实验室”
Nhắn tin riêng với từ khóa: 原型批注
Tôi sẽ gửi cho bạn gói nén Skill và hướng dẫn sử dụng.
Sau khi nhận được gói nén, giải nén vào thư mục Codex Skill cá nhân:
C:\Users\tên người dùng của bạn\.codex\skills\prototype-notes
Mở lại tác vụ Codex, sau đó có thể gọi như sau:
Sử dụng $prototype-notes để thêm tính năng chú thích cho nguyên mẫu HTML hiện tại.
Cũng có thể nói bằng ngôn ngữ tự nhiên, ví dụ:
“Cài đặt chú thích nguyên mẫu cho dự án Vue/Vite này, tự động lưu dữ liệu vào Git JSON và không đưa mã chú thích vào bản build production.”
“Thêm mô tả yêu cầu và ý kiến chỉnh sửa có tên người đưa ra vào HTML Demo một trang này, đồng thời giúp tôi khởi động bản xem trước cục bộ.”
Các vấn đề thường gặp khi sử dụng
1. Trang mở được nhưng JSON không thay đổi sau khi lưu
Trong đa số trường hợp, bạn đang dùng máy chủ tĩnh thông thường. Trình duyệt không thể trực tiếp ghi tệp Git; cần dùng máy chủ phát triển HTML được cài đặt bởi Skill hoặc bật plugin phát triển đi kèm trong Vite. Khi thanh công cụ hiển thị “đồng bộ thất bại”, bộ nhớ đệm cục bộ vẫn giữ lại bản nháp.
2. Không thấy chú thích sau khi đổi sang máy tính khác
Hãy xác nhận .prototype-notes/annotations.json đã được commit lên Git và người kia đã lấy mã nguồn mới nhất. localStorage chỉ là phương án dự phòng trên máy cục bộ, không phải môi trường chia sẻ cho cả nhóm.
3. Không xuất hiện menu chú thích khi nhấp chuột phải
Trước tiên hãy nhấp vào nút “Chú thích” ở góc dưới bên phải để vào chế độ chú thích. Chế độ thông thường vẫn giữ thao tác nhấp chuột phải nguyên bản của trình duyệt để tránh ảnh hưởng đến hoạt động hằng ngày.
4. Vị trí đánh dấu bị lệch sau khi trang được thiết kế lại
Trong chế độ chú thích, hãy kéo biểu tượng đến vị trí mới. Với những khu vực quan trọng thường xuyên thay đổi cấu trúc, có thể yêu cầu AI thêm data-prototype-anchor ổn định để tránh phụ thuộc vào cấp DOM dễ thay đổi.
5. Xảy ra xung đột khi hợp nhất annotations.json trong Git
Công cụ này phù hợp với cộng tác không đồng bộ, không phải chỉnh sửa đồng thời theo thời gian thực. Hãy lấy nhánh mới nhất trước khi bắt đầu chú thích; khi nhiều người cùng chỉnh sửa, kiểm tra xung đột theo ID đánh dấu và thời gian cập nhật. Nếu thực sự cần đồng bộ nhiều người theo thời gian thực, hãy cân nhắc sử dụng dịch vụ cơ sở dữ liệu.
6. Lo ngại việc gửi yêu cầu nội bộ hoặc ảnh chụp ra ngoài
Nội dung chú thích, tên người review, route trang và hình ảnh dán vào đều có thể chứa thông tin nhạy cảm. Dự án nên sử dụng kho riêng tư; không để máy chủ phát triển cục bộ lộ ra mạng không đáng tin cậy và cũng không phát hành thư mục .prototype-notes lên môi trường trực tuyến.
7. Có quá nhiều hình ảnh khiến trình duyệt không thể lưu trữ
Runtime sẽ nén hình ảnh và giới hạn số lượng hình trong mỗi nội dung mô tả, nhưng ảnh chụp màn hình vẫn làm tăng kích thước JSON. Khuyến nghị chỉ giữ lại phần hình ảnh liên quan trực tiếp đến vấn đề; với ảnh lớn, hãy cắt trước khi dán.
Cuối cùng
AI đã khiến việc “tạo ra một trang” ngày càng nhanh hơn, nhưng để biến trang thành sản phẩm có thể bàn giao, vẫn cần yêu cầu, review và cộng tác rõ ràng.
Tôi tạo Skill này không phải để xây thêm một hệ thống quản lý dự án khổng lồ, mà chỉ muốn lấp vào một khoảng trống nhỏ và cụ thể:
Để ý kiến được lưu lại ngay tại nơi nó thực sự phát sinh.