Tùy chỉnh

OpenSpec cung cấp ba cấp độ tùy chỉnh:

Cấp độ	Chức năng	Phù hợp nhất cho
Cấu hình dự án	Đặt giá trị mặc định, tiêm ngữ cảnh/quy tắc	Hầu hết các nhóm
Schema tùy chỉnh	Định nghĩa các artifact quy trình làm việc riêng	Các nhóm có quy trình độc đáo
Ghi đè toàn cục	Chia sẻ schema giữa tất cả các dự án	Người dùng nâng cao

Cấu hình dự án

File openspec/config.yaml là cách dễ nhất để tùy chỉnh OpenSpec cho nhóm của bạn. Nó cho phép bạn:

Đặt schema mặc định - Bỏ qua --schema ở mỗi lệnh
Tiêm ngữ cảnh dự án - AI nhận thấy tech stack, các quy ước, v.v. của bạn
Thêm quy tắc theo từng artifact - Quy tắc tùy chỉnh cho các artifact cụ thể
Thêm hướng dẫn theo từng thao tác - Ưu tiên tư vấn cho công việc apply và archive
Ghi nhớ các lựa chọn tích hợp - ví dụ: chọn tham gia GitHub Copilot cloud coding agent

Thiết lập nhanh

bash

openspec init

Lệnh này sẽ hướng dẫn bạn tạo cấu hình tương tác. Hoặc tạo thủ công:

yaml

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

Cách hoạt động

Schema mặc định:

bash

# Without config
openspec new change my-feature --schema spec-driven

# With config - schema is automatic
openspec new change my-feature

Tiêm ngữ cảnh và quy tắc:

Khi tạo bất kỳ artifact nào, ngữ cảnh và quy tắc của bạn được tiêm vào prompt AI:

xml

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

Ngữ cảnh xuất hiện trong TẤT CẢ các artifact
Quy tắc CHỈ xuất hiện cho artifact khớp

Hướng dẫn thao tác:

operations.apply.guidance và operations.archive.guidance là các mảng tùy chọn chứa các chỉ dẫn tư vấn về cách một agent nên thực hiện các thao tác đó. Chúng riêng biệt với rules: hướng dẫn thao tác không ràng buộc nội dung artifact, và quy tắc artifact không bao giờ được gán nhãn lại thành hướng dẫn thao tác.

Apply và archive lấy các đầu vào này tại thời điểm thực thi:

bash

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Cả hai bề mặt đều trả về context dự án hiện tại và operationGuidance khớp như các trường tùy chọn riêng biệt. Mỗi lần gọi đọc một snapshot mới từ root đã phân giải. Khi --store <id> được chọn, change, context và guidance đều đến từ store đó thay vì repository hiện tại. Lệnh instruction archive chỉ đọc: nó không kiểm tra hoặc merge delta specs, không ghi main specs, không di chuyển change, và không chạy quy trình archive tĩnh.

Ngữ cảnh dự án là đầu vào cấp prompt bắt buộc. Các workflow được tạo đọc nó và áp dụng các sự thật, quy ước và ràng buộc dự án liên quan. Hướng dẫn thao tác là lời khuyên bổ sung tùy chọn: các workflow xem xét mọi mục và tuân theo các mục phù hợp và tương thích với workflow tích hợp.

Cả hai trường đều riêng biệt với trạng thái do CLI kiểm soát, các đường dẫn đã phân giải, các bước tích hợp, các lựa chọn người dùng rõ ràng, và quy tắc artifact. Một workflow báo cáo xung đột ngữ cảnh trong khi giữ nguyên giá trị kiểm soát. Nó không tuân theo hướng dẫn không áp dụng hoặc xung đột và giải thích lý do. Không trường nào là kiểm tra có thể thực thi, và các workflow không sao chép văn bản của chúng vào các file triển khai, specs, change artifacts, hoặc summaries trừ khi người dùng yêu cầu riêng nội dung đó.

An toàn đầu vào cho archive và spec-sync:

Archive, bulk archive và standalone sync sử dụng artifactPaths.specs.existingOutputPaths từ openspec status --json làm nguồn delta-spec duy nhất. Một schema không có artifact specs, hoặc một change có danh sách đầu ra cụ thể trống, thì không có gì để sync; các artifact khác không được dùng để suy luận delta specs.

