spec-driven
Các artifact của quy trình mặc định: thứ tự, định dạng và thư mục thay đổi mà chúng tạo ra.
spec-driven là schema mặc định tích hợp sẵn của OpenSpec. schema.yaml định nghĩa các trường mà nó thiết lập.
Artifacts
Quy trình soạn thảo bốn artifacts:
| Artifact | Tệp | Mục đích |
|---|---|---|
proposal | proposal.md | Lý do cần thay đổi |
specs | specs/<capability-path>/spec.md, một tệp cho mỗi năng lực | Hành vi nào thay đổi |
design | design.md | Cách xây dựng |
tasks | tasks.md | Danh sách kiểm tra triển khai |
Thứ tự soạn thảo
text
┌─ specs ──┐
proposal ────┤ ├── tasks ── apply
└─ design ─┘Proposal được soạn trước. Specs và design theo sau theo bất kỳ thứ tự nào, và tasks cần cả hai. Việc triển khai (apply) bắt đầu khi tasks.md đã sẵn sàng.
Hai artifact có thể được bỏ qua:
design: khi không có điều kiện nào của nó áp dụng, agent sẽ bỏ qua và vẫn soạntasks.specs: đặtskip_specs: truetrong.openspec.yamlcủa thay đổi.
Ví dụ thư mục thay đổi
Một thay đổi có tên add-user-auth, với đầy đủ các artifact được soạn thảo:
text
openspec/changes/add-user-auth/
├── .openspec.yaml change metadata, written when the change is created
├── proposal.md
├── specs/
│ └── user-auth/
│ └── spec.md one delta spec per capability
├── design.md
└── tasks.mdproposal.md
Thiết lập lý do tại sao thay đổi này cần thiết.
Cấu trúc
Template mà agent nhận được làm định dạng đầu ra (templates/proposal.md):
md
# Đề xuất
## Tại sao
<!-- Giải thích động lực cho thay đổi này. Điều này giải quyết vấn đề gì? Tại sao là bây giờ? -->
## Những gì thay đổi
<!-- Mô tả những gì sẽ thay đổi. Cụ thể về các khả năng mới, sửa đổi hoặc loại bỏ. -->
## Khả năng
### Khả năng mới
<!-- Các khả năng được giới thiệu. Đặt tên cho mỗi khả năng theo hành vi hệ thống
gắn kết có thể sở hữu các yêu cầu liên quan khi hệ thống phát triển. Không đặt tên
theo nhiệm vụ triển khai hoặc phần của đề xuất. Tránh tên chung chung bao trùm.
Sử dụng kebab-case cho các đoạn đường dẫn bạn giới thiệu (ví dụ: user-auth hoặc identity/user-auth)
theo tổ chức spec hiện có của dự án. Mỗi khả năng tạo ra
specs/<capability-path>/spec.md. -->
- `<capability-path>`: <mô tả ngắn gọn về khả năng này bao gồm những gì>
### Khả năng sửa đổi
<!-- Các khả năng hiện có có YÊU CẦU đang thay đổi (không chỉ triển khai).
Chỉ liệt kê ở đây nếu hành vi ở cấp spec thay đổi. Mỗi khả năng cần một tệp spec delta.
Sử dụng đường dẫn hiện có chính xác dưới openspec/specs/. Để trống nếu không có
thay đổi yêu cầu. Một thay đổi không có khả năng nào (refactor thuần, tooling, docs)
phải đặt `skip_specs: true` trong .openspec.yaml - openspec validate từ chối
thay đổi không có delta mà không có dấu hiệu đó. Không bịa ra yêu cầu chỉ để
thỏa mãn việc xác thực. -->
- `<existing-capability-path>`: <yêu cầu nào đang thay đổi>
## Tác động
<!-- Mã, API, dependency, hệ thống bị ảnh hưởng -->Hướng dẫn
Chỉ dẫn được gửi đến agent khi nó soạn artifact này (từ schema.yaml):
md
Tạo tài liệu đề xuất thiết lập TẠI SAO thay đổi này cần thiết.
Các phần:
- **Tại sao**: 1-2 câu về vấn đề hoặc cơ hội. Điều này giải quyết vấn đề gì? Tại sao là bây giờ?
- **Những gì thay đổi**: Danh sách bullet các thay đổi. Cụ thể về các khả năng mới, sửa đổi hoặc loại bỏ. Đánh dấu thay đổi đột phá với **BREAKING**.
- **Khả năng**: Xác định những spec sẽ được tạo hoặc sửa đổi:
- **Khả năng mới**: Liệt kê các khả năng được giới thiệu. Mỗi khả năng trở thành một `specs/<capability-path>/spec.md` mới. Đặt tên cho mỗi khả năng theo hành vi hệ thống bền vững (ví dụ: `user-auth`), không phải công việc trong thay đổi này (ví dụ: `add-login-endpoint`). Chọn ranh giới gắn kết có thể sở hữu các yêu cầu liên quan khi hệ thống phát triển; tránh các khả năng chung chung bao trùm. Sử dụng kebab-case cho các đoạn đường dẫn bạn giới thiệu (ví dụ: `user-auth` hoặc `identity/user-auth`) và theo tổ chức spec hiện có của dự án.
- **Khả năng sửa đổi**: Liệt kê các khả năng hiện có có YÊU CẦU đang thay đổi. Chỉ bao gồm nếu hành vi ở cấp spec thay đổi (không chỉ chi tiết triển khai). Mỗi khả năng cần một tệp spec delta. Sử dụng đường dẫn hiện có chính xác dưới `openspec/specs/`. Để trống nếu không có thay đổi yêu cầu.
- **Tác động**: Mã, API, dependency hoặc hệ thống bị ảnh hưởng.
QUAN TRỌNG: Phần Khả năng là rất quan trọng. Nó tạo ra hợp đồng giữa
pha đề xuất và pha specs. Nghiên cứu các spec hiện có trước khi điền phần này:
chạy `openspec list --specs` để xem danh mục khả năng của dự án, sau đó
`openspec show "<spec-id>" --type spec --json --no-scenarios` cho bất kỳ
spec nào trông liên quan - lệnh này trả về mục đích và nội dung yêu cầu của
khả năng mà không kéo toàn bộ tệp spec vào ngữ cảnh. Thêm `--store "<id>"` vào
cả hai lệnh chỉ khi có standalone store đã đăng ký, và giữ `--type
spec`: một thay đổi và một spec trùng tên nếu không sẽ gây lỗi ambiguous-item.
`openspec list` không có `--specs` liệt kê các thay đổi đang thực hiện, không phải
specs - nó không bao giờ hiển thị những gì dự án đã bao gồm. Sử dụng lại đường dẫn
chính xác của khả năng hiện có thay vì giới thiệu tên gần trùng lặp.
Bản đọc đã lọc chỉ là tổng quan. Trước khi quyết định những gì đã được bao gồm
hoặc những gì nên thay đổi, hãy đọc đầy đủ từng spec liên quan, bao gồm
cả scenarios, với `openspec show "<spec-id>" --type spec` (cùng quy tắc `--store`).
Mỗi khả năng được liệt kê ở đây sẽ cần một tệp spec tương ứng.
Mọi thay đổi phải khai báo ít nhất một khả năng (mới hoặc
sửa đổi) hoặc tường minh từ chối specs: `openspec validate` từ chối
thay đổi không có delta trừ khi `.openspec.yaml` của thay đổi đặt
`skip_specs: true`. Chỉ sử dụng `skip_specs: true` khi không có thay đổi
hành vi ở cấp spec (refactor thuần, tooling, docs) - specs mô tả
hành vi, vì vậy nếu hành vi không thay đổi, không spec nào nên thay đổi.
Không bịa ra yêu cầu chỉ để thỏa mãn việc xác thực.
Giữ ngắn gọn (1-2 trang). Tập trung vào "tại sao" chứ không phải "thế nào" -
chi tiết triển khai thuộc về design.md.
Đây là nền tảng - specs, design và tasks đều xây dựng trên đó.Delta specs (spec.md)
Định nghĩa những hành vi thay đổi, với một delta spec cho mỗi khả năng mà proposal liệt kê.
Mỗi delta spec là spec.md bên trong thư mục khả năng của nó. openspec validate và openspec archive từ chối các phần delta được viết trong bất kỳ tệp nào khác dưới specs/, chẳng hạn specs/user-auth.md, vì archive không bao giờ hợp nhất chúng.
Cấu trúc
Template mà agent nhận được làm định dạng đầu ra (templates/spec.md):
md
# Spec Delta
## Mục đích
<!-- Chỉ dành cho khả năng mới: một hoặc hai câu (50+ ký tự) về khả năng này dùng để làm gì. Xóa phần này đối với khả năng hiện có. -->
## YÊU CẦU THÊM VÀO
### Yêu cầu: <!-- tên yêu cầu -->
<!-- nội dung yêu cầu -->
#### Kịch bản: <!-- tên kịch bản -->
- **KHI** <!-- điều kiện -->
- **THÌ** <!-- kết quả mong đợi -->Hướng dẫn
Chỉ dẫn được gửi đến agent khi nó soạn artifact này (từ schema.yaml):
md
Tạo các tệp đặc tả định nghĩa HỆ THỐNG nên làm gì.
Một spec là hợp đồng hành vi, không phải kế hoạch triển khai.
Nội dung spec tốt:
- Hành vi quan sát được mà người dùng hoặc hệ thống downstream dựa vào
- Đầu vào, đầu ra và điều kiện lỗi
- Ràng buộc bên ngoài (bảo mật, quyền riêng tư, độ tin cậy, tương thích)
- Các kịch bản có thể kiểm thử hoặc xác thực rõ ràng
Tránh trong specs:
- Tên class/function nội bộ
- Lựa chọn thư viện hoặc framework
- Chi tiết triển khai từng bước
- Kế hoạch thực thi chi tiết (những thứ này thuộc về design.md hoặc tasks.md)
Kiểm tra nhanh: nếu triển khai có thể thay đổi mà không thay đổi hành vi
nhìn thấy từ bên ngoài, nó có thể không thuộc về spec.
Tạo một tệp spec cho mỗi khả năng được liệt kê trong phần Khả năng của proposal.
`<capability-path>` là thư mục spec tương đối so với `specs/` (ví dụ,
`user-auth` hoặc `identity/user-auth`). Giữ nguyên đường dẫn đầy đủ:
- Khả năng mới: sử dụng đường dẫn chính xác từ proposal tại `specs/<capability-path>/spec.md`. Bất kỳ đoạn đường dẫn nào mới được giới thiệu trong proposal phải là kebab-case. Theo tổ chức hiện có của dự án; không thêm cấp domain mới khi dự án sử dụng bố cục phẳng.
- Khả năng sửa đổi: sử dụng đường dẫn hiện có chính xác từ `openspec/specs/<capability-path>/` khi tạo delta tại `specs/<capability-path>/spec.md`. Chạy `openspec list --specs` để xác nhận đường dẫn đó trước khi viết delta, thêm `--store "<id>"` chỉ khi có standalone store đã đăng ký - đường dẫn gõ sai hoặc bịa ra sẽ nhắm đến khả năng không tồn tại thay vì khả năng bạn muốn. Không di chuyển hoặc đổi tên khả năng.
Viết các tệp spec một tại một, để người dùng thấy tiến độ và
lần chạy bị gián đoạn vẫn giữ các tệp đã viết:
- Trước khi viết bất cứ thứ gì, so sánh các khả năng proposal liệt kê
với các tệp `specs/<capability-path>/spec.md` đã tồn tại,
và bắt đầu với khả năng đầu tiên chưa có tệp. Không viết lại
tệp đã tồn tại trừ khi người dùng yêu cầu.
- Trước mỗi tệp, nói một dòng bạn đang viết khả năng nào.
- Viết mỗi tệp ngay khi bạn đã soạn xong. Không lên kế hoạch mọi tệp
trước khi viết tệp đầu tiên.
- Dừng khi mọi khả năng proposal liệt kê đã có tệp.
Phải có ít nhất một tệp spec trừ khi `.openspec.yaml` của thay đổi đặt
`skip_specs: true` (không có thay đổi hành vi ở cấp spec) - `openspec validate`
từ chối thay đổi không có delta mà không có dấu hiệu đó. Nếu proposal không liệt kê
khả năng nào và `skip_specs` không được đặt, hãy xem lại proposal trước.
Các thao tác delta (sử dụng tiêu đề ##):
- **YÊU CẦU THÊM VÀO**: Khả năng mới
- **YÊU CẦU SỬA ĐỔI**: Hành vi thay đổi - PHẢI bao gồm nội dung cập nhật đầy đủ
- **YÊU CẦU LOẠI BỎ**: Tính năng không còn dùng - PHẢI bao gồm **Lý do** và **Chuyển đổi**
- **YÊU CẦU ĐỔI TÊN**: Chỉ thay đổi tên - sử dụng định dạng FROM:/TO:
Yêu cầu định dạng:
- Mỗi yêu cầu: `### Yêu cầu: <tên>` theo sau bằng mô tả
- Sử dụng SHALL/MUST cho yêu cầu chuẩn (tránh should/may)
- Mỗi kịch bản: `#### Kịch bản: <tên>` với định dạng KHI/THÌ
- **QUAN TRỌNG**: Kịch bản PHẢI sử dụng đúng 4 dấu hashtag (`####`). Sử dụng 3 dấu hashtag hoặc bullet sẽ thất bại âm thầm.
- Mọi yêu cầu PHẢI có ít nhất một kịch bản.
- Mọi kịch bản PHẢI có bước KHI/GIVEN (kích hoạt) và bước THÌ (kết quả). Kịch bản chỉ có các dòng AND hoặc văn xuôi vẫn được tính là kịch bản, nhưng `openspec validate` gắn cờ cảnh báo: xác thực thường vẫn đạt, nhưng `openspec validate --strict` thất bại.
- Giữ mô tả của mỗi yêu cầu (văn bản giữa `### Yêu cầu:` và kịch bản đầu tiên) tối đa 500 ký tự. `openspec validate` gắn cờ mô tả dài trong YÊU CẦU THÊM VÀO và trong spec chính. Đây là cảnh báo: xác thực thường vẫn đạt, nhưng `openspec validate --strict` thất bại. Khi viết yêu cầu mới, nêu một hành vi mỗi yêu cầu: chuyển ví dụ và trường hợp biên vào kịch bản, và tách yêu cầu bao gồm nhiều hành vi thành các khối `### Yêu cầu:` riêng biệt, mỗi khối có kịch bản riêng. Trong YÊU CẦU SỬA ĐỔI, giữ nguyên khối yêu cầu hiện có; không tách, cắt hoặc viết lại văn bản hiện có chỉ để đáp ứng độ dài. Chỉ tách yêu cầu hiện có dài khi người dùng yêu cầu, trong thay đổi làm cho mục đích đó: trong YÊU CẦU SỬA ĐỔI, giữ tiêu đề và mọi kịch bản, cắt mô tả xuống một hành vi mà không thay đổi nghĩa, sau đó thêm mỗi hành vi đã loại bỏ thành YÊU CẦU THÊM VÀO riêng với kịch bản riêng.
Chỉ khả năng mới: phần đầu tiên của spec delta là `## Mục đích` -
một hoặc hai câu (50+ ký tự, hoặc `openspec validate --strict`
báo cáo nó quá ngắn) mô tả khả năng dùng để làm gì. Archive
sao chép nó vào spec chính mà nó tạo; không có nó thì spec chính mới
để lại placeholder `TBD ... Update Purpose after archive` để điền tay.
Không thêm `## Mục đích` vào delta cho khả năng hiện có -
spec đó đã có một và delta bị bỏ qua. Để thay đổi Mục đích của
khả năng hiện có - bao gồm placeholder `TBD` còn sót lại -
sửa trực tiếp `<planningHome.root>/openspec/specs/<capability-path>/spec.md`.
`planningHome.root` đến từ phản hồi `openspec instructions ... --json`.
Luôn sử dụng nó thay vì đường dẫn tương đối repo: nó
phân giải tới store bất cứ khi nào thay đổi nằm trong store - cho dù đó
đến từ `--store`, con trỏ `store:` của dự án, hoặc store mặc định toàn cục -
và tới repo hiện tại nếu không. Không cố gắng tìm ra
trường hợp nào áp dụng; trường đã có sẵn.
Quy trình YÊU CẦU SỬA ĐỔI:
1. Định vị yêu cầu hiện có trong `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (cùng root nhận biết store như trên)
2. Sao chép TOÀN BỘ khối yêu cầu (từ `### Yêu cầu:` qua tất cả kịch bản)
3. Dán vào `## YÊU CẦU SỬA ĐỔI` và sửa để phản ánh hành vi mới
4. Đảm bảo văn bản tiêu đề khớp chính xác (không phân biệt khoảng trắng)
Cái bẫy phổ biến: Sử dụng YÊU CẦU SỬA ĐỔI với nội dung một phần làm mất chi tiết lúc archive.
Nếu thêm mối quan tâm mới mà không thay đổi hành vi hiện có, sử dụng YÊU CẦU THÊM VÀO.
Ví dụ (một khả năng mới, vì vậy phần đầu tiên của nó là `## Mục đích`):
```
# Spec DeltaMục đích
Cho phép người dùng xuất dữ liệu của họ khỏi sản phẩm ở định dạng di động.
Các yêu cầu được thêm vào
Yêu cầu: Người dùng có thể xuất dữ liệu
Hệ thống PHẢI cho phép người dùng xuất dữ liệu của họ ở định dạng CSV.
Kịch bản: Xuất thành công
- WHEN người dùng nhấp vào nút "Export"
- THEN hệ thống tải xuống một file CSV chứa tất cả dữ liệu người dùng
Các yêu cầu bị loại bỏ
Yêu cầu: Legacy export
Lý do: được thay thế bởi hệ thống xuất dữ liệu mới Di chuyển: sử dụng điểm cuối xuất dữ liệu mới tại /api/v2/export
Specs should be testable - each scenario is a potential test case.design.md
Giải thích cách thực hiện thay đổi. Chỉ được phác thảo khi thay đổi cần đến nó.
Cấu trúc
Mẫu mà agent nhận được dưới dạng định dạng đầu ra (templates/design.md):
md
# Design
## Context
<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
## Goals / Non-Goals
**Goals:**
<!-- What this design aims to achieve -->
**Non-Goals:**
<!-- What is explicitly out of scope -->
## Decisions
<!-- Key design decisions with rationale and alternatives considered -->
## Risks / Trade-offs
<!-- Known risks and trade-offs -->Hướng dẫn
Lời hướng dẫn gửi đến agent khi nó phác thảo artifact này (từ schema.yaml):
md
Create the design document that explains HOW to implement the change.
When to include design.md (create only if any apply):
- Cross-cutting change (multiple services/modules) or new architectural pattern
- New external dependency or significant data model changes
- Security, performance, or migration complexity
- Ambiguity that benefits from technical decisions before coding
Sections:
- **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
- **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
- **Open Questions**: Unknowns that can safely be answered later without
changing the specs, the approach, or the task breakdown. Omit if none.
Open questions are for genuinely deferrable unknowns, not decisions you
skipped. If a question would change the specs, the chosen approach, or the
task breakdown, resolve it now - ask the user instead of guessing.
Focus on architecture and approach, not line-by-line implementation.
The proposal covers why and what; design covers how. Reference the
proposal for motivation and, once written, the specs for requirements -
if a section would only restate them, point to them instead.
Good design docs explain the "why" behind technical decisions.tasks.md
Phân công việc thực hiện thành các task có thể kiểm tra được. apply theo dõi tiến độ tại đây.
Cấu trúc
Mẫu mà agent nhận được dưới dạng định dạng đầu ra (templates/tasks.md):
md
# Tasks
## 1. <!-- Task Group Name -->
- [ ] 1.1 <!-- Task description -->
- [ ] 1.2 <!-- Task description -->
## 2. <!-- Task Group Name -->
- [ ] 2.1 <!-- Task description -->
- [ ] 2.2 <!-- Task description -->Hướng dẫn
Lời hướng dẫn gửi đến agent khi nó phác thảo artifact này (từ schema.yaml):
md
Create the task list that breaks down the implementation work.
Before writing tasks, check design.md for Open Questions. If any of them
would change what gets built, resolve them with the user first - do not
bake an unstated assumption into the task list.
**IMPORTANT: Follow the template below for tracked tasks.** The apply phase parses
checkbox format to track progress. A box holding only `x` counts as done,
upper or lower case and with any spacing, so `- [ x]` is done too. Every
other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
unfinished. A line with no checkbox is not tracked at all.
Guidelines:
- Group related tracked tasks under ## numbered headings
- Each tracked task MUST be a checkbox: `- [ ] X.Y Task description`
- Tasks should be small enough to complete in one session
- Order tasks by dependency (what must be done first?)
- Track implementation and verification work that can be completed before
archive. If the requested workflow includes archive or work that requires
this change to be archived, preserve those steps as plain bullets in an
optional `## Workflow follow-up` section at the end of tasks.md. These
bullets are reference information outside tracked task progress.
- Each task MUST state how to verify completion (a test, command,
observable behavior, or delivered artifact). Put the verification in
that task's checkbox description. Use a separate verification task only
when it checks broader integration or system behavior that spans
multiple implementation tasks.
- Each task group MUST land the tests and documentation its own work
calls for. Do NOT collect testing or documentation into a final group -
when a late group first exercises work from an early one, the failures
cascade back through every group in between and force rework. A group
whose work calls for neither, such as scaffolding or dependency setup,
carries neither. A final group is for integration checks only, not for
the tests and docs an earlier group owed.
Example:
```
# Tasks
## 1. Setup
- [ ] 1.1 Create new module structure and verify expected files are present
- [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
## 2. Core Implementation
- [ ] 2.1 Implement data export function and verify the export test passes
- [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
- [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
```
When applicable, append workflow follow-up as plain bullets, for example:
```
## Workflow follow-up
- Archive the change after the project's review requirements are satisfied.
- Verify the archived result.
```
Reference specs for what needs to be built, design for how to build it.Apply
Bàn giao từ lập kế hoạch đến thực hiện. Apply là giai đoạn làm việc qua tasks.md, không phải là một artifact.
- Bắt đầu: khi
tasks.mdtồn tại và liệt kê ít nhất một task. - Theo dõi: các ô checkbox trong
tasks.md. Đánh dấu chúng là bản ghi tiến độ. - Kết thúc: mọi ô checkbox đều được đánh dấu. OpenSpec sau đó đề xuất lưu trữ thay đổi.
Cài đặt
Cài đặt apply (từ schema.yaml):
yaml
apply:
requires: [tasks]
tracks: tasks.md
# instruction: shown belowHướng dẫn
Lời hướng dẫn gửi đến agent khi bắt đầu thực hiện (từ schema.yaml):
md
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.schema.yaml
Toàn bộ schema.yaml, với phần hướng dẫn bị loại bỏ. Mỗi phần được hiển thị đầy đủ ở mục trên.
yaml
name: spec-driven
version: 1
description: Default OpenSpec workflow - proposal → specs → design → tasks
artifacts:
- id: proposal
generates: proposal.md
description: Initial proposal document outlining the change
template: proposal.md
# instruction: shown in full under proposal.md above
requires: []
- id: specs
generates: "specs/**/*.md"
description: Detailed specifications for the change
template: spec.md
# instruction: shown in full under Delta specs above
requires:
- proposal
- id: design
generates: design.md
description: Technical design document with implementation details
template: design.md
# instruction: shown in full under design.md above
requires:
- proposal
- id: tasks
generates: tasks.md
description: Implementation checklist with trackable tasks
template: tasks.md
# instruction: shown in full under tasks.md above
requires:
- specs
- design
apply:
requires: [tasks]
tracks: tasks.md
# instruction: shown below