Đặc tả cho agent: biến ý tưởng thành nhiệm vụ

Hai yêu cầu gửi agent, cái này nối tiếp cái kia. Yêu cầu thứ nhất: "dựng trang theo đặc tả trong file SPEC_LANDING.md". Vài phút sau, trong thư mục xuất hiện index.html, và nó trông đúng như dự định. Yêu cầu thứ hai, cũng tối hôm đó: "làm game 2048". Lần này agent hoặc hỏi liền một lúc năm câu, hoặc lặng lẽ dựng một bàn chơi 5×5 kèm nút hoàn tác nước đi mà chẳng ai yêu cầu.

Khác biệt không nằm ở agent. Khác biệt nằm ở thứ nó nhận được ở đầu vào. Trong bài này, chúng ta sẽ xem đặc tả cho một nhiệm vụ nhỏ gồm những gì, lấy nội dung ở đâu để ghi vào đó, làm gì khi mới chỉ biết hướng đi, và vì sao sau chữ "xong" bạn kiểm tra kết quả theo đúng những dòng đã viết trước khi bắt đầu.

1. Ý tưởng chưa phải là nhiệm vụ

"Muốn làm 2048". "Làm cho tôi một trang thật đẹp". "Làm một game mới, hay hơn chút". Tất cả đều là ý tưởng, và chúng có chung một vấn đề: trong đầu bạn là cả một bức tranh, còn trong câu chữ chỉ có vài từ. Agent chỉ thấy phần chữ.

Gặp một chỗ trống trong yêu cầu, agent có hai lối đi. Lối thứ nhất là hỏi. Lối thứ hai là tự lấp: chọn kích thước bàn chơi, tự nghĩ ra một luật, thêm một cái nút. Lối thứ hai êm hơn, nên cũng nguy hiểm hơn. bạn sẽ không nhận ra có người đã quyết định thay mình cho đến khi nhìn thấy kết quả. Mỗi chỗ để trống trong yêu cầu là một quyết định mà ai đó sẽ đưa ra, và mặc định người đó không phải là bạn.

"Ai cũng biết chơi 2048" - đó là điều nằm trong đầu bạn. Agent không đọc được cái "ai cũng biết" ấy. Bàn chơi cỡ nào? Ô mới xuất hiện từ đâu và khi nào? Những ô nào gộp lại và gộp thành gì? Khi nào thắng, khi nào hết ván? Với bạn đó là một từ, với agent đó là chỗ trống cho đến khi được tách thành các luật cụ thể. Trong đoạn chat, chuyện đó trông như thế này:

Bạn:   làm game 2048
Agent: Cho tôi hỏi vài điều trước khi bắt đầu:
       1. Bàn chơi cỡ nào, 4×4?
       2. Thế nào thì tính là thắng?
       3. Có cần hoàn tác nước đi không?

Đó là kết cục tốt. Còn có một kết cục khác, với đúng yêu cầu đó:

Bạn:   làm game 2048
Agent: Xong. Game nằm trong file index.html:
       - bàn chơi 5×5
       - nút hoàn tác nước đi vừa rồi
       - bảng điểm cao trong localStorage

Đây không phải lỗi của agent. Đây là ba chỗ trống của bạn, đã bị lấp mà không có bạn tham gia.

Đó là con đường từ ý tưởng đến một kết quả đáng tin. Bài viết đi theo nó từ trái sang phải. Còn bước cuối cùng dẫn ngược về bước thứ ba: kiểm tra, phát hiện lỗ hổng, viết thêm một dòng vào đặc tả rồi giao lại cho agent.

2. Nội dung lấy từ đâu

Agent dựng khung của một trang hay một game chỉ trong vài phút, và đó thật sự không phải phần khó nhất. Cái khó là biết trên trang phải có gì và rốt cuộc chúng ta đang chơi trò gì. Điều đó không có trong code. Nó nằm trong đầu con người, đôi khi là chính bạn, và agent cũng biết được đôi điều. Muốn có nó thì phải hỏi, và có ba nguồn: người khác, chính bạn, agent.

