OpenSpec

Workflows ​

Hướng dẫn này bao gồm các mẫu quy trình làm việc phổ biến cho OpenSpec và thời điểm sử dụng từng mẫu. Để biết thông tin thiết lập cơ bản, xem Bắt đầu. Để tham chiếu lệnh, xem Lệnh.

Triết lý: Hành động, không phải Giai đoạn ​

Các quy trình làm việc truyền thống bắt buộc bạn phải trải qua các giai đoạn: lập kế hoạch, sau đó là triển khai, rồi mới kết thúc. Tuy nhiên, công việc thực tế không dễ dàng xếp gọn vào các khung cố định như vậy.

OPSX áp dụng một cách tiếp cận khác:

text
Truyền thống (khóa theo giai đoạn):

  LẬP KẾ HOẠCH ────────► TRIỂN KHAI ────────► XONG
      │                    │
      │   "Không thể quay lại"  │
      └────────────────────┘

OPSX (hành động linh hoạt):

  proposal ──► specs ──► design ──► tasks ──► implement

Các nguyên tắc chính:

  • Hành động, không phải giai đoạn - Các lệnh là những việc bạn có thể thực hiện, chứ không phải các giai đoạn mà bạn bị mắc kẹt
  • Phụ thuộc là yếu tố hỗ trợ - Chúng cho thấy những gì khả thi, chứ không phải thứ bắt buộc phải làm tiếp theo

Tùy chỉnh: Các quy trình làm việc của OPSX được điều khiển bởi các lược đồ (schemas) xác định chuỗi các artifact. Xem Tùy chỉnh để biết chi tiết về cách tạo các lược đồ tùy chỉnh.

Tổng quan Quy trình Làm việc ​

Quy trình làm việc mặc định luôn linh hoạt: việc khám phá và xác minh là tùy chọn, và bạn có thể cập nhật các tạo tác lập kế hoạch bất cứ khi nào quá trình triển khai hé lộ điều gì mới.

mermaid
flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

Trợ lý AI dẫn dắt quy trình làm việc, trong khi CLI cung cấp việc khởi tạo, trạng thái và hướng dẫn tạo tác một cách xác định:

mermaid
sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

Hai Chế Độ ​

Đường Dẫn Nhanh Mặc Định (hồ sơ core) ​

Các cài đặt mới mặc định là core, cung cấp:

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:update
  • /opsx:sync
  • /opsx:archive

Luồng thông thường:

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (optional)

Bắt Đầu Bằng Việc Khám Phá (thói quen đáng hình thành) ​

/opsx:explore là một phần của hồ sơ mặc định, không phải là tiện ích nâng cao. Đây là bước nên thực hiện bất cứ khi nào bạn có vấn đề nhưng chưa có kế hoạch – điều mà với trợ lý AI, phần lớn thời gian là như vậy.

text
Bạn: /opsx:explore

AI:  Bạn muốn khám phá điều gì?

Bạn: Kết quả tìm kiếm của chúng tôi có vẻ cũ. Tôi không chắc là do bộ nhớ đệm,
     chỉ mục, hay do chính truy vấn.

AI:  Để tôi xem... [đọc dịch vụ tìm kiếm và lớp bộ nhớ đệm]
     Vấn đề nằm ở chỉ mục: nó chỉ được xây dựng lại hàng đêm, vì vậy các chỉnh sửa
     không hiển thị cho đến ngày hôm sau. Có hai lựa chọn: xây dựng lại khi ghi
     (đơn giản, tải nhiều hơn) hoặc hủy bộ nhớ đệm với TTL ngắn (nhiều thành phần
     chuyển động hơn, tải ít hơn). Với khối lượng ghi của bạn thấp, xây dựng lại
     khi ghi là giải pháp gọn gàng hơn. Bạn muốn xác định phạm vi không?

Bạn: Có.

Bạn: /opsx:propose rebuild-search-index-on-write

