Spec Kit: build app production-ready với coding agent theo spec

Đi trọn workflow Spec Kit của GitHub: constitution, specify, clarify, plan, tasks, implement theo TDD, rồi PR và merge, qua một app Next.js quản lý chi tiêu.

Đã duyệt độc lập · cập nhật 12/11/2026 · 28 min

1. Vì sao coding agent cần cấu trúc

Leon van Zyl mở đầu bằng một lời khẳng định: đây không phải lại thêm một video vibe coding nữa. Video dành cho người thật sự muốn build những app production-ready, chứ không phải những thứ dễ hỏng (theo video đăng ngày 01/10/2025).

Anh tả một cảnh mà theo anh ai cũng từng gặp. Ta có một ý tưởng app rất hay, viết một prompt, ném nó cho coding agent và nghĩ "được rồi, chạy thôi". Rồi kết quả trả về không hẳn đúng: feature bị thiếu, bug ở khắp nơi, UX khá tệ, và agent còn thêm vào những thứ bạn không hề yêu cầu (theo Leon, video đăng ngày 01/10/2025).

Điểm mấu chốt, theo Leon (video đăng ngày 01/10/2025): coding agent mạnh một cách khó tin, nhưng chúng cần cấu trúc. Chúng cần cùng loại chi tiết mà developer thật vẫn dùng, như edge case, user story, các quyết định về architecture, những thứ kiểu đó.

Đó là chỗ Spec Kit xuất hiện. Leon giới thiệu nó là một workflow có cấu trúc đến từ GitHub, đưa cho agent mọi context nó cần để build những ứng dụng ổn định và production-ready (theo video đăng ngày 01/10/2025).

Trong video, anh sẽ hướng dẫn cách dùng Spec Kit với bất kỳ coding agent nào, dù đó là Claude Code, Cursor, Windsurf, Codex hay thứ gì bạn đang dùng. Anh cũng đi theo các thực hành phát triển phần mềm đúng bài: dùng Git để quản lý version, tạo branch, viết test và nhiều thứ khác. Theo Leon (video đăng ngày 01/10/2025), xem hết video thì bạn sẽ build được app chất lượng một cách đều đặn, khớp với những gì bạn đã hình dung.

Prompt thẳngSpec Kit một promptcoding agent feature bị thiếubug ở khắp nơi, UX khá tệthêm thứ không ai yêu cầu context có cấu trúccoding agent edge case, user storyquyết định architectureGit, branch, test
Hình 1.1Vấn đề và cách giải Leon nêu ở đầu video (đăng ngày 01/10/2025): prompt trần cho ra kết quả lỗi, còn agent được đưa chi tiết như developer thật dùng thì build được app ổn định.

2. Spec Kit và spec-driven development là gì

Trước khi bắt tay vào, Leon trả lời câu hỏi Spec Kit là gì. Nói ngắn gọn, theo anh (video đăng ngày 01/10/2025), nó là một workflow chạy các script và những prompt được tinh chỉnh rất kỹ để tạo ra context chất lượng cao cho coding agent. Anh sẽ đi qua từng bước một cách chi tiết.

Trang README của repo github/spec-kit với logo Spec Kit
README của repo github/spec-kit trong video đăng ngày 01/10/2025, với dòng "Build high-quality software faster." và câu mô tả Spec Kit là nỗ lực giúp các tổ chức tập trung vào kịch bản sản phẩm thay vì viết code không tạo khác biệt, nhờ Spec-Driven Development.

Về cơ bản, Spec Kit đưa (hoặc đưa trở lại) spec-driven development vào workflow của bạn. Leon nói spec-driven development đã có từ rất lâu: đó là cách các team phát triển phần mềm thật xác định xem mình cần build gì. Các team đi qua một giai đoạn phân tích, lên kế hoạch cho các thay đổi, chia mọi thứ thành từng task riêng, có khi còn chia việc cho nhiều developer, và cuối cùng mới implement và test các thay đổi đó (theo Leon, video đăng ngày 01/10/2025).

Giờ đây, theo Leon (video đăng ngày 01/10/2025), ta bắt đầu thấy phương pháp đã được chứng minh này được coding agent sử dụng. Vì mọi thứ được viết thành tài liệu và lên kế hoạch từ trước, agent biết rõ mình phải làm gì. Thậm chí nếu bạn mở một conversation mới, agent cứ thế tiếp tục từ chỗ nó đã dừng.

3. Các thành phần của workflow: constitution và feature lifecycle

Leon mở một sơ đồ để đi qua các thành phần cốt lõi của workflow, và anh sẽ quay lại từng phần chi tiết khi thật sự dùng nó trong hệ thống (video đăng ngày 01/10/2025).

Sơ đồ Spec Kit Workflow với ô constitution và chuỗi Feature Life Cycle
Ô /constitution (Project principles & standards) ở trên, và dải "Feature Life Cycle" gồm /specify (define what to build, no technical info), /clarify (follow up questions), /plan (implementation plan), /tasks (break plan into actionable steps), /analyze (validate docs) và /implement (execute tasks & test).

