Thiết lập dự án của bạn

Thêm OpenSpec vào dự án: chạy init, xem những gì nó tạo ra và điều chỉnh chúng.

Chọn vị trí đặt OpenSpec

• Trong kho mã nguồn của bạn (mặc định): các tài liệu đặc tả (specs) và thay đổi nằm cạnh mã nguồn mà chúng mô tả và được quản lý phiên bản cùng với nó. Phần còn lại của trang này sẽ làm theo lộ trình này.
• Trong một cửa hàng lưu trữ (store): một kho lập kế hoạch riêng được chia sẻ bởi các kho mã nguồn sử dụng nó, phù hợp cho cấu hình nhiều kho hoặc để tách biệt hoàn toàn khâu lập kế hoạch khỏi kho mã nguồn. Mục Stores (beta) giải thích khi nào việc này là cần thiết và cách thiết lập.

Khởi tạo dự án của bạn

Khi đã cài đặt CLI (Cài đặt), hãy chạy lệnh init tại thư mục gốc của dự án. Trong terminal của bạn:

cd <your-project>
openspec init

Init sẽ hỏi các công cụ AI mà bạn sử dụng, viết các tệp workflow cho những công cụ bạn chọn và báo cáo kết quả nhận được:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Khởi động lại IDE của bạn để các lệnh mới có hiệu lực.

Chạy lại init là an toàn:

• Các công cụ đã được cấu hình sẵn sẽ in Refreshed thay vì Created.
• Chạy init lần nữa với một công cụ mới được chọn sẽ thêm công cụ đó.
• Cờ --tools sẽ bỏ qua bước chọn (Tham chiếu CLI).

Chuyển đổi tệp project.md hiện có

Init không sao chép tệp openspec/project.md cũ vào config.yaml. Nó giữ nguyên tệp đó và in ra yêu cầu chuyển đổi có hỗ trợ của AI.

Trong hội thoại với AI của bạn:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

Xem xét config.yaml, sau đó xóa project.md khi bạn đã sẵn sàng.

Những gì init cài đặt

Chạy init sẽ tạo hai thứ trong dự án của bạn:

• Thư mục openspec/ tại thư mục gốc của kho mã nguồn
• Các tệp workflow (kỹ năng và lệnh) được thêm vào thư mục của công cụ AI của bạn (.agents/, .claude/, v.v.)

Commit tất cả chúng giống như phần còn lại của mã nguồn của bạn. Init không thay đổi bất kỳ điều gì khác trong kho mã nguồn của bạn (nếu nó tìm thấy các phần còn lại từ phiên bản OpenSpec cũ hơn, nó sẽ hỏi trước khi dọn dẹp).

Thư mục openspec/

Mọi sản phẩm (artifact) của OpenSpec đều nằm ở đây, tại thư mục gốc của dự án. Đây là cách nó trông:

openspec/
├── config.yaml     thiết lập dự án và ngữ cảnh cho AI
├── specs/          specs của bạn (trống cho đến hiện tại)
└── changes/        các thay đổi đang diễn ra (trống cho đến hiện tại)
    └── archive/    các thay đổi hoàn tất sẽ được chuyển đến đây

Mục Cấu hình dự án nói về config.yaml.

Các tệp workflow (kỹ năng và lệnh)

Đây là các workflow của OpenSpec, tức là các hành động bạn sẽ sử dụng trong khi làm việc. Dưới đây là chúng dưới dạng kỹ năng (skills) được cài đặt, nằm trong thư mục .agents/ chung mà hầu hết các công cụ sử dụng:

.agents/skills/
├── openspec-explore/              suy nghĩ thấu đáo một ý tưởng trước
├── openspec-propose/              đề xuất một thay đổi
├── openspec-apply-change/         thực hiện các tác vụ của một thay đổi
├── openspec-update-change/        chỉnh sửa kế hoạch của một thay đổi
├── openspec-sync-specs/           đồng bộ cập nhật spec của một thay đổi vào specs/
├── openspec-archive-change/       chuyển một thay đổi đã hoàn thành vào kho lưu trữ
├── openspec-verify-change/        kiểm tra xem phần triển khai có khớp với kế hoạch không (không được bao gồm theo mặc định)
└── openspec-bulk-archive-change/  lưu trữ hàng loạt các thay đổi tại một (không được bao gồm theo mặc định)

Đây là bộ mặc định cộng thêm hai workflow tùy chọn. Mục Profiles liệt kê đủ mười hai.

Theo mặc định, mỗi workflow được cài đặt dưới hai hình thức:

• Kỹ năng (openspec-apply-change): các hướng dẫn mà tác tử (agent) của bạn tự động áp dụng khi bạn yêu cầu công việc.
• Lệnh (/opsx:apply trong Claude Code): một điểm nhập dạng gõ cho cùng một workflow, dưới một tên ngắn hơn.

Hai hình thức này giống hệt nhau về mặt chức năng. Kỹ năng và lệnh của một workflow mang cùng các hướng dẫn.

Tại sao có hai: các lệnh xuất hiện trước, và mỗi công cụ viết chúng theo cách riêng của mình. Kỹ năng là tiêu chuẩn mới hơn được chia sẻ giữa các công cụ, nhưng không phải công cụ nào cũng có thể gọi trực tiếp một kỹ năng, do đó lệnh vẫn được giữ làm điểm nhập cho những công cụ đó.

Một số công cụ chỉ được cài đặt dưới dạng kỹ năng. Ở nơi công cụ chạy kỹ năng trực tiếp, init sẽ bỏ qua các lệnh và thông báo điều đó (Commands skipped for: codex (uses skills)).

Chúng tôi ưu tiên kỹ năng và dự định loại bỏ lệnh vào một thời điểm sau.

Thay đổi những gì được cài đặt

Trình chọn tương tác (picker) sẽ thay đổi hình thức cung cấp và bộ workflow (Profiles). Trong terminal của bạn:

openspec config profile

Dưới đây là cách chuyển sang chỉ dùng kỹ năng:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

Trả lời "vâng" sẽ áp dụng ngay lập tức vào dự án hiện tại. Các dự án khác sẽ nhận được cài đặt này vào lần openspec update tiếp theo. Cài đặt này là toàn cục, theo máy.

Claude Code không hiển thị các workflow

Claude Code tải các workflow OpenSpec từ một hoặc cả hai đường dẫn dự án này, dựa trên cài đặt cung cấp của bạn:

• Kỹ năng: .claude/skills/openspec-*/SKILL.md
• Lệnh: .claude/commands/opsx/<id>.md

Nếu các tệp bị thiếu, hãy làm mới dự án. Trong terminal của bạn:

openspec update

Nếu các tệp lệnh tồn tại nhưng /opsx: không hiển thị các lệnh OpenSpec, hãy cập nhật Claude Code và khởi động lại nó. Nếu các lệnh vẫn không được nạp, hãy bật cả kỹ năng. Trong terminal của bạn:

openspec config set delivery both
openspec update

Khởi động lại Claude Code, sau đó chạy /openspec-propose trong hội thoại của nó. Nếu chỉ một số workflow bị thiếu, đổi profile của bạn.

Quá trình thiết lập hoàn tất. Mục Quickstart sẽ hướng dẫn bạn thực hiện thay đổi đầu tiên từ đây.