Phân định nhiệm vụ với Claude Code: từ yêu cầu mơ hồ đến các commit

Tại sao yêu cầu tính năng mơ hồ lãng phí thời gian

Một yêu cầu mơ hồ nghe có vẻ vô hại: “Thêm tìm kiếm tốt hơn,” “Làm onboarding mượt hơn,” “Người dùng cần thông báo.” Trong các đội thực tế, nó thường tới dưới dạng một tin nhắn chat một dòng, một ảnh chụp màn hình kèm mũi tên, hoặc một cuộc gọi khách hàng nửa nhớ nửa quên. Mọi người đồng ý, nhưng mỗi người hình dung một thứ khác nhau.

Chi phí thể hiện sau đó. Khi phạm vi không rõ, người ta xây dựa trên phỏng đoán. Demo đầu tiên biến thành vòng làm rõ khác: “Không phải ý tôi.” Công việc bị làm lại, và thay đổi âm thầm phình to. Chỉnh sửa thiết kế kéo theo thay đổi mã, rồi kéo theo kiểm thử thêm. Review chậm lại vì một thay đổi mơ hồ khó kiểm chứng. Nếu không ai có thể định nghĩa “đúng” là gì, reviewer sẽ tranh luận về hành vi thay vì kiểm tra chất lượng.

Bạn thường có thể nhận ra nhiệm vụ mơ hồ sớm:

• Không có ví dụ bước từng bước về những gì người dùng nên làm được
• Không có các trường hợp biên (trạng thái rỗng, quyền, lỗi)
• Công việc “chỉ phòng ngừa” phình thành thành một PR lớn
• Bình luận review tranh luận về hành vi, không phải triển khai
• “Ta sẽ tính sau” trở thành kế hoạch

Một nhiệm vụ được phân định tốt cho đội một vạch kết thúc: tiêu chí chấp nhận rõ ràng, một kế hoạch UI và API tối thiểu, và ranh giới rõ ràng về những gì không bao gồm. Đó là khác biệt giữa “cải thiện tìm kiếm” và một thay đổi nhỏ dễ xây và review.

Một thói quen thực tế: tách “định nghĩa hoàn thành” khỏi “điểm cộng.” “Hoàn thành” là một danh sách ngắn các kiểm tra bạn có thể chạy (ví dụ: “Tìm kiếm trả kết quả theo tiêu đề, hiển thị ‘Không có kết quả’ khi rỗng, và giữ truy vấn trong URL”). “Điểm cộng” là mọi thứ có thể đợi (từ đồng nghĩa, điều chỉnh xếp hạng, làm nổi bật, analytics). Gắn nhãn ngay từ đầu ngăn phạm vi vô tình tăng lên.

Bắt đầu từ kết quả, không phải giải pháp

Yêu cầu mơ hồ thường bắt đầu như các đề xuất sửa: “Thêm một nút,” “Chuyển sang luồng mới,” “Dùng model khác.” Dừng lại và dịch đề xuất thành kết quả trước.

Một định dạng đơn giản giúp: “Là một [người dùng], tôi muốn [làm gì], để tôi có thể [đạt mục tiêu].” Giữ thật ngắn. Nếu không thể nói trong một hơi thở, thì vẫn còn mơ hồ.

Tiếp theo, mô tả điều gì thay đổi với người dùng khi xong. Tập trung vào hành vi thấy được, không phải chi tiết triển khai. Ví dụ: “Sau khi tôi gửi form, tôi thấy xác nhận và có thể tìm bản ghi mới trong danh sách.” Điều đó tạo vạch kết thúc rõ ràng và khiến việc “thêm một chỉnh sửa nữa” khó len lỏi.

Cũng viết ra những gì không đổi. Những không-mục tiêu bảo vệ phạm vi. Nếu yêu cầu là “cải thiện onboarding,” một không-mục tiêu có thể là “không redesign dashboard” hoặc “không thay đổi logic phân tầng giá.”

Cuối cùng, chọn một luồng chính để hỗ trợ trước: lát cắt end-to-end duy nhất chứng minh tính năng hoạt động.

