Hướng dẫn sử dụng Cafekit ở Haposoft

Vấn đề:

Hiện tại mọi người Vibe Code ra ứng dụng đã trở nên phổ biến. Tuy nhiên Vibe code thì tuỳ hứng, không có kế hoạch rõ ràng khiến về lâu dài hệ thống trở nên khó maintain và lãng phí thời gian.

Bạn: "AI ơi, tạo cho tôi một app todo"
AI: *tạo ra 500 dòng code*
Bạn: "Không, tôi muốn có filter theo ngày"
AI: *viết lại 300 dòng*
Bạn: "Quên mất, cần thêm authentication"
AI: *refactor toàn bộ*

Để giải quyết vấn đề trên, Haposoft release Cafekit theo Spec-Driven Development, chỉnh sửa workflow theo đúng quy trình phát triển phần mềm ở công ty theo 6 bước

1. Định nghĩa Yêu cầu (cái gì) → Requirements
2. Thiết kế hệ thống -> Design
3. Chia nhỏ tasks → Task 
4. Implement từng phần → Code
5. Test lại -> Test
6. Kiểm tra lại kết quả (UAT) -> Review

Cài đặt

Trước khi cài đặt, hãy đảm bảo bạn có:

• Node.js 18+ - Yêu cầu để chạy CLI
• Trợ lý lập trình AI - CafeKit hoạt động với Claude Code hoặc Antigravity
• Model mạnh mẽ - Bắt buộc sử dụng Claude Opus 4.5 (Thinking Mode) để đảm bảo logic tốt nhất cho các kỹ năng lập kế hoạch (spec-*).
• Git - Để quản lý phiên bản và cập nhật
• repomix - Yêu cầu cho lệnh /docs init để gom codebase thành XML cho AI phân tích:

npm install -g repomix
# hoặc: pnpm install -g repomix
# hoặc: yarn global add repomix

Cài đặt Cafekit

npx @haposoft/cafekit

Bộ cài đặt sẽ yêu cầu bạn chọn nền tảng:

? Select your AI coding assistant platform:
  ❯ Claude Code
    Antigravity

Lệnh này sẽ:

• Phát hiện cấu trúc dự án của bạn
• Cài đặt bộ lệnh cốt lõi (/spec-init, /spec-requirements, /spec-design, /spec-tasks, /spec-status, /code, /test, /review)
• Cấu hình workspace cho quy trình phát triển theo spec

Sau khi chạy lệnh cài đặt, bạn sẽ có framework CafeKit trong dự án:

Claude Code

.claude/
├── commands/
│   ├── spec-init.md
│   ├── spec-requirements.md
│   ├── spec-design.md
│   ├── spec-tasks.md
│   ├── spec-status.md
│   ├── code.md
│   ├── test.md
│   ├── review.md
│   └── docs.md
├── agents/
│   ├── tester.md
│   ├── code-reviewer.md
│   ├── fullstack-developer.md
│   └── debugger.md
├── skills/
│   └── specs/
└── ROUTING.md

Antigravity

.agent/
├── workflows/
│   ├── spec-init.md
│   ├── spec-requirements.md
│   ├── spec-design.md
│   ├── spec-tasks.md
│   ├── spec-status.md
│   ├── code.md
│   ├── test.md
│   ├── review.md
│   ├── docs-init.md
│   └── docs-update.md
├── agents/
│   ├── frontend-specialist.md
│   ├── test-engineer.md
│   └── code-archaeologist.md
├── skills/
│   └── specs/
└── rules/
    └── GEMINI.md

Thiết lập Documentation (Chỉ Claude Code)

Sử dụng lệnh /docs để tạo documentation cho dự án:

# Khởi tạo bộ docs nền của dự án
/docs init

# Hoặc cập nhật docs hiện có
/docs update

Lệnh này sẽ tạo:

• File context theo nền tảng (CLAUDE.md hoặc .agent/rules/AGENTS.md)
• Thư mục docs/ với:
  • codebase-summary.md
  • project-overview-pdr.md
  • code-standards.md
  • system-architecture.md
  • design-guidelines.md
  • deployment-guide.md
  • project-roadmap.md

