Di chuyển sang OPSX
Hướng dẫn này giúp bạn chuyển đổi từ quy trình làm việc OpenSpec cũ sang OPSX. Việc di chuyển được thiết kế để diễn ra suôn sẻ—các công việc hiện có của bạn sẽ được bảo toàn, và hệ thống mới mang lại nhiều linh hoạt hơn.
Có gì thay đổi?
OPSX thay thế quy trình làm việc bị khóa theo giai đoạn cũ bằng cách tiếp cận dựa trên hành động, linh hoạt hơn. Dưới đây là sự thay đổi cốt lõi:
| Khía cạnh | Cũ (Legacy) | OPSX |
|---|---|---|
| Lệnh | /openspec:proposal, /openspec:apply, /openspec:archive | Mặc định: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (có thể tùy chọn thêm các lệnh mở rộng) |
| Quy trình làm việc | Tạo tất cả các tài liệu cùng một lúc | Tạo từng bước hoặc tạo tất cả cùng lúc—tùy chọn của bạn |
| Quay lại | Các cổng giai đoạn cứng nhắc | Tự nhiên—cập nhật bất kỳ tài liệu nào bất cứ lúc nào |
| Tùy chỉnh | Cấu trúc cố định | Dựa trên Schema, hoàn toàn có thể tùy biến |
| Cấu hình | CLAUDE.md với các đánh dấu + project.md | Cấu hình gọn gàng trong openspec/config.yaml |
Sự thay đổi về triết lý: Công việc không phải là tuyến tính. OPSX ngừng giả vờ rằng nó là như vậy.
Trước Khi Bắt Đầu
Công Việc Hiện Có Của Bạn Được An Toàn
Quy trình di chuyển được thiết kế với mục tiêu bảo tồn:
- Các thay đổi đang hoạt động trong
openspec/changes/— Được bảo tồn hoàn toàn. Bạn có thể tiếp tục chúng bằng các lệnh OPSX. - Các thay đổi đã lưu trữ — Không bị thay đổi. Lịch sử của bạn vẫn nguyên vẹn.
- Các spec chính trong
openspec/specs/— Không bị thay đổi. Đây là nguồn sự thật của bạn. - Nội dung của bạn trong CLAUDE.md, AGENTS.md, v.v. — Được bảo tồn. Chỉ các khối đánh dấu OpenSpec bị xóa; mọi thứ bạn viết vẫn còn.
Những Gì Bị Xóa
Chỉ các tệp do OpenSpec quản lý đang được thay thế:
| Gì | Tại Sao |
|---|---|
| Các thư mục/tệp lệnh slash cũ | Được thay thế bằng hệ thống skills mới |
openspec/AGENTS.md | Bộ kích hoạt quy trình đã lỗi thời |
Các đánh dấu OpenSpec trong CLAUDE.md, AGENTS.md, v.v. | Không còn cần thiết |
Vị trí lệnh cũ theo từng công cụ (ví dụ—công cụ của bạn có thể khác):
- Claude Code:
.claude/commands/openspec/ - Cursor:
.cursor/commands/openspec-*.md - Devin Desktop, trước đây là Windsurf:
.windsurf/workflows/openspec-*.md - Cline:
.clinerules/workflows/openspec-*.md - Roo:
.roo/commands/openspec-*.md - GitHub Copilot:
.github/prompts/openspec-*.prompt.md(chỉ trong phần mở rộng IDE; không hỗ trợ trong Copilot CLI) - Codex: OpenSpec hiện sử dụng đường dẫn chính thức
.agents/skills/openspec-*. Các tệpSKILL.mddo OpenSpec quản lý dưới đường dẫn.codex/skillstrước đây chỉ được điều chỉnh sau khi các bản thay thế đã tồn tại; các tệp tùy chỉnh và các bản sao phân kỳ vẫn giữ nguyên vị trí. Nếu cây.agentschưa được đánh dấu đã chứa các skills OpenSpec, OpenSpec sẽ bảo tồn cách hiển thị Codex ($openspec-*) hoặc chung (/openspec-*) hiện có thay vì đoán từ thư mục cũ. Chọncodexrõ ràng bằngopenspec initđể chuyển quyền sở hữu. Việc dọn dẹp prompt cũ vẫn chỉ nhắm vào các tên tệp được OpenSpec cho phép trong$CODEX_HOME/promptshoặc~/.codex/prompts. - Và các công cụ khác (Augment, Continue, Amazon Q, v.v.)
Quy trình di chuyển sẽ phát hiện các công cụ bạn đã cấu hình và dọn dẹp các tệp cũ của chúng.
Danh sách xóa có thể trông dài, nhưng tất cả đều là các tệp mà OpenSpec ban đầu đã tạo. Nội dung của riêng bạn không bao giờ bị xóa.
Những Gì Cần Sự Chú Ý Của Bạn
Một tệp yêu cầu di chuyển thủ công:
openspec/project.md — Tệp này không bị xóa tự động vì nó có thể chứa ngữ cảnh dự án mà bạn đã viết. Bạn sẽ cần:
- Xem xét nội dung của nó
- Di chuyển ngữ cảnh hữu ích sang
openspec/config.yaml(xem hướng dẫn bên dưới) - Xóa tệp khi đã sẵn sàng
Tại sao chúng tôi thực hiện thay đổi này:
Tệp project.md cũ bị động—các agent có thể đọc nó, có thể không, có thể quên những gì đã đọc. Chúng tôi nhận thấy độ tin cậy không nhất quán.
Ngữ cảnh config.yaml mới được chủ động tiêm vào mọi yêu cầu lập kế hoạch OpenSpec. Điều này có nghĩa là các quy ước dự án, công nghệ và quy tắc của bạn luôn hiện diện khi AI tạo các sản phẩm. Độ tin cậy cao hơn.
Sự đánh đổi:
Vì ngữ cảnh được tiêm vào mọi yêu cầu, bạn sẽ muốn viết ngắn gọn. Tập trung vào những gì thực sự quan trọng:
- Công nghệ và các quy ước chính
- Các ràng buộc không hiển nhiên mà AI cần biết
- Các quy tắc thường bị bỏ qua trước đây
Đừng lo lắng về việc làm cho nó hoàn hảo. Chúng tôi vẫn đang học hỏi điều gì hoạt động tốt nhất ở đây, và chúng tôi sẽ cải thiện cách tiêm ngữ cảnh khi thử nghiệm.
Chạy Quy Trình Di Chuyển
Cả openspec init và openspec update đều phát hiện các tệp cũ và hướng dẫn bạn qua cùng một quy trình dọn dẹp. Sử dụng lệnh phù hợp với tình huống của bạn:
- Cài đặt mới mặc định dùng profile
core(propose,explore,apply,update,sync,archive). - Cài đặt đã di chuyển sẽ bảo tồn các quy trình làm việc đã cài đặt trước đó bằng cách ghi một profile
customkhi cần.
Sử Dụng openspec init
Chạy lệnh này nếu bạn muốn thêm công cụ mới hoặc cấu hình lại các công cụ được thiết lập:
openspec initLệnh init phát hiện các tệp cũ và hướng dẫn bạn dọn dẹp:
Upgrading to the new OpenSpec
OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.
Files to remove
No user content to preserve:
• .claude/commands/openspec/
• openspec/AGENTS.md
Files to update
OpenSpec markers will be removed, your content preserved:
• CLAUDE.md
• AGENTS.md
Needs your attention
• openspec/project.md
We won't delete this file. It may contain useful project context.
The new openspec/config.yaml has a "context:" section for planning
context. This is included in every OpenSpec request and works more
reliably than the old project.md approach.
Review project.md, move any useful content to config.yaml's context
section, then delete the file when ready.
? Upgrade and clean up legacy files? (Y/n)Điều gì xảy ra khi bạn nói có:
- Các thư mục lệnh slash cũ bị xóa
- Các đánh dấu OpenSpec bị gỡ khỏi
CLAUDE.md,AGENTS.md, v.v. (nội dung của bạn vẫn còn) openspec/AGENTS.mdbị xóa- Các skills mới được cài đặt vào
.claude/skills/ openspec/config.yamlđược tạo với schema mặc định
Sử Dụng openspec update
Chạy lệnh này nếu bạn chỉ muốn di chuyển và làm mới các công cụ hiện có lên phiên bản mới nhất:
openspec updateLệnh update cũng phát hiện và dọn dẹp các sản phẩm cũ, sau đó làm mới các skills/commands được tạo để phù hợp với profile và cài đặt phân phối hiện tại của bạn.
Môi Trường Không Tương Tác / CI
Đối với di chuyển bằng script:
openspec init --force --tools claudeCờ --force bỏ qua các lời nhắc và tự động chấp nhận dọn dẹp.
Điều này bao gồm việc dọn dẹp các tệp prompt Codex do OpenSpec quản lý trong thư mục prompt Codex toàn cục. Việc dọn dẹp chỉ nhắm vào các tên tệp prompt Codex cũ được OpenSpec cho phép, chỉ xóa chúng sau khi các skills thay thế .agents/skills/openspec-* đã tồn tại, và bảo tồn tất cả các tệp khác.
Di Chuyển project.md Sang config.yaml
Tệp openspec/project.md cũ là tệp markdown tự do cho ngữ cảnh dự án. Tệp openspec/config.yaml mới có cấu trúc và—quan trọng hơn—được tiêm vào mọi yêu cầu lập kế hoạch để các quy ước của bạn luôn hiện diện khi AI làm việc.
Trước (project.md)
# Project Context
This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.
## Conventions
- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specificationsSau (config.yaml)
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
Testing: Jest with React Testing Library
API: RESTful, documented in docs/api.md
We maintain backwards compatibility for all public APIs
rules:
proposal:
- Include rollback plan for risky changes
specs:
- Use Given/When/Then format for scenarios
- Reference existing patterns before inventing new ones
design:
- Include sequence diagrams for complex flowsNhững Khác Biệt Chính
| project.md | config.yaml |
|---|---|
| Markdown tự do | YAML có cấu trúc |
| Một khối văn bản duy nhất | Ngữ cảnh riêng và quy tắc theo từng sản phẩm |
| Không rõ khi nào được sử dụng | Ngữ cảnh xuất hiện trong TẤT CẢ sản phẩm; quy tắc chỉ xuất hiện trong sản phẩm khớp |
| Không có lựa chọn schema | Trường schema: rõ ràng thiết lập quy trình làm việc mặc định |
Giữ Lại Gì, Bỏ Gì
Khi di chuyển, hãy chọn lọc. Tự hỏi: "AI có cần điều này cho mọi yêu cầu lập kế hoạch không?"
Ứng cử viên tốt cho context:
- Công nghệ (ngôn ngữ, framework, cơ sở dữ liệu)
- Các mẫu kiến trúc chính (monorepo, microservices, v.v.)
- Các ràng buộc không hiển nhiên ("chúng ta không thể dùng thư viện X vì...")
- Các quy ước quan trọng thường bị bỏ qua
Chuyển sang rules: thay vì
- Định dạng cụ thể cho từng sản phẩm ("dùng Given/When/Then trong specs")
- Tiêu chí đánh giá ("các đề xuất phải bao gồm kế hoạch hoàn tác")
- Những điều này chỉ xuất hiện cho sản phẩm khớp, giữ các yêu cầu khác nhẹ hơn
Loại bỏ hoàn toàn
- Các thực hành tốt chung mà AI đã biết
- Các giải thích dài dòng có thể tóm tắt
- Ngữ cảnh lịch sử không ảnh hưởng đến công việc hiện tại
Các Bước Di Chuyển
Tạo config.yaml (nếu chưa được tạo bởi init):
yamlschema: spec-drivenThêm ngữ cảnh của bạn (ngắn gọn—điều này đi vào mọi yêu cầu):
yamlcontext: | Your project background goes here. Focus on what the AI genuinely needs to know.Thêm quy tắc theo từng sản phẩm (tùy chọn):
yamlrules: proposal: - Your proposal-specific guidance specs: - Your spec-writing rulesXóa project.md sau khi bạn đã di chuyển mọi thứ hữu ích.
Đừng suy nghĩ quá nhiều. Bắt đầu với những điều thiết yếu và lặp lại. Nếu bạn nhận thấy AI bỏ sót điều gì quan trọng, hãy thêm vào. Nếu ngữ cảnh cảm thấy phình to, hãy cắt giảm. Đây là một tài liệu sống.
Cần Giúp Đỡ? Dùng Prompt Này
Nếu bạn không chắc cách cô đọng project.md của mình, hãy hỏi trợ lý AI:
I'm migrating from OpenSpec's old project.md to the new config.yaml format.
Here's my current project.md:
[paste your project.md content]
Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)
Leave out anything generic that AI models already know. Be ruthless about brevity.AI sẽ giúp bạn xác định điều gì là thiết yếu và điều gì có thể cắt giảm.
Các Lệnh Mới
Sự khả dụng của lệnh phụ thuộc vào profile:
Mặc định (profile core):
| Lệnh | Mục Đích |
|---|---|
/opsx:propose | Tạo một thay đổi và sinh các sản phẩm lập kế hoạch trong một bước |
/opsx:explore | Suy nghĩ về các ý tưởng không có cấu trúc |
/opsx:apply | Triển khai các tác vụ từ tasks.md |
/opsx:update | Tu chỉnh các sản phẩm lập kế hoạch của một thay đổi và giữ chúng nhất quán |
/opsx:sync | Hợp nhất các delta specs vào specs chính |
/opsx:archive | Hoàn tất và lưu trữ thay đổi |
Quy trình mở rộng (chọn tùy chỉnh):
| Lệnh | Mục Đích |
|---|---|
/opsx:new | Bắt đầu một khung thay đổi mới |
/opsx:continue | Tạo sản phẩm tiếp theo (một cái một lúc) |
/opsx:ff | Fast-forward—tạo các sản phẩm lập kế hoạch cùng lúc |
/opsx:verify | Xác thực triển khai khớp với specs |
/opsx:bulk-archive | Lưu trữ nhiều thay đổi cùng lúc |
/opsx:onboard | Quy trình onboarding đầu-cuối có hướng dẫn |
Bật các lệnh mở rộng bằng openspec config profile, sau đó chạy openspec update.
Ánh Xạ Lệnh Từ Bản Cũ
| Bản Cũ | OPSX Tương Đương |
|---|---|
/openspec:proposal | /opsx:propose (mặc định) hoặc /opsx:new rồi /opsx:ff (mở rộng) |
/openspec:apply | /opsx:apply |
/openspec:archive | /opsx:archive |
Các Khả Năng Mới
Các khả năng này là một phần của bộ lệnh quy trình mở rộng.
Tạo sản phẩm chi tiết:
/opsx:continueTạo một sản phẩm một lúc dựa trên các phụ thuộc. Sử dụng khi bạn muốn xem xét từng bước.
Chế độ khám phá:
/opsx:exploreSuy nghĩ về các ý tưởng cùng một đối tác trước khi cam kết vào một thay đổi.
Hiểu về Kiến trúc Mới
Từ Khóa chặt chẽ sang Linh hoạt
Quy trình cũ bắt buộc sự tiến triển theo tuyến tính:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │
│ PHASE │ │ PHASE │ │ PHASE │
└──────────────┘ └──────────────┘ └──────────────┘
Nếu bạn đang ở giai đoạn thực hiện và nhận ra thiết kế sai?
Thật không may. Các cửa pha (phase gates) không cho phép bạn quay lại dễ dàng.OPSX sử dụng các hành động (actions), không phải các pha (phases):
┌───────────────────────────────────────────────┐
│ ACTIONS (not phases) │
│ │
│ new ◄──► continue ◄──► apply ◄──► archive │
│ │ │ │ │ │
│ └──────────┴───────────┴─────────────┘ │
│ any order │
└───────────────────────────────────────────────┘Đồ thị phụ thuộc
Các sản phẩm trung gian (artifacts) tạo thành một đồ thị có hướng. Các phụ thuộc là điều kiện tiên quyết, không phải rào cản:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)Khi bạn chạy /opsx:continue, hệ thống sẽ kiểm tra những gì đã sẵn sàng và đề xuất sản phẩm trung gian tiếp theo. Bạn cũng có thể tạo nhiều sản phẩm trung gian sẵn sàng theo bất kỳ thứ tự nào.
Kỹ năng (Skills) so với Lệnh
Hệ thống cũ sử dụng các tệp lệnh cụ thể cho công cụ:
.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.mdOPSX sử dụng tiêu chuẩn skills đang phát triển:
.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...Skills được nhận diện trên nhiều công cụ lập trình AI khác nhau và cung cấp siêu dữ liệu phong phú hơn.
Codex chỉ hỗ trợ skills trong OPSX. OpenSpec không còn tạo các tệp prompt tùy chỉnh cho Codex; hãy sử dụng các thư mục .agents/skills/openspec-* được tạo ra thay thế.
Tiếp tục các Thay đổi Hiện có
Các thay đổi đang dang dở của bạn hoạt động liền mạch với các lệnh OPSX.
Bạn có một thay đổi đang hoạt động từ quy trình cũ?
/opsx:apply add-my-featureOPSX đọc các sản phẩm trung gian hiện có và tiếp tục từ nơi bạn đã dừng lại.
Bạn muốn thêm nhiều sản phẩm trung gian hơn vào một thay đổi hiện có?
/opsx:continue add-my-featureHiển thị những gì sẵn sàng để tạo dựa trên những gì đã tồn tại.
Cần xem trạng thái?
openspec status --change add-my-featureHệ thống Cấu hình Mới
Cấu trúc config.yaml
# Bắt buộc: Schema mặc định cho các thay đổi mới
schema: spec-driven
# Tùy chọn: Ngữ cảnh dự án (tối đa 50KB)
# Được đưa vào TẤT CẢ các hướng dẫn về sản phẩm trung gian
context: |
Bối cảnh dự án, stack công nghệ,
quy ước và ràng buộc của bạn.
# Tùy chọn: Quy tắc cho từng sản phẩm trung gian
# Chỉ được đưa vào các sản phẩm trung gian khớp
rules:
proposal:
- Bao gồm kế hoạch hoàn tác (rollback plan)
specs:
- Sử dụng định dạng Given/When/Then
design:
- Tài liệu hóa các chiến lược dự phòng
tasks:
- Chia nhỏ thành các phần tối đa 2 giờPhân giải Schema
Khi xác định schema nào sẽ sử dụng, OPSX kiểm tra theo thứ tự ưu tiên sau:
- Lệnh CLI:
--schema <name>(ưu tiên cao nhất) - Siêu dữ liệu thay đổi:
.openspec.yamltrong thư mục thay đổi - Cấu hình dự án:
openspec/config.yaml - Mặc định:
spec-driven
Các Schema Có sẵn
| Schema | Sản phẩm trung gian | Phù hợp nhất cho |
|---|---|---|
spec-driven | proposal → specs → design → tasks | Hầu hết các dự án |
Liệt kê tất cả các schema có sẵn:
openspec schemasSchema Tùy chỉnh
Tạo quy trình làm việc của riêng bạn:
openspec schema init my-workflowHoặc sao chép một schema hiện có:
openspec schema fork spec-driven my-workflowXem Customization để biết chi tiết.
Khắc phục sự cố
"Legacy files detected in non-interactive mode"
Bạn đang chạy trong môi trường CI hoặc không tương tác. Hãy sử dụng:
openspec init --forceLệnh không xuất hiện sau khi di chuyển
Khởi động lại IDE của bạn. Skills được phát hiện khi khởi động.
"Unknown artifact ID in rules"
Kiểm tra xem các khóa rules: của bạn có khớp với các ID sản phẩm trung gian trong schema của bạn hay không:
- spec-driven:
proposal,specs,design,tasks
Chạy lệnh sau để xem các ID sản phẩm trung gian hợp lệ:
openspec schemas --jsonCấu hình không được áp dụng
- Đảm bảo tệp nằm ở
openspec/config.yaml(không phải.yml) - Xác minh cú pháp YAML
- Các thay đổi cấu hình có hiệu lực ngay lập tức—không cần khởi động lại
project.md chưa được di chuyển
Hệ thống cố tình giữ lại project.md vì nó có thể chứa nội dung tùy chỉnh của bạn. Hãy xem xét thủ công, di chuyển các phần hữu ích sang config.yaml, sau đó xóa nó.
Muốn xem những gì sẽ được dọn dẹp?
Chạy lệnh init và từ chối lời nhắc dọn dẹp—you sẽ thấy tóm tắt phát hiện đầy đủ mà không thực hiện bất kỳ thay đổi nào.
Tham chiếu Nhanh
Tệp sau khi Di chuyển
project/
├── openspec/
│ ├── specs/ # Không thay đổi
│ ├── changes/ # Không thay đổi
│ │ └── archive/ # Không thay đổi
│ └── config.yaml # MỚI: Cấu hình dự án
├── .claude/
│ └── skills/ # MỚI: OPSX skills
│ ├── openspec-propose/ # hồ sơ cốt lõi mặc định
│ ├── openspec-explore/
│ ├── openspec-apply-change/
│ ├── openspec-update-change/
│ ├── openspec-sync-specs/
│ ├── openspec-archive-change/
│ └── ... # hồ sơ mở rộng thêm new/continue/ff/v.v.
├── CLAUDE.md # Đã xóa các dấu hiệu OpenSpec, nội dung của bạn được giữ nguyên
└── AGENTS.md # Đã xóa các dấu hiệu OpenSpec, nội dung của bạn được giữ nguyênNhững gì đã bị loại bỏ
.claude/commands/openspec/— được thay thế bằng.claude/skills/openspec/AGENTS.md— lỗi thờiopenspec/project.md— di chuyển sangconfig.yaml, sau đó xóa- Các khối dấu hiệu OpenSpec trong
CLAUDE.md,AGENTS.md, v.v.
Bảng tra cứu Lệnh
/opsx:propose Bắt đầu nhanh (hồ sơ cốt lõi mặc định)
/opsx:apply Thực hiện các nhiệm vụ
/opsx:archive Hoàn tất và lưu trữ
# Quy trình làm việc mở rộng (nếu được bật):
/opsx:new Tạo khung thay đổi
/opsx:continue Tạo sản phẩm trung gian tiếp theo
/opsx:ff Tạo các sản phẩm trung gian lập kế hoạchNhận trợ giúp
- Discord: discord.gg/YctCnvvshC
- GitHub Issues: github.com/Fission-AI/OpenSpec/issues
- Tài liệu: docs/opsx.md cho tài liệu tham khảo đầy đủ về OPSX