Ví dụ: thay vì “thêm snapshots khắp nơi,” viết: “Là chủ dự án, tôi có thể khôi phục snapshot mới nhất của app, để hoàn tác thay đổi xấu.” Không-mục tiêu: “không khôi phục hàng loạt, không redesign UI.”

Hỏi vài câu để xóa bỏ mơ hồ

Một yêu cầu mơ hồ hiếm khi thiếu nỗ lực. Nó thiếu quyết định.

Bắt đầu với các ràng buộc thay đổi phạm vi lặng lẽ. Hạn chót quan trọng, nhưng quyền truy cập và yêu cầu compliance cũng vậy. Nếu bạn xây trên nền tảng có các tầng và vai trò, quyết định sớm ai được tính năng và thuộc gói nào.

Rồi yêu cầu một ví dụ cụ thể. Một ảnh chụp màn hình, hành vi đối thủ, hoặc ticket trước đó tiết lộ “tốt hơn” thực sự nghĩa là gì. Nếu người yêu cầu không có, hỏi họ tái hiện lần cuối cùng họ cảm thấy khó chịu: họ ở màn hình nào, họ bấm gì, họ mong thấy gì?

Các trường hợp biên là nơi phạm vi phình to, nên liệt kê lớn ngay từ đầu: dữ liệu rỗng, lỗi validate, kết nối chậm hoặc thất bại, và “hoàn tác” thực sự nghĩa là gì.

Cuối cùng, quyết định cách bạn xác minh thành công. Không có kết quả kiểm thử được, nhiệm vụ biến thành ý kiến.

Năm câu hỏi này thường loại bỏ phần lớn mơ hồ:

• Ai được truy cập (tầng và vai trò)?
• Hạn chót là khi nào, và phiên bản nhỏ nhất chấp nhận được là gì?
• Một ví dụ về hành vi mong đợi là gì?
• Khi rỗng, lỗi, hoặc kết nối chậm thì sao?
• Làm sao chúng ta xác nhận nó hoạt động (tiêu chí hoặc metric cụ thể)?

Ví dụ: “Thêm custom domains cho khách hàng” rõ ràng hơn khi bạn quyết domain thuộc tầng nào, ai có thể cài, vị trí hosting có ảnh hưởng compliance không, lỗi hiển thị khi DNS không hợp lệ ra sao, và “xong” nghĩa là gì (domain xác thực, HTTPS bật, và kế hoạch rollback an toàn).

Chuyển ghi chú lộn xộn thành tiêu chí chấp nhận

Ghi chú lộn xộn trộn mục tiêu, phỏng đoán và các trường hợp biên nhớ nửa vời. Công việc là biến nó thành các phát biểu ai cũng có thể kiểm tra mà không cần đọc tâm trí bạn. Các tiêu chí giống nhau nên hướng dẫn thiết kế, lập trình, review và QA.

Một mẫu đơn giản giữ rõ ràng. Bạn có thể dùng Given/When/Then, hoặc các gạch đầu dòng ngắn mang ý nghĩa tương tự.

Mẫu tiêu chí chấp nhận nhanh

Viết mỗi tiêu chí như một bài test duy nhất ai đó có thể chạy:

• Given một trạng thái bắt đầu, when người dùng làm X, then Y xảy ra.
• Bao gồm quy tắc validate (những input được phép).
• Bao gồm ít nhất một trường hợp thất bại (lỗi người dùng thấy là gì).
• Xác định “tín hiệu hoàn thành” (QA kiểm tra gì, reviewer mong gì).

Bây giờ áp dụng. Giả sử ghi chú nói: “Làm snapshot dễ hơn. Muốn rollback nếu thay đổi gần nhất làm hỏng.” Biến thành các phát biểu có thể kiểm tra:

• Given một project có 2 snapshot, when tôi mở Snapshots, then tôi thấy cả hai kèm thời gian và nhãn ngắn.
• Given một snapshot, when tôi click Roll back và xác nhận, then project trở về snapshot đó và app build thành công.
• Given tôi không phải chủ dự án, when tôi cố rollback, then tôi thấy lỗi và không có gì thay đổi.
• Given rollback đang tiến hành, when tôi refresh trang, then tôi vẫn thấy trạng thái và kết quả cuối cùng.
• Given rollback thất bại, when nó dừng, then tôi thấy thông báo rõ ràng và phiên bản hiện tại vẫn hoạt động.

Nếu QA có thể chạy các kiểm tra này và reviewer kiểm chứng trong UI và logs, bạn sẵn sàng lên kế hoạch UI và API và chia nhỏ thành các commit nhỏ.

Phác thảo kế hoạch UI tối thiểu

Kế hoạch UI tối thiểu là một lời hứa: thay đổi nhìn thấy nhỏ nhất chứng minh tính năng hoạt động.

Bắt đầu bằng việc nêu tên màn hình nào sẽ thay đổi và người ta sẽ nhận thấy gì trong 10 giây. Nếu yêu cầu nói “làm dễ hơn” hoặc “dọn dẹp,” dịch điều đó thành một thay đổi cụ thể bạn có thể chỉ ra.

Viết nó như một bản đồ nhỏ, không phải redesign. Ví dụ: “Trang Orders: thêm một thanh filter phía trên bảng,” hoặc “Settings: thêm một toggle mới dưới Notifications.” Nếu bạn không thể nêu màn hình và phần tử chính xác thay đổi, phạm vi vẫn chưa rõ.

Xác định các trạng thái UI chính

Hầu hết thay đổi UI cần vài trạng thái dự đoán. Chỉ liệt kê những trạng thái áp dụng:

• Loading
• Empty
• Error (và có retry hay không)
• Success (toast, thông báo inline, danh sách cập nhật)

Xác nhận chữ hiển thị cho người dùng

Copy UI là một phần của phạm vi. Ghi lại nhãn và thông báo cần được phê duyệt: chữ trên nút, nhãn trường, text trợ giúp và thông báo lỗi. Nếu câu chữ vẫn mở, ghi là placeholder và ghi ai sẽ xác nhận.

Giữ một ghi chú nhỏ “không phải bây giờ” cho mọi thứ không bắt buộc để dùng tính năng (polish responsive, sort nâng cao, animation, icon mới).

Phác thảo API và kế hoạch dữ liệu tối thiểu

Một nhiệm vụ có phạm vi cần một hợp đồng nhỏ rõ ràng giữa UI, backend và data. Mục tiêu không phải thiết kế cả hệ thống. Là xác định bộ request và trường nhỏ nhất chứng minh tính năng hoạt động.

Bắt đầu bằng liệt kê dữ liệu bạn cần và nguồn của nó: trường hiện có bạn có thể đọc, trường mới phải lưu, và giá trị bạn có thể tính. Nếu bạn không thể nêu nguồn cho từng trường, bạn chưa có kế hoạch.

Giữ bề mặt API nhỏ. Với nhiều tính năng, một read và một write là đủ:

• GET /items/{id} trả về trạng thái cần để render màn hình
• POST /items/{id}/update chỉ nhận những gì người dùng có thể thay đổi và trả về trạng thái cập nhật

Viết inputs và outputs dưới dạng object rõ ràng, không đoạn văn. Bao gồm trường required vs optional, và chuyện gì xảy ra với lỗi phổ biến (not found, validation failed).

Làm một lượt kiểm tra auth nhanh trước khi chạm DB. Quyết ai được đọc ai được viết, và nêu quy tắc trong một câu (ví dụ: “any signed-in user can read, only admins can write”). Bỏ qua bước này thường dẫn đến sửa lại.

Cuối cùng, quyết cái gì phải lưu và cái gì có thể tính. Quy tắc đơn giản: lưu các facts, tính các view.

Dùng Claude Code để tạo một nhiệm vụ có phạm vi

