Skip to content

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ạnhCũ (Legacy)OPSX
Lệnh/openspec:proposal, /openspec:apply, /openspec:archiveMặ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ệcTạo tất cả các tài liệu cùng một lúcTạ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ạiCác cổng giai đoạn cứng nhắcTự 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ỉnhCấu trúc cố địnhDựa trên Schema, hoàn toàn có thể tùy biến
Cấu hìnhCLAUDE.md với các đánh dấu + project.mdCấ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.mdBộ 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ệp SKILL.md do OpenSpec quản lý dưới đường dẫn .codex/skills trướ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 .agents chư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ọn codex rõ ràng bằng openspec 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/prompts hoặ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:

  1. Xem xét nội dung của nó
  2. Di chuyển ngữ cảnh hữu ích sang openspec/config.yaml (xem hướng dẫn bên dưới)
  3. 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 custom khi 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:

bash
openspec init

Lệ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ó:

  1. Các thư mục lệnh slash cũ bị xóa
  2. 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)
  3. openspec/AGENTS.md bị xóa
  4. Các skills mới được cài đặt vào .claude/skills/
  5. 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:

bash
openspec update

Lệ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:

bash
openspec init --force --tools claude

Cờ --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) ​

markdown
# 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 specifications

Sau (config.yaml) ​

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 flows

Những Khác Biệt Chính ​

project.mdconfig.yaml
Markdown tự doYAML có cấu trúc
Một khối văn bản duy nhấtNgữ cảnh riêng và quy tắc theo từng sản phẩm
Không rõ khi nào được sử dụngNgữ 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 schemaTrườ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 ​

  1. Tạo config.yaml (nếu chưa được tạo bởi init):

    yaml
    schema: spec-driven
  2. Thê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):

    yaml
    context: |
      Your project background goes here.
      Focus on what the AI genuinely needs to know.
  3. Thêm quy tắc theo từng sản phẩm (tùy chọn):

    yaml
    rules:
      proposal:
        - Your proposal-specific guidance
      specs:
        - Your spec-writing rules
  4. Xó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ệnhMục Đích
/opsx:proposeTạo một thay đổi và sinh các sản phẩm lập kế hoạch trong một bước
/opsx:exploreSuy nghĩ về các ý tưởng không có cấu trúc
/opsx:applyTriển khai các tác vụ từ tasks.md
/opsx:updateTu 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:syncHợp nhất các delta specs vào specs chính
/opsx:archiveHoàn tất và lưu trữ thay đổi

Quy trình mở rộng (chọn tùy chỉnh):

LệnhMục Đích
/opsx:newBắt đầu một khung thay đổi mới
/opsx:continueTạo sản phẩm tiếp theo (một cái một lúc)
/opsx:ffFast-forward—tạo các sản phẩm lập kế hoạch cùng lúc
/opsx:verifyXác thực triển khai khớp với specs
/opsx:bulk-archiveLưu trữ nhiều thay đổi cùng lúc
/opsx:onboardQuy 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:continue

Tạ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:explore

Suy 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.md

OPSX 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-feature

OPSX đọ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-feature

Hiể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?

bash
openspec status --change add-my-feature

Hệ thống Cấu hình Mới ​

Cấu trúc config.yaml ​

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:

  1. Lệnh CLI: --schema <name> (ưu tiên cao nhất)
  2. Siêu dữ liệu thay đổi: .openspec.yaml trong thư mục thay đổi
  3. Cấu hình dự án: openspec/config.yaml
  4. Mặc định: spec-driven

Các Schema Có sẵn ​

SchemaSản phẩm trung gianPhù hợp nhất cho
spec-drivenproposal → specs → design → tasksHầu hết các dự án

Liệt kê tất cả các schema có sẵn:

bash
openspec schemas

Schema Tùy chỉnh ​

Tạo quy trình làm việc của riêng bạn:

bash
openspec schema init my-workflow

Hoặc sao chép một schema hiện có:

bash
openspec schema fork spec-driven my-workflow

Xem 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:

bash
openspec init --force

Lệ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ệ:

bash
openspec schemas --json

Cấu hình không được áp dụng ​

  1. Đảm bảo tệp nằm ở openspec/config.yaml (không phải .yml)
  2. Xác minh cú pháp YAML
  3. 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ên

Những gì đã bị loại bỏ ​

  • .claude/commands/openspec/ — được thay thế bằng .claude/skills/
  • openspec/AGENTS.md — lỗi thời
  • openspec/project.md — di chuyển sang config.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 ​

text
/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ạch

Nhận trợ giúp ​