Context pack cho vibe coding: screenshot, mockup, data, rules, edge case

AI không đọc được ý nghĩ của bạn. Nó đọc được context bạn đưa vào. Trong vibe coding, nhiều app sai không phải vì model không biết code, mà vì người dùng đưa quá ít context rồi ngạc nhiên khi AI tự bịa requirement. Bạn nói “làm app quản lý lớp học”, nó không biết lớp học của bạn là yoga, tiếng Anh, nhạc, hay luyện thi. Bạn nói “giống dashboard cũ”, nhưng không đưa screenshot. Bạn nói “data giống file Excel”, nhưng không đưa sample CSV.

Context pack là gói input nhỏ giúp AI build đúng hơn. Nó không phải tài liệu dài 40 trang. Nó là một bộ bằng chứng: screenshot, sketch, data mẫu, rule nghiệp vụ, API docs, brand note, edge case, và những thứ không được đụng. Mục tiêu là giảm khoảng trống để AI phải đoán.

Context pack không phải prompt dài

Prompt dài chưa chắc là context tốt. Một đoạn chat 8.000 chữ có thể đầy nhiễu: ý tưởng cũ, quyết định đã bỏ, feedback mâu thuẫn, câu nói nửa đùa, spec lỗi thời. AI có thể bám nhầm một câu cũ và sửa sai hướng.

Context pack tốt thì ngắn, có cấu trúc, và phân biệt rõ:

• Hiện trạng là gì.
• Mục tiêu vòng này là gì.
• Dữ liệu thật hoặc mẫu trông như thế nào.
• Rule nào bắt buộc.
• Điều gì không được thay đổi.
• Edge case nào cần test.

Nếu chat đã dài, đừng bảo AI “đọc lại từ đầu”. Hãy tạo context pack mới. Nó giống việc bạn brief một freelancer: không gửi toàn bộ lịch sử Slack, gửi brief cập nhật.

Screenshot: bằng chứng nhanh nhất

Screenshot giúp giảm rất nhiều hiểu nhầm. Nếu bạn muốn AI sửa UI, đừng chỉ nói “button bị lệch”. Chụp màn hình, khoanh vùng nếu cần, mô tả điều bạn muốn.

Ví dụ feedback kém:

The mobile layout looks bad. Fix it.

Feedback tốt hơn:

In the attached mobile screenshot at 390px width, the status filter wraps into two lines and pushes the primary button below the fold.
Keep the filter visible, but make the primary action easier to reach.
Do not change the table columns.

Screenshot cũng hữu ích khi bạn muốn clone hoặc cải tiến UI có sẵn. Nhưng đừng dùng kiểu “make it exactly like this” nếu bạn không có quyền hoặc không cần pixel-perfect. Hãy nói rõ phần nào cần học: density, hierarchy, form layout, navigation, color mood.

Sketch và mockup: xấu cũng được, miễn rõ

Một sketch tay trên giấy nhiều khi tốt hơn một đoạn mô tả dài. Bạn vẽ ba box: filter trên cùng, table ở giữa, detail panel bên phải. Chụp ảnh gửi vào tool. AI không cần sketch đẹp. Nó cần layout intent.

Sketch nên đi kèm chữ:

Use this sketch as layout intent, not exact visual design.
Top: filter row.
Middle: booking table.
Right: detail panel on desktop.
On mobile, detail panel becomes full-screen drawer.

Nếu không nói “not exact visual design”, AI có thể bắt chước cả nét xấu của sketch. Nếu không nói mobile behavior, nó có thể chỉ scale layout desktop xuống điện thoại.

Mockup Figma cũng tương tự. Đừng gửi cả file lớn nếu chỉ cần một screen. Export screenshot hoặc link đúng frame. Ghi rõ frame nào là source of truth.

Sample data: đưa vài dòng thật hơn lorem ipsum

Data mẫu tốt giúp AI hiểu domain. Với app booking, data kiểu này ít giá trị:

name,date,status
John,2026-06-01,active
Jane,2026-06-02,inactive

Data này tốt hơn:

customer_name,phone,shoot_date,package,deposit_status,note
Minh Anh,0901234567,2026-06-04,Family Outdoor,paid,Chụp tại Thảo Điền lúc 16:00
Huy Tran,0912345678,2026-06-07,Wedding Pre-shoot,partial,Cần gửi moodboard trước thứ Sáu
Linh Studio,0987654321,2026-06-09,Product,unpaid,Khách cần hóa đơn VAT

AI nhìn data sẽ hiểu field nào quan trọng, text dài ra sao, tiếng Việt có dấu, status thật là gì. Bạn cũng dễ test UI với long note, phone, date, status.

Nếu data nhạy cảm, tạo sample đã ẩn thông tin. Đừng paste dữ liệu khách hàng thật vào tool nếu chưa rõ policy, retention, account boundary. Dữ liệu mẫu nên giống cấu trúc thật, không cần là dữ liệu thật.

