Dùng smyw để Agent lập trình phác thảo prototype trước khi viết mã: Hướng dẫn cài đặt, đánh giá và phản hồi đầy đủ

smyw là gì

smyw, viết tắt của “show me you want”, là một skill dành cho Agent lập trình, phù hợp với Claude Code, DeepSeek Harness và các Agent hỗ trợ SKILL.md. Skill này yêu cầu Agent đọc mã nguồn trước khi chỉnh sửa trang, quy trình tương tác hoặc API frontend/backend, viết spec có cấu trúc, rồi tạo prototype HTML một tệp có thể mở ngoại tuyến.

Prototype này không phải bản thiết kế trực quan cuối cùng, mà là wireframe độ trung thực thấp dùng để thể hiện thành phần, vị trí bố cục, quan hệ kích hoạt và thay đổi chức năng. Phần triển khai chính thức vẫn phải tuân theo quy chuẩn thiết kế hiện có của dự án.

Giải quyết vấn đề gì

Quy trình lập trình Agent truyền thống thường chuyển thẳng từ yêu cầu bằng văn bản sang triển khai, nên dễ phát sinh sai lệch trong cách hiểu về cấu trúc trang, phương thức tương tác hoặc ranh giới API. smyw bổ sung một giai đoạn xác nhận trực quan giữa yêu cầu và mã nguồn:

1. Người dùng đưa ra yêu cầu chức năng.
2. Agent đọc mã nguồn dự án và tạo spec.json.
3. Script build kiểm tra spec và xuất preview.html.
4. Người dùng xem, trình diễn, kéo thả và chú thích phương án trong trình duyệt.
5. Người dùng sao chép phản hồi và gửi lại vào cuộc hội thoại.
6. Agent áp dụng phản hồi và tạo phiên bản prototype tiếp theo.
7. Chỉ sau khi người dùng xác nhận phương án, Agent mới bắt đầu viết mã.

Trọng tâm của smyw không phải là thay thế công cụ thiết kế, mà là giúp người dùng và Agent lập trình thống nhất trước khi triển khai về “cần sửa gì, đặt ở đâu và kích hoạt như thế nào”.

Tính năng chính

Đánh dấu bằng số và so sánh trước sau

Prototype vẽ toàn bộ giao diện theo bố cục trang thực tế và dùng màu để phân biệt thay đổi: màu vàng biểu thị chỉnh sửa, màu xanh lá biểu thị thêm mới, màu đỏ biểu thị xóa. Chỉ các module ở lớp ngoài cùng có thay đổi mới được đánh số, tránh xuất hiện quá nhiều dấu đánh dấu lặp lại ở các phần tử bên trong.

Khi nhấp vào số trên canvas hoặc danh sách thay đổi bên trái, canvas sẽ tập trung vào khu vực tương ứng. Bên phải hiển thị wireframe cục bộ trước và sau thay đổi, khác biệt trường dữ liệu, mô tả của Agent, component mã nguồn và các hàm hoặc API liên quan.

Nếu toàn bộ module là nội dung được thêm mới, phần “Trước thay đổi” trong chi tiết sẽ cho biết module này trước đó không tồn tại; các nút và văn bản bên trong sẽ không được đánh số riêng lẻ.

Thể hiện chính xác việc di chuyển component

Khi một component được di chuyển từ vị trí này sang vị trí khác, vị trí cũ hiển thị “di chuyển ra” màu đỏ, còn vị trí mới hiển thị “di chuyển vào” màu xanh lá. Hai bản ghi có thể chuyển qua lại cho nhau, giúp xác nhận đây không phải là một lần xóa kết hợp với một lần thêm mới không liên quan.

Lớp phủ, menu và nội dung mở rộng

Cửa sổ bật lên, ngăn kéo, menu thả xuống, bong bóng và nội dung chỉ mở rộng sau khi nhấp sẽ được đặt trong các panel riêng cạnh màn hình chính, với đường nối trỏ đến nút kích hoạt. Một lớp phủ có thể liên kết với nhiều điểm kích hoạt; lớp phủ bị xóa được biểu thị bằng đường nét đứt màu đỏ.

Menu nhiều cấp sẽ tiếp tục được tách thành các panel liền kề. Nội dung mở rộng tại chỗ sẽ để lại một vùng giữ chỗ nét đứt màu tím trên trang, cho biết vị trí xuất hiện sau khi mở rộng. Đường nối chuyển trang và chuyển trạng thái mặc định bị ẩn; có thể xem khi chọn phần tử liên quan hoặc mở đồng thời qua “Tất cả đường nối”.

Chế độ trình diễn có thể nhấp

