Examples & Recipes

Những thay đổi thực tế, từ đầu đến cuối. Mỗi công thức (recipe) hiển thị các lệnh bạn sẽ nhập và những gì bạn sẽ nhận lại, để bạn có thể đối chiếu tình huống của mình với một mẫu và sao chép nó. Các công thức này sử dụng các lệnh core mặc định (propose, explore, apply, update, sync, archive); khi bộ lệnh mở rộng hữu ích hơn, điều đó sẽ được ghi chú.

Một lời nhắc trước khi bạn bắt đầu: các lệnh slash như /opsx:propose được nhập trong chat của trợ lý AI, còn các lệnh openspec được nhập trong terminal. Nếu điều này còn mới mẻ, hãy đọc How Commands Work trước. Trong các bản ghi dưới đây, You: và AI: là phần chat, còn các dòng bắt đầu bằng $ là phần terminal.

Chưa chắc chắn mình đang xây dựng gì? Hầu hết các công thức này sẽ sắc bén hơn nếu bạn bắt đầu với /opsx:explore để suy nghĩ kỹ trước. Recipe 3 minh họa điều này trong thực tế, và hướng dẫn Explore First trình bày đầy đủ lý do.

Recipe 1: Một tính năng nhỏ, đường tắt nhanh

Khi nào sử dụng: bạn biết mình muốn gì và đó là một phần việc được giới hạn. Đây là công thức phổ biến nhất.

Toàn bộ quy trình chỉ gồm ba lệnh. Đề xuất, xây dựng, lưu trữ.

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

Bây giờ hãy đọc kế hoạch. Mở proposal và delta spec. Đây là khoảnh khắc mà OpenSpec được xây dựng để phục vụ: bắt được một giả định sai khi nó vẫn chỉ là một đoạn văn, chứ không phải 400 dòng code. Chỉnh sửa bất kỳ artifact nào trực tiếp nếu có gì đó không ổn, sau đó tiếp tục.

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

Chỉ vậy thôi. Hành vi đăng xuất giờ đã là một phần của specs của bạn, và thay đổi đã được lưu trữ cùng toàn bộ ngữ cảnh.

Recipe 2: Sửa lỗi

Khi nào sử dụng: có gì đó bị hỏng và bạn muốn việc sửa được ghi nhận như một thay đổi có chủ đích đối với hành vi, chứ không phải một commit bí ẩn.

Sửa lỗi hoạt động y hệt như tính năng. Sự khác biệt nằm ở cách bạn trình bày proposal: mô tả hành vi đúng, chứ không chỉ "sửa lỗi".

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

Vì bản sửa được ghi nhận như một requirement MODIFIED với một scenario mới, người tiếp theo (hoặc phiên AI tiếp theo) sẽ thấy không chỉ rằng bạn đã sửa, mà còn "đúng" nghĩa là gì. Sau đó /opsx:apply và /opsx:archive như bình thường.

Mẹo: đối với một bản sửa, một scenario tốt chính là bài kiểm thử hồi quy bằng văn bản. "GIVEN một người dùng đã đăng xuất, WHEN họ gửi thông tin xác thực hợp lệ, THEN họ đến được dashboard và không bị chuyển hướng lại." Viết điều đó ra, và việc triển khai sẽ có một mục tiêu rõ ràng.

Recipe 3: Khám phá trước khi cam kết

Khi nào sử dụng: bạn có một vấn đề nhưng chưa có kế hoạch. Bạn không chắc chắn mình nên xây dựng gì, hay phương pháp nào là đúng.

Bắt đầu với /opsx:explore. Đây là một đối tác suy nghĩ không có cấu trúc và không tạo artifact nào. Nó đọc codebase của bạn và giúp bạn quyết định.

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

You: /opsx:propose optimize-product-list-fetching

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

Khám phá làm rõ suy nghĩ của bạn trước khi bạn dành một thay đổi cho nó. Khi nhận thức trở nên rõ ràng, hãy đề xuất, và AI sẽ mang ngữ cảnh theo.

Recipe 4: Juggling hai thay đổi cùng lúc

Khi nào sử dụng: bạn đang làm dở một tính năng và một bản sửa khẩn cấp chen ngang hàng đợi.

Các thay đổi là các thư mục độc lập, nên công việc song song không xung đột. Bắt đầu bản sửa, phát hành nó, sau đó quay lại tính năng ngay chỗ bạn đã dừng.

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

