OpenSpec

Bắt đầu ​

Hướng dẫn này giải thích cách OpenSpec hoạt động sau khi bạn đã cài đặt và khởi tạo nó. Để biết hướng dẫn cài đặt, hãy xem README chính hoặc Hướng dẫn Cài đặt. Bạn mới làm quen với toàn bộ tài liệu? Trang chủ tài liệu cung cấp bản đồ tổng quan cho mọi thứ.

Bạn gõ những lệnh này ở đâu? Ở hai nơi, và việc nhầm lẫn giữa chúng là lỗi phổ biến nhất trong giai đoạn đầu.

  • Các lệnh openspec ... (như openspec init) chạy trong terminal của bạn.
  • Các lệnh /opsx:... (như /opsx:propose) chạy trong trò chuyện của trợ lý AI, cùng khung đó nơi bạn yêu cầu nó viết mã.

Không có chế độ "tương tác" riêng biệt để bắt đầu. Bạn chỉ cần gõ lệnh slash trong cuộc trò chuyện và trợ lý sẽ xử lý các bước tiếp theo. Giải thích chi tiết: Cách Lệnh Hoạt Động.

Năm phút đầu tiên của bạn ​

Toàn bộ vòng lặp, với mỗi bước được gắn nhãn vị trí thực hiện:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (tùy chọn: suy nghĩ kỹ trước)
AI CHAT      /opsx:propose add-dark-mode      (AI soạn thảo kế hoạch; bạn xem xét lại)
AI CHAT      /opsx:apply                      (AI xây dựng nó)
AI CHAT      /opsx:archive                    (các đặc tả đã cập nhật, thay đổi được lưu trữ)

Hai bước terminal để thiết lập, sau đó bạn làm việc chủ yếu trong cuộc trò chuyện. Phần còn lại của hướng dẫn này sẽ giải thích chi tiết từng bước thực hiện và những gì bạn sẽ thấy.

Không muốn tự làm phần terminal? Dán lời nhắc thiết lập vào trợ lý của bạn và nó sẽ xử lý cả hai dòng, sau đó báo cáo những gì nó đã tạo ra.

Chưa chắc chắn nên xây dựng gì? Hãy bắt đầu với /opsx:explore. Đây là một đối tác tư duy không áp lực, đọc cơ sở mã của bạn, cân nhắc các tùy chọn và tinh chỉnh một ý tưởng mơ hồ thành một kế hoạch cụ thể, tất cả trước khi bất kỳ tài liệu nào hoặc mã nguồn được tạo ra. Khi bức tranh trở nên rõ ràng, nó sẽ chuyển giao cho /opsx:propose. Đây là thói quen tốt nhất để làm việc với một trợ lý AI, người nếu không sẽ tự tin xây dựng sai thứ. Xem Hướng dẫn Khám phá.

Cách hoạt động ​

OpenSpec giúp bạn và trợ lý lập trình AI của bạn thống nhất về những gì cần xây dựng trước khi bất kỳ mã nào được viết.

Đường dẫn nhanh mặc định (hồ sơ cốt lõi):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (tùy chọn)

Bắt đầu với /opsx:explore khi bạn đang xác định những gì cần làm, hoặc nhảy thẳng vào /opsx:propose khi bạn đã biết rõ. Explore nằm trong hồ sơ mặc định, vì vậy nó luôn sẵn sàng khi bạn cần.

Đường dẫn mở rộng (lựa chọn quy trình làm việc tùy chỉnh):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Hồ sơ toàn cầu mặc định là core, bao gồm propose, explore, apply, update, sync, và archive. Bạn có thể kích hoạt các lệnh quy trình làm việc mở rộng bằng cách sử dụng openspec config profile và sau đó là openspec update.

OpenSpec tạo ra những gì ​

Sau khi chạy openspec init, dự án của bạn có cấu trúc như sau:

openspec/
├── specs/              # Nguồn sự thật (hành vi của hệ thống của bạn)
│   └── <domain>/
│       └── spec.md
├── changes/            # Các đề xuất cập nhật (một thư mục cho mỗi thay đổi)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Đặc tả delta (những gì đang thay đổi)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Cấu hình dự án (tùy chọn)