Nhấp vào “▶ Trình diễn” ở góc trên bên phải để prototype ẩn các khung thay đổi và mô phỏng thao tác thực tế trên một màn hình. Chế độ này có thể trình diễn việc mở menu, ngăn kéo trượt ra, mở cửa sổ bật lên, thay đổi trạng thái nút và chuyển trang.

Nếu nhấp vào khu vực không thể thao tác, tất cả vị trí hiện có thể nhấp sẽ nhấp nháy bằng khung màu xanh dương, đồng thời bên trái liệt kê các thao tác có thể thực hiện. Chế độ trình diễn hỗ trợ quay lại, bắt đầu lại từ đầu và chuyển đổi giữa “Trước thay đổi” và “Sau thay đổi”.

Chỉnh sửa trực tiếp và tập trung phản hồi

• Chỉnh sửa cấu trúc: kéo thả component để điều chỉnh thứ tự hoặc container chứa, đồng thời sửa văn bản, loại, chiều rộng và cách sắp xếp.
• Chuyển đổi hình thức: chuyển module nội tuyến thành cửa sổ bật lên, menu thả xuống, ngăn kéo hoặc bong bóng; hệ thống sẽ tạo nút kích hoạt và đường nối.
• Hoàn tác và làm lại: hỗ trợ dùng Ctrl hoặc Command cùng Z để hoàn tác thao tác.
• Chú thích phần tử: thêm ý kiến cho phần tử được chỉ định theo các nhóm như vị trí, tương tác, loại component, kiểu dáng, nội dung hoặc thiếu chức năng.
• Mức độ ý kiến: chú thích có thể được đánh dấu là “Bắt buộc sửa”, “Đề xuất” hoặc “Câu hỏi”.
• Phản hồi tổng thể: ghi lại ý kiến về phong cách, định hướng tham khảo và trả lời các câu hỏi xác nhận do Agent liệt kê trước.
• Gửi lại bản vá: các chỉnh sửa cấu trúc chỉ được đính kèm ở cuối phản hồi dưới dạng bản vá định vị theo ID, không cần gửi lại toàn bộ phương án.

Chuẩn bị trước khi cài đặt

Để build prototype smyw, chỉ cần Node.js 18 trở lên; bản thân dự án không cần server và không có dependency khi chạy. Trước tiên hãy kiểm tra phiên bản Node.js:

node --version

Nếu muốn chạy kiểm thử end-to-end của repository hoặc tạo lại ảnh chụp màn hình, bạn cũng cần cài Google Chrome. Có thể chỉ định đường dẫn cài đặt không mặc định bằng biến môi trường CHROME.

Cài đặt skill smyw

Bước 1: Clone repository

git clone https://github.com/nishuzumi/show-me-you-want-skill.git
cd show-me-you-want-skill

Bước 2: Đặt skill tại vị trí Agent có thể đọc

Người dùng Claude Code có thể tạo liên kết tượng trưng toàn cục để mọi dự án đều sử dụng được smyw:

ln -s "$PWD/skills/smyw" ~/.claude/skills/smyw

Nếu Agent đọc thư mục skills dùng chung, bạn cũng có thể liên kết đến:

ln -s "$PWD/skills/smyw" ~/.agents/skills/smyw

Nếu chỉ muốn bật skill trong một dự án, hãy sao chép vào thư mục skill cục bộ của dự án đó:

cp -r skills/smyw <dự án của bạn>/.claude/skills/smyw

Sau khi cài đặt, bạn có thể yêu cầu Agent thực hiện thay đổi giao diện hoặc API, hoặc nói trực tiếp: “Hãy tạo prototype cho tôi xem trước.”

Chạy ví dụ của repository trước

Repository đã cung cấp hai ví dụ HTML được tạo sẵn. Không cần khởi động server, chỉ cần mở trực tiếp bằng trình duyệt:

• skills/smyw/examples/helpdesk-ai/preview.html: ví dụ một màn hình hoàn chỉnh về việc thêm đề xuất trả lời bằng AI vào workspace chăm sóc khách hàng.
• skills/smyw/examples/task-tags/preview.html: ví dụ nhiều trang minh họa việc thêm mới và xóa toàn bộ trang.

Sau khi sửa spec của ví dụ, có thể dùng lệnh sau để tạo lại bản xem trước:

node skills/smyw/scripts/build.mjs skills/smyw/examples/helpdesk-ai/spec.json

Kết quả build là một tệp frontend thuần, có thể mở và đánh giá ngoại tuyến.

Cách sử dụng cơ bản từ yêu cầu đến prototype

Bước 1: Mô tả yêu cầu cho Agent

Hãy cố gắng nêu mục tiêu nghiệp vụ và các ràng buộc, nhưng không cần quyết định trước mọi chi tiết giao diện. Ví dụ:

Hãy thêm đề xuất trả lời bằng AI vào chi tiết ticket hỗ trợ khách hàng. Trước tiên đọc trang và API hiện có, chưa viết mã ngay; dùng smyw để tạo prototype để tôi xác nhận điểm vào của ngăn kéo, quy trình thay thế câu trả lời và các API liên quan.

Bước 2: Kiểm tra spec và bản xem trước được tạo

Agent sẽ lưu phương án có cấu trúc trong thư mục tương tự:

.smyw/<ngày>-<tên>/spec.json

Sau đó Agent dùng build.mjs để kiểm tra và tạo preview.html. Sau khi mở bản xem trước, hãy kiểm tra theo thứ tự sau:

1. Trước tiên dùng “Vừa khung” để đưa toàn bộ canvas vào khung nhìn.
2. Kiểm tra các khung thay đổi màu vàng, xanh lá và đỏ có phù hợp với yêu cầu không.
3. Lần lượt nhấp vào danh sách thay đổi để đối chiếu khác biệt trước sau và các trường đã thay đổi.
4. Kiểm tra component, hàm và API liên quan có tương ứng với mã nguồn hiện có không.
5. Mở “Thay đổi quy trình” và “Thay đổi backend” để kiểm tra ảnh hưởng xuyên lớp.
6. Vào chế độ trình diễn và trực tiếp nhấp vào menu, cửa sổ bật lên, ngăn kéo và các nút trạng thái.

Bước 3: Chỉnh sửa và chú thích phương án

Nếu cấu trúc không đúng như mong đợi, hãy chuyển sang “Chỉnh sửa phương án” để kéo thả component trực tiếp hoặc chuyển nội dung nội tuyến thành lớp phủ. Với những ý kiến không phù hợp để chỉnh sửa trực tiếp, hãy chọn phần tử, thêm chú thích và thiết lập nhóm cùng mức độ ưu tiên.

Nên phân biệt rõ ba loại phản hồi:

• Bắt buộc sửa: vấn đề phải được xử lý trước khi triển khai.
• Đề xuất: Agent có thể đánh giá việc tiếp nhận, nhưng nếu không tiếp nhận thì cần nêu lý do.
• Câu hỏi: cần trả lời và làm rõ trước, sau đó mới quyết định cách điều chỉnh.

Bước 4: Sao chép phản hồi và gửi lại Agent

Vào trang “Phản hồi”, bổ sung ý kiến tổng thể về phong cách, trả lời các câu hỏi cần xác nhận, rồi nhấp vào “Sao chép phản hồi”. Dán Markdown được tạo vào cuộc hội thoại với Agent.

Agent thường sẽ lưu phản hồi dưới dạng feedback-v<N>.md, rồi chạy:

node skills/smyw/scripts/apply-feedback.mjs .smyw/<dir>/feedback-v1.md .smyw/<dir>/spec.json
node skills/smyw/scripts/build.mjs .smyw/<dir>/spec.json

apply-feedback.mjs sẽ sao lưu spec cũ, áp dụng các bản vá trong phản hồi và tăng số phiên bản. Nếu phiên bản phản hồi không khớp với spec hiện tại, script sẽ từ chối áp dụng để tránh ghi đè phương án mới hơn.

Bước 5: Xác nhận rồi mới bắt đầu lập trình

Kiểm tra prototype phiên bản tiếp theo và xác nhận tất cả ý kiến “Bắt buộc sửa” đã được xử lý, các “Câu hỏi” đã được trả lời. Khi không còn vấn đề nào khác, nhấp vào “Xác nhận phương án, có thể bắt đầu thực hiện”, rồi yêu cầu Agent chuyển sang giai đoạn triển khai chính thức.

Hiểu cấu trúc cơ bản của spec

smyw dùng một cây để mô tả đồng thời giao diện trước và sau thay đổi. Mỗi node đánh dấu thay đổi bằng change, còn tương tác và trạng thái được mô tả bằng on, hidden và states.

{
  "id": "reply",
  "type": "form",
  "label": "Phản hồi khách hàng",
  "component": "<ReplyBox>",
  "change": "modified",
  "before": { "label": "Phản hồi" },
  "children": [
    {
      "id": "reply-quick",
      "type": "select",
      "text": "Phản hồi nhanh",
      "change": "removed"
    },
    {
      "id": "reply-polish",
      "type": "button",
      "label": "AI chỉnh sửa",
      "change": "added",
      "fn": "openDraftDrawer({ mode: \"polish\" })",
      "on": [
        { "action": "open", "target": "ai-drawer" }
      ]
    }
  ]
}

Ví dụ này cho biết tiêu đề biểu mẫu phản hồi được đổi từ “Phản hồi” thành “Phản hồi khách hàng”, mục phản hồi nhanh hiện có đã bị xóa và một nút mở ngăn kéo AI được thêm vào. component tương ứng với component mã nguồn, còn fn biểu thị hành vi liên quan hoặc phần giữ chỗ cho API.