Người khác ở đây là khách hàng và người sẽ dùng sản phẩm. Câu hỏi cho họ nên gửi thành một loạt. Một danh sách năm-sáu mục cùng lúc, chứ không phải mỗi ngày một câu. Gửi cả loạt trông có vẻ phiền, tôi biết. Nhưng thực tế nó giúp mọi người đỡ được cả tuần nhắn qua nhắn lại.

Khi khách hàng là chính bạn (game của mình, trang của mình), bạn tự đặt câu hỏi cho bản thân, và ở đây cám dỗ lớn nhất là trả lời "thì hiển nhiên rồi". Điều hiển nhiên cũng được ghi ra y như điều không hiển nhiên. "Bàn chơi 4×4" chỉ mất hai giây để gõ, nhưng với agent, hai giây đó khép lại cả một ngã rẽ.

Nguồn thứ ba là agent, và ở đây có một cái bẫy nên biết trước: bạn không thể hỏi về điều mình không biết. Một nước đi không làm ô nào dịch chuyển có tính là một nước không? Có cần vuốt trên điện thoại không? Có hiển thị điểm không? Những câu hỏi này không nảy ra trong đầu cho đến khi game hiện ngay trước mắt. Còn agent đã thấy cả nghìn game như vậy và biết người ta thường vấp ở đâu. Vì thế, thay vì "làm đi", đôi khi nên bắt đầu bằng "mình bàn trước đã":

Tôi muốn làm game 2048 chạy trên trình duyệt. Tạm thời đừng viết gì cả.
Hãy hỏi tôi những câu mà thiếu chúng thì bạn không bắt đầu được. Hỏi hết một lần, thành danh sách.
Tôi sẽ trả lời, rồi chúng ta gom đặc tả vào file SPEC_2048.md.

Hai quy tắc cho kiểu trò chuyện này, nếu không nó sẽ chẳng bao giờ kết thúc. Thứ nhất: cuộc bàn bạc kết thúc khi bốn trụ cột ở phần tiếp theo đã được điền đủ, và thành quả của nó là một file chứ không phải đoạn chat. Thứ hai: câu hỏi của agent là các phương án, không phải yêu cầu. Nó sẽ sẵn lòng hỏi "có làm bảng điểm cao không?", và "không" là một câu trả lời hoàn toàn bình thường. Chữ "không" đó cũng là một dòng của đặc tả, chỉ là nằm ở mục "không làm".

Và dù thế nào - bạn hỏi hay agent hỏi - câu trả lời được ghi vào file đặc tả, chứ không nằm lại thành một tin nhắn trong chat. Nếu không, yêu cầu tiếp theo sẽ lại bắt đầu từ đúng lỗ hổng đó.

Ba nguồn bên trái, một đích đến bên phải. Mũi tên đứt nét đi xuống là con đường mà câu trả lời hay rơi vào nhất: ở lại trong chat, và mười tin nhắn sau thì không tìm lại được nữa. Mũi tên có trên sơ đồ, nhưng ở cuối nó không có file nào.

Bạn còn có thể nhờ agent làm nhiều hơn: không chỉ hỏi mà còn tự phác thảo bản nháp đặc tả dựa trên câu trả lời của bạn, điền luôn những gì bạn chưa nói. Làm gì tiếp với những thứ nó tự nghĩ thêm - xem ở phần 4. Trước hết là chuyện đặc tả gồm những gì.

3. Bốn trụ cột của đặc tả

Với một nhiệm vụ nhỏ, đặc tả chỉ dài sáu đến tám dòng. Chúng dựa trên bốn trụ cột: mục tiêu, điều gì cần xảy ra, phiên bản đầu sẽ không có gì, kiểm tra thế nào. Đây là bản đầy đủ cho game:

# Đặc tả: 2048