Khám phá không tạo ra tạo tác và không viết mã. Đó là một cuộc trò chuyện miễn phí, không ràng buộc, biến một mối lo mơ hồ thành một thay đổi chính xác, để đề xuất tiếp theo trở nên sắc bén. Bạn đã biết chính xác mình muốn gì? Bỏ qua nó và chuyển thẳng đến /opsx:propose. Hướng dẫn đầy đủ: Khám Phá Trước.

Quy Trình Mở Rộng/Đầy Đủ (lựa chọn tùy chỉnh) ​

Nếu bạn muốn các lệnh khởi tạo và xây dựng rõ ràng (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), hãy kích hoạt chúng bằng:

bash
openspec config profile
openspec update

Các Mẫu Quy Trình (Chế Độ Mở Rộng) ​

Tính Năng Nhanh ​

Khi bạn biết mình muốn xây dựng gì và chỉ cần thực thi:

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

Ví dụ hội thoại:

text
Bạn: /opsx:new add-logout-button

AI:  Đã tạo openspec/changes/add-logout-button/
     Sẵn sàng tạo: proposal

Bạn: /opsx:ff

AI:  Đang tạo tất cả các tạo tác lập kế hoạch...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Sẵn sàng triển khai!

Bạn: /opsx:apply

AI:  Đang thực hiện các tác vụ...
     ✓ Đã thêm nút đăng xuất vào header
     ✓ Đã triển khai xóa phiên
     ✓ Đã thêm hộp thoại xác nhận
     Tất cả các tác vụ đã hoàn thành!

Bạn: /opsx:archive

AI:  ✓ Đã hợp nhất các đặc tả
     ✓ Đã lưu trữ thay đổi

Phù hợp nhất cho: Các tính năng nhỏ đến trung bình, sửa lỗi, các thay đổi đơn giản.

Khám Phá ​

Khi yêu cầu không rõ ràng hoặc bạn cần điều tra trước:

text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Ví dụ hội thoại:

text
Bạn: /opsx:explore

AI:  Bạn muốn khám phá điều gì?

Bạn: Tôi muốn cải thiện hiệu suất tải trang nhưng không chắc
     nút thắt cổ chai nằm ở đâu.

AI:  Để tôi giúp bạn điều tra...
     [Phân tích kích thước bundle, xác định các truy vấn chậm, xem xét
     các mẫu render component]

     Tôi đã tìm thấy ba nút thắt chính:
     1. Hình ảnh lớn chưa được tối ưu
     2. Truy xuất dữ liệu đồng bộ trong ProductList
     3. Re-render do thay đổi context

     Bạn muốn giải quyết vấn đề nào trước?

Bạn: Hãy giải quyết vấn đề truy xuất dữ liệu.

Bạn: /opsx:new optimize-product-list-fetching

AI:  Đã tạo thay đổi. Sẵn sàng tạo: proposal

Bạn: /opsx:continue

AI:  Đang tạo proposal dựa trên khám phá của chúng ta...
     [Viết proposal với các thông tin chi tiết từ điều tra]

     Sẵn sàng tạo: specs, design
     Bạn muốn tiếp theo là gì?

Bạn: /opsx:continue

AI:  Đang tạo các đặc tả...

Phù hợp nhất cho: Tối ưu hiệu suất, gỡ lỗi, quyết định kiến trúc, yêu cầu không rõ ràng.

Thay Đổi Song Song ​

Làm việc trên nhiều thay đổi cùng một lúc:

text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Ví dụ hội thoại:

text
Bạn: Tôi đang làm add-dark-mode nhưng bị kéo vào một bản sửa lỗi

Bạn: /opsx:new fix-login-redirect

AI:  Đã tạo openspec/changes/fix-login-redirect/

Bạn: /opsx:ff

AI:  ✓ Đã tạo các tạo tác lập kế hoạch

Bạn: /opsx:apply

AI:  Đang làm fix-login-redirect...
     [Triển khai bản sửa]
     Tất cả các tác vụ đã hoàn thành!

Bạn: /opsx:archive

AI:  ✓ Đã lưu trữ fix-login-redirect

Bạn: Hãy quay lại chế độ tối

Bạn: /opsx:apply add-dark-mode