Đầu tiên là bước Constitution. Theo Leon (video đăng ngày 01/10/2025), bước này thường được làm ngay khi bắt đầu project, và đây là nơi bạn đặt mọi nguyên tắc (principles) và tiêu chuẩn (standards) của project. Thông thường anh chỉ làm một lần lúc khởi đầu, và chỉ đụng lại nếu muốn thêm thứ gì vào tech stack hoặc đổi hành vi của agent.

Phần workflow chính là thứ Leon gọi là feature lifecycle. Đây là nơi ta chạy mọi action cần thiết để lên kế hoạch và implement một feature thật (theo video đăng ngày 01/10/2025):

  • Specify: nơi ta nói với agent mình muốn build gì. Bước này không chứa thông tin kỹ thuật nào, nó thuần là business requirement của feature (theo Leon, video đăng ngày 01/10/2025).
  • Clarify (tuỳ chọn): agent đọc requirement của ta và hỏi lại các câu hỏi follow-up (theo video đăng ngày 01/10/2025).
  • Plan: khi requirement đã rõ hơn, ta vào giai đoạn planning. Leon thấy bước này rất hay: nó tạo ra plan, các data model, các service interface, và thậm chí làm cả research (theo video đăng ngày 01/10/2025).
  • Tasks: có implementation plan rồi thì bước kế là lấy plan đó chia thành từng task riêng, tức các thay đổi code thật để implement feature (lời Leon, video đăng ngày 01/10/2025).
  • Analyze (tuỳ chọn): bước này nhìn lại mọi thứ đã được tạo ra trước nó để chắc rằng tài liệu đầy đủ và ta đã bao quát hết (theo video đăng ngày 01/10/2025).
  • Implement: nơi ta bảo coding agent "này, ta có mọi thứ cần rồi, cứ implement hết các task này đi" (theo video đăng ngày 01/10/2025).

Sau đó, theo Leon (video đăng ngày 01/10/2025), ta test các thay đổi trong hệ thống và nhờ agent sửa hay điều chỉnh gì cần thiết. Khi đã hài lòng, ta tạo một pull request và merge thay đổi vào branch main. Nếu sau này muốn thêm feature mới, ta chỉ việc bắt đầu lại cả quy trình, và nó sẽ tạo ra spec riêng, plan riêng, v.v. cho feature đó.

4. Tạo project Next.js và cài Spec Kit bằng uvx

"Nói thế đủ rồi", Leon chuyển sang thêm Spec Kit vào một project và chạy qua từng bước của workflow. Cho demo này, anh tạo một project Next.js mới: mở terminal và chạy lệnh dưới đây, thêm dấu chấm ở cuối để cài Next.js vào chính thư mục hiện tại (demo trong video đăng ngày 01/10/2025).

npx create-next-app@latest .

Anh chọn yes cho mọi lựa chọn mặc định. Để kiểm tra bản cài chạy được, anh chạy npm run dev hoặc pnpm run dev, mở URL được in ra và thấy trang boilerplate của Next.js (demo trong video đăng ngày 01/10/2025).

Tiếp theo là thêm Spec Kit. Điều đầu tiên Leon muốn lưu ý: Spec Kit được hầu như mọi coding agent hiện có hỗ trợ. Bạn xem được danh sách agent đang được hỗ trợ trên trang GitHub của Spec Kit, và theo anh nhóm làm Spec Kit liên tục thêm hỗ trợ cho nhiều agent nữa (theo video đăng ngày 01/10/2025). Anh nói một khi bạn thấy cách nó hoạt động, bạn có thể dùng nó với hầu như mọi agent ngoài kia. Trong video này anh hướng dẫn cách dùng với Claude Code, Cursor và Codex CLI.

Theo Leon (video đăng ngày 01/10/2025), cách dễ nhất để cài Spec Kit là chạy một lệnh, nhưng máy bạn phải có uvx. Để cài uv, trang cài đặt của uv có sẵn lệnh cho macOS, Linux hoặc Windows; nếu dùng Windows, bạn copy lệnh đó và chạy trong PowerShell. Sau đó copy lệnh cài Spec Kit.

Quay lại project, Leon mở một terminal mới, dán lệnh vào, xoá phần tên project và thay bằng một dấu chấm, để Spec Kit được cài vào thư mục làm việc hiện tại (demo trong video đăng ngày 01/10/2025). Lệnh anh dán vào terminal, với phần tên project đã đổi thành dấu chấm:

uvx --from git+https://github.com/github/spec-kit.git specify init .
Terminal PowerShell trong editor với lệnh uvx specify init đang được gõ
Lệnh uvx --from git+https://github.com/github/spec-kit.git specify init <PROJ… vừa được dán vào terminal PowerShell của project spec-kit-tutorial, trước khi Leon thay phần tên project bằng dấu chấm (demo trong video đăng ngày 01/10/2025).

Một màn hình hiện ra, anh chọn yes, rồi chọn AI agent. Vì muốn chỉ vài agent trong video, lần đầu anh cài cho Claude, và ở mục script type anh chọn PowerShell vì đang dùng Windows. Thế là xong: Spec Kit in ra các bước tiếp theo, nói rằng ta có thể chạy constitution, specify, plan, v.v., cùng các lệnh tuỳ chọn như clarify và analyze. Đó chính là các bước trên sơ đồ ban nãy (demo trong video đăng ngày 01/10/2025).

