Phát triển theo spec
Viết spec trước khi ra lệnh cho AI coding agent
Spec Kit là dự án mã nguồn mở của chính GitHub. Hướng dẫn này độc lập, không liên kết với GitHub và không được GitHub chứng thực.
Phần lớn sự bực bội khi dùng AI coding agent đều xuất phát từ một nguyên nhân: yêu cầu mơ hồ thì kết quả cũng mơ hồ, và bạn chỉ nhận ra mình thực sự muốn gì sau khi đọc đoạn code không khớp với mong muốn. Spec giúp sắp xếp lại thứ tự công việc. Trước khi gửi bất kỳ prompt nào, bạn viết ra ba điều ngắn gọn bằng ngôn ngữ thông thường: sản phẩm cần làm gì, dành cho ai, và những kiểm tra cụ thể cho biết khi nào thì xong. Không điều nào trong đó đòi hỏi biết lập trình. Spec Kit của GitHub, một bộ công cụ mã nguồn mở được duy trì trong kho mã của chính GitHub, xây dựng một quy trình có cấu trúc và lặp lại được cho coding agent dựa trên đúng thói quen này, với công cụ dòng lệnh riêng và một chuỗi bước có tên, đi từ các nguyên tắc chỉ đạo của dự án đến bản build chạy được. Hướng dẫn này trình bày spec ba phần bạn có thể tự viết tay trong năm phút, cách quy trình của Spec Kit tách cùng ý tưởng đó thành các lệnh riêng, và khi nào nên cài cả bộ công cụ so với việc chỉ tự viết spec.
Spec là bản mô tả ngắn, viết bằng ngôn ngữ thông thường, mà bạn soạn trước khi nhờ bất kỳ coding agent nào xây dựng thứ gì đó: nó làm gì, dành cho ai, và các kiểm tra hoàn thành chứng minh nó đã xong. Spec Kit của GitHub, một bộ công cụ mã nguồn mở được xây dựng trong kho mã của chính GitHub, biến thói quen này thành quy trình lặp lại được với các lệnh riêng để đặt nguyên tắc, viết spec, lập kế hoạch, chia kế hoạch thành các tác vụ, triển khai và hội tụ. Tài liệu của nó nêu tên các agent mà nó kết nối, trong đó có Claude Code của Anthropic và GitHub Copilot. Bạn không cần bộ công cụ này để có được lợi ích: gõ cùng bản mô tả ba phần đó làm tin nhắn đầu tiên cũng hiệu quả với bất kỳ coding agent nào bạn đang dùng.
Ngày đăng
Bài học miễn phí · không cần tài khoảnGặp Gỡ ClaudeVì Sao Chọn Claude?6 phútBắt đầu bài học miễn phíĐiểm chính
- Spec gồm ba thứ viết trước prompt đầu tiên: agent cần xây dựng gì, dành cho ai, và các kiểm tra hoàn thành chứng minh nó đã xong.
- Spec Kit của GitHub là bộ công cụ mã nguồn mở miễn phí, theo giấy phép MIT theo chính kho mã của nó, biến thói quen này thành sáu lệnh có tên: constitution, spec, kế hoạch, danh sách tác vụ, triển khai, rồi hội tụ.
- Bạn không cần Spec Kit để hưởng lợi từ spec. Gõ cùng bản mô tả ba phần đó làm tin nhắn đầu tiên cũng dùng được trong Claude Code, Codex của OpenAI, Copilot, Cursor của Anysphere hay bất kỳ coding agent nào khác.
- Tài liệu cài đặt của Spec Kit nêu tên các coding agent mà nó kết nối bằng một khóa tích hợp, trong đó có Claude Code và GitHub Copilot, kèm hướng dẫn thêm các agent khác.
- Bỏ qua các kiểm tra hoàn thành là cách phổ biến nhất khiến một spec thất bại một cách âm thầm: không có chúng, cả bạn lẫn agent đều không biết tác vụ đã thực sự xong hay chưa.
Sao chép và dán
Prompt bạn có thể dùng ngay hôm nay
Spec ba phần để mở đầu cuộc trò chuyện đầu tiên
Đây là spec cho thứ tôi muốn bạn xây dựng. LÀM GÌ: một script sắp xếp các tệp trong thư mục Downloads của tôi vào các thư mục con theo ngày, phân loại theo loại tệp. DÀNH CHO AI: chỉ mình tôi, chạy thủ công từ terminal, không có người dùng nào khác. XONG KHI: chạy trên một thư mục thử gồm 20 tệp mẫu thì mọi tệp đều được xếp đúng thư mục con, không có gì bên ngoài thư mục đó bị đụng tới, và tôi có thể hoàn tác toàn bộ lần chạy bằng một lệnh. Hãy hỏi tôi bất cứ điều gì bạn cần trước khi bắt đầu xây dựng.
Dán đoạn này làm tin nhắn đầu tiên, trước mọi trao đổi qua lại về cách nó nên hoạt động.
Nhờ agent biến ý tưởng mơ hồ thành spec
Tôi muốn xây dựng một thứ gì đó, nhưng ý tưởng của tôi vẫn còn mơ hồ. Đại khái tôi đang hình dung thế này: mô tả ý tưởng sơ bộ của bạn trong một hai câu ở đây. Trước khi viết bất kỳ dòng code nào, hãy hỏi tôi cho đến khi bạn có thể nhắc lại cho tôi, theo ba phần ngắn, thứ này làm gì, dành cho ai, và làm sao cả hai ta biết nó đã xong. Đừng bắt đầu xây dựng cho đến khi tôi xác nhận rõ cả ba phần.
Hữu ích khi bạn đã hình dung được dạng của vấn đề nhưng chưa chốt các chi tiết.
Kiểm tra các điều kiện hoàn thành trước khi duyệt bản build
Trước khi bắt đầu triển khai, hãy liệt kê các kiểm tra cụ thể bạn sẽ chạy để chứng minh việc này đã xong: bạn sẽ kiểm thử gì, kết quả mong đợi của từng kiểm tra là gì, và thế nào được coi là thất bại. Nếu có kiểm tra nào cần thứ mà bạn không thể tự xác minh từ bên trong phiên này, hãy nói với tôi ngay bây giờ thay vì cho rằng sau này nó sẽ chạy được.
Một agent tốt phải trả lời được câu này chi tiết trước khi viết một dòng code.
Thói quen cốt lõi
Vì sao spec đi trước prompt
Gõ yêu cầu thẳng vào coding agent có vẻ nhanh hơn việc viết ra giấy trước, và với một tác vụ thật sự đơn giản thì thường đúng như vậy. Rắc rối bắt đầu với bất cứ việc gì có hơn một cách hiểu hợp lý: agent chọn một cách, xây theo hướng đó, và bạn chỉ biết nó chọn sai khi đang đọc đoạn code đã hoàn chỉnh. Từ đó, mỗi vòng sửa đều tốn hơn vài phút mà một bản spec đã có thể tiết kiệm.
Spec đảo lại thứ tự công việc. Trước khi viết bất kỳ đoạn code nào, bạn ghi ra ba điều bằng ngôn ngữ thông thường: sản phẩm cần làm gì, dành cho ai, và các kiểm tra hoàn thành chứng minh nó chạy đúng. Đây không phải tài liệu kỹ thuật. Nó giống ghi chú bạn để lại cho một trợ lý giỏi chưa từng gặp bạn: đủ chi tiết để họ không phải đoán ở những chỗ quan trọng.
Cách này hiệu quả vì một lý do đơn giản. Agent thôi lấp các khoảng trống trong yêu cầu của bạn bằng giả định của riêng nó, vì còn rất ít khoảng trống để lấp. Còn bạn cũng thôi phải khám phá mình thực sự muốn gì bằng cách đọc kết quả của agent sau khi mọi việc đã xong, vì bạn đã viết ra từ trước khi nhờ làm bất cứ điều gì.
Điều này không riêng cho công cụ nào. Claude Code, Codex, Copilot, Cursor và mọi coding agent khác đều hoạt động theo cùng một cách cơ bản: đưa vào chỉ dẫn bằng ngôn ngữ thông thường, nhận ra code và lệnh. Spec thay đổi thứ được đưa vào, và do đó thay đổi thứ nhận lại, dù bạn đang nói chuyện với agent nào.
Spec ba phần
Những gì nằm trong một spec bạn có thể viết trong năm phút
Bốn phần ngắn, bằng ngôn ngữ thông thường. Không phần nào đòi hỏi biết lập trình.
Nó làm gì
Một hai câu mô tả hành vi, không phải cách triển khai. "Sắp xếp tệp theo loại vào các thư mục theo ngày", chứ không phải mô tả dùng hàm hay thư viện nào.
Dành cho ai
Chỉ mình bạn, chạy thủ công? Hay một đồng nghiệp chưa từng thấy dự án? Câu trả lời này thay đổi thứ bạn thực sự cần xây, thường nhiều hơn cả mô tả tính năng.
Các kiểm tra hoàn thành
Những điều kiện cụ thể, kiểm thử được, chứng minh bản build đã xong. Đây là phần nhiều người bỏ qua, và cũng là phần quan trọng nhất khi có chuyện không ổn.
Ranh giới an toàn
Không bắt buộc, nhưng nên thêm khi rủi ro là thật: những việc agent tuyệt đối không được làm, như đụng vào tệp bên ngoài một thư mục hay tự động gửi bất cứ thứ gì.
Một cấu trúc mã nguồn mở cho việc này
Spec Kit của GitHub biến spec thành quy trình như thế nào
Spec Kit của GitHub là bộ công cụ mã nguồn mở, được duy trì trong kho mã của chính GitHub theo giấy phép MIT, nhằm mang đến cho AI coding agent các quy trình có cấu trúc, mẫu dùng lại được và kết quả được ghi lại, thay vì những cuộc trò chuyện dùng một lần. Nó được cài qua công cụ dòng lệnh riêng, và README của chính nó mô tả đây là bộ công cụ để bắt đầu với phát triển theo spec, hoặc bất kỳ quy trình có cấu trúc nào khác mà bạn muốn agent tuân theo.
Theo tài liệu của dự án, quy trình phát triển theo spec cốt lõi gồm một chuỗi sáu lệnh có tên: một lệnh đặt các nguyên tắc chỉ đạo của dự án, một lệnh viết chính bản spec, một lệnh biến spec thành kế hoạch kỹ thuật, một lệnh chia kế hoạch thành danh sách tác vụ có thứ tự, một lệnh thực hiện các tác vụ và viết code thực tế, và lệnh cuối kiểm tra kết quả hội tụ về spec đến mức nào. Hướng dẫn của dự án là chạy từng lệnh một, xem lại kết quả của mỗi lệnh trước khi tiếp tục, và lặp lại các bước triển khai và hội tụ cho đến khi bước hội tụ báo công việc đã hội tụ, thay vì giao toàn bộ công việc cho agent trong một lần.
Bộ công cụ cũng có các phần mở rộng riêng để thêm vào quy trình cốt lõi, cũng theo tài liệu của nó: một bộ lệnh xoay quanh việc đánh giá và sửa một lỗi cụ thể, và một bộ khác xoay quanh việc đưa một ý tưởng thô qua nghiên cứu và xác định trước khi quyết định có nên xây hay không.
Về các agent mà nó kết nối, tài liệu cài đặt của Spec Kit nêu tên một số agent bằng khóa tích hợp bạn truyền vào lúc cài, trong đó có Claude Code và GitHub Copilot, và chỉ đến tài liệu riêng của nó để kết nối thêm các agent ngoài những cái được nêu trực tiếp. Hãy coi bất kỳ danh sách agent cụ thể nào, kể cả danh sách này, là ảnh chụp tại một thời điểm: kiểm tra tài liệu hiện tại của Spec Kit trước khi cho rằng một công cụ hiện được hỗ trợ hay không.
Quy trình, từng lệnh một
Sáu lệnh cốt lõi của Spec Kit
Theo README của dự án, quy trình phát triển theo spec đi qua sáu bước này theo thứ tự, lặp lại hai bước cuối cho đến khi kết quả hội tụ.
Đặt constitution
Một lệnh ghi lại các nguyên tắc toàn dự án mà agent cần tôn trọng trong mọi việc về sau, viết một lần và dùng lại trong các công việc tiếp theo.
Viết spec
Một lệnh tạo ra chính tài liệu spec, cũng là bản mô tả bằng ngôn ngữ thông thường đã nói ở trên, nay được lưu thành một tệp dùng lại được thay vì một tin nhắn dùng một lần.
Lập kế hoạch cách tiếp cận
Một lệnh biến spec thành kế hoạch kỹ thuật, chọn cách tiếp cận trước khi viết bất kỳ dòng code nào, để một quyết định thiết kế không bị chôn vùi trong phần triển khai.
Chia thành tác vụ
Một lệnh chia kế hoạch thành danh sách tác vụ cụ thể, có thứ tự, mỗi tác vụ đủ nhỏ để kiểm tra riêng.
Triển khai
Một lệnh thực hiện danh sách tác vụ và viết code, lấy mọi thứ từ các bước trước làm kim chỉ nam thay vì bắt đầu lại từ đầu.
Hội tụ
Một lệnh kiểm tra kết quả khớp với spec đến mức nào. Theo hướng dẫn của dự án, bạn lặp lại triển khai và hội tụ cùng nhau cho đến khi bước hội tụ báo công việc đã hội tụ.
Không cần cài gì
Tự viết spec bằng tay, không cần bộ công cụ
Với người không làm lập trình đang xây một thứ nhỏ, chạy cả quy trình Spec Kit có thể nhiều thủ tục hơn mức tác vụ cần. Chỉ riêng spec ba phần, gõ làm tin nhắn đầu tiên cho agent bạn đang dùng, đã làm được phần lớn công việc thực sự mà không cần cài gì.
Hãy dán spec, rồi để agent hỏi bạn các câu làm rõ trước khi nó viết bất cứ thứ gì. Một agent giỏi sẽ hỏi khi có chỗ chưa rõ, và spec cho nó điều cụ thể để hỏi, thay vì lặng lẽ đoán rồi tự tin xây sai thứ.
Phiên bản đơn giản của thói quen này dùng được ở mọi nơi. Cùng một bản mô tả ba phần hoạt động dù bạn đang nói chuyện với Claude Code, Codex, Copilot, Cursor hay bất kỳ coding agent nào khác, vì không phần nào phụ thuộc vào tính năng riêng của một công cụ. Đó là thói quen bạn đang xây dựng, không phải plugin bạn đang cài.
Chỗ dễ sai
Những sai lầm làm hỏng một spec
Viết spec giúp được ít hơn mức đáng có khi một trong các lỗi này lọt vào.
Không có kiểm tra hoàn thành
Spec không có cách xác minh hoàn thành chỉ dời việc đoán từ prompt sang khâu xem lại, nơi khó phát hiện hơn.
Trộn chi tiết triển khai vào
Chỉ định ngôn ngữ lập trình hay thuật toán cụ thể trước khi quyết định tính năng đó có thực sự cần không sẽ biến spec thành thiết kế quá sớm.
Viết sau khi đã xong
Spec soạn để khớp với code đã có chỉ ghi lại những gì đã được xây. Nó không thể bắt được một vấn đề mà nó được viết ra để đồng ý với.
Một spec, nhiều tác vụ
Spec bao trùm nhiều hơn một tác vụ thật sự sẽ chôn vùi tác vụ thực sự quan trọng. Hãy giữ mỗi spec cho một phần việc đơn lẻ, kiểm tra được.
Khi nào nên dùng bộ công cụ
Spec đơn giản hay cả Spec Kit: chọn một
Với một bản build nhỏ đơn lẻ, spec ba phần đơn giản gõ thẳng vào cuộc trò chuyện là đủ, và nhanh hơn việc cài bất cứ thứ gì. Hầu hết các ví dụ trong hướng dẫn này được viết cho đúng trường hợp đó.
Spec Kit bắt đầu đáng công cài đặt khi bạn lặp lại việc này trên cùng một dự án, muốn các nguyên tắc của mình được áp dụng tự động cho mọi tính năng mới, hoặc muốn dùng cấu trúc có sẵn của các phần mở rộng sửa lỗi hay đánh giá ý tưởng thay vì tự nghĩ ra phiên bản riêng mỗi lần.
Dù chọn cách nào, kỹ năng thực sự vẫn như nhau: nêu rõ nó làm gì, dành cho ai, và làm sao bạn biết nó đã xong, trước khi viết một dòng code nào. Bộ công cụ chỉ tự động hóa việc ghi lại điều đó một cách nhất quán, khi thói quen này đã đủ thường xuyên để đáng tự động hóa.
Luyện viết spec trước khi xây dựng
Viết một spec rõ ràng, và đưa cho AI coding agent những chỉ dẫn thường trực của dự án, là kỹ năng dùng được với mọi công cụ trong hướng dẫn này. Bài học miễn phí của Nightschool AI về tệp chỉ dẫn của dự án sẽ hướng dẫn đúng điều đó, lấy Claude Code làm ví dụ.
Câu hỏi thường gặp
Trong bối cảnh này, spec chính xác là gì?
Là bản mô tả ngắn bằng ngôn ngữ thông thường mà bạn viết trước khi nhờ coding agent xây dựng thứ gì đó. Tối thiểu nó nêu thứ đó cần làm gì, dành cho ai, và các kiểm tra hoàn thành chứng minh nó đã xong. Nó không phải tài liệu kỹ thuật và không đòi hỏi biết lập trình.
Tôi có cần biết lập trình để viết spec không?
Không. Spec mô tả hành vi và kết quả bằng ngôn ngữ thông thường, không phải cách triển khai. Mô tả một công cụ cần làm gì và làm sao bạn biết nó chạy đúng không đòi hỏi kiến thức lập trình, dù agent xây dựng nó sẽ viết code thật.
Spec Kit của GitHub là gì?
Là bộ công cụ mã nguồn mở theo giấy phép MIT, được duy trì trong kho mã của chính GitHub. Nó cung cấp cho AI coding agent một quy trình có cấu trúc, lặp lại được, xây dựng quanh phát triển theo spec, với công cụ dòng lệnh riêng và một chuỗi sáu lệnh có tên, từ các nguyên tắc chỉ đạo của dự án đến triển khai và hội tụ.
Spec Kit hoạt động với những coding agent nào?
Theo tài liệu cài đặt của nó, bạn kết nối một agent lúc cài bằng khóa tích hợp; tài liệu nêu tên một số agent theo cách này, trong đó có Claude Code và GitHub Copilot, và dẫn đến tài liệu riêng để kết nối các agent khác. Hãy kiểm tra tài liệu hiện tại của Spec Kit để có danh sách đầy đủ, cập nhật trước khi cho rằng một công cụ cụ thể được hỗ trợ.
Hướng dẫn này có liên kết với GitHub không?
Không. Đây là hướng dẫn giáo dục độc lập, không do GitHub xuất bản hay chứng thực. Spec Kit và GitHub là dự án và nhãn hiệu của chính GitHub, được nhắc đến ở đây chỉ để mô tả chúng cho chính xác.
Spec khác gì với một prompt dài hơn?
Prompt dài hơn vẫn chỉ là một tin nhắn mô tả một tác vụ. Spec là bản mô tả có cấu trúc với ba phần cụ thể: làm gì, dành cho ai và các kiểm tra hoàn thành, được viết ra để đọc, xác nhận và dùng lại, chứ không chỉ gõ một lần rồi bỏ quên.
Cụ thể thì "kiểm tra hoàn thành" (done-when) là gì?
Là các điều kiện kiểm thử được chứng minh một bản build đã xong: bạn sẽ kiểm tra gì, kết quả mong đợi của từng kiểm tra, và thế nào được coi là thất bại. Không có chúng, sẽ không có cách thống nhất để biết agent đã thực sự hoàn thành tác vụ hay chỉ dừng lại.
Tôi có cần cài Spec Kit để hưởng lợi từ thói quen này không?
Không. Gõ cùng spec ba phần đó làm tin nhắn đầu tiên cho bất kỳ coding agent nào, Claude Code, Codex, Copilot, Cursor hay agent khác, đã mang lại phần lớn lợi ích mà không cần cài gì. Spec Kit là cấu trúc lặp lại được để làm việc này thường xuyên, không phải điều kiện bắt buộc để làm.
Spec Kit có miễn phí không?
Có. Đây là dự án mã nguồn mở phát hành theo giấy phép MIT, theo chính kho mã của nó, và được cài qua công cụ dòng lệnh miễn phí của riêng nó.
Lệnh viết spec của Spec Kit thực sự tạo ra gì?
Theo tài liệu của dự án, nó tạo ra chính tài liệu spec, cũng là bản mô tả bằng ngôn ngữ thông thường được nói đến xuyên suốt hướng dẫn này, lưu thành một tệp dùng lại được trong dự án của bạn thay vì gõ mới vào cuộc trò chuyện mỗi lần.
Biến spec thành AI agent đầu tiên của bạn
Nêu rõ nó làm gì, dành cho ai, và làm sao bạn biết nó đã xong, rồi hãy xây dựng.