Cấu hình dự án

Làm cho các quy trình lập kế hoạch thay đổi theo cách bạn muốn với vài dòng trong config.yaml.

openspec/config.yaml cho các quy trình biết cách bạn muốn lập kế hoạch thay đổi.

Ví dụ, cấu hình sau cập nhật quy tắc tạo cho artifact tasks.md:

rules:
  tasks:
    - End every task with a commit

Khi agent chạy, nó lấy từ các quy tắc này và đảm bảo mọi nhiệm vụ kết thúc bằng một bước commit.

Giữ quy tắc ngắn gọn. Mọi thứ ở đây đều được đưa vào ngữ cảnh của agent, và quy tắc dài dòng có thể làm đầu ra tệ hơn.

Cách hoạt động

config.yaml chứa các hướng dẫn mà agent nhận được khi tạo artifact hoặc thực hiện quy trình làm việc.

Đây là những gì xảy ra trong mỗi lần chạy:

1. Bạn chạy một quy trình làm việc (ví dụ: /openspec-propose).
2. Agent gọi lệnh openspec instructions.
3. Lệnh đọc ngữ cảnh và quy tắc của bạn từ config.yaml.
4. Hướng dẫn tích hợp sẵn của OpenSpec và các tùy chỉnh của bạn được kết hợp thành một prompt duy nhất cho agent.
5. Agent tuân theo prompt đó để viết artifact.

Ví dụ, với trường context và quy tắc ở đầu trang này, đây là những gì openspec instructions trả về cho tasks.md (rút gọn và có chú thích):

<artifact id="tasks" change="add-dark-mode" schema="spec-driven">

  <!-- Từ config.yaml của bạn: context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- Từ config.yaml của bạn: quy tắc cho tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- Từ OpenSpec: hướng dẫn tích hợp sẵn -->
  <instruction>
    ...cách viết tasks.md tốt...
  </instruction>

  <template>
    ...cấu trúc tasks.md để điền vào...
  </template>

</artifact>

Config của bạn đến trước, sau đó là hướng dẫn và template tích hợp sẵn của OpenSpec. Quy tắc bổ sung vào phần tích hợp sẵn và không bao giờ thay thế chúng. Chỉnh sửa config.yaml sẽ được chuyển đến agent trong lần chạy tiếp theo.

Các trường

Ba trường định hình những gì agent nhận được. Đặc tả chính xác của mỗi trường (kiểu dữ liệu, giới hạn, xác thực) có trong Cấu hình dự án (config.yaml).

Trường	Chức năng	Được tiêm vào
context	Hướng dẫn agent luôn nhận được	Mọi thứ: mọi artifact, apply, archive
rules	Hướng dẫn bổ sung cho một artifact	Chỉ khi tạo artifact đó
operations	Hướng dẫn cách thực hiện một bước trong quy trình	Chỉ apply và archive

Các trường khác của config.yaml (schema, store, references) chọn schema và thư mục gốc OpenSpec mà dự án sử dụng. Trang đặc tả sẽ đề cập đến chúng.

Cột cuối cùng là chính xác, nên một trường chỉ đến các bước được liệt kê ở đó. Cụ thể, verify không bao giờ nhận rules. Nó kiểm tra việc triển khai dựa trên artifact như đã viết.

context

context là thông tin nền mà agent nhận được khi tạo artifact, áp dụng nhiệm vụ hoặc lưu trữ thay đổi.

context: |
  We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

Sử dụng context cho các sự thật và ràng buộc nên định hình đầu ra của quy trình làm việc. Giữ tài liệu dự án lâu dài trong các tệp tài liệu của dự án, và loại trừ mọi thứ mà agent có thể tìm hiểu bằng cách đọc mã.

Ngôn ngữ khác: vì context đến mọi artifact, bạn có thể thêm Write all artifacts in Spanish. để hướng dẫn agent viết proposal, spec, design và tasks artifact bằng tiếng Tây Ban Nha.

rules

rules gắn với một artifact, được liên kết theo artifact id. Mỗi dòng được thêm vào hướng dẫn tích hợp sẵn của artifact đó:

rules:
  proposal:
    - Keep proposals under 500 words
  tasks:
    - Every UI task includes a Playwright test

Proposal giờ đây sẽ ngắn gọn và tasks.md luôn lập kế hoạch kiểm thử trình duyệt. Mọi artifact khác không bị ảnh hưởng.

operations

operations hướng dẫn cách agent thực hiện apply và archive, thay vì nội dung artifact nói:

operations:
  apply:
    guidance:
      - Run the linter before marking a task complete
  archive:
    guidance:
      - Summarize what shipped before archiving

Trong quá trình apply, agent chạy linter khi hoàn thành nhiệm vụ. Trong quá trình archive, nó kết thúc bằng một bản tóm tắt.

Khi config.yaml không đủ

Config thêm hướng dẫn bên trên quy trình làm việc tiêu chuẩn, nhưng không thể thay đổi artifact nào tồn tại hoặc cách chúng được cấu trúc. Khi bạn muốn mức độ kiểm soát đó, hoặc quy tắc không điều khiển hành vi một cách nhất quán, fork một schema.