Viết đặc tả cho AI Coding: Cách xây dựng yêu cầu để Claude Code làm đúng ngay từ lần đầu tiên
Các công cụ AI coding như Claude Code có thể tạo ra cả một tính năng chỉ trong vài phút. Tuy nhiên, tốc độ không có nhiều ý nghĩa nếu logic nghiệp vụ bên dưới bị sai. Nguyên nhân gốc rễ thường không nằm ở mô hình AI, mà ở việc chúng ta vẫn đang cung cấp cho AI những tài liệu yêu cầu được viết cho con người, chứa đầy các giả định ngầm mà chỉ con người mới hiểu được. Khi gặp sự mơ hồ, AI không hỏi lại để làm rõ; nó sẽ tự suy đoán. Và những suy đoán đó sớm hay muộn cũng sẽ gây ra lỗi trên môi trường thực tế. Bài viết này sẽ giúp bạn thu hẹp khoảng cách đó bằng cách nắm vững cách viết đặc tả cho AI coding. Chúng ta sẽ cùng tìm hiểu vì sao các tài liệu PRD truyền thống không còn phù hợp với các AI agent tự động, cách áp dụng framework 6 thành phần của CafeKit để loại bỏ sự mơ hồ, cũng như các kỹ thuật thực tiễn như EARS và Example Mapping để xử lý những trường hợp ngoại lệ phức tạp. Sau khi đọc xong, bạn sẽ biết cách biến những ý tưởng còn mơ hồ thành các “hợp đồng” rõ ràng, có thể đọc hiểu bởi máy, giúp Claude Code triển khai chính xác ngay từ lần đầu. Vì sao viết đặc tả cho AI Coding lại khác biệt Các tài liệu PRD truyền thống hoạt động rất hiệu quả với đội ngũ phát triển phần mềm bởi các lập trình viên thường chia sẻ với nhau một lượng lớn ngữ cảnh ngầm. Họ có thể hiểu ý giữa các dòng chữ, đặt câu hỏi nhanh để làm rõ và thống nhất mục tiêu kinh doanh chỉ sau một cuộc trao đổi ngắn. Trong khi đó, AI agent hoạt động trong một môi trường hoàn toàn không có bất kỳ kiến thức nền hay ngữ cảnh chung nào như vậy. Khi nhận được một yêu cầu chưa rõ ràng, lập trình viên sẽ dừng lại để xác nhận trước khi viết mã. Nhưng với AI, cùng một yêu cầu đó sẽ được chuyển ngay thành code dựa trên những suy đoán mang tính xác suất. Sự khác biệt cốt lõi này làm thay đổi hoàn toàn cách chúng ta xây dựng tài liệu yêu cầu. AI không diễn giải yêu cầu giống con người Lập trình viên là những người đọc và diễn giải nội dung. Khi thấy một yêu cầu như: "Người dùng cần nhận được thông báo khi đơn hàng được giao." Họ hiểu ngữ cảnh nghiệp vụ đằng sau câu nói đó. Họ biết rằng "thông báo" trong hệ thống B2B có thể là email, còn trong ứng dụng di động có thể là push notification. Họ sẽ xem lại code hiện có để tìm các mẫu triển khai tương tự và trao đổi với Product Owner nếu có điểm chưa rõ. AI thì không, nó sẽ xử lý thông tin dựa trên các mẫu đã học từ dữ liệu huấn luyện và tạo ra phương án triển khai có xác suất xuất hiện cao nhất. Không nhất thiết là phương án đúng, mà chỉ là phương án phổ biến nhất mà nó từng thấy. Lập trình viên AI Coding Agent Đặt câu hỏi để làm rõ Tự đưa ra giả định dựa trên ngữ cảnh hiện có Sử dụng kiến thức nghiệp vụ Chỉ biết những gì được ghi trong tài liệu Chất vấn các yêu cầu chưa rõ Hiểu yêu cầu theo nghĩa đen Dựa vào trao đổi trong nhóm Không thể truy cập các quyết định chưa được tài liệu hóa Ví dụ, với yêu cầu "Hệ thống phải áp dụng giảm giá cho đơn hàng." AI có thể triển khai theo nhiều cách khác nhau như giảm theo phần trăm, giảm theo số tiền cố định, giảm theo từng mức giá trị đơn hàng. AI cũng có thể lựa chọn phương án áp dụng giảm giá trước thuế/ sau thuế, hoặc chỉ áp dụng cho một số nhóm sản phẩm nhất định. Nếu không được hướng dẫn cụ thể, AI sẽ chọn phương án mà nó gặp nhiều nhất trong các dự án open source code. Điều đó có thể đúng, hoặc hoàn toàn sai so với logic kinh doanh của bạn. Sự mơ hồ sẽ trở thành phần triển khai Đây là nguyên tắc quan trọng nhất khi viết đặc tả cho AI: Mọi điểm mơ hồ trong yêu cầu đều sẽ trở thành một quyết định mà AI tự đưa ra thay bạn. Khi bạn viết: "Thông báo cho người dùng khi đơn hàng được giao." AI buộc phải tự tìm hiểu xem kênh gửi thông báo là gì, mẫu email nào sẽ được sử dụng, địa chỉ người gửi, cơ chế gửi lại khi thất bại, xử lý opt-out, và quy tắc giới hạn tần suất gửi. Nó sẽ âm thầm chọn một phương án cho từng yếu tố mà không hề thông báo cho bạn. AI không chỉ ra các giả định của mình và cũng không cảnh báo những khu vực chưa chắc chắn. Với lập trình viên, sự mơ hồ dẫn đến câu hỏi. Với AI, sự mơ hồ dẫn đến code. Đoạn code đó vẫn có thể biên dịch thành công, vượt qua các bài test và có vẻ hoạt động bình thường cho đến khi một trường hợp ngoại lệ xuất hiện trên môi trường production. Thiếu ngữ cảnh dẫn đến những giả định sai AI agent chỉ làm việc với lượng ngữ cảnh bạn cung cấp và không hơn. Nó không chủ động khám phá codebase để hiểu các quy ước hay ràng buộc kiến trúc hiện có. Ví dụ: Nếu đặc tả không đề cập rằng toàn bộ thao tác cơ sở dữ liệu phải sử dụng Repository Pattern, AI có thể viết SQL trực tiếp trong controller. Nếu bạn quên nói rằng hệ thống dùng JWT để xác thực, AI có thể triển khai bằng session cookie. Nếu bạn không chỉ rõ rằng timestamp phải được lưu dưới dạng UTC, AI sẽ dùng múi giờ của máy chủ. Lập trình viên sẽ nhìn vào code xung quanh và tuân theo các quy ước hiện có. Claude Code thì nhìn vào đặc tả. Nếu thông tin không nằm trong đặc tả, với AI nó coi như không tồn tại. Vì vậy, tài liệu đặc tả phải đóng vai trò là toàn bộ “thế giới quan” của AI. Không được để sót bất kỳ giả định nào. Nguyên tắc Shift-Left bắt đầu từ giai đoạn đặc tả Trong phát triển phần mềm truyền thống, Shift-Left nghĩa là đưa hoạt động kiểm thử lên sớm hơn trong vòng đời phát triển. Đối với AI coding, Shift-Left có nghĩa là đưa sự rõ ràng lên sớm hơn – ngay từ giai đoạn viết đặc tả.Chi phí sửa lỗi trong mã do AI tạo ra không nằm ở việc debug, mà nằm ở việc phải tạo lại toàn bộ. Quy trình thường bắt đầu từ phát hiện vấn đề, viết lại yêu cầu, và cuối cùng là chạy lại AI agent. Mỗi vòng lặp đều tiêu tốn thời gian và token, nhưng một đặc tả chặt chẽ giúp loại bỏ các vòng lặp này. Ví dụ: "WHEN order.status changes to 'shipped', THE SYSTEM SHALL send an email to customer.email_address." Trong trường hợp này, AI gần như không còn khoảng trống để tự suy diễn. Kết quả đầu ra sẽ sát với ý định ban đầu vì dữ liệu đầu vào không để lại chỗ cho sự diễn giải. Đây chính là đòn bẩy năng suất quan trọng nhất trong AI coding: Đặc tả tốt hơn, chứ không phải prompt tốt hơn. Và một trong những cách thực tế nhất để viết đặc tả ở mức độ chính xác này là sử dụng EARS – một cú pháp được thiết kế để loại bỏ sự mơ hồ. Sử dụng EARS để giảm sự mơ hồ trong yêu cầu dành cho AI EARS là gì EARS là viết tắt của Easy Approach to Requirements Syntax. Phương pháp này được phát triển bởi John M. Wingfield cho các hệ thống hàng không vũ trụ và quốc phòng – những lĩnh vực mà chỉ một hiểu nhầm nhỏ cũng có thể gây thiệt hại hàng triệu đô la. EARS buộc người viết yêu cầu phải tuân theo một cấu trúc nghiêm ngặt và nhất quán nhằm loại bỏ sự mơ hồ vốn có của ngôn ngữ tự nhiên. Mỗi yêu cầu theo EARS đều tuân theo một khuôn mẫu rõ ràng, xác định: Điều gì kích hoạt hành động Những điều kiện nào áp dụng Hệ thống phải phản hồi như thế nào Cấu trúc này đặc biệt hữu ích với các AI coding agent vì AI xử lý các mẫu có cấu trúc tốt hơn rất nhiều so với việc suy diễn ý định. Khi viết yêu cầu bằng ngôn ngữ tự nhiên, AI phải tự đoán đâu là trigger, đâu là điều kiện và đâu là hành động. Khi sử dụng EARS, các vai trò đó được thể hiện rõ ngay trong cú pháp. AI không cần suy luận nữa – chỉ cần ánh xạ đầu vào có cấu trúc thành đầu ra có cấu trúc. Vì sao EARS hoạt động hiệu quả với AI Agent AI coding agent đạt hiệu quả cao nhất khi nhận được các chỉ dẫn theo một khuôn mẫu nhất quán. Ví dụ một yêu cầu trong PRD thường được viết như sau: "Người dùng nên nhận được thông báo khi đơn hàng được giao." Mặc dù mọi người đều hiểu ý nghĩa của câu này, vẫn còn rất nhiều chi tiết chưa được xác định: Thông báo dưới dạng nào? Ai nhận thông báo? Kích hoạt vào thời điểm nào? Nếu gửi thất bại thì sao? Viết bằng EARS: "WHEN an order status changes to 'Shipped' THE SYSTEM SHALL send an email notification to the customer's registered email address within 5 minutes." Ý nghĩa nghiệp vụ vẫn giữ nguyên, nhưng cách triển khai đã trở nên rõ ràng hơn rất nhiều. Thay vì yêu cầu AI suy diễn một câu mô tả chung chung, đặc tả đã chỉ rõ: Trigger Hành động Kết quả mong muốn Điều này giúp giảm đáng kể sự mơ hồ và tạo nền tảng vững chắc để Claude Code sinh ra phần triển khai chính xác ngay từ lần đầu tiên. Các loại yêu cầu EARS cốt lõi EARS được xây dựng dựa trên một số mẫu yêu cầu cơ bản. Những mẫu này bao phủ hầu hết các tình huống trong phát triển phần mềm và giúp các nhóm duy trì tính nhất quán trong tài liệu đặc tả. Pattern Cấu trúc Khi nào sử dụng Ví dụ Ubiquitous THE SYSTEM SHALL Hành vi luôn đúng trong mọi trường hợp THE SYSTEM SHALL log all payment transactions Event-Driven WHEN THE SYSTEM SHALL Hành vi được kích hoạt bởi một sự kiện cụ thể WHEN a user submits a password reset request THE SYSTEM SHALL send a reset link State-Driven WHILE THE SYSTEM SHALL Hành vi diễn ra liên tục trong một trạng thái WHILE a user session is active THE SYSTEM SHALL refresh the authentication token every 15 minutes Optional Feature WHERE THE SYSTEM SHALL Hành vi chỉ áp dụng khi một tính năng hoặc điều kiện được bật WHERE the user has administrator privileges THE SYSTEM SHALL display the audit log Unwanted Behaviour IF THE SYSTEM SHALL Xử lý lỗi và các trường hợp ngoại lệ IF the payment gateway returns a timeout error THE SYSTEM SHALL retry up to 3 times So sánh Yêu cầu Truyền thống và Yêu cầu theo EARS Sự khác biệt giữa một yêu cầu truyền thống và một yêu cầu viết theo EARS không chỉ nằm ở cách trình bày, mà còn nằm ở việc AI có thể tự suy diễn đến đâu và đâu là những gì bạn bắt buộc phải mô tả rõ ràng. Yêu cầu truyền thống: "Người dùng nên nhận được thông báo khi đơn hàng được giao." Khi đọc yêu cầu này, AI phải tự quyết định: "Thông báo" nghĩa là gì "Đơn hàng được giao" được xác định như thế nào "Người dùng" là ai Kênh gửi thông báo là gì Nội dung thông báo ra sao Cần làm gì nếu việc gửi thất bại Tất cả những quyết định này sẽ được AI đưa ra dựa trên dữ liệu huấn luyện, chứ không phải dựa trên yêu cầu thực tế của hệ thống. Yêu cầu theo EARS: "WHEN an order status changes to 'shipped' THE SYSTEM SHALL send an email notification to the customer's registered email address within 5 minutes of the status change." Lúc này AI biết chính xác cần xây dựng điều gì: Trigger là việc trạng thái đơn hàng chuyển sang một giá trị cụ thể Hành động là gửi email Địa chỉ nhận được xác định rõ Có ràng buộc về thời gian thực hiện Bằng cách này, AI sẽ không còn tự suy diễn, nếu muốn quy định cách xử lý khi gửi email thất bại, bạn chỉ cần bổ sung thêm một yêu cầu xử lý lỗi riêng. Dưới đây là ví dụ so sánh trực tiếp những gì AI phải quyết định trong từng trường hợp. Yêu cầu truyền thống Yêu cầu theo EARS Khách hàng có thể áp dụng mã giảm giá khi thanh toán. KHI khách hàng nhập mã giảm giá hợp lệ trong quá trình thanh toán, HỆ THỐNG SẼ áp dụng mức giảm giá tương ứng trước khi tính tổng giá trị đơn hàng. Mã giảm giá không hợp lệ sẽ hiển thị thông báo lỗi. Nếu mã giảm giá không tồn tại hoặc đã hết hạn, HỆ THỐNG sẽ hiển thị thông báo lỗi và ngăn không cho áp dụng mã giảm giá. Người dùng cao cấp có thể sử dụng các ưu đãi dành cho khách hàng thân thiết. TRƯỜNG HỢP khách hàng có trạng thái Khách hàng Cao cấp, HỆ THỐNG SẼ cho phép kết hợp các khoản giảm giá dành cho khách hàng thân thiết với mã giảm giá khuyến mãi. Cả hai phiên bản đều truyền tải cùng một ý tưởng nghiệp vụ. Điểm khác biệt là EARS loại bỏ phần lớn quá trình suy diễn trong lúc triển khai. Đối với lập trình viên, điều này giúp yêu cầu rõ ràng hơn. Đối với Claude Code, nó cung cấp tín hiệu mạnh mẽ hơn về hành vi chính xác cần được tạo ra. EARS tạo đầu vào tốt hơn cho hoạt động kiểm thử Một lợi ích khác của EARS là khả năng liên kết tự nhiên với các phương pháp kiểm thử. Nhiều đội ngũ hiện nay sử dụng Behavior-Driven Development (BDD) để xây dựng tiêu chí nghiệm thu thông qua các kịch bản Given-When-Then. EARS cũng theo cùng một tư duy khi buộc người viết phải mô tả rõ: Trigger Điều kiện Kết quả mong đợi Ví dụ: Yêu cầu: WHEN a customer's subscription expires, THE SYSTEM SHALL revoke access to premium features. Có thể chuyển đổi rất dễ dàng thành kịch bản kiểm thử: Given: Một khách hàng đang có gói Premium còn hiệu lực When: Gói đăng ký đạt đến ngày hết hạn Then: Người dùng không còn truy cập được các tính năng Premium Mối liên hệ này đặc biệt hữu ích khi làm việc với các công cụ AI coding. Claude Code có thể sử dụng cùng một yêu cầu để: Sinh mã nguồn Sinh unit test Sinh integration test Sinh acceptance criteria Thay vì tạo code từ một mô tả mơ hồ, AI làm việc dựa trên một đặc tả đã mô tả rõ hành vi mong muốn. Tuy nhiên, EARS không phải là một framework hoàn chỉnh để xây dựng đặc tả sẵn sàng cho AI. Nó không mô tả: Bối cảnh nghiệp vụ Thuật ngữ chuyên ngành Ràng buộc kỹ thuật Các trường hợp ngoại lệ Nhưng EARS là nền tảng rất tốt để mô tả hành vi hệ thống theo cách giảm thiểu tối đa sự mơ hồ và nâng cao độ chính xác khi triển khai. Đọc thêm: Phát triển hướng đặc tả cho Claude Code: So sánh CafeKit, GitHub Spec Kit, BMAD và claude-code-spec-workflow. Cấu trúc của một đặc tả sẵn sàng cho AI (AI-Ready Specification) EARS giúp mô tả hành vi hệ thống rõ ràng hơn, nhưng để viết đặc tả cho AI coding hiệu quả, chỉ có yêu cầu được cấu trúc tốt là chưa đủ. Claude Code vẫn cần thêm ngữ cảnh để hiểu: Bài toán nghiệp vụ Miền nghiệp vụ (domain) Các ràng buộc kỹ thuật phải tuân thủ Một sai lầm phổ biến là cho rằng chỉ cần tập hợp các yêu cầu EARS là đủ để triển khai. Trên thực tế, hai nhóm khác nhau có thể cung cấp cùng một yêu cầu nhưng nhận được kết quả hoàn toàn khác nhau tùy thuộc vào lượng ngữ cảnh đi kèm. Đó là lý do các đội ngũ AI Engineering hiệu suất cao đang chuyển sang sử dụng AI-ready specifications – những tài liệu được thiết kế không chỉ để con người đọc và review mà còn để AI trực tiếp thực thi. Mặc dù mỗi tổ chức có thể áp dụng định dạng khác nhau, hầu hết các đặc tả AI-ready hiệu quả đều bao gồm những thành phần cốt lõi sau. Bối cảnh và Mục tiêu Trước khi mô tả yêu cầu, đặc tả cần giải thích: Tính năng này tồn tại để làm gì Nó giải quyết vấn đề gì Phần này cung cấp cho AI ngữ cảnh nghiệp vụ để đưa ra các quyết định triển khai tốt hơn. Nếu không có ngữ cảnh, mô hình có thể chỉ tập trung hoàn thành từng yêu cầu riêng lẻ mà bỏ lỡ mục tiêu tổng thể của tính năng. Ví dụ, thay vì đi thẳng vào yêu cầu: "WHEN a customer enters a discount code, THE SYSTEM SHALL apply the corresponding discount." Hãy mô tả mục tiêu trước: "Mục tiêu của tính năng này là tăng tỷ lệ sử dụng các chương trình khuyến mãi bằng cách cho phép khách hàng nhập mã giảm giá trong quá trình thanh toán, đồng thời đảm bảo các quy tắc giảm giá được áp dụng nhất quán trên cả nền tảng web và mobile." Điều này giúp Claude Code hiểu rõ hơn kết quả kinh doanh mà tính năng đang hướng tới. Domain Glossary Một trong những nguyên nhân nhanh nhất dẫn đến sự nhầm lẫn trong mã do AI tạo ra là thuật ngữ không nhất quán. Nhiều tổ chức thường sử dụng các từ như: User Customer Member Subscriber thay thế cho nhau trong các cuộc thảo luận, dù trên thực tế chúng có thể đại diện cho các thực thể nghiệp vụ hoàn toàn khác nhau. Một AI-ready specification nên có phần từ điển thuật ngữ trước khi bắt đầu triển khai. Thuật ngữ Định nghĩa Customer Người dùng đã đăng ký và có thể đặt hàng Guest User Khách truy cập có thể xem sản phẩm nhưng không xem được lịch sử đơn hàng Discount Code Mã khuyến mãi dùng để giảm giá trị đơn hàng khi đáp ứng điều kiện áp dụng Premium Customer Khách hàng tham gia chương trình khách hàng thân thiết Yêu cầu chức năng sử dụng EARS Sau khi đã xác định bối cảnh và thuật ngữ, các yêu cầu chức năng nên được mô tả bằng một cấu trúc thống nhất. Đây chính là nơi EARS trở thành công cụ chính để mô tả hành vi hệ thống. Thay vì các đoạn mô tả tự do, mỗi yêu cầu cần xác định rõ: Trigger Điều kiện Phản hồi mong muốn Năm mẫu EARS có thể bao phủ hầu hết các tình huống: Hành vi luôn áp dụng (Ubiquitous) Hành vi theo sự kiện (Event-Driven) Hành vi theo trạng thái (State-Driven) Tính năng tùy chọn (Optional Feature) Xử lý lỗi (Error Handling) Đặc biệt, các yêu cầu xử lý lỗi rất quan trọng vì nhiều nhóm chỉ tập trung vào happy path và bỏ quên ngoại lệ. Nếu bạn không mô tả điều gì xảy ra khi coupon không hợp lệ, AI sẽ: Bỏ qua trường hợp đó Hoặc tự nghĩ ra cách xử lý Với mỗi yêu cầu Event-Driven, nên có ít nhất một yêu cầu IF tương ứng để xử lý thất bại. Ví dụ yêu cầu cho hệ thống mã giảm giá KHI khách hàng nhập mã giảm giá hợp lệ trong quá trình thanh toán, HỆ THỐNG SẼ áp dụng mức giảm giá tương ứng trước khi tính tổng giá trị đơn hàng. NẾU mã giảm giá đã hết hạn, HỆ THỐNG SẼ hiển thị thông báo lỗi và ngăn không cho áp dụng giảm giá. NẾU mã giảm giá đã vượt quá giới hạn sử dụng, HỆ THỐNG SẼ từ chối áp dụng và hiển thị "Mã giảm giá này đã đạt đến giới hạn sử dụng." NẾU khách hàng áp dụng mã giảm giá khi đơn hàng đang ở trạng thái ĐÃ XÁC NHẬN, HỆ THỐNG SẼ từ chối sửa đổi và hiển thị "Không thể sửa đổi đơn hàng đã xác nhận." NẾU hai khách hàng áp dụng cùng một mã giảm giá cùng lúc, HỆ THỐNG SẼ xử lý các ứng dụng theo trình tự và thực thi giới hạn sử dụng một cách chính xác. Do các yêu cầu này đều tuân theo cùng một cấu trúc nên cả người review và AI coding agent đều dễ hiểu hơn. AI không cần tự đoán cách xử lý ngoại lệ vì mọi thứ đã được mô tả rõ. Tiêu chí Chấp thuận (Acceptance Criteria) Yêu cầu mô tả hệ thống phải làm gì. Acceptance Criteria mô tả thế nào được coi là thành công. Phần này giúp tránh việc các bên liên quan hiểu cùng một yêu cầu theo những cách khác nhau. Đồng thời nó cũng cung cấp mục tiêu kiểm chứng rõ ràng cho phần triển khai do AI tạo ra. Ví dụ: Given: Một mã giảm giá hợp lệ tồn tại When: Khách hàng áp dụng mã trong lúc thanh toán Then: Mức giảm giá chính xác phải được phản ánh trong tổng giá trị đơn hàng Acceptance Criteria tạo ra mối liên kết trực tiếp giữa kỳ vọng kinh doanh và kết quả triển khai. Khó khăn về mặt kỹ thuật Một trong những nguyên nhân phổ biến khiến AI tạo ra các giải pháp phức tạp không cần thiết là thiếu hướng dẫn kỹ thuật. Khi không có ràng buộc, Claude Code có thể: Đưa vào pattern mới Bổ sung dependency mới Chọn kiến trúc khác với phần còn lại của hệ thống Một phần Technical Constraints riêng biệt sẽ giúp giảm đáng kể rủi ro này. Ví dụ: Sử dụng Repository Pattern hiện có Tái sử dụng Notification Service cho mọi giao tiếp với khách hàng Không thêm dependency từ bên thứ ba Tuân thủ định dạng API response hiện tại của dự án Đảm bảo thời gian phản hồi dưới 500ms trong điều kiện tải thông thường Quy tắc Xác thực và Quy tắc Nghiệp vụ Nhiều yêu cầu thất bại vì logic kiểm tra dữ liệu chỉ được ngầm hiểu chứ không được mô tả rõ. Ví dụ: "Validate discount code input." Yêu cầu này vẫn để lại quá nhiều khoảng trống cho việc suy diễn. Một đặc tả tốt hơn nên mô tả cụ thể: Mã giảm giá không được dài quá 50 ký tự Không phân biệt chữ hoa và chữ thường Mã hết hạn không được sử dụng Không được cộng dồn nhiều mã trừ khi được đánh dấu là stackable Quy tắc nghiệp vụ càng chi tiết, AI càng ít phải đoán. Kịch bản Kiểm thử và Định nghĩa Hoàn thành Phần cuối cùng cần mô tả: Tính năng sẽ được kiểm chứng như thế nào Khi nào được xem là hoàn thành Điều này tạo ra một vạch đích rõ ràng cho cả lập trình viên và AI coding agent. Định nghĩa Hoàn thành có thể bao gồm: Tất cả yêu cầu EARS đã được triển khai Unit test chạy thành công Integration test chạy thành công Acceptance Criteria được đáp ứng Không còn lỗ hổng bảo mật nghiêm trọng Tài liệu đã được cập nhật Khi kết hợp lại, các thành phần này sẽ biến một tài liệu yêu cầu truyền thống thành một AI-ready specification hoàn chỉnh. EARS cung cấp cấu trúc để mô tả hành vi. Context, thuật ngữ, ràng buộc kỹ thuật và quy tắc kiểm tra cung cấp cho Claude Code toàn bộ thông tin cần thiết để tạo ra mã nguồn phù hợp với kỳ vọng kinh doanh. Tuy nhiên, ngay cả một đặc tả được xây dựng tốt vẫn có thể thất bại nếu bỏ sót các trường hợp ngoại lệ, tình huống lỗi hoặc điều kiện biên. Vì vậy, việc tài liệu hóa đầy đủ các trường hợp này là bước tiếp theo mang tính quyết định. Xây dựng đặc tả có thể thực thi bởi AI với CafeKit Viết được một đặc tả tốt mới chỉ là một phần của bài toán. Khi AI ngày càng được áp dụng rộng rãi trong các đội ngũ kỹ thuật, các tổ chức nhanh chóng gặp phải một thách thức khác: làm thế nào để duy trì tính nhất quán giữa yêu cầu, ngữ cảnh nghiệp vụ, quyết định kiến trúc và tri thức domain theo thời gian. Một đặc tả cho một tính năng có thể chứa: Hàng chục yêu cầu EARS Các quy tắc kiểm tra dữ liệu Các trường hợp ngoại lệ Acceptance Criteria Nhân điều đó lên nhiều đội nhóm và nhiều dự án, việc duy trì một nguồn thông tin đáng tin cậy ngày càng khó khăn. Khi thông tin bị phân tán trong tài liệu đầu vào, ticket, biên bản họp hay đoạn chat, AI coding agent rất dễ nhận được ngữ cảnh thiếu hoặc lỗi thời. Đây chính là lúc những nền tảng như CafeKit phát huy giá trị. Thay vì coi đặc tả là các tài liệu rời rạc, CafeKit giúp các nhóm quản lý toàn bộ ngữ cảnh mà AI coding agent cần để làm việc. Các thành phần như: Yêu cầu Business rules Thuật ngữ domain Kiến thức hỗ trợ được tổ chức theo cấu trúc thống nhất để cả con người và AI đều có thể truy cập cùng một nguồn thông tin. Đọc thêm về CafeKit: Vượt xa "Vibe Coding": Cách CafeKit đưa Phát triển dựa trên đặc tả (SDD) vào Tự động hóa AI. Tập trung hóa ngữ cảnh nghiệp vụ Một trong những nguyên nhân phổ biến nhất khiến AI triển khai sai là ngữ cảnh bị phân mảnh. Yêu cầu nghiệp vụ nằm ở một tài liệu. Quyết định kiến trúc nằm ở tài liệu khác. Thuật ngữ nghiệp vụ lại ở nơi khác. Lập trình viên giàu kinh nghiệm có thể lấp đầy các khoảng trống này nhưng AI thì không. Một kho tri thức tập trung giúp tạo ra một nguồn sự thật duy nhất (single source of truth) cho cả yêu cầu và ngữ cảnh liên quan. Thay vì phải suy đoán, Claude Code làm việc với thông tin đã được tài liệu hóa và kiểm chứng. Duy trì kiến thức domain nhất quán Khi hệ thống phát triển lớn hơn, thuật ngữ trở nên cực kỳ quan trọng. Các khái niệm như: Customer Member Subscriber User có vẻ giống nhau nhưng thường đại diện cho các thực thể nghiệp vụ khác nhau. Không có glossary chung, sự thiếu nhất quán sẽ lan từ yêu cầu sang code, API và tài liệu. Các triển khai do AI tạo ra đặc biệt nhạy cảm với vấn đề này vì mô hình thường hiểu thuật ngữ theo nghĩa đen. Khi AI biết chính xác "Premium Customer" là gì, nó sẽ triển khai đúng các business rule liên quan mà không tạo ra các lỗi khó phát hiện. Lưu giữ các quyết định kiến trúc Yêu cầu mô tả hệ thống cần làm gì. Quyết định kiến trúc mô tả hệ thống nên được xây dựng như thế nào. Những quyết định này thường được ghi lại dưới dạng Architecture Decision Records (ADR), bao gồm: Design pattern Hạ tầng Phương thức tích hợp Ràng buộc hiệu năng Các lập trình viên có thể đã quen thuộc với những quyết định này. AI chỉ có thể tuân thủ chúng nếu được cung cấp trong quá trình triển khai. Khi AI có quyền truy cập vào các hướng dẫn kiến trúc, nguy cơ lệch khỏi tiêu chuẩn kỹ thuật của tổ chức sẽ giảm đáng kể. Nếu Claude Code biết nhóm đang sử dụng Repository Pattern và các quy ước API cụ thể, nó sẽ tạo ra mã phù hợp với codebase hiện tại thay vì đưa vào những pattern mới cần phải refactor sau này. Xây dựng quy trình làm việc hiệu quả hơn cho Claude Code Nhiều đội ngũ hiện nay đang chuyển từ cách phát triển dựa trên prompt sang quy trình phát triển dựa trên đặc tả. Thay vì yêu cầu Claude Code: "Hãy xây dựng tính năng này." Quy trình trở thành: Xác định mục tiêu nghiệp vụ và yêu cầu Tài liệu hóa EARS requirements và Acceptance Criteria Ghi nhận edge cases và validation rules Cung cấp technical constraints và ngữ cảnh hỗ trợ Sinh mã nguồn và test từ đặc tả Cách tiếp cận này tạo ra nền tảng vững chắc hơn cho phát triển phần mềm có hỗ trợ AI. Mô hình dành ít thời gian hơn cho việc suy đoán và nhiều thời gian hơn cho việc thực thi các yêu cầu đã được xác định rõ. Kết quả không chỉ là mã nguồn tốt hơn mà còn: Tính nhất quán cao hơn Ít vòng sửa đổi hơn Sự đồng bộ tốt hơn giữa kỳ vọng kinh doanh và kết quả kỹ thuật Cuối cùng, các công cụ như Claude Code phát huy hiệu quả cao nhất khi hoạt động trong một môi trường đặc tả có cấu trúc rõ ràng. Kết luận Viết đặc tả kỹ thuật cho lập trình AI khác biệt hoàn toàn so với viết yêu cầu cho lập trình viên con người. Lập trình viên con người diễn giải, đặt câu hỏi và bổ sung những thiếu sót. Claude Code thực thi chính xác những gì bạn chỉ định, và khi đặc tả đó không rõ ràng, nó sẽ đoán. EARS loại bỏ sự mơ hồ bằng cách buộc bạn phải chỉ định rõ ràng các trình kích hoạt, điều kiện và phản hồi. CafeKit cung cấp không gian làm việc và quy trình làm việc – ngữ cảnh, thuật ngữ, ràng buộc và quy tắc xác thực – mà các tác nhân AI cần để tạo ra mã phù hợp với kỳ vọng kinh doanh của bạn. Chúng tôi đang tích cực sử dụng các phương pháp này trong các dự án của mình tại Haposoft và nhận thấy những cải tiến đáng kể về chất lượng mã và tốc độ phát triển. CafeKit là open source code và có sẵn để sử dụng sớm. Hãy cài đặt nó và bắt đầu viết đặc tả kỹ thuật cho lập trình AI thực sự hiệu quả. Có câu hỏi hoặc cần tư vấn? Liên hệ ngay với chúng tôi. Sẵn sàng áp dụng vào thực tế? CafeKit là dự án open source code và hiện đã sẵn sàng cho giai đoạn sử dụng sớm. Hãy cài đặt và bắt đầu viết những đặc tả cho AI coding thực sự hiệu quả. npx @haposoft/cafekit GitHub Repository →
.png&w=828&q=75)