AI:  Tiếp tục add-dark-mode...
     Bắt đầu từ tác vụ 2.3: Cập nhật Header...

Phù hợp nhất cho: Các luồng công việc song song, gián đoạn khẩn cấp, cộng tác nhóm.

Khi bạn có nhiều thay đổi đã hoàn thành, hãy sử dụng /opsx:bulk-archive:

text
Bạn: /opsx:bulk-archive

AI:  Đã tìm thấy 3 thay đổi đã hoàn thành:
     - add-dark-mode (tất cả tác vụ đã xong)
     - fix-login-redirect (tất cả tác vụ đã xong)
     - update-footer (tất cả tác vụ đã xong)

     Đang kiểm tra xung đột đặc tả...
     ⚠ add-dark-mode và update-footer đều chạm vào specs/ui/

     Đang kiểm tra codebase để giải quyết...
     Cả hai thay đổi đều đã được triển khai. Sẽ áp dụng theo thứ tự thời gian.

     Lưu trữ cả 3 thay đổi?

Bạn: Có

AI:  ✓ Đã lưu trữ add-dark-mode
     ✓ Đã lưu trữ fix-login-redirect
     ✓ Đã lưu trữ update-footer
     Các đặc tả đã được hợp nhất theo thứ tự: add-dark-mode → update-footer

Lưu trữ hàng loạt phát hiện khi nhiều thay đổi chạm vào cùng các đặc tả và giải quyết xung đột bằng cách kiểm tra những gì thực sự đã được triển khai.

Hoàn Thành Một Thay Đổi ​

Luồng hoàn thành được khuyến nghị:

text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              xác thực          nhắc đồng bộ
              triển khai        nếu cần

Xác Minh: Kiểm Tra Công Việc Của Bạn ​

/opsx:verify xác thực việc triển khai dựa trên các tạo tác của bạn trên ba khía cạnh:

text
Bạn: /opsx:verify

AI:  Đang xác minh add-auth...

     TÍNH ĐẦY ĐỦ
     ✓ Tất cả 12 tác vụ trong tasks.md đã được đánh dấu
     ✓ Tất cả yêu cầu trong đặc tả đều có mã tương ứng
     ⚠ Kịch bản "Hết thời gian chờ phiên sau khi không hoạt động" chưa được kiểm thử

     TÍNH ĐÚNG ĐẮN
     ✓ Triển khai khớp với ý định đặc tả
     ✓ Các trường hợp biên từ các kịch bản đã được xử lý
     ✓ Các trạng thái lỗi khớp với định nghĩa đặc tả

     TÍNH NHẤT QUÁN
     ✓ Các quyết định thiết kế được phản ánh trong cấu trúc mã
     ✓ Quy ước đặt tên nhất quán với design.md
     ⚠ Thiết kế đề cập đến "hướng sự kiện" nhưng triển khai sử dụng polling

     TÓM TẮT
     ─────────────────────────────
     Vấn đề nghiêm trọng: 0
     Cảnh báo: 2
     Sẵn sàng lưu trữ: Có (với cảnh báo)

     Khuyến nghị:
     1. Thêm kiểm thử cho kịch bản hết thời gian chờ phiên
     2. Xem xét tái cấu trúc theo hướng sự kiện như thiết kế, hoặc cập nhật design.md

Những gì xác minh kiểm tra:

Khía cạnhXác thực điều gì
Tính đầy đủTất cả tác vụ đã xong, tất cả yêu cầu được triển khai, các kịch bản được bao phủ
Tính đúng đắnTriển khai khớp với ý định đặc tả, các trường hợp biên được xử lý
Tính nhất quánCác quyết định thiết kế được phản ánh trong mã, các mẫu nhất quán

Xác minh sẽ không chặn lưu trữ, nhưng nó chỉ ra các vấn đề bạn có thể muốn giải quyết trước.

Lưu Trữ: Hoàn Tất Thay Đổi ​

/opsx:archive hoàn tất thay đổi và chuyển nó vào kho lưu trữ:

text
Bạn: /opsx:archive