Việc đặt tên thay đổi trong /opsx:apply add-dark-mode là cách bạn chỉ định cho AI một thay đổi cụ thể khi có nhiều thay đổi đang hoạt động. Vì các task theo dõi hoàn thành trong tasks.md, AI biết chính xác bạn đã dừng ở đâu.

Khi nhiều thay đổi hoàn thành cùng lúc, /opsx:bulk-archive mở rộng sẽ lưu trữ chúng cùng nhau và giải quyết xung đột spec bằng cách kiểm tra những gì thực sự đã được triển khai. Xem Workflows.

Recipe 5: Refactor không thay đổi hành vi

Khi nào sử dụng: bạn đang tái cấu trúc code, và hành vi có thể quan sát từ bên ngoài nên giữ nguyên.

Đây là trường hợp thú vị, vì một refactor thuần túy không có gì để thêm vào specs của bạn. Hợp đồng hành vi không thay đổi; chỉ việc triển khai mới thay đổi. Vì vậy công việc nằm trong design và tasks, còn delta spec thì trống hoặc vắng mặt.

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

Khai báo delta trống một cách tường minh bằng cách đặt skip_specs: true trong .openspec.yaml của thay đổi:

schema: spec-driven
skip_specs: true

Không có marker này, openspec validate sẽ từ chối một thay đổi có zero deltas (để một giai đoạn specs bị quên vẫn bị bắt); có nó, validation sẽ thông qua và openspec status hiển thị giai đoạn specs là đã bị bỏ qua tường minh thay vì đang chờ. Nếu refactor hóa ra lại thay đổi hành vi, hãy xóa skip_specs khỏi .openspec.yaml và viết delta specs — validate coi marker cùng với các tệp spec là một xung đột, nên marker cũ không thể âm thầm tồn tại.

Lưu trữ một thay đổi đã đánh dấu không cần cờ bổ sung (không có delta để hợp nhất). Độc lập, cờ --skip-specs báo cho lệnh terminal bỏ qua bước spec một cách tường minh:

$ openspec archive refactor-payment-module --skip-specs

Cờ tương tự cũng hữu ích cho tooling, CI và các thay đổi chỉ liên quan đến tài liệu. Nguyên tắc: specs mô tả hành vi, nên nếu hành vi không thay đổi, spec cũng không nên thay đổi. Xem Concepts.

Recipe 6: Kiểm soát từng bước (lệnh mở rộng)

Khi nào sử dụng: một thay đổi phức tạp hoặc rủi ro mà bạn muốn xem xét từng artifact trước khi tiếp tục.

Lệnh core /opsx:propose phác thảo mọi thứ cùng lúc. Khi bạn muốn đi từng bước một, hãy bật các lệnh mở rộng:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Bây giờ bạn có thể dựng khung và xây dựng theo từng phần:

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

Xem xét từng artifact khi nó xuất hiện, chỉnh sửa tự do, và tiếp tục khi bạn hài lòng. Khi bạn muốn phần còn lại được phác thảo một lần, /opsx:ff sẽ nhanh chóng tạo ra các artifact lập kế hoạch còn lại. Trước khi lưu trữ, /opsx:verify kiểm tra rằng việc triển khai thực sự khớp với specs. Xem Workflows.

Recipe 7: Học toàn bộ vòng lặp qua thực hành

Khi nào sử dụng: bạn đã cài đặt OpenSpec và muốn cảm nhận quy trình trên code của chính mình, chứ không phải một ví dụ đồ chơi.

Bật các lệnh mở rộng (xem Recipe 6), sau đó:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

/opsx:onboard tìm một cải tiến thực tế (nhỏ), tạo một thay đổi cho nó, triển khai và lưu trữ, đồng thời tường thuật từng bước. Nó mất từ 15 đến 30 phút và để lại cho bạn một thay đổi thực tế mà bạn có thể giữ hoặc bỏ. Đây là cách học nhẹ nhàng nhất. Xem Commands.

Kiểm tra công việc từ terminal

Bất cứ lúc nào, từ terminal, bạn có thể kiểm tra trạng thái:

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

Đây là các công cụ đọc và kiểm tra. Việc đề xuất và xây dựng vẫn diễn ra thông qua các lệnh slash trong chat. Chi tiết đầy đủ trong CLI reference.

Bước tiếp theo

• Explore First: cách bắt đầu được khuyến nghị khi bạn chưa chắc chắn
• Workflows: các mẫu ở trên, kèm hướng dẫn ra quyết định về khi nào sử dụng từng cái
• Commands: chi tiết từng lệnh slash
• Getting Started: hướng dẫn thay đổi đầu tiên chính thống
• Concepts: lý do các mảnh ghép khớp với nhau như vậy