Claude Code hoạt động tốt khi bạn đưa mục tiêu rõ và hộp chặt. Bắt đầu bằng dán yêu cầu lộn xộn và mọi ràng buộc (hạn chót, người dùng bị ảnh hưởng, quy tắc dữ liệu). Rồi yêu cầu đầu ra có phạm vi bao gồm:

1. Một câu tóm tắt bằng ngôn ngữ thường về phạm vi và một checklist tiêu chí chấp nhận ngắn.
2. Một chuỗi commit nhỏ (nhắm 3–7), mỗi commit có kết quả rõ ràng.
3. Các file hoặc folder có khả năng bị chạm cho mỗi commit, và thay đổi bên trong chúng.
4. Kế hoạch kiểm thử nhanh cho mỗi commit (một happy path và một edge case).
5. Ghi chú rõ ràng những thứ ngoài phạm vi.

Sau khi nó trả lời, đọc như một reviewer. Nếu bạn thấy cụm từ như “cải thiện hiệu năng” hoặc “làm sạch hơn,” yêu cầu từ ngữ đo lường.

Ví dụ nhỏ (một cái “đẹp” trông như thế nào)

Yêu cầu: “Thêm cách tạm dừng subscription.”

Một phiên bản có phạm vi có thể nói: “Người dùng có thể tạm dừng 1 đến 3 tháng; ngày thanh toán tiếp theo cập nhật; admin có thể xem trạng thái tạm dừng,” và ngoài phạm vi: “Không thay đổi proration.”

Từ đó, kế hoạch commit trở nên thực tế: một commit cho DB và shape API, một cho control UI, một cho validate và trạng thái lỗi, một cho end-to-end tests.

Chia công việc thành các commit nhỏ, dễ review

Thay đổi lớn che giấu bug. Commit nhỏ khiến review nhanh hơn, rollback an toàn hơn, và giúp bạn nhận ra khi đi lệch tiêu chí chấp nhận.

Quy tắc hữu ích: mỗi commit nên mở bật một hành vi mới, và kèm một cách nhanh để chứng minh nó hoạt động.

Một chuỗi phổ biến như sau:

• Model dữ liệu hoặc migration (nếu cần) kèm tests
• Hành vi API và validate
• Wiring UI với trạng thái empty và error
• Logging hoặc analytics chỉ khi cần, rồi polish nhỏ

Giữ mỗi commit tập trung. Tránh refactor “nhân tiện” trong commit. Giữ app hoạt động end-to-end, ngay cả khi UI cơ bản. Đừng gom migration, hành vi và UI vào một commit trừ khi có lý do mạnh.

Ví dụ minh họa: “Export reports”

Stakeholder nói: “Thêm Export reports?” Nó ẩn nhiều lựa chọn: loại report nào, định dạng nào, ai có quyền export, và cách giao hàng hoạt động.

Hỏi chỉ những câu thay đổi design:

• Loại report nào thuộc phạm vi v1?
• Định dạng v1 cần (CSV, PDF)?
• Ai có thể export (admins, vai trò cụ thể)?
• Tải trực tiếp hay gửi email?
• Giới hạn nào (khoảng ngày tối đa, giới hạn số dòng, timeout)?

Giả sử câu trả lời: “Sales Summary, chỉ CSV, vai trò manager, tải trực tiếp, tối đa 90 ngày.” Giờ tiêu chí v1 cụ thể: manager có thể click Export trên trang Sales Summary; CSV khớp cột bảng trên màn hình; export tuân theo filter hiện tại; export hơn 90 ngày báo lỗi rõ; download hoàn thành trong 30 giây cho tới 50k dòng.

Kế hoạch UI tối thiểu: một nút Export gần các action của bảng, trạng thái loading khi tạo file, và thông báo lỗi chỉ dẫn người dùng cách sửa (ví dụ “Chọn 90 ngày trở xuống”).

Kế hoạch API tối thiểu: một endpoint nhận filters và trả file CSV, tái sử dụng cùng query với bảng trong khi ép luật 90 ngày ở phía server.