Trước khi semantic merge ghi một main spec, workflow tiêu thụ đầu ra hiện tại của openspec instructions specs --change <name> --json. Các quy tắc specs được trả về chỉ ràng buộc các main specs do merge đó tạo ra. Single archive truyền snapshot đó vào inline sync, standalone sync lấy trực tiếp, và bulk archive thu nhận mọi snapshot cần thiết trước khi ghi spec đầu tiên. Một phản hồi instruction archive/specs JSON không bằng không hoặc không hợp lệ là lỗi tra cứu, không phải đầu vào trống: workflow dừng trước khi ghi spec bị ảnh hưởng hoặc di chuyển change (đối với bulk archive, trước bất kỳ thao tác ghi hoặc di chuyển khối nào).

Cấu hình này không thay đổi các giai đoạn thực thi archive, các prompt người dùng, các thao tác hệ thống tệp, quyền sở hữu semantic merge, lệnh openspec archive trực tiếp, hoặc cấu trúc và đầu ra của rules artifact.

Thứ tự phân giải schema

Khi OpenSpec cần một schema, nó kiểm tra theo thứ tự này:

CLI flag: --schema <name>
Metadata của change (.openspec.yaml trong thư mục change)
Cấu hình dự án (openspec/config.yaml)
Mặc định (spec-driven)

Custom Schemas

Khi cấu hình dự án không đủ, hãy tạo lược đồ (schema) của riêng bạn với quy trình làm việc hoàn toàn tùy chỉnh. Các lược đồ tùy chỉnh được lưu trữ trong thư mục openspec/schemas/ của dự án và được kiểm soát phiên bản cùng với mã nguồn.

text

your-project/
├── openspec/
│   ├── config.yaml        # Cấu hình dự án
│   ├── schemas/           # Lược đồ tùy chỉnh nằm ở đây
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Các thay đổi của bạn
└── src/

Fork một Lược đồ Có sẵn

Cách nhanh nhất để tùy chỉnh là fork một lược đồ tích hợp sẵn:

bash

openspec schema fork spec-driven my-workflow

Lệnh này sao chép toàn bộ lược đồ spec-driven vào openspec/schemas/my-workflow/, nơi bạn có thể chỉnh sửa tự do.

Những gì bạn nhận được:

text

openspec/schemas/my-workflow/
├── schema.yaml           # Định nghĩa quy trình làm việc
└── templates/
    ├── proposal.md       # Mẫu cho artifact đề xuất
    ├── spec.md           # Mẫu cho đặc tả kỹ thuật
    ├── design.md         # Mẫu cho thiết kế
    └── tasks.md          # Mẫu cho danh sách tác vụ

Bây giờ hãy chỉnh sửa schema.yaml để thay đổi quy trình làm việc, hoặc chỉnh sửa các mẫu để thay đổi những gì AI tạo ra.

Tạo Lược đồ Từ Đầu

Đối với một quy trình làm việc hoàn toàn mới:

bash

# Tương tác
openspec schema init research-first

# Không tương tác
openspec schema init rapid \
  --description "Quy trình lặp lại nhanh" \
  --artifacts "proposal,tasks" \
  --default

Cấu trúc Lược đồ

Một lược đồ xác định các artifact trong quy trình làm việc của bạn và cách chúng phụ thuộc lẫn nhau:

yaml

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: Quy trình làm việc tùy chỉnh của nhóm tôi

artifacts:
  - id: proposal
    generates: proposal.md
    description: Tài liệu đề xuất ban đầu
    template: proposal.md
    instruction: |
      Tạo một đề xuất giải thích TẠI SAO sự thay đổi này là cần thiết.
      Tập trung vào vấn đề, không phải giải pháp.
    requires: []

  - id: design
    generates: design.md
    description: Thiết kế kỹ thuật
    template: design.md
    instruction: |
      Tạo tài liệu thiết kế giải thích CÁCH thức triển khai.
    requires:
      - proposal    # Không thể tạo thiết kế cho đến khi đề xuất tồn tại

  - id: tasks
    generates: tasks.md
    description: Danh sách kiểm tra triển khai
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Các trường chính:

Trường	Mục đích
`id`	Định danh duy nhất, được sử dụng trong các lệnh và quy tắc
`generates`	Tên tệp đầu ra (hỗ trợ glob như `specs/*/.md`)
`template`	Tệp mẫu trong thư mục `templates/`
`instruction`	Hướng dẫn dành cho AI để tạo artifact này
`requires`	Phụ thuộc - các artifact nào phải tồn tại trước tiên

Liệt kê các artifact theo thứ tự bạn muốn chúng được ghi. requires quyết định những gì có thể xảy ra; thứ tự của danh sách artifacts: quyết định cái nào xuất hiện trước khi nhiều artifact sẵn sàng cùng lúc.

Mẫu (Templates)