AI:  Đang lưu trữ add-auth...

     Trạng thái tạo tác:
     ✓ proposal.md tồn tại
     ✓ specs/ tồn tại
     ✓ design.md tồn tại
     ✓ tasks.md tồn tại (12/12 tác vụ hoàn thành)

     Đặc tả delta: Chưa được đồng bộ với chính
     → Bạn có muốn đồng bộ ngay bây giờ không?

Bạn: Có

AI:  ✓ Đã đồng bộ các đặc tả vào openspec/specs/auth/spec.md
     ✓ Đã chuyển vào openspec/changes/archive/2025-01-24-add-auth/

     Thay đổi đã được lưu trữ thành công.

Lưu trữ sẽ nhắc nếu các đặc tả chưa được đồng bộ. Nó sẽ không chặn các tác vụ chưa hoàn thành, nhưng sẽ cảnh báo bạn.

Khi Nào Sử Dụng Cái Gì ​

/opsx:ff so với /opsx:continue ​

Tình huốngSử dụng
Yêu cầu rõ ràng, sẵn sàng xây dựng/opsx:ff
Đang khám phá, muốn xem xét từng bước/opsx:continue
Muốn lặp lại proposal trước khi có đặc tả/opsx:continue
Áp lực thời gian, cần tiến nhanh/opsx:ff
Thay đổi phức tạp, muốn kiểm soát/opsx:continue

Nguyên tắc nhỏ: Nếu bạn có thể mô tả toàn bộ phạm vi trước, hãy dùng /opsx:ff. Nếu bạn đang tìm hiểu dần, hãy dùng /opsx:continue.

Khi Nào Cập Nhật so Với Bắt Đầu Mới ​

Một câu hỏi thường gặp: khi nào thì cập nhật một thay đổi hiện có là ổn, và khi nào bạn nên bắt đầu một thay đổi mới?

Cập nhật thay đổi hiện có khi:

  • Cùng ý định, tinh chỉnh cách thực hiện
  • Phạm vi thu hẹp (MVP trước, phần còn lại sau)
  • Các điều chỉnh do học hỏi (codebase không như bạn mong đợi)
  • Tinh chỉnh thiết kế dựa trên những phát hiện khi triển khai

Bắt đầu một thay đổi mới khi:

  • Ý định đã thay đổi cơ bản
  • Phạm vi bùng nổ sang công việc hoàn toàn khác
  • Thay đổi ban đầu có thể được đánh dấu "xong" một cách độc lập
  • Các bản vá sẽ gây nhầm lẫn hơn là làm rõ
text
                     ┌─────────────────────────────────────┐
                     │     Đây có phải cùng một công việc?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Cùng ý định?      >50% chồng lấn?      Có thể "xong" mà
          Cùng vấn đề?     Cùng phạm vi?        không cần những
                 │                  │           thay đổi này?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      CÓ               KHÔNG CÓ           KHÔNG KHÔNG              CÓ
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    CẬP NHẬT            MỚI  CẬP NHẬT       MỚI  CẬP NHẬT          MỚI

Ví dụ: "Thêm chế độ tối"

  • "Cũng cần hỗ trợ các chủ đề tùy chỉnh" → Thay đổi mới (phạm vi bùng nổ)
  • "Phát hiện tùy chọn hệ thống khó hơn dự kiến" → Cập nhật (cùng ý định)
  • "Hãy triển khai nút chuyển đổi trước, thêm tùy chọn sau" → Cập nhật rồi lưu trữ, sau đó là thay đổi mới

Thực hành tốt nhất ​

Giữ các thay đổi tập trung ​

Mỗi lần thay đổi nên bao gồm một đơn vị công việc logic duy nhất. Nếu bạn đang thực hiện "thêm tính năng X và cũng tái cấu trúc Y", hãy cân nhắc tạo hai lần thay đổi riêng biệt.

Tại sao điều này quan trọng:

  • Dễ dàng xem xét và hiểu hơn
  • Lịch sử kho lưu trữ (archive history) rõ ràng hơn
  • Có thể triển khai độc lập
  • Khôi phục lại (rollback) đơn giản hơn nếu cần thiết