Rồi phát hành trong vài commit chặt: đầu tiên endpoint cho happy path cố định, rồi wiring UI, rồi validate và lỗi hiển thị, cuối cùng tests và docs.

Sai lầm phổ biến khi phân định phạm vi (và cách tránh)

Các yêu cầu ẩn len vào

Những yêu cầu như “thêm roles đội” thường ẩn quy tắc về mời, chỉnh sửa, và chuyện gì xảy ra với user cũ. Nếu bạn phát hiện đang phỏng đoán, ghi giả định xuống và biến nó thành câu hỏi hoặc quy tắc rõ ràng.

Độ hoàn thiện UI bị trộn với hành vi cốt lõi

Đội mất ngày khi một nhiệm vụ vừa bao gồm “làm cho hoạt động” vừa “làm cho đẹp.” Giữ nhiệm vụ đầu tiên tập trung vào hành vi và dữ liệu. Đặt styling, animation và khoảng cách vào nhiệm vụ sau trừ khi chúng cần để dùng tính năng.

Cố gắng giải mọi edge case trong v1

Edge case quan trọng, nhưng không phải tất cả đều phải giải ngay. Xử lý những cái có thể phá niềm tin (double submit, conflict edits) và hoãn phần còn lại với ghi chú rõ ràng.

Trạng thái lỗi và quyền bị đẩy sang “sau”

Nếu bạn không ghi chúng, bạn sẽ quên. Bao gồm ít nhất một đường không-happy và ít nhất một quy tắc quyền trong tiêu chí chấp nhận.

Tiêu chí không thể xác minh

Tránh từ “nhanh” hoặc “trực quan” trừ khi kèm số hoặc kiểm tra cụ thể. Thay bằng điều bạn có thể chứng minh trong review.

Checklist nhanh trước khi bắt đầu code

Ghim nhiệm vụ lại để đồng đội có thể review và test mà không đọc suy nghĩ:

• Kết quả và không-mục tiêu: một câu cho kết quả, cộng 1–3 không-mục tiêu rõ ràng.
• Tiêu chí chấp nhận: 5–10 kiểm tra có thể chạy, ngôn ngữ đơn giản.
• Trạng thái UI: các trạng thái tối thiểu loading, empty, error, success.
• Ghi chú API và dữ liệu: shape endpoint nhỏ nhất và thay đổi dữ liệu, kèm ai được đọc/ghi.
• Kế hoạch commit với tests: 3–7 commit, mỗi commit có bằng chứng nhanh.

Ví dụ: “Thêm saved searches” thành “Người dùng có thể lưu bộ lọc và áp lại sau,” với không-mục tiêu như “không chia sẻ” và “không thay đổi sắp xếp.”

Bước tiếp theo: giữ phạm vi ổn định khi xây

Khi đã có nhiệm vụ có phạm vi, bảo vệ nó. Trước khi code, làm một rà soát nhanh với người yêu cầu thay đổi:

• Đọc tiêu chí chấp nhận và xác nhận nó khớp kết quả mong muốn.
• Xác nhận quyền, trạng thái rỗng, và hành vi khi thất bại.
• Xác nhận lại những gì ngoài phạm vi.
• Đồng ý về thay đổi UI và API nhỏ nhất đáp ứng tiêu chí.
• Quyết cách demo và tiêu chí “xong” trông như thế nào.

Rồi lưu tiêu chí nơi công việc diễn ra: trong ticket, mô tả PR, và mọi nơi đội bạn thật sự xem.

Nếu bạn xây trong Koder.ai (koder.ai), việc khoá kế hoạch trước rồi sinh code từ nó sẽ hữu ích. Planning Mode phù hợp với workflow đó, và snapshots + rollback giữ an toàn khi bạn thử cách tiếp cận rồi muốn quay lại.

Khi ý tưởng mới xuất hiện giữa chừng, giữ phạm vi ổn định: ghi chúng vào danh sách theo dõi, tạm hoãn để phân định lại nếu chúng thay đổi tiêu chí, và giữ commit gắn với một tiêu chí tại một thời điểm.