Mẫu là các tệp markdown hướng dẫn AI. Chúng được chèn vào prompt khi tạo artifact đó.

markdown

<!-- templates/proposal.md -->
## Tại sao

<!-- Giải thích động lực cho sự thay đổi này. Nó giải quyết vấn đề gì? -->

## Những Thay Đổi

<!-- Mô tả những gì sẽ thay đổi. Hãy cụ thể về các khả năng mới hoặc sửa đổi. -->

## Tác Động

<!-- Mã bị ảnh hưởng, API, phụ thuộc, hệ thống -->

Mẫu có thể bao gồm:

Tiêu đề phần mà AI nên điền vào
Nhận xét HTML chứa hướng dẫn cho AI
Ví dụ về định dạng hiển thị cấu trúc mong đợi

Xác thực Lược đồ Của Bạn

Trước khi sử dụng lược đồ tùy chỉnh, hãy xác thực nó:

bash

openspec schema validate my-workflow

Điều này kiểm tra:

Cú pháp schema.yaml đúng
Tất cả các mẫu được tham chiếu đều tồn tại
Không có vòng lặp phụ thuộc
ID artifact hợp lệ

Sử Dụng Lược Đồ Tùy Chỉnh Của Bạn

Sau khi tạo, hãy sử dụng lược đồ của bạn bằng cách:

bash

# Chỉ định trên dòng lệnh
openspec new change feature --schema my-workflow

# Hoặc đặt làm mặc định trong config.yaml
schema: my-workflow

Gỡ lỗi Việc Phân giải Lược đồ

Không chắc chắn lược đồ nào đang được sử dụng? Hãy kiểm tra bằng cách:

bash

# Xem một lược đồ cụ thể được phân giải từ đâu
openspec schema which my-workflow

# Liệt kê tất cả các lược đồ có sẵn
openspec schema which --all

Đầu ra hiển thị xem nó đến từ dự án, thư mục người dùng hay gói:

text

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

Lưu ý: OpenSpec cũng hỗ trợ các lược đồ cấp người dùng tại ~/.local/share/openspec/schemas/ để chia sẻ giữa các dự án, nhưng các lược đồ cấp dự án trong openspec/schemas/ được khuyến nghị vì chúng được kiểm soát phiên bản cùng với mã nguồn của bạn.

Ví dụ

Quy trình Làm việc Lặp lại Nhanh

Một quy trình làm việc tối thiểu cho các lần lặp nhanh:

yaml

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Lặp lại nhanh với chi phí tối thiểu

artifacts:
  - id: proposal
    generates: proposal.md
    description: Đề xuất nhanh
    template: proposal.md
    instruction: |
      Tạo một đề xuất ngắn gọn cho sự thay đổi này.
      Tập trung vào cái gì và tại sao, bỏ qua các đặc tả chi tiết.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Danh sách kiểm tra triển khai
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Thêm Artifact Đánh giá

Fork mặc định và thêm bước đánh giá:

bash

openspec schema fork spec-driven with-review

Sau đó chỉnh sửa schema.yaml để thêm:

yaml

  - id: review
    generates: review.md
    description: Danh sách kiểm tra đánh giá trước triển khai
    template: review.md
    instruction: |
      Tạo danh sách kiểm tra đánh giá dựa trên thiết kế.
      Bao gồm các cân nhắc về bảo mật, hiệu suất và kiểm thử.
    requires:
      - design

  - id: tasks
    # ... cấu hình tasks hiện có ...
    requires:
      - specs
      - design
      - review    # Bây giờ tasks cũng yêu cầu review

Lược đồ Cộng đồng

OpenSpec cũng hỗ trợ các lược đồ do cộng đồng duy trì, được phân phối thông qua các kho lưu trữ độc lập. Những điều này cung cấp các quy trình làm việc mang tính định hướng, tích hợp OpenSpec với các công cụ hoặc hệ thống khác, tương tự như cách catalog mở rộng cộng đồng của github/spec-kit hoạt động đối với spec-kit.

Các lược đồ cộng đồng không được đóng gói vào lõi OpenSpec — chúng sống trong các kho lưu trữ riêng biệt với nhịp độ phát hành riêng. Để sử dụng một lược đồ, hãy sao chép gói lược đồ vào thư mục openspec/schemas/<tên-lược đồ>/ của dự án (README của mỗi repo đều có hướng dẫn cài đặt).