Anh muốn cài thêm cho các agent khác, nên chạy lại cùng lệnh đó, lần này chọn Cursor, lại chọn PowerShell. Cuối cùng chạy thêm một lần nữa và cài cho Codex (demo trong video đăng ngày 01/10/2025).

5. Spec Kit thêm gì vào project: memory, scripts, templates, commands

Vậy các lệnh đó thật ra đã làm gì? Trong project giờ có một thư mục mới là .specify, và ta thấy thay đổi trong các thư mục của Cursor, Codex và Claude (demo trong video đăng ngày 01/10/2025).

Mở thư mục .specify, ta có thư mục memory chứa file constitution. Theo Leon (video đăng ngày 01/10/2025), mặc định file này chỉ là một template trống, chứa các mục chính của một constitution. Trên sơ đồ, đó là bước constitution: ta sẽ chạy một lệnh để thật sự sinh ra constitution và điền vào file đó mọi nguyên tắc và tiêu chuẩn của project.

Kế đến là thư mục scripts. Đây là các helper script nhỏ mà agent dùng để dựng một số thứ trong project. Leon thấy các script này rất thú vị: agent dùng chúng để làm những việc như tạo branch mới và mọi thứ khác nó cần trong workflow (theo video đăng ngày 01/10/2025). Rồi tới templates: agent tham chiếu các template này khi tạo file spec, file plan và file task cho feature.

Tuỳ bạn cài cho agent nào, có thể chỉ Claude, chỉ Codex hay chỉ Cursor, nhưng theo Leon (video đăng ngày 01/10/2025) các thư mục này trông rất giống nhau. Ta có các command. Mở thư mục Codex thì thấy y hệt, có điều thay vì "commands" thì nó gọi là "prompts". Mở thư mục Claude cũng thấy cùng các command đó. Mỗi command đơn giản là một danh sách hướng dẫn chi tiết mà agent sẽ làm theo trong workflow của Spec Kit.

.specify/ memory/constitution.md scripts/powershell/ check-prerequisites.ps1 common.ps1 create-new-feature.ps1 setup-plan.ps1 update-agent-context.ps1 templates/ .codex/prompts/ analyze.mdclarify.mdconstitution.md implement.mdplan.mdspecify.mdtasks.md .claude/ và .cursor/: cùng các command
Hình 5.1Các file Spec Kit đặt vào project trong demo (video đăng ngày 01/10/2025): constitution trong memory, năm helper script PowerShell, thư mục templates, và bảy file prompt cho Codex; Claude Code và Cursor nhận cùng các command đó.

6. Bước constitution trong Claude Code

Giờ mới thật sự bắt đầu đi qua workflow, và bước đầu tiên là dựng constitution. Leon nói trong editor ta cứ mở coding agent của mình, dù là Cursor, Claude Code hay Codex, không quan trọng, bạn vẫn làm theo được (theo video đăng ngày 01/10/2025).

Vì Sonnet 4.5 vừa ra mắt (tính đến lúc video đăng ngày 01/10/2025), anh bắt đầu với Claude Code. Anh bật chế độ accept all edits và chạy lệnh /init. Lệnh này không thuộc Spec Kit, nhưng theo Leon (video đăng ngày 01/10/2025) nó cho Claude Code context về các công nghệ project đang dùng và cấu trúc thư mục trông ra sao. Anh cũng đổi tên terminal đó thành "Claude Code".

Project đã dựng xong và Spec Kit đã cài, nên anh tạo commit đầu tiên, đặt tên là "initial", rồi mới làm tiếp (demo trong video đăng ngày 01/10/2025).

Bước đầu tiên cần chạy là constitution. Về kỹ thuật thì nó là tuỳ chọn, nhưng Leon rất khuyên nên chạy, và nó rất dễ (theo video đăng ngày 01/10/2025). Trong Claude Code, Codex hay agent nào bạn dùng, quy trình đều y hệt. Để chạy các command này, bạn mở một conversation mới; trong Claude Code thì gõ dấu gạch chéo, chọn constitution, rồi đưa vào các quy tắc và tiêu chuẩn cho project. Vì đang dùng Next.js, anh giữ nó rất đơn giản. Theo lời anh, phần anh gõ sau lệnh constitution là:

write clean and modular code and use Next.js 15 best practices

Chạy xong, bước constitution hoàn tất, và trong thư mục .specify, mục memory, file constitution quả thật đã thay đổi. Mở ra thì không còn là bộ khung template nữa: nó đã được viết đầy đủ với rất nhiều chi tiết, như Next.js 15 best practices, phần rationale, cách tổ chức component, và nhiều thứ khác (demo trong video đăng ngày 01/10/2025).

File constitution.md đã được điền với các nguyên tắc Clean and Modular Code và Next.js 15 Best Practices
File constitution.md sau khi Claude Code điền (demo trong video đăng ngày 01/10/2025): tiêu đề "Spec-Kit Tutorial Constitution", mục Core Principles với "I. Clean and Modular Code (NON-NEGOTIABLE)" kèm Rationale, và "II. Next.js 15 Best Practices (NON-NEGOTIABLE)".

Một đoạn của file constitution.md trong demo (video đăng ngày 01/10/2025):