MỤC TIÊU:   game 2048 chạy trên trình duyệt, mở thẳng từ file, không cần cài đặt.
            HTML, CSS và JavaScript, không cần build

LUẬT CHƠI:  bàn chơi 4×4
            khi bắt đầu và sau mỗi nước đi xuất hiện một ô mới: 2 hoặc 4
            phím mũi tên đẩy tất cả các ô về một phía, đến tận cùng
            hai ô giống nhau khi va vào nhau gộp thành một ô bằng tổng của chúng
            thắng: trên bàn xuất hiện ô 2048
            thua: hết nước đi, bàn đã đầy, không còn gì để gộp

KHÔNG LÀM:  bảng điểm cao, hiệu ứng chuyển động, hoàn tác nước đi

KIỂM TRA:   mở index.html trong trình duyệt, thấy bàn chơi và các ô khởi đầu
            đi ba nước bằng phím mũi tên, sau mỗi nước xuất hiện một ô mới
            gộp hai ô 2, được một ô 4
            chơi đến hết, thấy màn hình thua

Tiếp theo là từng trụ cột một, mỗi trụ cột minh họa bằng hai nhiệm vụ: game và trang mời tham dự buổi gặp mặt của một câu lạc bộ board game.

Mục tiêu

Dòng đầu tiên. Đọc xong, người ta phải hình dung ra kết quả chứ không phải code. "Game 2048 chạy trên trình duyệt, mở thẳng từ file, không cần cài đặt". "Trang mời tham dự buổi gặp mặt của câu lạc bộ: người xem hiểu đây là buổi gặp gì và đăng ký bằng một nút bấm".

Cách kiểm tra mục tiêu: nếu khi đọc nó bạn thấy code, chứ không phải thứ mà người dùng sẽ thấy, thì đó không còn là mục tiêu nữa. "Viết hàm gộp ô" không phải mục tiêu, đó là một phần việc.

Mục này cũng nên có một dòng "dựng bằng gì": HTML, CSS và JavaScript, không cần build. Thiếu dòng này, agent sẽ tự chọn, và chưa chắc nó chọn thứ mà bạn biết cách chạy.

Còn "làm cho đẹp" thì không thể là mục tiêu. Không rõ đẹp với ai và xem ở đâu.

Điều gì cần xảy ra

Trụ cột dài nhất, và với game thì nó đã được viết ở trên. Chỉ có một quy tắc: một dòng là tốt nếu sau khi chạy, bạn nhìn vào nó và nói được "có" hoặc "không". "Bàn chơi 4×4" - có hoặc không. "Hai ô giống nhau gộp thành một ô bằng tổng của chúng" - có hoặc không. "Hay hơn chút" - chẳng có cũng chẳng không, và dòng như vậy không có chỗ trong đặc tả.

Mỗi dòng một ý. "Ô xuất hiện và gộp lại" là hai lần kiểm tra, vậy là hai dòng.

Với trang web cũng vậy, chỉ khác là thay cho luật chơi thì ghi những gì có trên trang: "phần đầu trang có tên và ngày", "ba khối: sẽ có gì, dành cho ai, ở đâu", "nút Đăng ký dẫn tới địa chỉ của biểu mẫu". Mỗi dòng đều có thể mở ra và nhìn thấy.

Danh sách như thế trông thật nhàm chán bên cạnh ý tưởng. Nhàm chán chính là điều tốt. thứ nhàm chán thì kiểm tra được.

Phiên bản đầu sẽ không có gì

Đây là trụ cột duy nhất mà người ta thường quên, và vì thế nó có giá trị nhất. Agent tự lấp chỗ trống, và cách nó thích nhất là thêm thắt. Bảng điểm cao, hiệu ứng chuyển động cho ô, nút hoàn tác nước đi, giao diện tối. Tất cả đều có ích, và tất cả đều không phải thứ bạn yêu cầu.

