Bắt đầu nhanh

Thay đổi đầu tiên của bạn, từ ý tưởng đến khi lưu trữ, trong dự án mới hoặc dự án hiện có.

Trước khi bắt đầu, bạn cần CLI trên máy của mình (Cài đặt) và OpenSpec được khởi tạo trong dự án của bạn (Thiết lập dự án).

Bắt đầu từ dự án trống

Bạn có thể bắt đầu mà không cần chọn stack hoặc kiến trúc hoàn chỉnh. Khởi tạo OpenSpec trong thư mục dự án của bạn, sau đó yêu cầu agent của bạn khám phá các lựa chọn cùng bạn. Trong trò chuyện AI của bạn:

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

Quyết định những gì thay đổi đầu tiên cần và để các lựa chọn kiến trúc sau mở. Yêu cầu agent của bạn đề xuất thay đổi duy nhất đó, sau đó làm theo các bước bên dưới. Bạn có thể xem xét lại kiến trúc khi dự án phát triển.

Tổng quan về vòng lặp

Mọi thay đổi đều trải qua cùng năm bước: bạn suy nghĩ ý tưởng cùng với agent, nó soạn thảo kế hoạch, bạn sửa kế hoạch trước khi có bất kỳ mã nào, agent xây dựng từ nó, và lưu trữ cập nhật spec của bạn với những gì đã triển khai.

flowchart LR
    explore["1 · Khám phá<br/>suy nghĩ cùng nhau"] --> propose["2 · Đề xuất<br/>agent soạn thảo kế hoạch"]
    propose --> review["3 · Xem xét<br/>bạn sửa kế hoạch"]
    review --> apply["4 · Áp dụng<br/>agent xây dựng, từng tác vụ"]
    apply --> archive["5 · Lưu trữ<br/>spec hấp thụ thay đổi"]
    archive -. "thay đổi tiếp theo" .-> explore

Mọi prompt bên dưới đều đưa vào trò chuyện AI của bạn, cùng nơi bạn yêu cầu mã. Các ví dụ sử dụng ngôn ngữ đơn giản để hoạt động trên các công cụ. Bạn cũng có thể gọi trực tiếp một skill; cú pháp khác nhau tùy theo công cụ (công cụ được hỗ trợ).

Bước 1: Khám phá

Suy nghĩ ý tưởng cùng với agent trước khi bạn yêu cầu kế hoạch. Trong trò chuyện AI của bạn:

Help me explore how rate limiting should work in this app.

Khám phá là một chế độ suy nghĩ. Agent điều tra codebase của bạn, đặt các câu hỏi quan trọng, phác thảo các lựa chọn và thách thức các giả định. Nó không bao giờ viết mã. Nó không viết bất cứ điều gì khác trừ khi bạn yêu cầu nó ghi lại những gì bạn đã quyết định, hoặc nói có khi nó đề nghị. Kết quả là một ý tưởng sắc bén hơn.

Ở lại đây bao lâu tùy theo nhu cầu của vấn đề. Khi hình dạng cảm thấy đúng, chuyển giao nó:

Propose the change we just discussed.

Dòng đó bắt đầu đề xuất cho bạn, mang theo mọi thứ bạn đã quyết định. Bỏ qua prompt đầu tiên ở bước 2.

Bước 2: Đề xuất

Đề xuất biến ý tưởng thành kế hoạch có thể xem xét. Đến từ khám phá, nó đã chạy. Bắt đầu từ đầu, khi thay đổi rõ ràng trong đầu bạn, hỏi trực tiếp. Trong trò chuyện AI của bạn:

Propose a change to add rate limiting.

Agent hỏi những gì nó cần, sau đó viết một thư mục thay đổi:

openspec/changes/add-rate-limiting/
├── proposal.md    why, and what changes
├── specs/         what "done" means, as testable requirements
├── design.md      technical decisions (only when the change needs one)
└── tasks.md       the implementation checklist

Chưa có mã. Đề xuất dừng ở kế hoạch.

Bước 3: Xem xét và sửa kế hoạch

Sửa kế hoạch trong khi nó vẫn là lời và chưa có gì được xây dựng. Đọc theo thứ tự này:

• proposal.md: đây có phải là vấn đề đúng, ở kích thước đúng không?
• specs/: nội dung đọc có giá trị nhất. Bạn có chấp nhận các yêu cầu này là hoàn thành không?
• tasks.md: các tác vụ có bao phủ spec và không hơn không?

Để sửa điều gì, cả hai cách đều hoạt động:

• Tự sửa tệp. Các sản phẩm là markdown đơn giản và các tệp là kế hoạch.
• Nói với agent của bạn những gì sai ("spec thiếu trường hợp chưa xác thực"). Nó sửa đổi các sản phẩm.