### I. Clean and Modular Code (NON-NEGOTIABLE)
All code MUST follow clean code principles with clear separation of concerns. Components, utilities, and business logic MUST be isolated into dedicated modules. Each module MUST have a single, well-defined responsibility. Avoid monolithic files exceeding 300 lines; refactor into smaller, focused units. Code readability and maintainability take precedence over cleverness.

**Rationale**: Modular architecture enables easier testing, debugging, and feature iteration. It reduces cognitive load and allows multiple developers to work in parallel without conflicts.

### II. Next.js 15 Best Practices (NON-NEGOTIABLE)
MUST adhere to Next.js 15 conventions and React 19 patterns:
- Use App Router architecture (`src/app/` directory structure)
- Leverage Server Components by default; use Client Components only when required (interactivity, browser APIs, state)
- Apply proper data fetching patterns (async Server Components, streaming)

Tới đây Leon phải nói rõ một điều: đây là một quy trình human in the loop. Tất nhiên bạn có thể làm theo các bước này một cách mù quáng và nhiều khả năng vẫn có kết quả rất tốt. Nhưng theo anh (video đăng ngày 01/10/2025), đừng ngại sửa các file này: thấy gì không thích thì cứ xoá đi, hoặc thêm vào. Riêng anh thì hài lòng với file đó, nên lại tạo một commit nữa, đặt tên "constitution".

7. Cùng lệnh đó trong Cursor và Codex, rồi publish lên GitHub

Trước khi sang bước kế, Leon hướng dẫn cách dùng các command này trong những coding agent khác (demo trong video đăng ngày 01/10/2025).

Với Cursor, bạn bấm dấu gạch chéo, tìm command constitution, rồi đưa vào các quy tắc, ví dụ "update the constitution with Next.js 15 best practices", vậy là xong. Theo Leon (video đăng ngày 01/10/2025), nó hoạt động y hệt như với Claude Code.

Với Codex, thứ cũng đã được cài lúc nãy, bạn sẽ thấy khi gõ dấu gạch chéo thì các command của Spec Kit không có ở đó (demo trong video đăng ngày 01/10/2025). Dù vậy vẫn dùng Spec Kit được: mở thư mục Codex ra, thay vì command, ở đó ta có chính các prompt. Thế là ta gõ giống như trước, kiểu "use Next.js 15 best practices", rồi kéo file command tương ứng vào chat.

Codex CLI mở trong terminal, thư mục .codex/prompts chứa các file analyze, clarify, constitution, implement, plan, specify, tasks
OpenAI Codex v0.42.0 với model gpt-5-codex chạy trong terminal, bên trái là thư mục .codex/prompts với bảy file prompt của Spec Kit (demo trong video đăng ngày 01/10/2025).

Vì vậy Leon mới nói dùng coding agent nào thật ra không quan trọng. Theo anh (video đăng ngày 01/10/2025), dù agent có hỗ trợ slash command hay không, bạn chỉ việc kéo thả prompt vào chat và agent sẽ biết cần làm gì.

Đến đây, cấu trúc project cơ bản đã có, mọi file đã được tạo, constitution cũng xong, nên có thể chuyển sang build feature đầu tiên, về thực chất là bản app cơ bản. Nhưng trước đó Leon muốn đẩy project lên GitHub: anh chọn Publish Branch, chọn tạo một private repository, và project đã có trên GitHub (demo trong video đăng ngày 01/10/2025).

8. Specify: mô tả feature, branch mới và file spec

Leon clear chat để bắt đầu implement feature đầu tiên. Việc đầu tiên là chạy Specify: nói với agent rằng ta muốn build một feature mới và feature đó là gì. Anh nhắc lại: ở giai đoạn này không đưa thông tin kỹ thuật nào, thuần là business requirement (theo video đăng ngày 01/10/2025).

Trong coding agent, anh gõ specify rồi đưa chi tiết về feature muốn build (demo trong video đăng ngày 01/10/2025). Theo lời anh, phần mô tả gửi kèm là:

I would like to build a basic expense tracking app. So add, view and delete expenses. Track personal expenses with amount, date, categories and description. It's a simple dashboard showing recent expenses and basic totals. Do not implement user auth as this is just a personal tracker for myself.

Vậy thôi, anh chạy nó. Leon nói đây là một app rất đơn giản, nhưng anh muốn tập trung vào các khái niệm cốt lõi khi dùng Spec Kit, chứ không ngồi hàng giờ chờ agent build một project khổng lồ (video đăng ngày 01/10/2025).

Rồi anh chỉ một điều anh thấy hay. Sau khi gửi prompt, agent chạy một script, và script đó tạo ra một branch mới: ta đã rời branch master và giờ đang ở branch 001-i-would-like (demo trong video đăng ngày 01/10/2025). Leon rất thích hành vi này. Ta không ghi đè mọi thứ trên master; ta tạo một branch riêng để làm các thay đổi một cách tách biệt, và chỉ khi hài lòng với kết quả mới merge lại vào master, giữ cho master sạch và ổn định (theo Leon, video đăng ngày 01/10/2025).