Sử dụng /opsx:explore cho các yêu cầu chưa rõ ràng ​

Trước khi cam kết thực hiện một thay đổi, hãy khám phá không gian vấn đề:

text
Bạn: /opsx:explore

AI:  Bạn muốn khám phá điều gì?

Bạn: Chúng ta nên xử lý giới hạn tốc độ (rate limiting) cho API như thế nào?

AI:  Để tôi tìm hiểu về cài đặt hiện tại và các tùy chọn của bạn...
     [Nghiên cứu cơ sở mã, xem xét các mẫu]

     Tôi thấy có ba cách tiếp cận chúng ta có thể thực hiện:
     1. Dựa trên Middleware (đơn giản, theo từng điểm cuối)
     2. Dựa trên Redis (có khả năng mở rộng, trạng thái chia sẻ)
     3. Bucket token theo người dùng (công bằng, phức tạp)

     Ngăn xếp công nghệ hiện tại của bạn gợi ý cách #1 hoặc #2. Quy mô của bạn là bao nhiêu?

Việc khám phá giúp làm rõ tư duy trước khi bạn tạo ra các sản phẩm (artifacts).

Xác minh trước khi lưu trữ ​

Sử dụng /opsx:verify để kiểm tra xem việc triển khai có khớp với các sản phẩm (artifacts) hay không:

text
Bạn: /opsx:verify

AI:  Đang xác minh add-dark-mode...

     ✓ Tất cả các tác vụ trong tasks.md đều đã được đánh dấu hoàn thành
     ✓ Các yêu cầu trong specs có mã tương ứng
     ✓ Các quyết định thiết kế đã được phản ánh trong việc triển khai

     Sẵn sàng để lưu trữ!

Phát hiện các sự không khớp trước khi bạn đóng lần thay đổi.

Đặt tên thay đổi rõ ràng ​

Tên rõ ràng giúp lệnh openspec list trở nên hữu ích:

text
Tốt:                           Tránh:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Tham chiếu nhanh lệnh ​

Để biết chi tiết đầy đủ về các lệnh và tùy chọn, xem Commands.

LệnhMục đíchKhi nào sử dụng
/opsx:proposeTạo thay đổi + các sản phẩm lập kế hoạchĐường dẫn mặc định nhanh (core profile)
/opsx:exploreSuy nghĩ qua các ý tưởng với AIBắt đầu ở đây khi không chắc chắn: yêu cầu chưa rõ, điều tra, so sánh các tùy chọn
/opsx:newBắt đầu khung thay đổi (change scaffold)Chế độ mở rộng, kiểm soát rõ ràng các sản phẩm
/opsx:continueTạo sản phẩm tiếp theoChế độ mở rộng, tạo sản phẩm từng bước
/opsx:ffTạo tất cả các sản phẩm lập kế hoạchChế độ mở rộng, phạm vi rõ ràng
/opsx:applyTriển khai các tác vụSẵn sàng viết mã
/opsx:verifyXác thực việc triển khaiChế độ mở rộng, trước khi lưu trữ
/opsx:syncHợp nhất các đặc tả deltaChế độ mở rộng, tùy chọn
/opsx:archiveHoàn tất thay đổiĐã hoàn thành tất cả công việc
/opsx:bulk-archiveLưu trữ nhiều thay đổiChế độ mở rộng, công việc song song

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

  • Writing Good Specs - Mô tả về một yêu cầu và kịch bản mạnh mẽ trông như thế nào, cũng như cách xác định quy mô phù hợp cho một thay đổi
  • Reviewing a Change - Quy trình xem xét nhanh hai phút đối với kế hoạch dự thảo trước khi bắt đầu viết mã
  • OpenSpec on a Team - Cách các thay đổi liên quan đến nhánh (branches) và pull requests
  • Commands - Tài liệu tham khảo đầy đủ về các lệnh kèm tùy chọn
  • Concepts - Tìm hiểu sâu về đặc tả (specs), sản phẩm (artifacts) và lược đồ (schemas)
  • Customization - Tạo các quy trình làm việc tùy chỉnh