Bước 4: Áp dụng

Áp dụng biến kế hoạch thành mã. Bắt đầu một phiên trò chuyện mới, vì việc triển khai diễn ra tốt hơn trên cửa sổ ngữ cảnh sạch. Trong trò chuyện AI của bạn:

Apply the add-rate-limiting change.

Agent đọc thư mục thay đổi, sau đó làm việc qua tasks.md, đánh dấu từng tác vụ khi hoàn thành.

• Bị gián đoạn, hoặc hết ngữ cảnh? Mở một phiên mới và yêu cầu nó áp dụng lại. Nó tiếp tục từ tác vụ đầu tiên chưa được đánh dấu.
• Kế hoạch hóa ra sai? Sửa các sản phẩm (theo bất kỳ cách nào từ bước 3), sau đó tiếp tục áp dụng.
• Tiến độ nằm trong các hộp kiểm tasks.md. Không có trạng thái ẩn.

Bước 5: Lưu trữ

Lưu trữ làm hai điều: cập nhật spec chính của bạn với các yêu cầu của thay đổi, và di chuyển thư mục thay đổi vào thư mục lưu trữ (trong /openspec/changes/archive/*).

Khi mọi hộp trong tasks.md được đánh dấu, trong trò chuyện AI của bạn:

Archive the add-rate-limiting change.

Đi qua những gì lưu trữ làm:

## The finished change
> Implementation is done. The delta spec (what this change adds) still sits inside the change folder; specs/ doesn't know about rate limiting yet.
  openspec/
  ├── specs/                                   (no rate-limiting spec yet)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         every box checked
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta: ADDED requirements

## Requirements land in specs/
> Each requirement in the delta lands in the main spec: added ones append, modified ones replace their old version. A new capability gets a new spec file.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gains "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta, source of the merge

## The folder moves to archive/
> The whole change folder, delta included, moves into the archive under a date prefix. Nothing is deleted.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs describe the system as built
> changes/ is clear for the next change. specs/ is the source of truth for what the system does; archive/ is the history of how it got there.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          the spec as built
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git là một vấn đề riêng biệt. Commit thư mục thay đổi với mã, và không có gì khác trong quy trình làm việc của bạn thay đổi.

Giữ hoặc cắt tỉa các thay đổi đã lưu trữ

openspec/changes/archive/ giữ proposal, design, tasks và delta cho mỗi thay đổi đã hoàn thành. Trong quy trình lưu trữ ở trên, delta đã cập nhật openspec/specs/.

• Giữ toàn bộ thư mục thay đổi khi bạn muốn một bản ghi tự chứa trong checkout hiện tại.
• Xóa thư mục specs/ của thay đổi đã lưu trữ khi Git là lịch sử spec của bạn. Commit lưu trữ trước, sau đó xóa openspec/changes/archive/<change>/specs/. Proposal, design và tasks vẫn còn trong checkout. openspec validate --archived vẫn hoạt động vì nó kiểm tra hoàn thành tác vụ, không phải delta đã áp dụng.
• Xóa toàn bộ thư mục thay đổi chỉ khi bạn không còn cần proposal, design hoặc lịch sử tác vụ của nó trong checkout. Spec hiện tại không thay đổi, nhưng openspec validate --archived và tìm kiếm checkout không còn bao gồm thay đổi đó.

WARNING

Giữ commit lưu trữ trong lịch sử kho lưu trữ của bạn nếu bạn muốn Git giữ lại các tệp đã xóa. Nén commit lưu trữ và dọn dẹp cùng nhau sẽ xóa ảnh chụp trung gian đó.

OpenSpec không tự động cắt tỉa các thay đổi đã lưu trữ hoặc cung cấp cài đặt lưu giữ.

Đi xa hơn

• Delta specs: cách viết các thay đổi hành vi trong delta spec.
• Profiles: quy trình tùy chọn vượt ra ngoài bộ lõi (xác minh trước khi lưu trữ, lập kế hoạch gia tăng).

Hướng dẫn nâng cao

Chưa viết; các hướng dẫn chúng tôi dự định thêm:

• Prototype trước: thử nghiệm mã trước bất kỳ spec nào, sau đó điền proposal từ những gì prototype đã dạy bạn.
• Xây dựng lặp đi lặp lại: một chuỗi các thay đổi nhỏ thay vì một proposal lớn.
• Sửa đổi thay đổi đã triển khai: kế hoạch cần di chuyển lại sau khi áp dụng, nhưng thay đổi chưa được hợp nhất hoặc lưu trữ.