Spec Kit cũng tạo thư mục specs, trong đó có một thư mục mới trùng tên với branch, và bên trong có file spec (demo trong video đăng ngày 01/10/2025). File spec ghi lại input ban đầu của người dùng, cùng rất nhiều thứ giá trị: user scenarios and testing, acceptance scenarios, edge cases, functional requirements và một acceptance checklist. Leon nói nếu bạn là project manager hay từng làm phát triển phần mềm, những thứ này sẽ rất quen.

File spec.md: Feature Specification Personal Expense Tracker với Primary User Story
File specs/001-i-would-like/spec.md (demo trong video đăng ngày 01/10/2025): "Feature Specification: Personal Expense Tracker", mục "User Scenarios & Testing (mandatory)" và Primary User Story của một người quản lý tài chính muốn ghi chi tiêu hằng ngày để biết tiền đi đâu.

Một đoạn của spec.md trong demo (video đăng ngày 01/10/2025):

## User Scenarios & Testing *(mandatory)*

### Primary User Story
As a person managing my finances, I need to record my daily expenses so I can understand where my money is going. I want to quickly add expenses with relevant details like amount, when it happened, what category it falls under, and any notes I want to remember. I also want to see my recent spending at a glance with basic totals to stay aware of my spending patterns.

Spec đã xong, anh lại tạo commit, đặt tên "specify", và clear chat. Theo Leon (video đăng ngày 01/10/2025), cái hay của workflow này là không phải lặp lại những gì đã làm trước đó: ta cứ mở conversation mới và agent biết chính xác mình đang ở đâu trong quy trình.

9. Clarify: năm câu hỏi làm rõ spec

Phần thứ hai của workflow là clarify. Có file spec rồi thì ta chạy command clarify, và agent sẽ đọc file spec rồi hỏi ta các câu hỏi làm rõ. Agent báo rằng nó đã phân tích specification và tìm ra một số điểm mơ hồ quan trọng, nên có năm câu hỏi cho ta (demo trong video đăng ngày 01/10/2025).

Leon thấy chỗ này rất hay và rất khuyến khích bạn tự thử. Theo anh (video đăng ngày 01/10/2025), thật thú vị khi thấy agent tìm ra được các lỗ hổng và hỏi những câu rất tốt. Tất nhiên ta cũng có thể tự đưa ra lựa chọn của mình nếu không phương án nào phù hợp.

Câu hỏi 1 trên 5 của clarify: hiển thị tổng theo category với các phương án A, B, C, Short
Câu hỏi đầu tiên của clarify trong demo (video đăng ngày 01/10/2025): "Question 1 of 5: Category-specific totals display", hỏi dashboard nên hiện tổng theo category hay chỉ tổng chung, với các phương án A (chỉ tổng chung), B (tổng chung kèm breakdown theo category), C (cả hai, có nút chuyển) và Short (câu trả lời ngắn khác, tối đa 5 từ).

Các câu hỏi và câu trả lời của Leon trong demo (video đăng ngày 01/10/2025):

  • Câu 1, hiển thị tổng theo category: anh chọn B rồi sang câu kế (demo trong video đăng ngày 01/10/2025).
  • Câu 2: hệ thống có nên cho phép số tiền âm để biểu diễn khoản hoàn tiền hay trả hàng không? Leon thấy câu này thú vị và chọn A (demo trong video đăng ngày 01/10/2025).
  • Câu 3: cả description lẫn category có bắt buộc khi thêm một khoản chi không? Anh chọn A (demo trong video đăng ngày 01/10/2025).
  • Câu 4: "recent expenses" trên dashboard nghĩa là gì: 10 khoản chi gần nhất, mọi khoản chi trong 30 ngày qua, hay mọi khoản chi từng được ghi? Anh chọn B (demo trong video đăng ngày 01/10/2025).
  • Câu 5: những category nào nên có để phân loại khoản chi? Lần này agent không đưa phương án nào. Leon không đưa danh sách mà gõ "Use your best guess", để agent tự quyết (demo trong video đăng ngày 01/10/2025).

Vậy là xong, file spec đã được cập nhật với mọi thông tin mới (demo trong video đăng ngày 01/10/2025). Theo Leon (video đăng ngày 01/10/2025), đó thật sự là sức mạnh của workflow này: nó buộc bạn nghĩ về thứ mình đang cố build, và bằng cách hỏi các câu làm rõ, nó thật sự làm requirement đầy đặn lên.

Spec đã hoàn chỉnh, anh tạo commit mới tên "clarify". Agent của anh còn đề xuất bước kế là chạy command plan. Một lần nữa, Leon thích giữ conversation gọn nhẹ, nên anh clear conversation (demo trong video đăng ngày 01/10/2025).

10. Plan: lúc đưa tech stack vào

Tiếp theo Leon chạy plan. Theo anh (video đăng ngày 01/10/2025), điểm đáng chú ý ở bước plan là bạn có thể chạy nó không kèm gì, nhưng đây cũng là cơ hội để đưa các chi tiết kỹ thuật agent cần để implement. Ví dụ với app này, anh sẽ không dùng authentication và chỉ dùng local storage để lưu dữ liệu.

Bạn có thể đưa vào cả tech stack của mình ở đây, như dùng database Postgres với Drizzle ORM, một thư viện authentication như Better Auth, hay shadcn cho component. Theo Leon (video đăng ngày 01/10/2025), đây là chỗ bạn đưa vào mọi thông tin và quy tắc kiểu đó. Theo lời anh, phần anh gõ sau lệnh plan là:

Use Next.js with the app router, route handlers and server actions. Add any backend server-side logic to a server folder in the source folder. Use local storage to persist data. Do not implement auth.

Anh chạy nó và nói sẽ tua nhanh qua các đoạn này, vì mỗi bước có thể mất vài phút mới xong (theo video đăng ngày 01/10/2025). Agent lập ra một checklist chi tiết cho mọi việc nó phải làm trong giai đoạn planning: điền phần Technical Context, hoàn thành Constitution Check, Phase 0 sinh research.md, Phase 1 sinh data-model.md, contracts và quickstart.md, cập nhật context agent trong CLAUDE.md, đánh giá lại Constitution Check, và lên cách tiếp cận cho việc sinh task ở Phase 2 (demo trong video đăng ngày 01/10/2025).

Planning xong, agent đã tạo rất nhiều thay đổi trong project (demo trong video đăng ngày 01/10/2025). Đầu tiên là file quickstart, theo Leon (video đăng ngày 01/10/2025) thật sự rất hữu ích: nó mô tả feature này là gì và cách dùng nó, như khởi động app thế nào, điều hướng trong app ra sao, và liệt kê mọi test scenario cùng các bước chính xác để tái hiện từng cái.

Tất nhiên bạn cũng có tài liệu plan, lại gồm phần tóm tắt feature, tech stack, những thứ như documentation, cấu trúc source code của project, mọi contract, và nhiều thứ khác nữa. Theo Leon (video đăng ngày 01/10/2025), nó lên kế hoạch cho mọi phase và mọi artifact tạo nên project.

File plan.md với mục Project Structure liệt kê cây thư mục src
plan.md của feature trong demo (video đăng ngày 01/10/2025), mục "Source Code (repository root)": src/app, components (expense-form, expense-list, expense-summary), server/actions (add-expense, delete-expense), server/services (expense-storage là LocalStorage abstraction, expense-utils), lib (types, constants) và __tests__/contract.

Bạn còn thấy cả data model. Theo Leon (video đăng ngày 01/10/2025), nếu bạn dùng database thì file này còn có cả schema được đề xuất. Ngoài ra có file research, và trong contracts là mọi định nghĩa interface cho những thứ như API, upload file, v.v.

Bước này cũng cập nhật các file dành cho agent: file CLAUDE.md và file AGENTS.md đều được sửa để phản ánh feature và plan (demo trong video đăng ngày 01/10/2025). Bước plan xong, anh tạo commit mới, đặt tên "plan".

11. Tasks: chia plan thành phase và task có mã số

Plan xong thì chuyển sang tasks. Bước này chia plan thành các bước hành động cụ thể. Leon chạy nó và để agent "nấu" một lúc. Bước tasks hoàn tất, anh mở file của nó ra và nói đây thật sự là phần cốt lõi của giải pháp (demo trong video đăng ngày 01/10/2025).

File cho thấy feature sẽ được implement theo từng phase (demo trong video đăng ngày 01/10/2025):

  • Phase 3.1 gồm mọi phần setup và nền móng (Setup & Foundation) (demo trong video đăng ngày 01/10/2025).
  • Phase 3.2 là storage và utility (demo trong video đăng ngày 01/10/2025).
  • Phase 3.3 là contract test theo test-driven development (demo trong video đăng ngày 01/10/2025).
  • Phase 3.4 gồm phần implement server action, cũng theo test-driven development (demo trong video đăng ngày 01/10/2025).
  • Rồi tới lớp component, v.v. (demo trong video đăng ngày 01/10/2025).
File tasks.md mở ở Phase 3.1 Setup and Foundation với các task T001 tới T004
tasks.md trong demo (video đăng ngày 01/10/2025), mục "Phase 3.1: Setup & Foundation": T001 tạo các TypeScript type trong src/lib/types.ts, T002 tạo hằng số trong src/lib/constants.ts với mảng EXPENSE_CATEGORIES gồm 7 category, T003 cài thư viện validation Zod, T004 tạo Zod validation schema.

Một đoạn của tasks.md trong demo (video đăng ngày 01/10/2025):

## Phase 3.1: Setup & Foundation

- [ ] **T001** [P] Create TypeScript types in `src/lib/types.ts`
  - Define `Expense`, `ExpenseInput`, `Category`, `CategoryTotal`, `ExpenseSummary`, `ActionResult`
  - Source: data-model.md sections 1-3

- [ ] **T002** [P] Create constants in `src/lib/constants.ts`
  - Define `EXPENSE_CATEGORIES` array with 7 categories
  - Source: data-model.md section 5

- [ ] **T003** [P] Install Zod validation library
  - Run `npm install zod`
  - Add to package.json dependencies

Mỗi task có một mã số riêng, như T001, T002, cho tới T030 (demo trong video đăng ngày 01/10/2025). Vì vậy, theo Leon (video đăng ngày 01/10/2025), nếu muốn, ta có thể nhắc tới một task cụ thể trong chat bằng cách nói "này, implement T001 đi", hoặc implement mọi thứ từ T001 tới T010 chẳng hạn.

