Hướng dẫn cho người lớn và vibe coder
Một phụ huynh không viết dòng mã nào, vẫn có một app Android chạy thật, 64 trò chơi và trang web này. Bí quyết không nằm ở câu lệnh “thần kỳ” mà ở cách làm việc: đặc tả rõ, luật ít mà cứng, đòi bằng chứng, sửa lỗi bằng handover. Cách làm đó dùng được cho game khác, công cụ nội bộ, và cả sản phẩm để bán.
Bố mẹ muốn các bé chơi những game học tập do chính mình nhờ AI làm, trên một điện thoại Android, mà không có quảng cáo, không vào mạng, không tự thoát sang ứng dụng khác. Mở game HTML bằng trình duyệt thì bé bấm vài cái là ra ngoài, nên cần một app “vỏ” riêng để chạy game.
Chín nguyên tắc dưới đây là phần đáng giá nhất của dự án. Mỗi nguyên tắc kèm ví dụ thật trong repo.
Quyết định sản phẩm (cho ai, làm gì, không làm gì) là việc của người. Chọn thư viện, kiến trúc, tên biến, màu nút là việc của AI, và AI không được hỏi lại những việc đó.
Trong dự án: bible mở đầu bằng “Không yêu cầu chủ dự án lựa chọn framework, màu sắc, tên class, thư viện hay cấu trúc thư mục”. Bố mẹ chỉ chốt: offline, PIN phụ huynh, bé không thoát ra được, thêm game bằng cách chép thư mục.
Thời gian đầu tư vào tài liệu cho lợi nhiều nhất. Một đặc tả tốt chốt sẵn mặc định, nói rõ phạm vi bản đầu và những gì để sau, và nói trung thực giới hạn của nền tảng.
Trong dự án: bible có bảng “mong muốn → cam kết thực tế”, ví dụ “Bé chỉ ở trong app” được diễn đạt lại thành “ghim ứng dụng hạn chế chuyển app, không hứa chặn nút nguồn”. Có cả mục “Vì sao chọn phương án này” so sánh sáu cách làm khác.
Một danh sách ngắn những điều không bao giờ được phá, kể cả để “cho demo chạy”. Trong khung đó AI được tự do. Luật nhiều quá thì AI lẫn; không có luật thì AI đi tắt.
Trong dự án: không quyền Internet; không cầu nối JavaScript có quyền; không đổi khóa ký (đổi là không cài đè được, gia đình mất dữ liệu); mã định danh game là vĩnh viễn; không in PIN.
AI rất dễ viết “đã kiểm thử, mọi thứ hoạt động”. Hãy đòi log, ảnh chụp, số test chạy thật, và bốn nhãn trạng thái: PASS, FAIL, NOT_RUN, BLOCKED. “PASS trên emulator” khác “PASS trên máy thật”.
Trong dự án: báo cáo 1.1.0 ghi thẳng: giọng đọc PASS với 3 game đại diện, NOT_RUN với 47 game còn lại từng cái một; mục tiêu “câu đầu < 500 ms” chưa đạt trên emulator Android 17.
Đọc mã không phải là kiểm thử. AI phải mở ứng dụng thật, chạm và kéo thật, ở nhiều cỡ màn hình, mất mạng, tải lại, cố tình làm sai. Rồi người thử trên thiết bị thật những gì máy không làm được: nghe bằng tai, ghim ứng dụng, chọn thư mục.
Trong dự án: mỗi game được chơi trọn bằng chạm giả lập ở 390×844, 844×390 và 1280×800. App được thử trên emulator Android 8 với WebView rất cũ (Chromium 69), nơi phát hiện nhiều lỗi nhất.
Một phần ổn định, ít thay đổi, lo an toàn (vỏ). Nhiều phần nhỏ, thay được, chỉ cần đúng một định dạng (nội dung). Hợp đồng giữa hai bên được viết thành tài liệu và có công cụ kiểm tra.
Trong dự án: player không biết gì về từng game. Game là thư mục HTML; game theo SDK có thêm game.json và player-sdk.js, được pack_game.py kiểm tra. Nhờ vậy bốn phiên AI làm 40 game cùng lúc mà không giẫm chân nhau, và thêm game không cần APK mới.
Khi gặp lỗi hay muốn thêm tính năng: đo nguyên nhân trước, chốt quyết định với người, viết yêu cầu phải đạt và kiểm thử bắt buộc, rồi giao cho một phiên AI mới với ngữ cảnh sạch.
Trong dự án: lỗi “game im lặng trong app” được giải quyết bằng HANDOVER_TTS_v1.1.0.md (xem mục sửa lỗi).
AI không nhớ gì giữa các phiên. Bộ nhớ dài hạn của dự án là tài liệu: sổ quyết định, trạng thái tiến độ, sổ tay cho AI. Mỗi cái bẫy đã gặp một lần phải được ghi lại để không gặp lần hai.
Trong dự án: DECISIONS.md (22 quyết định và lý do), BUILD_STATUS.md, AI_PLAYBOOK.md (bảng các bẫy, ví dụ “WebView Android 8 làm hỏng chữ có dấu khi gửi giữa trang và app”).
Không thu thập dữ liệu nếu không cần. Không để khóa, mật khẩu, đường dẫn máy tính hay thông tin cá nhân lọt vào mã nguồn, file nén, log hay báo cáo. Việc khó hoàn tác (xóa dữ liệu, đổi khóa, công bố) luôn hỏi người trước.
Trong dự án: trước khi đưa lên GitHub, AI quét toàn bộ hơn 1.100 file, kể cả bên trong APK và ZIP, và thay mọi đường dẫn, tên máy, cấu hình máy trong bản công khai.
| AI làm | Người làm |
|---|---|
| Toàn bộ mã, hình, âm thanh, icon, test, build, ký (khi có khóa), đóng gói, tài liệu, báo cáo | Quyết định sản phẩm: làm gì, cho ai, không làm gì |
| Tự chọn chi tiết kỹ thuật, ghi lý do vào sổ quyết định | Những bước chỉ chủ thiết bị làm được: cài app, cấp quyền, tạo PIN thật, nghe bằng tai, thử trên máy thật |
| Thử như người dùng thật trên emulator và trình duyệt tự động | Giữ và sao lưu khóa ký, mật khẩu, tài khoản |
| Báo cáo trung thực cái đã thử và cái chưa thử được | Duyệt trước mọi việc khó hoàn tác: xóa dữ liệu, đổi khóa, công bố, chi tiền |
Người không cần biết lập trình, nhưng cần biết đọc báo cáo một cách hoài nghi: hỏi “đã chạy thật chưa, bằng chứng đâu, cái gì chưa thử”.
KidsGamesPhụ huynh chép game vào bộ nhớ máyBUILD_STATUS.md để phiên sau làm tiếp được nếu bị ngắt.| Mốc | Nội dung | Cửa kiểm tra (rút gọn) |
|---|---|---|
| A | Môi trường, project, WebView nạp file nội bộ | Chứng minh sớm chạy được HTTPS giả lập cục bộ mà không cần quyền Internet |
| B | Từ thư mục đến game | Chép thêm một game vào thư mục thì menu nhận ra, không sửa APK |
| C | Player đúng vòng đời | Hai game dùng chung khóa lưu không đè nhau; đổi game hay ra nền thì hết tiếng |
| D | Điều khiển trẻ và phụ huynh | Không có đường từ game tới cài đặt hay bỏ ghim |
| E | Quy trình làm game | Một thư mục mới được đóng gói rồi chạy giống nhau trên trình duyệt và trong app |
| F | Bản bàn giao | File truy xuất được, mã nguồn không chứa bí mật, trạng thái test đúng thực tế |
| Phương án | Vấn đề với yêu cầu | Quyết định |
|---|---|---|
| Mở game trong trình duyệt hoặc PWA | Không quản lý được nhiều game, phiên chơi, cài đặt phụ huynh | Không chọn |
| Mỗi game một APK | Trái mục tiêu thêm game mà không build lại | Không chọn |
| Khung Capacitor, Cordova, Flutter | Thêm thư viện và cầu nối nhưng không giải quyết thư mục, ghim ứng dụng, vòng đời | Không cần |
| Máy chủ HTTP nội bộ trong app | Thêm cổng mạng, vòng đời, bề mặt tấn công | Không cần |
| WebView đọc thẳng thư mục | Đang chép dở thì bé mở trúng bản hỏng | Không ưu tiên |
| Thư mục → bản nội bộ không đổi → WebView | Tốn thêm dung lượng và phải có bộ nạp | Chọn |
Bài học: hãy để AI so sánh các phương án thật sự khác nhau và viết lý do, thay vì hỏi “dùng framework nào tốt nhất”. Đánh giá này đúng cho một app gia đình với nhiều game nhỏ, không phải kết luận chung về framework.
Có hai con đường, cả hai đều cho ra một thư mục HTML chép thẳng vào điện thoại.
Dành cho game cần chạy ổn định trong app, kể cả máy cũ. Hợp đồng gồm: index.html, game.json (mã định danh vĩnh viễn), icon.png và player-sdk.js chép nguyên văn. SDK lo tạm dừng, tắt tiếng, lưu tiến trình, vòng lặp khung hình.
Công cụ: khuôn mẫu MauGame, pack_game.py kiểm tra trước khi giao, preview_game.py xem thử với đúng luật chặn mạng như app. Đã dùng cho 3 game mẫu và 10 game trong KidsGames-1file/.
Dành cho làm nhanh nhiều game chạy cả trên trình duyệt. Mỗi game chỉ là index.html tự chứa và icon.png. Mỗi lô là một file prompt; bốn lô chạy song song trong bốn phiên AI.
Đổi lại, game làm cho trình duyệt mới có thể hỏng trên WebView cũ: trên Android 8 chưa cập nhật, 16/51 game không khởi động. Bài học: ghi rõ thiết bị mục tiêu ngay trong prompt.
File games/Bo game 2.md (163 dòng) có sáu phần. Cấu trúc này dùng lại được cho bất kỳ việc “sản xuất hàng loạt” nào: trang web, mẫu báo cáo, bài học, màn hình công cụ.
Chạy song song có giá: bốn phiên AI cùng mở nhiều Chrome tự động làm máy chậm hẳn, các kiểm thử phụ thuộc thời gian dễ chập chờn, và có lúc chạm giới hạn sử dụng của tài khoản. Hãy để mỗi phiên một thư mục riêng và chấp nhận chạy chậm hơn.
Bỏ đi chữ “game” và “trẻ em”, dự án này là hai thứ dùng lại được: một mô hình sản phẩm (vỏ an toàn + nội dung cắm vào) và một quy trình làm việc với AI (đặc tả → giao → bằng chứng → handover → ghi nhớ).
Game luyện trí nhớ cho ông bà, game ôn bài cho cả lớp, minigame cho sự kiện của cửa hàng. Prompt lô game dùng lại gần như nguyên vẹn, chỉ đổi đối tượng và tiêu chuẩn.
Khảo sát khách hàng, đăng ký, xếp hàng, tra cứu sản phẩm. Đúng mô hình của player: khóa máy, chạy offline, mã PIN quản trị, mỗi màn hình là một thư mục HTML thay được.
Checklist kiểm tra hiện trường không cần mạng, máy tính báo giá, tài liệu đào tạo tương tác, công cụ xử lý file Excel hay PDF lặp lại hằng ngày.
Script xử lý dữ liệu, báo cáo định kỳ, website giới thiệu. Quy trình giữ nguyên: đặc tả ngắn, luật không được phá, kiểm thử có bằng chứng, handover khi cần sửa.
Làm được, với điều kiện thêm những phần mà dự án gia đình bỏ qua: pháp lý, phát hành, bảo mật, hỗ trợ khách hàng (xem mục kế tiếp).
| Trong repo này | Trong dự án của bạn |
|---|---|
specs/…Bible.md | Bản đặc tả sản phẩm (SPEC.md): mục tiêu, phạm vi, mặc định, kiến trúc, kiểm thử, định nghĩa xong |
| Luật không được phá (AI_PLAYBOOK mục 3) | Danh sách ràng buộc: bảo mật, dữ liệu, những thứ không bao giờ đổi |
| Mốc A–F có cửa kiểm tra | Các mốc nhỏ, mỗi mốc có điều kiện qua cửa đo được |
player-sdk.js, GAME_FORMAT.md | Hợp đồng giữa vỏ và nội dung: định dạng, API, công cụ kiểm tra |
games/Bo game N.md | Prompt sản xuất theo lô |
HANDOVER_TTS_v1.1.0.md | Phiếu yêu cầu thay đổi |
DECISIONS.md, BUILD_STATUS.md | Sổ quyết định và nhật ký tiến độ |
BUILD_REPORT.md, evidence/ | Báo cáo kiểm thử kèm bằng chứng |
AI_PLAYBOOK.md | Sổ tay cho AI: bản đồ repo, quy trình, bẫy đã gặp |
Dự án gia đình được phép bỏ qua nhiều thứ mà sản phẩm thương mại thì không. AI giúp được ở hầu hết các việc dưới đây, nhưng trách nhiệm vẫn là của bạn, và các phần pháp lý, bảo mật nên có người có chuyên môn xem lại.
Thay phần trong ngoặc vuông. Các prompt này cố ý dài và cụ thể: với AI, mơ hồ là nguồn gốc của hầu hết kết quả tệ.
Tôi muốn làm [mô tả 2–3 câu: cho ai, giải quyết việc gì]. Chưa viết mã.
Hãy phỏng vấn tôi theo từng nhóm câu hỏi (người dùng, việc họ làm, dữ liệu, thiết bị, an toàn và riêng tư, cách phân phối, những gì KHÔNG làm) cho đến khi đủ thông tin.
Sau đó tra tài liệu chính thức của các nền tảng liên quan, so sánh vài phương án thật sự khác nhau, rồi viết SPEC.md để một AI lập trình khác đọc là làm được từ đầu đến cuối, gồm:
- mục 0: lệnh thực thi cho AI (làm hết, không dừng ở kế hoạch, tự quyết chi tiết kỹ thuật, không công bố hay mua gì);
- mục tiêu, phạm vi bản đầu và những gì để sau;
- bảng các mặc định đã chốt; bảng "mong muốn → cam kết thực tế" về giới hạn của nền tảng;
- kiến trúc, ranh giới trách nhiệm, luật không được phá;
- các mốc, mỗi mốc có điều kiện qua cửa đo được;
- ma trận kiểm thử, định nghĩa "xong", mẫu báo cáo với nhãn PASS / FAIL / NOT_RUN / BLOCKED;
- vì sao chọn phương án này.Đọc toàn bộ SPEC.md và thực thi từ đầu đến cuối. Tự quyết các chi tiết kỹ thuật thông thường và ghi lý do vào DECISIONS.md; không hỏi tôi chọn thư viện, tên biến, màu sắc.
Làm theo từng mốc; sau mỗi mốc cập nhật BUILD_STATUS.md để có thể làm tiếp nếu bị ngắt.
Chỉ viết "đã kiểm thử" khi đã chạy thật và có log hoặc ảnh; dùng nhãn PASS / FAIL / NOT_RUN / BLOCKED.
Bước nào cần tôi làm trên thiết bị thì ghi rõ từng thao tác và vẫn hoàn thành mọi phần còn lại.
Không xóa dữ liệu, không công bố, không đổi khóa hay mật khẩu khi chưa hỏi tôi.Làm [10] [game / màn hình / mẫu tài liệu] theo danh sách dưới đây, mỗi cái trong một thư mục riêng, đúng tên đã ghi.
Đã có hoặc đang được làm ở nơi khác (không làm trùng, không sửa thư mục của chúng): [danh sách].
Danh sách cần làm: [tên — thư mục — mô tả cụ thể].
Tiêu chuẩn bắt buộc cho mọi cái: [thiết bị và trình duyệt mục tiêu, ngôn ngữ, phong cách, khả năng dùng khi mất mạng, kích thước màn hình, hiệu năng, không lỗi console…].
Cách làm: viết phần dùng chung trước; làm một cái mẫu hoàn chỉnh làm chuẩn chất lượng; có thể chia phần còn lại cho agent con nhưng phải tự kiểm thử lại từng cái; đánh bóng ít nhất ba lượt bằng cách xem ảnh chụp.
Trước khi báo xong: tự dùng thử như người dùng thật ở [các kích thước / thiết bị], thao tác thật, cố tình làm sai, tải lại, mất mạng; chụp ảnh; báo cáo bảng kết quả, đã kiểm gì và CHƯA kiểm được gì.Chưa sửa gì. Hãy điều tra vấn đề sau: [mô tả, cách tái hiện, điều mong đợi, thiết bị].
Đo và tìm nguyên nhân thật (đọc mã, chạy thử). Đưa tôi 2–3 phương án kèm ưu nhược điểm để tôi chọn.
Sau khi tôi chọn, viết HANDOVER.md gồm: bối cảnh và quyết định đã chốt; tài liệu phải đọc; yêu cầu phải đạt; thiết kế đề xuất (có bước đo lại trước khi viết mã); kiểm thử bắt buộc; những gì phải bàn giao; ràng buộc giữ nguyên; tiêu chí hoàn thành.Đừng chỉ đọc mã. Chạy ứng dụng thật (trình duyệt tự động hoặc emulator), thao tác bằng chạm hoặc click thật theo kịch bản: [kịch bản].
Thử ở [kích thước / thiết bị], kể cả máy cũ nhất cần hỗ trợ; mất mạng; tải lại; xoay màn hình; cố tình nhập sai.
Chụp ảnh từng bước, ghi lại lỗi console. Báo cáo bảng PASS / FAIL / NOT_RUN kèm đường dẫn bằng chứng, và danh sách những gì tôi cần tự thử trên thiết bị thật.Bạn là người kiểm định độc lập, không phải người viết. Đọc yêu cầu gốc [file] và kết quả hiện tại.
Liệt kê: chỗ chưa đạt yêu cầu, chỗ báo cáo nói quá so với bằng chứng, rủi ro bảo mật và riêng tư (bí mật, đường dẫn máy tính, dữ liệu cá nhân trong repo), việc khó hoàn tác chưa được hỏi.
Không sửa gì, chỉ báo cáo, xếp theo mức nghiêm trọng.Trước khi kết thúc: cập nhật AI_PLAYBOOK.md với những gì phiên này học được (lệnh build và test, quyết định mới và lý do, bẫy đã gặp và cách tránh). Viết ngắn, cụ thể, để một phiên AI mới chỉ đọc file này là làm tiếp được. Cập nhật DECISIONS.md và BUILD_STATUS.md nếu có thay đổi.| Lỗi | Cách tránh |
|---|---|
| Yêu cầu mơ hồ: “làm app đẹp, dễ dùng” | Nói rõ người dùng, việc họ làm, thiết bị, giới hạn, ví dụ cụ thể |
| Không có định nghĩa “xong” | Viết tiêu chí nghiệm thu đo được trước khi giao việc |
| Tin chữ “đã test xong” | Đòi log, ảnh, số test, nhãn NOT_RUN cho phần chưa chạy |
| Sửa nhiều thứ trong một cuộc chat rất dài | Mỗi thay đổi lớn một handover, một phiên mới |
| AI tự đổi thứ không được đổi (khóa ký, mã định danh, định dạng dữ liệu) | Ghi thành luật không được phá, nhắc lại trong mỗi handover |
| Chỉ thử trên máy của mình | Thử trên thiết bị cũ nhất cần hỗ trợ; người tự thử phần máy không làm được |
| Lộ bí mật hoặc thông tin máy khi công khai | Loại trừ file bí mật ngay từ đầu; quét toàn bộ, kể cả file nén, trước khi đưa lên |
| Không ghi lại bài học | Sổ tay cho AI, sổ quyết định; cập nhật trước khi đóng phiên |