Lược đồ	Người duy trì	Kho lưu trữ	Mô tả
`intent-driven`	@harikrishnan83	intent-driven-dev/openspec-schemas	Ghi lại ý định thay đổi, hành vi quan sát được, thiết kế kỹ thuật và các quyết định kiến trúc bền vững trước khi triển khai. Thêm một bảng kê duyệt ADR cục bộ cho thay đổi và ghi các quyết định dài hạn đủ điều kiện dưới dạng ADR bất biến, có thể thay thế.
`superpowers-bridge`	@JiangWay	JiangWay/openspec-schemas	Tích hợp quản lý artifact của OpenSpec với các kỹ năng thực thi của obra/superpowers (brainstorming, viết kế hoạch, TDD thông qua subagents, xem lại mã, hoàn thành). Thêm một artifact `retrospective` ưu tiên bằng chứng, lấp đầy khoảng trống mà Superpowers không bao phủ nguyên bản.
`nanopm`	@nmrtn	nmrtn/nanopm	Quy trình làm việc lấy PM làm trung tâm. Chạy pipeline lập kế hoạch của nanopm (kiểm toán → chiến lược → lộ trình → PRD) phía trước triển khai. Cầu nối giữa lập kế hoạch sản phẩm và quy trình làm việc kỹ thuật dựa trên đặc tả của OpenSpec. Các artifact đọc từ `.nanopm/` nếu có — proposal lấy từ kiểm toán, design lấy từ chiến lược, và tasks lấy từ phân rã PRD.
`e2e-runbooks`	@Lukk17	Lukk17/openspec-schemas	Runbook kiểm thử end-to-end cấp khả năng. Mỗi khả năng có một đặc tả bất biến, một mẫu tasks bất biến và một bản ghi chạy có dấu thời gian cho mỗi lần thực thi. Các khẳng định chỉ là hành vi quan sát được (trạng thái HTTP, thân phản hồi, trạng thái được lưu trữ — không bao giờ là chuỗi con nhật ký); mỗi lần chạy ghi lại UTC bắt đầu/kết thúc, thời lượng và ước tính tốt nhất về tiêu thụ token LLM.
`anvil`	@jikkujoyce	jikkujoyce/openspec-schemas	Quy trình làm việc dựa trên đặc tả với kỷ luật TDD và bước xem xét đối kháng. Luồng: `proposal` → `specs` → `design` → `review` → `test-plan` → `tasks` → `apply` → `verify`. `review` được viết bởi một người xem chỉ đọc ngữ cảnh mới (một mô hình thứ hai khi có sẵn) và phát ra một dòng `VERDICT:` báo hiệu cho agent khóa `test-plan`, `tasks` và `apply`; OpenSpec chỉ kiểm tra xem các artifact có tồn tại hay không, vì vậy hãy thực thi khóa bằng CI hoặc hook của riêng bạn. `test-plan` ánh xạ mọi kịch bản đặc tả sang một bài kiểm tra có tên và đóng vai trò như sổ cái đỏ/xanh mà `verify` kiểm toán.

Muốn đóng góp một lược đồ cộng đồng? Hãy mở một issue với liên kết đến kho lưu trữ của bạn, hoặc gửi PR thêm một hàng vào bảng này.

Xem Thêm

Tham chiếu CLI: Các lệnh Schema - Tài liệu lệnh đầy đủ

Tùy chỉnh ​

Cấu hình dự án ​

Thiết lập nhanh ​

Cách hoạt động ​

Thứ tự phân giải schema ​

Custom Schemas ​

Fork một Lược đồ Có sẵn ​

Tạo Lược đồ Từ Đầu ​

Cấu trúc Lược đồ ​

Mẫu (Templates) ​

Xác thực Lược đồ Của Bạn ​

Sử Dụng Lược Đồ Tùy Chỉnh Của Bạn ​

Gỡ lỗi Việc Phân giải Lược đồ ​

Ví dụ ​

Quy trình Làm việc Lặp lại Nhanh ​

Thêm Artifact Đánh giá ​

Lược đồ Cộng đồng ​

Xem Thêm ​

Tùy chỉnh

Cấu hình dự án

Thiết lập nhanh

Cách hoạt động

Thứ tự phân giải schema

Custom Schemas

Fork một Lược đồ Có sẵn

Tạo Lược đồ Từ Đầu

Cấu trúc Lược đồ

Mẫu (Templates)

Xác thực Lược đồ Của Bạn

Sử Dụng Lược Đồ Tùy Chỉnh Của Bạn

Gỡ lỗi Việc Phân giải Lược đồ

Ví dụ

Quy trình Làm việc Lặp lại Nhanh

Thêm Artifact Đánh giá

Lược đồ Cộng đồng

Xem Thêm