Trước khi chạy bước implement, anh commit "tasks" và clear chat. Theo Leon (video đăng ngày 01/10/2025), ta có thể để trống phần mô tả và agent sẽ cứ thế chạy qua mọi task từ đầu tới cuối. Nhưng tất nhiên phải tính tới context window: context càng dài thì output càng tệ. Vì thế anh khuyên implement theo từng phần nhỏ.

Ví dụ bạn có thể gõ "implement T001", hoặc xem chỗ nào hợp lý để ngắt. Phase 3.1 kết thúc ở T005, nên có thể nói "implement T001 to T005", hoặc nói "implement phase 3.1". Leon chọn cách sau và chạy nó (demo trong video đăng ngày 01/10/2025).

12. Implement theo từng phase và test-driven development

Leon tua nhanh qua phần này; về cơ bản anh chấp nhận mọi lệnh và mọi thay đổi agent muốn làm. Agent implement xong mọi thứ trong phase 3.1, đồng thời cập nhật chính file tasks: mỗi task đã làm được đánh dấu X (demo trong video đăng ngày 01/10/2025).

Để dọn context, anh chạy lệnh clear, gọi command implement và gõ "please continue with phase 3.2" (demo trong video đăng ngày 01/10/2025).

Trong lúc agent đang sinh code, anh chỉ một điều. Trong thư mục source giờ có thư mục server chứa logic của các service. Theo Leon (video đăng ngày 01/10/2025), lý do là trong bước constitution hoặc bước planning, ta đã nói rõ muốn mọi logic backend nằm trong thư mục server. Vậy là agent thật sự tuân theo mọi quy tắc ta đặt ra từ đầu.

Một đặc điểm quan trọng khác của Spec Kit, theo Leon (video đăng ngày 01/10/2025), là nó rất "mê" test-driven development, nên bạn sẽ thấy một thư mục test ở đâu đó trong project. Anh giải thích nguyên tắc của test-driven development: trước khi build bất kỳ chức năng nào, bạn build các test sẽ chạy, và ban đầu mọi test đó đều fail. Rồi bạn mới implement chức năng thật để test pass, sau đó mới thêm phần trau chuốt, xử lý exception, cải thiện performance, v.v.

Phase 3.2 xong. Anh clear chat, chạy lại command implement và gõ "Please implement phase 3.3". Agent đã cập nhật mọi task của phase 3.2 trong file (demo trong video đăng ngày 01/10/2025). Leon nói anh thích sự có cấu trúc này: agent biết chính xác phải làm gì, và nếu ta đóng editor ngay bây giờ rồi một tiếng sau mở lại, agent vẫn biết chính xác cần tiếp tục từ đâu (theo video đăng ngày 01/10/2025).

Rồi tới đúng chỗ anh nhắc lúc nãy: agent chạy các testing script để chắc rằng mọi thứ đều fail, sau đó mới bắt đầu implement chức năng thật của ứng dụng (demo trong video đăng ngày 01/10/2025). Theo Leon (video đăng ngày 01/10/2025), nếu bạn thấy cả đống chữ đỏ hiện ra thì điều đó hoàn toàn hợp lệ. Agent còn tự nói đại ý: tốt, các test đang fail đúng như dự kiến vì ta chưa build app thật.

Terminal Claude Code chạy npm test cho contract test, cảnh báo đỏ, và thông báo các test fail đúng như dự kiến cho TDD
Claude Code chạy npm test -- src/__tests__/contract (demo trong video đăng ngày 01/10/2025): cảnh báo cấu hình Jest màu đỏ, rồi dòng "Perfect! The tests are failing as expected for TDD - they can't find the modules because we haven't implemented them yet."

Theo Leon (video đăng ngày 01/10/2025), về cuối phần implement, agent sẽ chạy lại các test này và lần đó chúng sẽ pass. Đó là cách agent biết để chốt (sign off) feature này.

Xong phase đó, lần này anh chỉ gõ "implement", vì đây là một feature tương đối nhỏ (demo trong video đăng ngày 01/10/2025).

Nhân nói về Claude Code CLI bản mới, Leon hỏi bạn có biết là xem được cả usage limit không: vào claude.ai, mở settings, bạn thấy chính xác mình còn bao nhiêu usage trong session hiện tại (theo video đăng ngày 01/10/2025).

Quay lại agent: ban đầu nó chạy các test script, và các script fail vì ta chưa implement logic. Giờ thì mọi logic backend của app đang được build: server action được thêm vào, cùng các client component. Và thế là mọi thứ đã được implement. Leon thấy rất hay: agent báo ứng dụng đã sẵn sàng để test thủ công theo quickstart guide, tức file quickstart ta đã xem lúc nãy, nơi có mọi test scenario và các bước cần làm để test (demo trong video đăng ngày 01/10/2025).

13. Test thủ công app expense tracker

Leon mở app ra xem. Ta có trang Personal Expense Tracker. Anh thử nhập một số tiền, đổi ngày, chọn category và bấm thêm: nó chạy (demo trong video đăng ngày 01/10/2025).

Mở local storage của trình duyệt, ta thấy khoản chi đang được lưu trong local storage. Anh thêm một khoản nữa, và nó cũng chạy, khoản này cũng thuộc Entertainment. Tất nhiên app có phần tổng và phần breakdown theo category (demo trong video đăng ngày 01/10/2025).