Có thể xem mô tả đầy đủ về các trường tại spec-format.md, còn quy tắc thực thi của Agent được nêu trong SKILL.md.

Kỹ thuật sử dụng nâng cao

Kiểm tra đồng thời giao diện, quy trình và backend

Đừng chỉ đánh giá bố cục trang. Với các tính năng liên quan đến API hoặc thay đổi dữ liệu, cũng cần xem xét sơ đồ luồng và các thay đổi ở backend. Sơ đồ luồng sẽ đối chiếu trước và sau thay đổi theo người dùng, frontend, backend, cơ sở dữ liệu và dịch vụ bên ngoài; điểm truy cập trên từng bước có thể đưa trở lại phần tử giao diện tương ứng.

Sử dụng thanh công cụ để hiểu ảnh hưởng đến mã nguồn

• Mở “ƒ Hàm” để xem hành vi hoặc phần giữ chỗ cho API phía sau phần tử.
• Mở “Component” để xem component mã nguồn tương ứng với module.
• Mở “Làm mờ phần không thay đổi” để tập trung vào phạm vi bị ảnh hưởng bởi yêu cầu lần này.
• Chỉ mở “Tất cả đường nối” khi cần kiểm tra đầy đủ các mối quan hệ kích hoạt.

Xác thực thay đổi trạng thái bằng chế độ trình diễn

Chế độ trình diễn không chỉ dùng để xem chuyển hướng mà còn phù hợp để xác thực sự liên kết giữa các trạng thái. Ví dụ, một nút “Thay thế vào hộp phản hồi” có thể điền bản nháp vào hộp phản hồi và đóng ngăn kéo. Ghi chú sẽ tự động lưu lại trang hiện tại, nội dung đang mở và lịch sử nhấp chuột, giúp Agent tái hiện vấn đề.

Giữ ID ổn định

Thay đổi cấu trúc trong phản hồi được định vị theo ID nút, vì vậy nên cố gắng giữ ID của các nút hiện có ổn định qua nhiều vòng lặp. Trừ khi bản thân phần tử bị xóa hoặc ngữ nghĩa thay đổi hoàn toàn, không nên tùy ý đổi ID.

Chú trọng việc kiểm tra build

build.mjs sẽ kiểm tra các vấn đề thường gặp như ID trùng lặp, nút bị sửa thiếu before, dùng “（không thay đổi）” để thay cho module thực tế và lớp phủ thiếu bộ kích hoạt. Khi xảy ra lỗi, trước tiên cần sửa spec rồi mới đánh giá kết quả được tạo.

Xử lý cửa sổ hẹp và giới hạn sandbox

Trong các cửa sổ hẹp như phần xem trước bên cạnh Agent, danh sách thay đổi sẽ được thu gọn vào nút “☰ Thay đổi”, còn phần chi tiết sẽ nổi trên canvas. Trong sandbox bị hạn chế, trình duyệt có thể không cho phép lưu tiến độ hoặc tự động sao chép; nếu sao chép thất bại, trang sẽ tự động chọn nội dung phản hồi, khi đó chỉ cần nhấn Ctrl hoặc Command cùng C.

Phát triển và kiểm thử dự án

Nếu cần sửa chính smyw, bạn có thể chạy kiểm thử đầu cuối hoặc tạo lại ảnh chụp README:

node tests/e2e.mjs
node tests/readme-shots.mjs

Kiểm thử yêu cầu Node.js phiên bản 18 trở lên và Google Chrome. Khi Chrome không nằm ở đường dẫn mặc định, có thể chỉ định như sau:

CHROME=/path/to/chrome node tests/e2e.mjs

Dự án được phát hành theo giấy phép MIT.

Tóm tắt

smyw chuyển quy trình làm việc của coding Agent từ “đọc hiểu yêu cầu rồi viết mã ngay” thành “đọc mã trước, tạo spec, trình bày prototype tương tác, thu thập phản hồi có cấu trúc rồi mới bắt đầu triển khai”. Công cụ đặc biệt phù hợp với các yêu cầu liên quan đến bố cục trang, lớp phủ, chuyển đổi trạng thái, quy trình nhiều trang hoặc API frontend và backend.

Hãy bắt đầu trải nghiệm từ các ví dụ trong repository, xác nhận Agent có thể đọc skill rồi mới áp dụng vào dự án thực tế. Thông qua đánh dấu thay đổi, chế độ trình diễn, chỉnh sửa trực tiếp, ghi chú và phản hồi có phiên bản, bạn có thể giảm đáng kể sai lệch trong việc hiểu yêu cầu, để quá trình lập trình chính thức được xây dựng trên một phương án đã được xác nhận.