OpenSpec – How to prompt with better accuracy and more spec driven

1️⃣ Vì sao OpenSpec quan trọng với AI coding?

AI coding assistants không “đọc được suy nghĩ” của bạn. Chúng chỉ dựa vào prompt bạn đưa ra và context có sẵn.

Prompt mơ hồ hoặc chỉ mô tả chung chung → AI đoán mò, code không đúng business rule, thiếu edge case hoặc không khớp architecture.

OpenSpec giải quyết vấn đề này bằng cách biến prompt thành một specification rõ ràng, có cấu trúc (thường là file Markdown) trước khi AI sinh code.

Kết quả:

• AI hiểu chính xác những gì cần build
• Dev dễ review
• Tránh những sự assumption đến từ phía AI
• Code nhất quán và dễ review hơn

OpenSpec hoạt động tốt với hầu hết các AI coding tool hiện nay mà không cần API key phức tạp.

2️⃣ Prompt thông thường vs Prompt theo OpenSpec

Ví dụ prompt yếu (thông thường):

[BE] Update relationship: 1 project can have many quotes
Description

Ensure one project can be linked to multiple quotes
Update Project entity to include quotes relationship

AI có thể thiếu update rất nhiều chỗ, bị miss migration, có thể sẽ ko chú ý đến FE mà chỉ focus vào BE. Kể cả dù ở plan mode nhiều AI cx có thể bị missed.

Prompt tốt hơn theo OpenSpec (Proposal phase):

Proposal: Update relationship – One project can have many quotes

### Requirement: Project-Quotes 1:N relationship

The system SHALL support linking multiple quotes to a single project.

#### Scenario: Retrieving quotes for a project

- **WHEN** a user requests quotes linked to a project
- **THEN** the system returns all active quotes where projectId matches the project

#### Scenario: Assigning quote to project

- **WHEN** a user assigns an existing quote to a project
- **THEN** the quote's projectId is updated and the relationship is persisted

#### Scenario: Listing project with quotes collection

- **WHEN** a user retrieves a project
- **THEN** the system includes the quotes collection in the response

### Requirement: Backward compatibility

The system SHALL maintain backward compatibility with existing quoteId references.

#### Scenario: Existing project with quoteId

- **WHEN** a project has a legacy quoteId value
- **THEN** the system continues to return quoteId in responses for backward compatibility

#### Scenario: Filtering projects by quoteId

- **WHEN** a user queries projects by a specific quote ID
- **THEN** the system returns matching projects based on quote relationship

Với Proposal có cấu trúc như vậy, AI sẽ hiểu rõ ngữ cảnh, sinh code chính xác và ít phải sửa lại hơn nhiều.

3️⃣ Viết Specification (Spec) trước khi yêu cầu code

OpenSpec khuyến khích bạn (hoặc để AI hỗ trợ draft) viết spec đầy đủ trước.

Khi dùng lệnh /opsx-propose <idea> => AI sẽ giúp mình generate ra 4 item là

design.md
proposal.md
specs
tasks.md

Và mình sẽ đọc và xem xem spec đã ổn hay chưa.

Một spec tốt thường bao gồm:

• Mô tả tổng quát tính năng
• Business rules & constraints
• Input/Output cụ thể
• Edge cases cần xử lý
• Tasks chi tiết step by step dễ theo dõi
• Kiến trúc & style yêu cầu (ví dụ: follow existing coding standard)

Chỉ khi đã có spec rõ ràng, bạn mới chuyển sang bước Apply — yêu cầu AI implement theo đúng spec đó.

Cách này giúp AI không còn “tự do sáng tạo” theo kiểu vibe coding nữa.

4️⃣ Prompt theo từng bước nhỏ theo OpenSpec workflow

Lỗi phổ biến là đưa toàn bộ tính năng lớn vào một prompt duy nhất.

OpenSpec có workflow đơn giản: Proposal → Apply → Archive

• Proposal: Viết spec chi tiết
• Apply: Yêu cầu AI code theo spec (có thể chia thành nhiều task nhỏ)
• Archive: Lưu spec lại để sau này reference hoặc update

Ví dụ chia nhỏ:

• Task 1: Implement login validation theo spec
• Task 2: Implement password reset flow
• Task 3: Write unit tests cho cả hai

Chia nhỏ giúp kiểm soát tốt hơn, giảm lỗi và dễ debug

Đồng thời theo setup của Opec Spec thì /opsx-apply sẽ không 1 lúc apply hết tất cả các task mà sẽ theo từng phần. Khiến cho mình có khả năng debug dễ hơn và dễ review hơn. Tránh trường hợp AI generate quá nhiều khiến người review bị overwhelmed.

5️⃣ Cách cài đặt open-spec

Cài đặt OpenSpec rất đơn giản và nhanh chóng, chỉ mất vài phút. OpenSpec là một công cụ CLI mã nguồn mở, hoạt động tốt với hầu hết các AI coding tools hiện nay (Cursor, Claude Code, Copilot Chat, Windsurf…).

Yêu cầu trước khi cài:

• Node.js phiên bản 20.19.0 trở lên (Kiểm tra bằng lệnh: node –version)

Cài đặt OpenSpec toàn cục:

Bash

npm install -g @fission-ai/openspec@latest

Hoặc nếu bạn dùng pnpm/yarn/bun:

Bash

pnpm add -g @fission-ai/openspec@latest
# hoặc
yarn global add @fission-ai/openspec@latest

Khởi tạo OpenSpec trong dự án:

Sau khi cài xong, di chuyển vào thư mục dự án và chạy:

Bash

cd your-project
openspec init

Lúc này OpenSpec sẽ hỏi bạn:

• Chọn AI tool bạn đang dùng (Cursor, Claude, v.v.)

Sau khi init xong, OpenSpec sẽ tạo thư mục .openspec/ và các file hướng dẫn cần thiết trong dự án của bạn.

Sau khi reboot lại AI ide thì sẽ dùng đc.

Kiểm tra cài đặt:

Bash

openspec --version

Cập nhật OpenSpec sau này:

Bash

npm install -g @fission-ai/openspec@latest
openspec update

Với OpenSpec đã cài đặt và init, bạn có thể bắt đầu ngay workflow Proposal → Apply → Archive một cách mượt mà.

Kết luận

OpenSpec biến AI coding từ “vibe coding” thành spec-driven development thực thụ.

Thay vì prompt và tin tưởng AI tự giúp bạn xử lí, bạn tạo specification rõ ràng trước, sau đó để AI implement theo đó.

Để dùng OpenSpec hiệu quả:

• Viết Proposal/spec chi tiết trước bằng open-spec
• Luôn review và spec, tasks, design và visualize task để dễ hình dung.
• Luôn test lại mọi thứ sau khi apply xong.
• Sử dụng workflow Proposal → Apply → Archive

Khi bạn master cách “spec-driven prompting”, AI sẽ trở thành một người pair programmer đáng tin cậy, code chính xác và ít phải sửa lại hơn rất nhiều.