API docs và endpoint contract

Khi chuyển từ prototype sang real data, context pack cần API contract. Không cần paste toàn bộ docs backend. Cần đúng endpoint, request, response, auth, error state.

Ví dụ:

Existing API contract:
- GET /api/bookings?from=YYYY-MM-DD&to=YYYY-MM-DD&status=paid|partial|unpaid
- POST /api/bookings
- PATCH /api/bookings/:id

Booking fields:
- id: string
- customerName: string
- phone: string
- shootDate: ISO date string
- packageName: string
- depositStatus: "paid" | "partial" | "unpaid"
- note: string | null

Do not create new endpoints.
If a required endpoint is missing, stop and tell me.

Trong repo thật, tốt hơn nữa là chỉ đường tới API client hoặc hook có sẵn:

Before editing, inspect:
- src/features/bookings/useBookings.ts
- src/api/bookings.ts

Reuse existing hooks. Do not create a second fetcher.

Điều này ngăn AI dựng mock hoặc tạo endpoint mới chỉ vì không tìm thấy trong vài giây.

Brand notes: ít nhưng cụ thể

Brand note không phải một bài thơ về thương hiệu. Nó nên đủ để AI chọn tone và visual đúng.

Kém:

Make it premium and modern.

Tốt:

Brand direction:
- Practical, calm, work-focused.
- Avoid playful gradients and oversized hero sections.
- Use Vietnamese labels.
- Primary color: #1F6F5B.
- Status colors should be distinct and readable.

Nếu có logo, font, color token, gửi đúng file hoặc ghi rõ. Nếu chưa có brand, nói thẳng “use neutral default styling for prototype, do not invent a brand system yet”. Đừng để AI dành cả vòng đầu tạo visual identity trong khi flow chưa chạy.

Repo rules và những thứ không được đổi

Nếu vibe coding trên repo hiện có, context pack phải có repo rules. Đây là phần nhiều non-tech bỏ qua vì tưởng AI tự hiểu. Nó không tự hiểu.

Ví dụ:

Repo rules:
- Use existing API hooks.
- Do not use mock data unless explicitly asked.
- Do not create barrel files.
- Do not modify global CSS.
- Do not add dependencies without asking.
- Do not commit or push.

Rule càng cụ thể càng tốt. “Write clean code” không giúp gì. “Do not add dependencies without asking” giúp rất nhiều. “Use existing endpoints” giúp tránh AI tạo backend song song.

Nếu bạn không biết repo rules, hỏi developer hoặc đọc AGENTS.md, CLAUDE.md, .cursor/rules, CONTRIBUTING.md. Không có rule thì tạo task nhỏ hơn và yêu cầu AI inspect trước khi sửa.

Edge case: đưa trước, không đợi bug

Edge case không cần phức tạp. Với UI app, edge case thường rất đời:

• Không có data.
• Data rất dài.
• Mạng chậm.
• API lỗi.
• User bấm submit hai lần.
• Mobile keyboard che form.
• Người dùng không có quyền.
• Refresh trang sau khi tạo record.

Đưa edge case vào context pack giúp AI build state sớm hơn. Nếu không, nó thường dựng happy path đẹp trước. Happy path cần, nhưng app thật sống trong edge case.

Ví dụ:

Edge cases to handle in this slice:
- Empty booking list should show a clear empty state.
- Long notes should wrap, not break the table.
- Submit button should prevent double submit.
- If API fails, show an inline error and keep form values.

Không cần đưa mọi edge case trong vòng đầu. Chọn edge case liên quan tới lát đang build.

Handoff cho agent khác

Khi một agent hoặc một chat khác tiếp tục, đừng gửi “đọc lại toàn bộ”. Handoff nên ngắn:

# Context Pack

## Product

Small booking tracker for a photography studio owner.

## Current state

- Booking list works with sample data.
- Create booking form works in local state.
- Edit deposit status works.
- No real API yet.

## Next task

Replace local sample data with existing booking API.

## Source of truth

- API contract in `docs/bookings-api.md`.
- Existing hook in `src/features/bookings/useBookings.ts`.

## Do not change

- Form fields.
- Status values.
- Table layout.
- Global styles.

## Edge cases

- Empty list.
- API loading.
- API error on create.
- Long note text.

## Manual checks

1. Load bookings from API.
2. Create booking and see it appear.
3. Refresh page and confirm booking persists.
4. Force API error and confirm form values remain.

Đây là context pack đủ để agent mới tiếp tục mà không ăn lại toàn bộ lịch sử.

Chốt lại

Vibe coding càng nhanh thì context càng quan trọng. Screenshot giúp AI thấy vấn đề. Sample data giúp nó hiểu domain. API contract ngăn nó invent backend. Repo rules giữ scope. Edge case biến demo thành app có thể test. Context pack tốt không dài. Nó chỉ cần đúng, gọn, và nói rõ điều gì là source of truth.