Tôi đang commit đặc tả bằng tiếng Hàn thay vì code — 3 chương đặc tả tạo app PWA + server

Có một điều cứ vướng mãi khi tôi để AI viết code. Code kết quả thì còn lại, nhưng cuộc hội thoại và ý định đã tạo ra code đó thì biến mất. Ba tháng sau, không còn chỗ nào để hỏi “vì sao code này lại được viết như thế này?”.

Vì vậy tôi thử đảo ngược hướng đi. Commit đặc tả chứa ý định vào git, và xem code là artifact của quá trình build. Để kiểm chứng, tôi đã làm một ứng dụng nhỏ đến cùng và công khai nó.

Đó là một PWA tên Rimlog, nơi AI nối các ghi chú cũ vào nhật ký đọc sách/học tập. Không server, không đăng ký, dữ liệu chỉ nằm trong trình duyệt.

Ứng dụng thì bình thường. Điều tôi muốn chia sẻ là cách nó được tạo ra.

Cách làm

Trong thư mục eux/ của repo có 3 bản đặc tả bằng tiếng Hàn. Toàn bộ khung ứng dụng là 40 dòng, widget thẻ AI là 25 dòng, server insight là một trang. Chúng được viết bằng những câu như thế này.

saveCapture : lưu form capture(tên nguồn·trích dẫn·suy nghĩ của tôi·tag) — chèn vào đầu captures + phản ánh vào local storage + toast “Đã lưu” + chuyển sang tab lịch sử.

Khi đưa file này vào một công cụ tên EstreUX, code sẽ được tạo ra(tôi gọi là brew). Trong code sinh ra có gắn hash của đặc tả, và nếu chỉ sửa đặc tả hoặc chỉ sửa code thì pre-commit sẽ chặn commit. Tức là dùng gate để ngăn vấn đề đặc tả trở thành lời nói dối ngay khi nó lỗi thời.

Tôi cũng đã đo số liệu. Khi đo thực tế theo cách hoàn nguyên một bàn phím số 152 dòng vốn có trong framework thành đặc tả 28 dòng, số dòng mà con người phải bảo trì giảm 60–82%. Bản thân code sinh ra đôi khi dài hơn bản gốc. Thứ giảm là phần con người đọc và sửa. Nhật ký đo lường nằm trong repo.

Server cũng là một trang đặc tả

Bản demo trên Pages là serverless nên AI chỉ chạy bằng fallback dựa trên tag trùng nhau. Để chạy đúng nghĩa, tôi thêm server tự host; phần này cũng là một file node đơn lẻ, không dependency, được brew từ một trang đặc tả. Có thể chọn backend để dùng.

• nvidia (mặc định): API miễn phí của build.nvidia.com. Cấp key mà không cần đăng ký thẻ, tương thích OpenAI và khoảng 40 lần/phút, đủ rộng rãi cho nhật ký cá nhân
• claude-cli / codex-cli: mỗi request gọi claude -p / codex exec như một child process. Đây là đường tái sử dụng gói Claude/ChatGPT đang trả tiền mà không cần API key
• openai / google: chỉ là proxy key

Key và auth chỉ nằm trên server, không đi ra trình duyệt.

Những điều tôi vẫn chưa chắc

Tôi đang mở rộng việc phán định tính nhất quán giữa đặc tả↔code từ static diff sang kiểm tra động dựa trên property, nhưng phần hiệu chỉnh trọng số vẫn chưa xong. Ngoài ra, tôi đã phát hiện một lớp false positive trong đó render của framework trong môi trường headless DOM chạy khác với trình duyệt thật, nên việc nâng môi trường kiểm chứng lên trình duyệt thật cũng là bài toán còn lại. Nếu xem lịch sử commit từ đầu, bạn sẽ thấy quá trình scaffold→đặc tả→sinh code→tinh chỉnh được lưu lại theo đúng thứ tự.

• Live: https://soliestre.github.io/Rimlog/
• Repo: https://github.com/SoliEstre/Rimlog
• Nhật ký build(chi tiết): https://estreui.tistory.com/5

Tôi muốn hỏi hai điều. Theo bạn, bẫy của cách đặt đặc tả làm SSoT là gì? Đặc biệt tôi tò mò bạn đã gặp những điểm nào mà sức biểu đạt của đặc tả không theo kịp code. Và với con đường tái sử dụng subscription bằng cách dùng claude -p làm backend ứng dụng, trong thực tế có thể vướng gì không(nhìn từ góc độ rate limit, điều khoản, latency)?