Lưu ý: /docs được cung cấp dưới dạng /docs init và /docs update. Mức độ hoạt động phụ thuộc vào khả năng của môi trường AI và context của dự án.

Xác nhận cài đặt

Mở trợ lý lập trình AI của bạn và gõ lệnh init cho nền tảng tương ứng:

Claude Code hoặc Antigravity gõ

/spec-init

Bạn sẽ thấy workflow khởi tạo spec bắt đầu.

Thử nghiệm nhanh

Trong hướng dẫn này, bạn sẽ tạo một spec cho tính năng đăng nhập người dùng sử dụng tất cả toàn bộ workflow của quy trình CafeKit.

Thời gian hoàn thành: 5-10 phút

Trước khi bắt đầu: Thiết lập Documentation (Tùy chọn)

Để đạt kết quả tốt nhất khi làm việc với AI, nên thiết lập documentation dự án trước. Điều này giúp AI hiểu cấu trúc và quy ước của dự án trước khi bạn bắt đầu tạo spec.

/docs init

Lệnh này sẽ phân tích codebase và tạo:

• Thư mục docs/ với tiêu chuẩn dự án và ngữ cảnh kiến trúc cho AI
• Thư mục docs/ với các tiêu chuẩn coding, kiến trúc và hướng dẫn

Bạn cũng có thể cập nhật docs sau bằng /docs update.

Bước 1: Khởi tạo Spec

Bắt đầu bằng cách tạo một không gian làm việc (workspace) spec mới:

/spec-init login-feature

Chuyện gì xảy ra:

• Tạo thư mục .specs/login-feature/
• Tạo cấu trúc thư mục ban đầu
• Thiết lập các file theo dõi

Kết quả mong đợi:

✅ Spec initialized: login-feature
📁 Created .specs/login-feature/
📄 Next step: Run /spec-requirements

Bước 2: Thu thập yêu cầu

Xác định những gì tính năng của bạn cần làm:

/spec-requirements login-feature

Trợ lý AI sẽ hỏi bạn các câu hỏi như:

• Mục tiêu chính của tính năng này là gì?
  • "Cho phép người dùng đăng nhập bằng email và mật khẩu"
• Ai sẽ sử dụng tính năng này?
  • "Người dùng cuối của ứng dụng"
• Các chức năng bắt buộc là gì?
  • Xác thực email/mật khẩu
  • Quản lý phiên (session)
  • Xử lý lỗi khi thông tin không hợp lệ
• Có ràng buộc hoặc yêu cầu kỹ thuật nào không?
  • Phải hoạt động trên di động và máy tính bàn
  • Sử dụng JWT để xác thực
  • Yêu cầu mật khẩu: tối thiểu 8 ký tự, 1 chữ hoa, 1 số

Chuyện gì xảy ra:

• AI hướng dẫn bạn qua các câu hỏi Socratic
• Ghi lại tất cả yêu cầu chức năng và phi chức năng
• Tạo file requirements.md trong .specs/login-feature/

Kết quả mong đợi:

✅ Requirements captured
📄 Saved to .specs/login-feature/requirements.md
📋 Next step: Run /spec-design

Bước 3: Tạo tài liệu thiết kế

Tạo thiết kế kỹ thuật từ các yêu cầu của bạn:

/spec-design login-feature

Chuyện gì xảy ra:

• AI đọc các yêu cầu của bạn
• Tạo sơ đồ kiến trúc
• Định nghĩa các endpoint API, lược đồ cơ sở dữ liệu (database schema), thành phần UI
• Xác định các trường hợp biên (edge cases) và kịch bản lỗi
• Tạo file design.md

Mẫu kết quả thiết kế:

# Login Feature - Design Document

## Architecture
- Frontend: React login form component
- Backend: POST /api/auth/login endpoint
- Database: users table with hashed passwords

## API Design
POST /api/auth/login
{
  "email": "user@example.com",
  "password": "SecurePass123"
}

## Database Schema
users table:
- id (UUID, primary key)
- email (string, unique)
- password_hash (string)
- created_at (timestamp)

## UI Components
- LoginForm.tsx
- PasswordInput.tsx (with visibility toggle)
- ErrorMessage.tsx

## Security Measures
- bcrypt password hashing
- Rate limiting (5 attempts per minute)
- JWT token expiry (24 hours)