App Personal Expense Tracker với form Add Expense, hai khoản chi gần đây và tổng 60 đô la
App Leon build trong demo (video đăng ngày 01/10/2025) chạy ở localhost:3000: form Add Expense (Amount, Date, Category, Description), danh sách "Recent Expenses (Last 30 Days)" với hai khoản $45.00 và $15.00 thuộc Entertainment, ô "Total Expenses (Last 30 Days)" $60.00 và Category Breakdown.

Feature đã chạy, nên anh commit với tên "implement". Theo anh, xét từ góc độ của mình thì feature này đã hoàn chỉnh (demo trong video đăng ngày 01/10/2025).

14. Pull request, merge và sync về master

Leon publish branch này, tức đẩy nó lên GitHub, rồi tạo pull request. Theo anh (video đăng ngày 01/10/2025), nếu bạn dùng Git CLI thì thật ra có thể nhờ agent tạo pull request giúp.

Còn anh làm trên GitHub (demo trong video đăng ngày 01/10/2025):

  • Vào repo trên GitHub, mở Pull requests, tạo một pull request mới để merge feature branch vào branch master (demo trong video đăng ngày 01/10/2025).
  • Đặt cho nó một tiêu đề và mô tả tử tế, ví dụ "create the base app" (demo trong video đăng ngày 01/10/2025).
  • Bấm Create pull request; không có conflict, nên bấm Merge pull request rồi Confirm merge (demo trong video đăng ngày 01/10/2025).
  • Merge đã thành công, nên giờ xoá được branch này, và anh xoá nó. Feature branch không còn trong danh sách, và master đã chứa mọi thay đổi mới (demo trong video đăng ngày 01/10/2025).

Quay lại code editor, anh chuyển branch về master và chạy lệnh sync để kéo mọi thay đổi vừa merge vào master về máy mình. Refresh app thì mọi thứ vẫn chạy (demo trong video đăng ngày 01/10/2025).

master 001-i-would-like: commit từng bước specifyplanimplement PR, merge sync về máy xoá branch sau merge
Hình 14.1Luồng Git Leon dùng trong demo (video đăng ngày 01/10/2025): Spec Kit tạo feature branch, mỗi bước được commit, rồi pull request merge vào master, branch bị xoá và master được sync về máy.

15. Thêm feature mới: budget tracking

Muốn thêm feature thì sao? Theo Leon (video đăng ngày 01/10/2025), việc đó rất dễ: không phải chạy lại constitution, chỉ cần chạy lại specify. Ví dụ ta muốn thêm tính năng ngân sách cho app, thì gõ "please add a budget tracking feature to this app".

Anh bảo hãy để ý chuyện xảy ra khi chạy lại specify. Trước hết, ở góc dưới ta thấy Spec Kit vừa tạo một feature branch mới, nên ta đã rời master và giờ làm việc trong một branch tách biệt, chỉ tập trung vào các tính năng này. Và trong thư mục specs có một thư mục con mang tên branch (demo trong video đăng ngày 01/10/2025).

Claude Code báo Specification completed cho branch 002-please-add-a với danh sách điểm cần làm rõ
Lần chạy specify thứ hai trong demo (video đăng ngày 01/10/2025): branch 002-please-add-a, file spec trong specs/002-please-add-a; agent ghi spec có 13 functional requirement và liệt kê các điểm cần làm rõ như kỳ ngân sách (monthly/weekly/custom), mức chi tiết (tổng hay theo category), cách cảnh báo, giữ lịch sử ngân sách và quy tắc chuyển kỳ, rồi gợi ý chạy /clarify trước khi sang /plan.

Giờ ta chỉ việc chạy lại cả workflow, và mọi file, mọi artifact nó tạo ra sẽ được thêm vào đúng thư mục này. Tất nhiên, sau khi test thay đổi và hài lòng, việc còn lại là tạo pull request đó và merge lại vào main (theo Leon, video đăng ngày 01/10/2025).

Leon kết lại rằng anh thật sự ấn tượng với Spec Kit, và hy vọng sau video này bạn cũng vậy (video đăng ngày 01/10/2025). Anh cảm ơn mọi người đã xem.

Nguồn và liên kết 6 nguồn

  1. Tên gốc: Spec Kit: How to Build Production-Ready Apps with AI Agents
  2. Sự kiện: YouTube
  3. Video gốc: https://www.youtube.com/watch?v=8jtIXRyGMQU youtube.com
  4. Kênh YouTube Leon van Zyl (Leon van Zyl): youtube.com/channel/UCtevzRsHEKhs-RK8pAqwSyQ youtube.com
  5. Repo Spec Kit của GitHub (đọc ngày 12/11/2026; README lúc này mô tả Spec Kit là toolkit open source cho coding agent, cài bằng uv tool install specify-cli rồi specify init, và đặt tên các lệnh dạng /speckit-constitution, /speckit-specify, /speckit-plan, khác với bản Leon dùng trong video đăng ngày 01/10/2025): github.com/github/spec-kit github.com
  6. Hướng dẫn cài uv (đọc ngày 12/11/2026), cần cho lệnh uvx trong video: docs.astral.sh/uv/getting-started/installation docs.astral.sh