Mục này ghi ra bằng tên cụ thể. Không phải "không thêm gì thừa" - đó không phải ranh giới mà chỉ là mong muốn - mà là "không làm: bảng điểm cao, hiệu ứng chuyển động, hoàn tác nước đi". Với trang web: "không làm: bản thân biểu mẫu đăng ký, thanh toán, thư viện ảnh". Ba cái tên thường là đủ, đằng nào cũng chẳng ai viết đến mười.

Vì sao điều này cần cho bạn chứ không phải cho agent. Càng dựng ít thì càng ít phải kiểm tra. Và khi có gì hỏng thì càng dễ biết nó từ đâu ra: tìm trong sáu dòng dễ hơn tìm trong sáu màn hình. Dấu hiệu cho thấy không có ranh giới: trong yêu cầu của bạn hay trong câu trả lời của agent, cụm "tiện thể" xuất hiện ngày một dày.

Kiểm tra thế nào

Mỗi dòng trong "điều gì cần xảy ra" là một lần kiểm tra sau khi agent nói "xong". Mở game - bàn chơi 4×4, có. Nhấn phím mũi tên - các ô trượt đi, xuất hiện một ô mới, có. Gộp hai ô 2 - ra ô 4, có. Danh sách kiểm tra không cần viết riêng, nó đã được viết sẵn rồi.

Thêm vào đó là hai-ba dòng "kiểm tra" ngay trong đặc tả: cụ thể cần tự tay làm gì. "Mở file trong trình duyệt, đi ba nước, chơi đến lúc thua". Những dòng này được viết trước khi gửi yêu cầu, không phải sau. Khi đã có kết quả, người ta vô tình chỉnh chúng cho khớp với những gì nhận được - chuyện đó tự nhiên xảy ra, và với bạn cũng sẽ như vậy.

Chữ "xong" từ agent là một câu nói, không phải một lần kiểm tra. Việc kiểm tra là của bạn, theo những dòng của bạn.

Giờ đến phần thực hành. Hãy lấy yêu cầu "làm một trang thật đẹp cho buổi gặp mặt của câu lạc bộ board game" và tách nó thành bốn trụ cột, mỗi trụ cột một-hai dòng. Đáp án ngay bên dưới, hãy đối chiếu:

# Đặc tả: trang mời

MỤC TIÊU:   trang mời tham dự buổi gặp mặt của câu lạc bộ board game:
            người xem hiểu đây là buổi gặp gì, khi nào, ở đâu, và đăng ký bằng một nút bấm.
            một file HTML, style viết ngay bên trong

TRÊN TRANG: phần đầu trang có tên câu lạc bộ và ngày gặp mặt
            ba khối: sẽ có gì, dành cho ai, ở đâu
            nút "Đăng ký" dẫn tới địa chỉ của biểu mẫu

KHÔNG LÀM:  bản thân biểu mẫu đăng ký, thanh toán, thư viện ảnh

KIỂM TRA:   mở trong trình duyệt, thấy phần đầu trang và ba khối
            nhấn nút, đến được địa chỉ của biểu mẫu

Để ý rằng chữ "thật đẹp" hoàn toàn không lọt vào đặc tả. Nó không kiểm tra được. Nếu cái đẹp thật sự quan trọng, nó cũng được tách thành các dòng như mọi thứ khác: "một hình ảnh ở phần đầu trang", "không quá hai màu", "mọi thứ vừa trên màn hình điện thoại". Những điều này thì đã có thể mở ra và xem được.

Tên các khối trong hai ví dụ khác nhau: với game là "luật chơi", với trang là "trên trang". Điều đó không quan trọng, đặt tên sao cho tiện là được. Quan trọng là mỗi bản đều có đủ bốn trụ cột:

4. Đây là quyết định của ai

