1. Bối cảnh & Động lực
Trong quá trình phát triển phần mềm, việc duy trì tài liệu nhất quán giữa tài liệu kỹ thuật, mã nguồn và quy trình nghiệp vụ luôn là một thách thức. Khi mình phát hiện OpenSpec của Fission AI — một mô hình “Phát triển dựa trên Đặc tả” (Spec-Driven Development) mô tả logic, domain,... dưới dạng Spec có cấu trúc — mình đã ngay lập tức muốn thử để xem nó có thể giúp AI tự động sinh ra đặc tả + checklist hiệu quả đến đâu.
Mình đã sử dụng Claude Code với một prompt để tạo trang quản lý Tin tức, kỳ vọng rằng chỉ với một mô tả đơn giản, hệ thống có thể tạo ra một đặc tả clear, tuân thủ các nguyên tắc code yêu cầu, sẵn sàng cho việc triển khai code nhanh chóng.
2. Mục tiêu
Mục tiêu của thử nghiệm này: Sử dụng [https://github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) để:
* Viết một prompt đơn giản mô tả yêu cầu API To-Do List.
* Dùng OpenSpec để AI tự động sinh ra một feature.
* Kiểm tra xem đặc tả sinh ra có sạch, logic và dễ triển khai không.
* Trải nghiệm quy trình: Prompt → Spec → Triển khai code.
* Ghi nhận ưu/nhược điểm khi dùng OpenSpec với AI (Claude Code).
3. Công cụ sử dụng
* OpenSpec (Fission-AI/OpenSpec) – Framework mô tả logic domain dưới dạng Spec có cấu trúc.
* Claude Code Pro: Mô hình AI mình tin dùng cho việc giảm "code toàn bug" hiện tại. (hahaha)
4. Các bước thực hiện
Bước 1 — Chuẩn bị Prompt & Gửi đến Claude Code CLI
Prompt:
/openspec:proposal
Bạn là chuyên gia Frontend. Hãy dùng Openspec để sinh ra document cho chức năng sau. Yêu cầu:
- Quản lý Tin tức:
Tin tức gồm các trường:
- id, name, description, image
Các page:
- danh sách tin tức
trong từng Item list có các action như xem detail, xóa tin tức
- tạo tin tức:
có button tạo tin tức, click vào sẽ đi đến màn hình tạo
- chi tiết tin tức:
có thể xem chi tiết cũng như chỉnh sửa, xóa tin tức
- Sử dụng cấu trúc FSD, UI sử dụng tailwind css, có thể responsive
Bước 2 — Gửi Prompt yêu cầu đến Claude code
Sau khi Claude Code nhận yêu cầu và phân tích thì sẽ sinh **Feature** theo cấu trúc thư mục dưới đây:
└── 📁openspec
└── 📁changes
└── 📁add-news-management
└── 📁specs
└── 📁news-create
├── spec.md
└── 📁news-detail
├── spec.md
└── 📁news-list
├── spec.md
├── design.md
├── proposal.md
└── tasks.md
Giải thích:
| Thư mục / File | Vai trò |
|---|---|
openspec/changes/ |
Chứa các đề xuất tính năng/change proposal đang được làm việc |
add-news-management/ |
Một proposal cụ thể cho tính năng quản lý tin |
proposal.md |
Mô tả mục tiêu và phạm vi thay đổi |
design.md |
Giải thích các quyết định kỹ thuật |
tasks.md |
Checklist các task để AI/dev thực hiện code |
specs/.../spec.md |
Các spec delta cho từng phần chức năng nhỏ |
Bước 3 — Rà soát & Điều chỉnh
Chúng ta cần xem lại đặc tả sinh ra trong `spec.md` và các task trong `tasks.md`.
`proposal.md` lưu các đề xuất thay đổi và ảnh hưởng đến codebase hiện tại.
So sánh với tài liệu được sinh ra bởi OpenSpec và yêu cầu thực tế, sau đó chỉnh sửa lại nếu có điểm chưa đúng.
Bước 4 — Triển khai - thực thi code
Dùng lệnh `\openspec:apply` để áp dụng đặc tả vào dự án hiện tại.
5. Kết quả
Kết quả triển khai:
* Một Feature OpenSpec hoàn chỉnh, có thể tích hợp vào bất kỳ dự án nào.
* Đặc tả rõ ràng, dễ đọc, phản ánh đúng domain To-Do List.
* Thời gian từ prompt → spec: chỉ khoảng ~1 phút.
* Giao diện tạo ra từ spec đúng như mong muốn.
Demo UI được sinh ra tự động
Kết quả mình chỉ tốn có 5 phút chờ đợi và kết quả cũng khá đúng với yêu cầu mình đưa ra.
Danh sách tin tức
Tạo tin tức
Chi tiết tin tức
Sửa tin tức
6. Thách thức
Nếu prompt thiếu chi tiết, Claude Code có thể “đoán” và sinh thêm logic ngoài ý muốn.
Token sử dụng tăng nếu không kiểm tra lại spec trước khi sinh code.
7. Tổng kết
* Việc sử dụng OpenSpec để viết logic code cần sinh ra rất có lợi đối với những feature lớn, nó giúp chúng ta kiểm soát được rủi ro, code sinh ra như mong muốn.
* Prompt càng cụ thể, spec càng sạch.
* OpenSpec giúp giảm đáng kể thời gian viết tài liệu triển khai.
* Có thể kiểm xoát được những gì AI làm.
Tham khảo
Fission-AI