Kết quả mong đợi:

✅ Design document created
📄 Saved to .specs/login-feature/design.md
🎯 Next step: Run /spec-tasks

Bước 4: Tạo danh sách công việc (Task Breakdown)

Chia nhỏ thiết kế thành các task có thể thực hiện được:

/spec-tasks login-feature

Chuyện gì xảy ra:

• AI phân tích tài liệu thiết kế
• Tạo danh sách task được ưu tiên
• Ước lượng thời gian cho từng task
• Xác định sự phụ thuộc giữa các task
• Tạo file tasks.md (kế hoạch sprint)

Mẫu danh sách task:

# Login Feature - Sprint Plan

## TASK 1: Setup Database Schema (30 min)
**Priority:** P0 (Blocker)
**Dependencies:** None

- Create users table migration
- Add email uniqueness constraint
- Test migration rollback

## TASK 2: Implement Password Hashing (45 min)
**Priority:** P0 (Blocker)
**Dependencies:** TASK 1

- Install bcrypt
- Create hashPassword() utility
- Create verifyPassword() utility
- Write unit tests

## TASK 3: Create Login API Endpoint (1 hour)
**Priority:** P0 (Blocker)
**Dependencies:** TASK 1, TASK 2

- POST /api/auth/login route
- Validate email/password
- Generate JWT token
- Handle errors (invalid credentials, rate limiting)

## TASK 4: Build Login Form UI (1 hour)
**Priority:** P1 (High)
**Dependencies:** TASK 3

- Create LoginForm component
- Form validation (email format, password requirements)
- Loading states
- Error message display

Kết quả mong đợi:

✅ Task breakdown created
📄 Saved to .specs/login-feature/tasks.md
🚀 Next step: Run /code login-feature

Bước 5: Thực hiện Task (Implement)

Bắt đầu code dựa trên kế hoạch sprint của bạn:

/code login-feature

Chuyện gì xảy ra:

• AI đọc danh sách task
• Chọn task pending tiếp theo
• Triển khai task đó
• Chuyển sang /test và /review

Mẫu tương tác:

AI: Reading tasks.md for login-feature...
AI: Next pending task is TASK 1: Setup Database Schema
✅ Created migration file: migrations/001_create_users_table.sql
✅ Added email uniqueness constraint
✅ TASK 1 complete
➡️ Next: run /test login-feature
➡️ Then: run /review login-feature

Bước 6: Theo dõi tiến độ

Giám sát trạng thái thực hiện của bạn:

/spec-status login-feature

Chuyện gì xảy ra:

• AI đọc các task đã hoàn thành
• Hiển thị bảng điều khiển tiến độ
• Xác định các vấn đề (blockers) hoặc mục đang chờ xử lý

Mẫu báo cáo trạng thái:

# Login Feature - Status Report

## Progress: 75% (3/4 tasks complete)

✅ TASK 1: Setup Database Schema (DONE)
✅ TASK 2: Implement Password Hashing (DONE)
✅ TASK 3: Create Login API Endpoint (DONE)
⏳ TASK 4: Build Login Form UI (IN PROGRESS)

## Blockers: None

## Next Steps:
- Complete TASK 4 (LoginForm UI)
- Run end-to-end tests
- Deploy to staging

Chúc mừng!

Bạn đã hoàn thành quy trình CafeKit spec đầu tiên. Bạn đã học cách:

• ✅ Khởi tạo spec với /spec-init
• ✅ Thu thập yêu cầu với /spec-requirements
• ✅ Thiết kế kiến trúc với /spec-design
• ✅ Chia nhỏ task với /spec-tasks
• ✅ Triển khai bằng /code
• ✅ Kiểm thử và review bằng /test và /review
• ✅ Theo dõi tiến độ với /spec-status

Khi Nào KHÔNG Nên Dùng Cafekit

CafeKit rất hữu ích, nhưng không phải lúc nào cũng cần thiết. Đây là hướng dẫn giúp bạn quyết định:

❌ KHÔNG cần Cafekit khi:

✅ NÊN dùng CafeKit khi:

Chi tiết hướng dẫn ở : https://cafekit.haposoft.com

Open source: https://github.com/haposoft/cafekit