Trong đặc tả xuất hiện những quyết định chưa ai thống nhất, và chuyện này xảy ra theo hai cách. Cách thứ nhất: bạn cho phép agent lấp lỗ hổng bằng "cái gì đó hợp lý" để có bản nháp ngay bây giờ, thay vì chờ câu trả lời đến tận thứ Ba. Cách thứ hai: chính bạn quyết định thay khách hàng, vì không có ai để hỏi hoặc không có thời gian hỏi.

Cả hai trường hợp đều bình thường. Điều không bình thường là quên rằng đó là một giả định. Một tuần sau sẽ chẳng ai nhớ ai đã nghĩ ra chuyện nút bấm dẫn tới email chứ không phải biểu mẫu, và người ta sẽ tranh cãi đúng về chuyện đó.

Với trường hợp thứ nhất, yêu cầu gửi agent trông như thế này:

Dựa trên những câu trả lời này, hãy soạn bản nháp đặc tả cho trang mời.
Chỗ nào chưa có câu trả lời thì tự nghĩ ra phương án hợp lý, và liệt kê
riêng thành một danh sách những gì bạn tự nghĩ ra. Ghi vào file SPEC_INVITE.md.

Danh sách những gì agent tự nghĩ thêm, bạn đọc trước tiên, trước cả bản đặc tả. Đó là những quyết định đã được đưa ra thay bạn: mỗi cái hoặc được gửi cho người nắm rõ vấn đề để thống nhất, hoặc ở lại trong đặc tả kèm một ghi chú đánh dấu.

Với trường hợp thứ hai - đánh dấu ngay trong file. Một dòng "giả định:" trước quyết định, hoặc đơn giản là dấu chấm hỏi ở cuối dòng: "nút bấm dẫn tới email của câu lạc bộ (?)". Khi có câu trả lời, nhìn là biết ngay cần sửa gì. và không phải nhớ lại nó từ đâu ra.

Đánh dấu có tác dụng theo cả hai chiều. Agent nhận được một đặc tả có dấu chấm hỏi thường sẽ hỏi về chúng đầu tiên: với nó, đó cũng là một tín hiệu giống như với bạn.

5. Sandbox thay cho câu hỏi

Có khi ngồi mãi mà bốn trụ cột vẫn không viết ra được. "Tôi muốn cái gì đó kiểu 2048, nhưng không biết có cần điểm không, có cần vuốt không, mà có phải 4×4 không nữa". Đây không phải đặc tả, thậm chí còn chưa phải một ý tưởng theo nghĩa thông thường. Đây là một định hướng: hướng đi thì rõ, còn kết quả thì chưa. Câu hỏi không giúp được gì ở đây: cả bạn lẫn khách hàng đều chưa có câu trả lời, còn các phương án từ agent thì bạn chẳng có gì để so sánh.

Trong trường hợp này, rẻ nhất là cứ nhìn tận mắt. Dựng một sandbox: phiên bản đơn giản nhất mà bạn có thể xem, bấm thử và hiểu ra mình thực sự muốn gì. Với agent, việc này tốn mười phút, và với mười phút đó thì bỏ kết quả đi cũng chẳng tiếc.

Sandbox cũng cần một bản đặc tả với bốn trụ cột, chỉ có mục tiêu là khác:

# Đặc tả: sandbox 2048

MỤC TIÊU:   xem 2048 chơi trên trình duyệt thế nào, và hiểu mình muốn gì.
            HTML, CSS và JavaScript, không cần build

LUẬT CHƠI:  bàn chơi 4×4
            phím mũi tên đẩy các ô, ô giống nhau gộp lại
            sau mỗi nước đi xuất hiện một ô mới

KHÔNG LÀM:  mọi thứ còn lại: thắng, thua, điểm, vuốt, giao diện

KIỂM TRA:   chơi năm phút và ghi lại cái gì còn thiếu, cái gì thừa