Hai thư mục quan trọng:

  • specs/ - Nguồn sự thật. Các đặc tả này mô tả hành vi hiện tại của hệ thống của bạn. Được tổ chức theo miền (ví dụ: specs/auth/, specs/payments/).

  • changes/ - Các sửa đổi được đề xuất. Mỗi thay đổi có thư mục riêng với tất cả các tài liệu liên quan. Khi một thay đổi hoàn tất, các đặc tả của nó sẽ hợp nhất vào thư mục specs/ chính.

Hiểu về các Tài liệu (Artifacts) ​

Mỗi thư mục thay đổi chứa các tài liệu hướng dẫn công việc:

Tài liệuMục đích
proposal.mdLý do "tại sao" và "cái gì" - nắm bắt ý định, phạm vi và phương pháp
specs/Các đặc tả delta hiển thị các yêu cầu ĐÃ THÊM/ĐÃ SỬA ĐỔI/ĐÃ XÓA BỎ
design.mdCách "làm thế nào" - phương pháp tiếp cận kỹ thuật và các quyết định kiến trúc
tasks.mdDanh sách kiểm tra triển khai với các hộp kiểm

Các tài liệu hỗ trợ lẫn nhau:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            cập nhật khi bạn học hỏi thêm

Bạn luôn có thể quay lại và tinh chỉnh các tài liệu sớm hơn khi bạn hiểu rõ hơn trong quá trình triển khai.

Cách các Đặc tả Delta hoạt động ​

Các đặc tả delta là khái niệm then chốt trong OpenSpec. Chúng hiển thị những gì đang thay đổi so với các đặc tả hiện tại của bạn.

Định dạng ​

Các đặc tả delta sử dụng các phần để chỉ định loại thay đổi:

markdown
# Delta cho Auth

## Yêu cầu ĐÃ THÊM

### Yêu cầu: Xác thực hai yếu tố
Hệ thống PHẢI yêu cầu một yếu tố thứ hai trong quá trình đăng nhập.

#### Kịch bản: Yêu cầu OTP
- GIVEN một người dùng đã bật 2FA
- WHEN người dùng gửi thông tin đăng nhập hợp lệ
- THEN một thách thức OTP được hiển thị

## Yêu cầu ĐÃ SỬA ĐỔI

### Yêu cầu: Hết hạn phiên
Hệ thống SẼ hết hạn các phiên sau 30 phút không hoạt động.
(Trước đây: 60 phút)

#### Kịch bản: Hết hạn khi nhàn rỗi
- GIVEN một phiên đã xác thực
- WHEN 30 phút trôi qua mà không có hoạt động
- THEN phiên bị vô hiệu hóa

## Yêu cầu ĐÃ XÓA BỎ

### Yêu cầu: Ghi nhớ tôi
(Đã lỗi thời để ưu tiên cho 2FA)

Điều gì xảy ra khi Lưu trữ (Archive) ​

Khi bạn lưu trữ một thay đổi:

  1. Các yêu cầu ĐÃ THÊM được nối vào đặc tả chính
  2. Các yêu cầu ĐÃ SỬA ĐỔI thay thế phiên bản hiện có
  3. Các yêu cầu ĐÃ XÓA BỎ bị xóa khỏi đặc tả chính

Thư mục thay đổi được di chuyển đến openspec/changes/archive/ để lưu lịch sử kiểm toán.

Ví dụ: Thay đổi đầu tiên của bạn ​

Hãy cùng đi qua việc thêm chế độ tối (dark mode) vào một ứng dụng.

1. Bắt đầu Thay đổi (Mặc định) ​

text
Bạn: /opsx:propose add-dark-mode

AI:  Đã tạo openspec/changes/add-dark-mode/
     ✓ proposal.md — lý do chúng ta làm điều này, những gì đang thay đổi
     ✓ specs/       — yêu cầu và kịch bản
     ✓ design.md    — phương pháp tiếp cận kỹ thuật
     ✓ tasks.md     — danh sách kiểm tra triển khai
     Sẵn sàng cho triển khai!

