Các khái niệm
Hướng dẫn này giải thích các ý tưởng cốt lõi của OpenSpec và cách chúng kết hợp với nhau. Để biết cách sử dụng thực tế, hãy xem Bắt đầu và Quy trình làm việc.
Triết lý
OpenSpec được xây dựng dựa trên bốn nguyên tắc:
linh hoạt chứ không cứng nhắc — không có các cửa pha (phase gates), tập trung vào những gì hợp lý
lặp lại chứ không theo kiểu thác nước — học hỏi trong khi xây dựng, tinh chỉnh dần dần
dễ dàng chứ không phức tạp — thiết lập nhẹ nhàng, ít thủ tục rườm rà
ưu tiên hệ thống hiện hữu — hoạt động tốt với các cơ sở mã hiện có, không chỉ dành cho dự án mớiTại sao các nguyên tắc này quan trọng
Linh hoạt chứ không cứng nhắc. Các hệ thống đặc tả truyền thống thường khóa bạn vào các giai đoạn cố định: trước tiên bạn lên kế hoạch, sau đó triển khai, và cuối cùng là hoàn tất. OpenSpec linh hoạt hơn — bạn có thể tạo các sản phẩm phụ (artifacts) theo bất kỳ thứ tự nào phù hợp với công việc của mình.
Lặp lại chứ không theo kiểu thác nước. Yêu cầu thay đổi. Sự hiểu biết ngày càng sâu sắc. Những gì ban đầu có vẻ là một phương pháp tiếp cận tốt có thể không còn phù hợp sau khi bạn xem xét cơ sở mã. OpenSpec chấp nhận thực tế này.
Dễ dàng chứ không phức tạp. Một số khung đặc tả yêu cầu thiết lập rộng rãi, định dạng cứng nhắc hoặc quy trình nặng nề. OpenSpec không cản trở công việc của bạn. Khởi tạo trong vài giây, bắt đầu làm việc ngay lập tức, và chỉ tùy chỉnh khi cần.
Ưu tiên hệ thống hiện hữu. Phần lớn công việc phát triển phần mềm không phải là xây dựng từ đầu mà là sửa đổi các hệ thống hiện có. Cách tiếp cận dựa trên sự khác biệt (delta-based) của OpenSpec giúp dễ dàng mô tả các thay đổi đối với hành vi hiện có, chứ không chỉ mô tả các hệ thống mới.
Bức Tranh Tổng Thể
OpenSpec tổ chức công việc của bạn thành hai khu vực chính:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Nguồn sự thật │◄─────│ Thay đổi đề xuất │ │
│ │ Cách hệ thống của │ hợp nhất│ Mỗi thay đổi = một thư mục│ │
│ │ bạn hiện đang │ │ Chứa các tài liệu và đặc │ │
│ │ hoạt động │ │ tả delta │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs là nguồn sự thật — chúng mô tả cách hệ thống của bạn hiện đang hoạt động.
Changes là các thay đổi được đề xuất — chúng nằm trong các thư mục riêng biệt cho đến khi bạn sẵn sàng hợp nhất.
Sự tách biệt này rất quan trọng. Bạn có thể làm việc trên nhiều thay đổi song song mà không xảy ra xung đột. Bạn có thể xem xét một thay đổi trước khi nó ảnh hưởng đến các spec chính. Và khi bạn lưu trữ một thay đổi, các delta của nó sẽ hợp nhất sạch sẽ vào nguồn sự thật.
Specs
Specs mô tả hành vi của hệ thống sử dụng các yêu cầu và tình huống có cấu trúc.
Cấu trúc
openspec/specs/
├── auth/
│ └── spec.md # Hành vi xác thực
├── payments/
│ └── spec.md # Xử lý thanh toán
├── notifications/
│ └── spec.md # Hệ thống thông báo
└── ui/
└── spec.md # Hành vi và chủ đề giao diệnTổ chức các spec theo lĩnh vực — các nhóm hợp lý phù hợp với hệ thống của bạn. Các mẫu phổ biến:
- Theo khu vực tính năng:
auth/,payments/,search/ - Theo thành phần:
api/,frontend/,workers/ - Theo ngữ cảnh giới hạn:
ordering/,fulfillment/,inventory/
Định dạng Spec
Một spec chứa các yêu cầu và mỗi yêu cầu có các tình huống:
# Đặc tả Xác thực
## Mục đích
Quản lý xác thực và phiên cho ứng dụng.
## Yêu cầu
### Yêu cầu: Xác thực người dùng
Hệ thống SHALL phát hành một token JWT khi đăng nhập thành công.
#### Tình huống: Thông tin xác thực hợp lệ
- GIVEN người dùng có thông tin xác thực hợp lệ
- WHEN người dùng gửi biểu mẫu đăng nhập
- THEN một token JWT được trả về
- AND người dùng được chuyển hướng đến bảng điều khiển
#### Tình huống: Thông tin xác thực không hợp lệ
- GIVEN thông tin xác thực không hợp lệ
- WHEN người dùng gửi biểu mẫu đăng nhập
- THEN một thông báo lỗi được hiển thị
- AND không có token nào được phát hành
### Yêu cầu: Hết hạn phiên
Hệ thống MUST hết hạn phiên sau 30 phút không hoạt động.
#### Tình huống: Hết thời gian chờ
- GIVEN một phiên đã được xác thực
- WHEN 30 phút trôi qua không có hoạt động
- THEN phiên bị vô hiệu hóa
- AND người dùng phải xác thực lạiCác yếu tố chính:
| Yếu tố | Mục đích |
|---|---|
## Mục đích | Mô tả cấp cao về lĩnh vực của spec này |
### Yêu cầu: | Một hành vi cụ thể mà hệ thống phải có |
#### Tình huống: | Một ví dụ cụ thể về yêu cầu đang hoạt động |
| SHALL/MUST/SHOULD | Các từ khóa RFC 2119 chỉ ra mức độ yêu cầu |
Tại sao lại cấu trúc spec theo cách này
Yêu cầu là "cái gì" — chúng nêu hệ thống nên làm gì mà không chỉ định cách thực hiện.
Tình huống là "khi nào" — chúng cung cấp các ví dụ cụ thể có thể kiểm chứng. Các tình huống tốt:
- Có thể kiểm thử (bạn có thể viết một bài kiểm thử tự động cho chúng)
- Bao gồm cả đường dẫn vui vẻ và các trường hợp biên
- Sử dụng Given/When/Then hoặc định dạng có cấu trúc tương tự
Các từ khóa RFC 2119 (SHALL, MUST, SHOULD, MAY) truyền đạt ý định:
- MUST/SHALL — yêu cầu tuyệt đối
- SHOULD — được khuyến nghị, nhưng vẫn có ngoại lệ
- MAY — tùy chọn
Spec là gì (và không phải là gì)
Spec là một hợp đồng hành vi, không phải là một kế hoạch thực hiện.
Nội dung spec tốt:
- Hành vi có thể quan sát mà người dùng hoặc hệ thống hạ nguồn dựa vào
- Đầu vào, đầu ra và các điều kiện lỗi
- Các ràng buộc bên ngoài (bảo mật, quyền riêng tư, độ tin cậy, khả năng tương thích)
- Các tình huống có thể kiểm thử hoặc xác thực rõ ràng
Tránh trong spec:
- Tên lớp/hàm nội bộ
- Lựa chọn thư viện hoặc framework
- Chi tiết triển khai từng bước
- Kế hoạch thực hiện chi tiết (những thứ đó thuộc về
design.mdhoặctasks.md)
Kiểm tra nhanh:
- Nếu việc triển khai có thể thay đổi mà không làm thay đổi hành vi có thể quan sát bên ngoài, thì điều đó có lẽ không thuộc về spec.
Giữ nhẹ nhàng: Mức độ nghiêm ngặt tiến triển
OpenSpec nhằm tránh quan liêu. Sử dụng mức độ nhẹ nhất vẫn làm cho thay đổi có thể kiểm chứng.
Spec nhẹ (mặc định):
- Các yêu cầu ngắn gọn hướng hành vi
- Phạm vi và những gì không làm rõ ràng
- Một vài điểm kiểm tra chấp nhận cụ thể
Spec đầy đủ (cho rủi ro cao hơn):
- Thay đổi liên đội hoặc liên kho lưu trữ
- Thay đổi API/hợp đồng, di chuyển, các vấn đề bảo mật/quyền riêng tư
- Thay đổi mà sự mơ hồ có thể dẫn đến làm lại tốn kém
Hầu hết các thay đổi nên ở chế độ Nhẹ.
Cộng tác giữa Con người và Tác nhân
Trong nhiều đội, con người khám phá và tác nhân soạn thảo các tài liệu. Vòng lặp dự kiến là:
- Con người cung cấp ý định, ngữ cảnh và ràng buộc.
- Tác nhân chuyển đổi điều này thành các yêu cầu và tình huống hướng hành vi.
- Tác nhân giữ chi tiết triển khai trong
design.mdvàtasks.md, không phảispec.md. - Xác thực xác nhận cấu trúc và sự rõ ràng trước khi triển khai.
Điều này giữ cho spec dễ đọc đối với con người và nhất quán đối với tác nhân.
Changes
Một thay đổi là một sửa đổi được đề xuất cho hệ thống của bạn, được đóng gói dưới dạng một thư mục với mọi thứ cần thiết để hiểu và triển khai nó.
Cấu trúc Thay đổi
openspec/changes/add-dark-mode/
├── proposal.md # Tại sao và cái gì
├── design.md # Cách thực hiện (phương pháp kỹ thuật)
├── tasks.md # Danh sách kiểm tra triển khai
├── .openspec.yaml # Metadata thay đổi (tùy chọn): schema, created, skip_specs, retire_capabilities
└── specs/ # Các đặc tả delta
└── ui/
└── spec.md # Những gì đang thay đổi trong ui/spec.mdMỗi thay đổi là khép kín. Nó có:
- Tài liệu — các tài liệu nắm bắt ý định, thiết kế và nhiệm vụ
- Đặc tả delta — các đặc tả cho những gì đang được thêm vào, sửa đổi hoặc loại bỏ
- Metadata — cấu hình tùy chọn cho thay đổi cụ thể này
Tại sao các thay đổi là thư mục
Đóng gói một thay đổi dưới dạng thư mục có một số lợi ích:
Mọi thứ cùng nhau. Đề xuất, thiết kế, nhiệm vụ và spec nằm cùng một chỗ. Không phải tìm kiếm khắp các vị trí khác nhau.
Làm việc song song. Nhiều thay đổi có thể tồn tại đồng thời mà không xung đột. Làm việc trên
add-dark-modetrong khifix-auth-bugcũng đang được tiến hành.Lịch sử sạch sẽ. Khi được lưu trữ, các thay đổi di chuyển vào
changes/archive/với toàn bộ ngữ cảnh được bảo tồn. Bạn có thể nhìn lại và hiểu không chỉ những gì đã thay đổi, mà cả tại sao.Thân thiện với việc xem xét. Một thư mục thay đổi rất dễ xem xét — mở nó, đọc đề xuất, kiểm tra thiết kế, xem các đặc tả delta.
Tài liệu
Tài liệu là các tài liệu trong một thay đổi hướng dẫn công việc.
Luồng tài liệu
đề xuất ──────► specs ──────► thiết kế ──────► nhiệm vụ ──────► triển khai
│ │ │ │
tại sao cái gì cách thực hiện các bước
+ phạm vi thay đổi phương pháp cần thực hiệnCác tài liệu xây dựng dựa trên nhau. Mỗi tài liệu cung cấp ngữ cảnh cho tài liệu tiếp theo.
Các loại tài liệu
Đề xuất (proposal.md)
Đề xuất nắm bắt ý định, phạm vi và phương pháp ở cấp độ cao.
# Đề 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
khi sử dụng vào ban đêm và khớp với tùy chọn hệ thống.
## Phạm vi
Trong phạm vi:
- Chuyển đổi chủ đề trong cài đặt
- Phát hiện tùy chọn hệ thống
- Lưu trữ tùy chọn trong localStorage
Ngoài phạm vi:
- Chủ đề màu tùy chỉnh (công việc trong tương lai)
- Ghi đè chủ đề theo từng trang
## Phương pháp
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. Phát hiện tùy chọn hệ thống khi tải lần đầu,
cho phép ghi đè thủ công.Khi nào cập nhật đề xuất:
- Phạm vi thay đổi (thu hẹp hoặc mở rộng)
- Ý định được làm rõ (hiểu rõ hơn về vấn đề)
- Phương pháp thay đổi cơ bản
Specs (đặc tả delta trong specs/)
Đặc tả delta mô tả những gì đang thay đổi so với các spec hiện tại. Xem Đặc tả Delta bên dưới.
Thiết kế (design.md)
Thiết kế nắm bắt phương pháp kỹ thuật và các quyết định kiến trúc.
# Thiết kế: Thêm Chế độ Tối
## Phương pháp kỹ thuật
Trạng thái chủ đề được quản lý qua React Context để tránh prop drilling.
CSS custom properties cho phép chuyển đổi thời gian chạy mà không cần bật tắt class.
## Các quyết định kiến trúc
### Quyết định: Context thay vì Redux
Sử dụng React Context cho trạng thái chủ đề vì:
- Trạng thái nhị phân đơn giản (sáng/tối)
- Không có chuyển đổi trạng thái phức tạp
- Tránh thêm phụ thuộc Redux
### Quyết định: CSS Custom Properties
Sử dụng biến CSS thay vì CSS-in-JS vì:
- Hoạt động với stylesheet hiện có
- Không có chi phí thời gian chạy
- Giải pháp gốc của trình duyệt
## Luồng dữ liệu
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## Các thay đổi tệp
- `src/contexts/ThemeContext.tsx` (mới)
- `src/components/ThemeToggle.tsx` (mới)
- `src/styles/globals.css` (được sửa đổi)Khi nào cập nhật thiết kế:
- Việc triển khai cho thấy phương pháp không hoạt động
- Giải pháp tốt hơn được phát hiện
- Các phụ thuộc hoặc ràng buộc thay đổi
Nhiệm vụ (tasks.md)
Nhiệm vụ là danh sách kiểm tra triển khai — các bước cụ thể với ô chọn.
# 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 CSS custom properties cho màu sắc
- [ ] 1.3 Triển khai lưu trữ localStorage
- [ ] 1.4 Thêm phát hiện tùy chọn hệ thống
## 2. Thành phần giao diện
- [ ] 2.1 Tạo thành phần ThemeToggle
- [ ] 2.2 Thêm chuyển đổi vào trang cài đặt
- [ ] 2.3 Cập nhật Header để bao gồm chuyển đổi nhanh
## 3. Kiểu dáng
- [ ] 3.1 Xác định bảng màu chủ đề tối
- [ ] 3.2 Cập nhật các thành phần để sử dụng biến CSS
- [ ] 3.3 Kiểm tra tỷ lệ tương phản cho khả năng truy cậpThực hành tốt về nhiệm vụ:
- Nhóm các nhiệm vụ liên quan dưới các tiêu đề
- Sử dụng đánh số phân cấp (1.1, 1.2, v.v.)
- Giữ nhiệm vụ đủ nhỏ để hoàn thành trong một phiên
- Đánh dấu nhiệm vụ khi hoàn thành
Đặc tả Delta
Đặc tả delta là khái niệm chính làm cho OpenSpec hoạt động cho phát triển brownfield. Chúng mô tả những gì đang thay đổi thay vì trình bày lại toàn bộ spec.
Định dạng
# Đặc tả delta cho Auth
## YÊU CẦU ĐƯỢC THÊM
### Yêu cầu: Xác thực hai yếu tố
Hệ thống MUST hỗ trợ xác thực hai yếu tố dựa trên TOTP.
#### Tình huống: Đăng ký 2FA
- GIVEN người dùng chưa bật 2FA
- WHEN người dùng bật 2FA trong cài đặt
- THEN một mã QR được hiển thị để thiết lập ứng dụng authenticator
- AND người dùng phải xác minh bằng mã trước khi kích hoạt
#### Tình huống: Đăng nhập 2FA
- GIVEN người dùng đã bật 2FA
- WHEN người dùng gửi thông tin xác thực hợp lệ
- THEN một thử thách OTP được hiển thị
- AND đăng nhập chỉ hoàn tất sau khi OTP hợp lệ
## YÊU CẦU ĐƯỢC SỬA
### Yêu cầu: Hết hạn phiên
Hệ thống MUST hết hạn phiên sau 15 phút không hoạt động.
(Trước đây: 30 phút)
#### Tình huống: Hết thời gian chờ
- GIVEN một phiên đã được xác thực
- WHEN 15 phút trôi qua không có hoạt động
- THEN phiên bị vô hiệu hóa
## YÊU CẦU BỊ XÓA
### Yêu cầu: Ghi nhớ tôi
(Bị loại bỏ vì ủng hộ 2FA. Người dùng nên xác thực lại mỗi phiên.)Các phần Delta
| Phần | Ý nghĩa | Điều gì xảy ra khi lưu trữ |
|---|---|---|
## YÊU CẦU ĐƯỢC THÊM | Hành vi mới | Thêm vào spec chính |
## YÊU CẦU ĐƯỢC SỬA | Hành vi đã thay đổi | Thay thế yêu cầu hiện có |
## YÊU CẦU BỊ XÓA | Hành vi bị loại bỏ | Xóa khỏi spec chính; xóa yêu cầu cuối cùng loại bỏ khả năng và xóa tệp spec của nó, khi thay đổi khai báo retire_capabilities: true |
## Mục đích | Những gì một khả năng mới dành cho | Gieo Mục đích của spec chính đang được tạo; bị bỏ qua khi spec đã tồn tại |
Tại sao là Delta thay vì Spec đầy đủ
Rõ ràng. Delta cho thấy chính xác những gì đang thay đổi. Đọc một spec đầy đủ, bạn sẽ phải tự động so sánh nó với phiên bản hiện tại.
Tránh xung đột. Hai thay đổi có thể chạm vào cùng một tệp spec mà không xung đột, miễn là chúng sửa đổi các yêu cầu khác nhau.
Hiệu quả xem xét. Người xem xét thấy thay đổi, không phải ngữ cảnh không thay đổi. Tập trung vào những gì quan trọng.
Phù hợp với brownfield. Hầu hết công việc sửa đổi hành vi hiện có. Delta làm cho các sửa đổi trở thành hạng nhất, không phải là suy nghĩ sau cùng.
Schemas
Schemas định nghĩa các loại artifact và các phụ thuộc của chúng cho một workflow.
Cách Schemas hoạt động
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Không có phụ thuộc, có thể tạo đầu tiên
- id: specs
generates: specs/**/*.md
requires: [proposal] # Cần proposal trước khi tạo
- id: design
generates: design.md
requires: [proposal] # Có thể tạo song song với specs
- id: tasks
generates: tasks.md
requires: [specs, design] # Cần cả specs và design trướcCác artifact tạo thành một đồ thị phụ thuộc:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)Phụ thuộc là yếu tố cho phép, không phải rào cản. Chúng cho biết điều gì có thể tạo, chứ không phải điều gì bạn bắt buộc phải tạo tiếp theo. Bạn có thể bỏ qua design nếu không cần. Bạn có thể tạo specs trước hoặc sau design — cả hai chỉ phụ thuộc vào proposal.
Schemas tích hợp sẵn
spec-driven (mặc định)
Workflow chuẩn cho phát triển theo spec:
proposal → specs → design → tasks → implementPhù hợp nhất cho: Hầu hết các công việc tính năng mà bạn muốn thống nhất spec trước khi triển khai.
Schemas tùy chỉnh
Tạo schemas tùy chỉnh cho workflow của nhóm bạn:
# Tạo từ đầu
openspec schema init research-first
# Hoặc fork một schema có sẵn
openspec schema fork spec-driven research-firstVí dụ schema tùy chỉnh:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Nghiên cứu trước
- id: proposal
generates: proposal.md
requires: [research] # Proposal dựa trên nghiên cứu
- id: tasks
generates: tasks.md
requires: [proposal] # Bỏ qua specs/design, đi thẳng đến tasksXem Customization để biết chi tiết đầy đủ về việc tạo và sử dụng schemas tùy chỉnh.
Archive
Archive hoàn tất một thay đổi bằng cách gộp các delta specs của nó vào specs chính và lưu trữ thay đổi đó cho lịch sử.
Điều gì xảy ra khi bạn Archive
Trước khi archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Sau khi archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Bây giờ bao gồm yêu cầu 2FA
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Được lưu trữ cho lịch sử
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdQuy trình Archive
Gộp deltas. Mỗi phần delta spec (ADDED/MODIFIED/REMOVED) được áp dụng vào spec chính tương ứng.
Di chuyển vào archive. Thư mục thay đổi được di chuyển vào
changes/archive/với tiền tố ngày tháng để sắp xếp theo thứ tự thời gian.Lưu trữ ngữ cảnh. Tất cả các artifact vẫn được giữ nguyên trong archive. Bạn luôn có thể nhìn lại để hiểu tại sao một thay đổi được thực hiện.
Tại sao Archive quan trọng
Trạng thái sạch. Các thay đổi đang hoạt động (changes/) chỉ hiển thị công việc đang tiến hành. Công việc hoàn tất được di chuyển ra khỏi tầm mắt.
Dấu vết kiểm toán. Archive lưu trữ đầy đủ ngữ cảnh của mọi thay đổi — không chỉ những gì đã thay đổi, mà còn proposal giải thích tại sao, design giải thích cách làm, và tasks cho thấy công việc đã thực hiện.
Sự tiến hóa của Specs. Specs phát triển tự nhiên khi các thay đổi được archive. Mỗi lần archive gộp các deltas của nó, xây dựng nên một đặc tả toàn diện theo thời gian.
Mọi thứ hoạt động cùng nhau như thế nào
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. BẮT ĐẦU │ /opsx:propose (core) hoặc /opsx:new (expanded) │
│ │ THAY ĐỔI │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. TẠO │ /opsx:ff hoặc /opsx:continue (expanded workflow) │
│ │ ARTIFACTS │ Tạo proposal → specs → design → tasks │
│ │ │ (dựa trên phụ thuộc của schema) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. TRIỂN KHAI │ /opsx:apply │
│ │ TASKS │ Thực hiện các tasks, đánh dấu hoàn thành │
│ │ │◄──── Cập nhật artifacts khi bạn học được điều mới │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. XÁC THỰC │ /opsx:verify (tùy chọn) │
│ │ CÔNG VIỆC │ Kiểm tra triển khai khớp với specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Delta specs gộp vào specs chính │ │
│ │ THAY ĐỔI │ │ Thư mục thay đổi di chuyển vào archive/ │ │
│ └────────────────┘ │ Specs bây giờ là nguồn sự thật đã cập nhật │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Vòng tuần hoàn tích cực:
- Specs mô tả hành vi hiện tại
- Changes đề xuất các sửa đổi (dưới dạng deltas)
- Triển khai biến các thay đổi thành hiện thực
- Archive gộp deltas vào specs
- Specs bây giờ mô tả hành vi mới
- Thay đổi tiếp theo xây dựng trên specs đã cập nhật
Thuật ngữ
| Thuật ngữ | Định nghĩa |
|---|---|
| Artifact | Một tài liệu trong một thay đổi (proposal, design, tasks, hoặc delta specs) |
| Archive | Quy trình hoàn tất một thay đổi và gộp các deltas của nó vào specs chính |
| Change | Một sửa đổi được đề xuất cho hệ thống, đóng gói dưới dạng thư mục với các artifact |
| Delta spec | Một spec mô tả các thay đổi (ADDED/MODIFIED/REMOVED) so với specs hiện tại |
| Domain | Một nhóm logic cho specs (ví dụ: auth/, payments/) |
| Requirement | Một hành vi cụ thể mà hệ thống phải có |
| Scenario | Một ví dụ cụ thể của một requirement, thường ở định dạng Given/When/Then |
| Schema | Định nghĩa các loại artifact và phụ thuộc của chúng |
| Spec | Một đặc tả mô tả hành vi hệ thống, chứa các requirements và scenarios |
| Source of truth | Thư mục openspec/specs/, chứa hành vi đã thống nhất hiện tại |
Các bước tiếp theo
- Getting Started - Các bước thực hành đầu tiên
- Workflows - Các mẫu phổ biến và khi nào sử dụng từng mẫu
- Commands - Tham khảo đầy đủ các lệnh
- Customization - Tạo schemas tùy chỉnh và cấu hình dự án của bạn