Hãy xem điều gì đã thay đổi. Mục tiêu không phải là game, mà là hiểu ra mình muốn gì. "Không làm" là dòng dài nhất, trong đó có mọi thứ bạn còn chưa chắc. Còn kiểm tra thì không phải "có chạy không", mà là "giờ tôi biết thêm được gì". Chơi năm phút - và những câu hỏi không thể đặt ra lúc đầu tự hiện ra: không cần vuốt, ngồi máy tính thì chơi bằng phím mũi tên; cần có điểm, không có thì chán; 4×4 hơi nhỏ, muốn thử 5×5; phải hiện màn hình thua, không thì chẳng biết game đã kết thúc.

Đó chính là kết quả của sandbox. Không phải code, mà là câu trả lời. Từ đó viết ra bản đặc tả thật, và phiên bản thật được dựng từ đầu, trong một thư mục sạch, bằng một câu: "làm game theo đặc tả trong file". Sandbox đã xong phần việc của nó.

Đây vẫn là chuỗi các bước ở phần đầu tiên, chỉ có điều bước "Câu hỏi" ở đây được thay bằng một vòng lặp: khi không có gì để hỏi, ta xem trước, ghi lại sau. Đi xuống, vào đặc tả, chỉ có một thứ - câu trả lời. Sandbox không có mũi tên tới agent, và đó không phải do vẽ sót: phiên bản thật được agent dựng trong một thư mục sạch, từ đầu. phần còn lại cứ theo chuỗi mà đi.

6. Đặc tả nằm trong file

Vì sao là file chứ không phải đoạn chat. Đoạn chat thì trôi mất: mười tin nhắn sau đã không tìm lại được luật gộp ô nữa. File nằm trong thư mục project ngay cạnh code, agent tự đọc nó khi bạn chỉ tới, còn muốn sửa rồi giao lại thì chỉ cần đúng câu đó. Tên gì cũng được: SPEC_2048.md, SPEC_LANDING.md, thậm chí task.txt. Đây là một file văn bản bình thường, không có định dạng đặc biệt nào.

Giao nó cho agent chỉ bằng một câu. Hãy so sánh:

Trước: "làm game 2048, kiểu đó đó, bạn hiểu mà, cho hay hơn chút".

Sau: "làm game theo đặc tả trong file SPEC_2048.md".

Yêu cầu thứ hai ngắn hơn yêu cầu thứ nhất, nhưng chứa nhiều thông tin hơn gấp mười lần - thông tin nằm trong file. Không cần chép nội dung đặc tả vào chat, agent sẽ tự mở file.

Cái gì thì sửa trong file, cái gì thì nói bằng lời. Có thể dựa vào nguyên tắc sau: luật hoặc ranh giới thay đổi thì sửa file rồi giao lại ("thắng khi đạt 2048, không phải 1024" - cái này vào file). Một chi tiết nhỏ về giao diện, không ảnh hưởng tới luật, thì có thể nói bằng lời ("cho nút màu xanh dương"). Còn phân vân - cứ ghi vào file: thừa một dòng vẫn rẻ hơn quên một luật.

Về độ dài. Với một nhiệm vụ nhỏ là sáu đến tám dòng, như khối đặc tả cho 2048 ở trên. Nếu đặc tả cho một game làm trong một buổi tối mà kéo dài đến hai trang, thì nhiều khả năng trong đó đã lọt vào những thứ lẽ ra phải nằm trong "không làm".

Và điều cuối cùng trước khi giao file cho agent: hãy đọc nó một lần như thể do người khác viết. Gần như lúc nào cũng tìm ra một dòng không kiểm tra được. tôi thì lần nào cũng tìm ra.

7. Agent làm gì với đặc tả, còn phần nào thuộc về bạn

Tổng kết lại: trong cách làm này Claude Code đảm nhận những gì, còn những gì nằm ở phía bạn. Theo từng cặp.

Mục đích của đặc tả không phải là để agent hiểu. Chỉ với hai từ, nó cũng sẽ dựng ra được cái gì đó. Mục đích là để chính bạn biết mình đã yêu cầu gì, và kiểm tra được điều đó.