Nếu bạn đã kích hoạt hồ sơ quy trình làm việc mở rộng, bạn cũng có thể thực hiện điều này dưới dạng hai bước: /opsx:new sau đó là /opsx:ff (hoặc /opsx:continue theo từng bước).

2. Những gì được tạo ra ​

proposal.md - Nắm bắt ý định:

markdown
# Đề xuất: Thêm Chế độ Tối

## Ý định
Người dùng đã yêu cầu một tùy chọn chế độ tối để giảm mỏi mắt
trong quá trình sử dụng ban đêm.

## Phạm vi
- Thêm nút chuyển đổi chủ đề trong cài đặt
- Hỗ trợ phát hiện sở thích hệ thống
- Lưu trữ sở thích trong localStorage

## Phương pháp tiếp cận
Sử dụng các thuộc tính tùy chỉnh CSS cho chủ đề với React context
để quản lý trạng thái.

specs/ui/spec.md - Delta hiển thị các yêu cầu mới:

markdown
# Delta cho UI

## Yêu cầu ĐÃ THÊM

### Yêu cầu: Chọn Chủ đề
Hệ thống SẼ cho phép người dùng chọn giữa các chủ đề sáng và tối.

#### Kịch bản: Chuyển đổi thủ công
- GIVEN một người dùng trên bất kỳ trang nào
- WHEN người dùng nhấp vào nút chuyển đổi chủ đề
- THEN chủ đề chuyển đổi ngay lập tức
- VÀ sở thích được lưu trữ xuyên suốt các phiên

#### Kịch bản: Sở thích hệ thống
- GIVEN một người dùng chưa có sở thích đã lưu
- WHEN ứng dụng tải lên
- THEN sơ đồ màu ưu tiên của hệ thống được sử dụng

tasks.md - Danh sách kiểm tra triển khai:

markdown
# Nhiệm vụ

## 1. Cơ sở hạ tầng Chủ đề
- [ ] 1.1 Tạo ThemeContext với trạng thái sáng/tối
- [ ] 1.2 Thêm các thuộc tính tùy chỉnh CSS cho màu sắc
- [ ] 1.3 Triển khai lưu trữ trong localStorage

## 2. Thành phần Giao diện Người dùng
- [ ] 2.1 Tạo thành phần ThemeToggle
- [ ] 2.2 Thêm nút chuyển đổi vào trang cài đặt
- [ ] 2.3 Cập nhật Header để bao gồm nút chuyển đổi nhanh

## 3. Kiểu dáng
- [ ] 3.1 Xác định bảng màu cho chủ đề tối
- [ ] 3.2 Cập nhật các thành phần để sử dụng biến CSS

3. Triển khai ​

Bạn: /opsx:apply

AI:  Đang xử lý các nhiệm vụ...
     ✓ 1.1 Đã tạo ThemeContext với trạng thái sáng/tối
     ✓ 1.2 Đã thêm các thuộc tính tùy chỉnh CSS vào globals.css
     ✓ 1.3 Đã triển khai lưu trữ trong localStorage
     ✓ 2.1 Đã tạo thành phần ThemeToggle
     ...
     Tất cả nhiệm vụ hoàn tất!

Trong quá trình triển khai, nếu bạn phát hiện ra rằng thiết kế cần điều chỉnh, chỉ cần cập nhật tài liệu và tiếp tục.

4. Lưu trữ ​

Bạn: /opsx:archive

AI:  Đang lưu trữ add-dark-mode...
     ✓ Đã hợp nhất các đặc tả vào openspec/specs/ui/spec.md
     ✓ Đã di chuyển đến openspec/changes/archive/2025-01-24-add-dark-mode/
     Hoàn tất! Sẵn sàng cho tính năng tiếp theo.

Các đặc tả delta của bạn bây giờ đã là một phần của các đặc tả chính, ghi lại cách hệ thống của bạn hoạt động.

Xác minh và Xem xét ​

Sử dụng CLI để kiểm tra các thay đổi của bạn:

bash
# Liệt kê các thay đổi đang hoạt động
openspec list

# Xem chi tiết thay đổi
openspec show add-dark-mode

# Xác thực định dạng đặc tả
openspec validate add-dark-mode

# Bảng điều khiển tương tác
openspec view

Các bước tiếp theo ​