Cách hoạt động của các lệnh

Điều quan trọng cần nhớ: OpenSpec có hai loại lệnh và chúng chạy ở hai nơi khác nhau.

• Các lệnh openspec ... chạy trong terminal của bạn. (Ví dụ: openspec init.)
• Các lệnh /opsx:... chạy trong trò chuyện của trợ lý AI. (Ví dụ: /opsx:propose.)

Nếu bạn từng gõ /opsx:propose vào terminal mà không thấy phản hồi gì, thì đây là lý do. Bạn đang giao tiếp với nửa sai của OpenSpec. Các lệnh gạch chéo (slash commands) không phải là lệnh terminal. Chúng là các hướng dẫn bạn cung cấp cho trợ lý lập trình AI của mình, ngay trong hộp trò chuyện nơi bạn thường gõ "thêm biểu mẫu đăng nhập".

Sự khác biệt đơn giản này là rào cản phổ biến nhất đối với người dùng mới, vì vậy hãy làm cho nó rõ ràng tuyệt đối.

Hai phần chính

OpenSpec là một dự án mặc hai vai trò.

CLI (nửa terminal). Một chương trình tên là openspec mà bạn cài đặt và chạy từ shell của mình. Nó thiết lập dự án của bạn, liệt kê và xác thực các thay đổi, hiển thị bảng điều khiển và lưu trữ công việc đã hoàn thành. Bạn gõ những lệnh này vào iTerm, terminal VS Code, PowerShell, hoặc bất kỳ đâu bạn thường chạy git hoặc npm.

openspec init        # thiết lập OpenSpec trong dự án này
openspec list        # xem các thay đổi đang hoạt động
openspec view        # mở bảng điều khiển tương tác

Các lệnh gạch chéo (nửa trò chuyện). Các lệnh ngắn như /opsx:propose và /opsx:apply mà bạn gõ vào trợ lý AI của mình. Những lệnh này báo cho AI tuân theo quy trình làm việc của OpenSpec: soạn thảo đề xuất, viết tài liệu đặc tả, xây dựng dựa trên danh sách tác vụ và lưu trữ khi hoàn tất. Bạn gõ những lệnh này vào Claude Code, Cursor, Devin Desktop, Copilot, hoặc bất kỳ trợ lý nào bạn sử dụng.

/opsx:propose add-dark-mode    (gõ trong trò chuyện AI của bạn)
/opsx:apply                    (gõ trong trò chuyện AI của bạn)
/opsx:archive                  (gõ trong trò chuyện AI của bạn)

Dưới đây là mô hình tư duy được minh họa bằng một hình ảnh:

        TERMINAL CỦA BẠN                           TRÒ CHUYỆN CỦA TRỢ LÝ AI
   ┌──────────────────────┐               ┌──────────────────────────────┐
   │  $ openspec init     │   cài đặt     │  /opsx:propose add-dark-mode  │
   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
   │  $ openspec view     │   các lệnh    │  /opsx:archive                │
   └──────────────────────┘    & kỹ năng  └──────────────────────────────┘
        Chạy openspec ở đây                       Chạy /opsx:* ở đây

Hãy chú ý đến mũi tên. Việc chạy openspec init trong terminal là cách cài đặt các lệnh gạch chéo vào công cụ AI của bạn. Nửa terminal thiết lập nửa trò chuyện. Sau đó, hầu hết các thao tác hàng ngày đều diễn ra trong trò chuyện.

"Làm thế nào để tôi bắt đầu chế độ tương tác?"

Không có chế độ tương tác riêng biệt nào để khởi động. Câu hỏi này xuất hiện rất nhiều, vì vậy nó xứng đáng có một câu trả lời thẳng thắn.

Bạn không cần nhập một chế độ OpenSpec đặc biệt. Bạn chỉ cần mở trợ lý lập trình AI của mình như mọi khi và gõ một lệnh gạch chéo vào cuộc trò chuyện. Lệnh gạch chéo chính là cách bạn "vào" OpenSpec. Trợ lý của bạn nhận ra nó, tải kỹ năng OpenSpec tương ứng và bắt đầu tuân theo quy trình làm việc.

Vì vậy, hướng dẫn thực sự là:

1. Mở trợ lý lập trình AI của bạn (Claude Code, Cursor, Devin Desktop, v.v.) trong dự án của bạn.
2. Gõ /opsx:propose trong cuộc trò chuyện của nó, cùng nơi bạn gõ bất kỳ yêu cầu nào khác.
3. Quan sát tính năng tự động điền: nếu OpenSpec đã được cài đặt, bạn sẽ thấy /opsx:propose, /opsx:apply và các lệnh liên quan xuất hiện khi bạn gõ dấu gạch chéo.

Đó là tất cả. Không có chế độ để bật/tắt, không có daemon nào để khởi chạy, không có cửa sổ riêng biệt.

Một thứ thực sự tương tác nằm trong terminal: openspec view. Nó mở một bảng điều khiển để duyệt qua các tài liệu đặc tả và thay đổi của bạn. Nhưng đó là một trình xem, không phải là thứ bạn sử dụng để đề xuất và xây dựng. Việc xây dựng diễn ra thông qua các lệnh gạch chéo trong trò chuyện.

Tại sao lại có sự phân chia này

Nên hiểu điều này, vì nó giải thích tại sao OpenSpec hoạt động với hơn 30 công cụ AI khác nhau.

CLI là động cơ. Nó biết các quy tắc: thư mục thay đổi trông như thế nào, các sản phẩm phụ phụ thuộc lẫn nhau ra sao, cách hợp nhất bản đặc tả delta vào nguồn dữ liệu thật của bạn. Nó giống nhau ở mọi nơi.

Các lệnh gạch chéo là bánh lái, và mỗi công cụ AI đều có một chiếc bánh lái hơi khác nhau. Claude Code gọi chúng là commands. Cursor và Devin Desktop có định dạng riêng của chúng. Một số công cụ gọi chúng là skills. Khi bạn chạy openspec init, OpenSpec tạo ra đúng loại tệp cho mỗi công cụ bạn đã chọn, vì vậy cùng một ý định /opsx:propose hoạt động bất kể bạn thích trợ lý nào.

Điểm mạnh của thiết kế này: bạn học quy trình làm việc một lần và mang nó sang các công cụ khác. Sự đánh đổi: cú pháp chính xác của một lệnh có thể khác nhau một chút giữa các công cụ, đây là phần tiếp theo.

Cú pháp lệnh gạch chéo theo công cụ

Ý định là giống hệt nhau ở mọi nơi. Chính tả tuân theo tệp mà công cụ của bạn tải.

Tệp lệnh của công cụ	Cách bạn gõ	Ví dụ về công cụ
.../commands/opsx/<id>.*	/opsx:propose	Claude Code, Gemini CLI, Crush
.../opsx-<id>.*	/opsx-propose	Cursor, GitHub Copilot (IDE), Devin Desktop, Trae, Oh My Pi
.amazonq/prompts/opsx-<id>.md	@opsx-propose	Amazon Q Developer
none — chỉ có skills	/openspec-propose	CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, .agents dùng chung
none — Kimi Code	/skill:openspec-propose	Kimi Code
none — Codex CLI	$openspec-propose	Codex

Devin là công cụ duy nhất xuất hiện ở hai dòng. Devin Desktop đọc .devin/workflows/, vì vậy /opsx-propose hoạt động ở đó; Devin Local không hoạt động, vì vậy trên agent đó hãy sử dụng kỹ năng /openspec-propose thay thế. Các kỹ năng mà OpenSpec ghi vào .devin/skills/ hoạt động trên cả hai, đó là lý do tại sao chúng tham chiếu đến nhau bằng tên kỹ năng.

Mọi công cụ đều được liệt kê trong Cách gọi lệnh — bảng đó là nguồn chính thức. Hai dòng cuối không phải là lệnh gạch chéo: Amazon Q tải các tệp của nó vào thư viện prompt được gọi bằng @, và ba dòng cuối sử dụng tên kỹ năng, không phải id lệnh (/opsx:apply là kỹ năng openspec-apply-change).

Khi nghi ngờ, hãy đọc dòng "Bắt đầu" mà openspec init in ra: nó đã sử dụng dạng lệnh mà công cụ của bạn đã đăng ký. Gõ một dấu gạch chéo và quan sát tính năng tự động điền cũng hoạt động, đối với các công cụ hiển thị lệnh gạch chéo.

Các lệnh đến đó như thế nào: kỹ năng và lệnh

Khi bạn chạy openspec init (hoặc openspec update), OpenSpec ghi các tệp nhỏ vào dự án của bạn để công cụ AI của bạn có thể tìm thấy quy trình làm việc. Tùy thuộc vào công cụ và cài đặt của bạn, đây là kỹ năng, lệnh, hoặc cả hai.

• Kỹ năng sống ở những nơi như .claude/skills/openspec-*/SKILL.md. Chúng là tiêu chuẩn xuyên công cụ đang nổi lên: một thư mục chứa hướng dẫn mà trợ lý của bạn tự động phát hiện.
• Lệnh sống ở những nơi như .cursor/commands/opsx-<id>.md hoặc .claude/commands/opsx/<id>.md — bố cục là của công cụ, và nó quyết định cách bạn gõ lệnh. Đây là các tệp lệnh gạch chéo cũ dành riêng cho từng công cụ. Codex không nhận được các tệp lệnh được tạo tự động; hãy sử dụng .agents/skills/openspec-*.

Bạn không cần phải quan tâm công cụ của bạn sử dụng cái nào. Bạn chỉ cần gõ lệnh gạch chéo và nó sẽ hoạt động. Nhưng biết rằng các tệp này tồn tại sẽ hữu ích khi có sự cố: nếu các lệnh của bạn biến mất, thường là do các tệp này bị thiếu hoặc lỗi thời, và openspec update sẽ tạo lại chúng.

Xem Công cụ hỗ trợ cho các đường dẫn chính xác theo từng công cụ, và Hướng dẫn di chuyển cho cách kỹ năng thay thế phương pháp chỉ dùng lệnh cũ.

Xác nhận rằng nó đã được cài đặt

Các kiểm tra nhanh, nhanh nhất trước tiên:

1. Gõ một dấu gạch chéo trong trò chuyện AI. Bắt đầu gõ /opsx và quan sát các gợi ý tự động điền. Nếu chúng xuất hiện, bạn đã sẵn sàng. Trên một công cụ chỉ có kỹ năng (Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, hoặc mục tiêu .agents dùng chung) /opsx không bao giờ tự động hoàn thành ngay cả khi cài đặt khỏe mạnh — hãy thử tên kỹ năng từ bảng ở trên thay thế.
2. Tìm kiếm các tệp. Đối với Claude Code, hãy kiểm tra xem .claude/skills/ có chứa các thư mục openspec-* hay không. Các công cụ khác sử dụng các thư mục riêng của chúng (Công cụ hỗ trợ liệt kê chúng).
3. Chạy lại quá trình thiết lập. Từ gốc dự án của bạn, chạy openspec update. Điều này tạo lại các tệp kỹ năng và lệnh cho bất kỳ công cụ nào bạn đã cấu hình.
4. Khởi động lại trợ lý của bạn. Nhiều công cụ quét kỹ năng và lệnh khi khởi động, vì vậy một cửa sổ mới có thể là bước còn thiếu.

Tôi thậm chí có những lệnh nào?

Theo mặc định, OpenSpec cài đặt bộ lệnh gạch chéo cốt lõi:

• /opsx:explore: suy nghĩ về một ý tưởng với AI trước khi cam kết thực hiện thay đổi (bước đầu tiên tuyệt vời khi bạn không chắc chắn)
• /opsx:propose: tạo một thay đổi và soạn thảo tất cả các tài liệu lập kế hoạch của nó trong một bước
• /opsx:apply: xây dựng thay đổi bằng cách làm qua danh sách tác vụ của nó
• /opsx:update: sửa đổi các tài liệu lập kế hoạch của một thay đổi và giữ cho chúng nhất quán
• /opsx:sync: hợp nhất các cập nhật đặc tả của một thay đổi vào các đặc tả chính của bạn (thường là tự động)
• /opsx:archive: hoàn tất một thay đổi và lưu trữ nó

Nhịp điệu tốt theo mặc định: explore khi bạn đang tìm hiểu những gì cần làm, sau đó là propose, apply, archive. Hướng dẫn Khám phá trước tiên giải thích tại sao bước mở đầu này mang lại hiệu quả.

Cũng có một bộ mở rộng dành cho những người muốn kiểm soát chi tiết hơn (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard). Bạn bật nó bằng openspec config profile, sau đó áp dụng nó bằng openspec update.

Mới với tất cả những điều này? /opsx:onboard (trong bộ mở rộng) sẽ hướng dẫn bạn qua một thay đổi hoàn chỉnh trên cơ sở mã của riêng bạn, tường thuật từng bước. Đó là lời giới thiệu thân thiện nhất có thể.

Để biết chi tiết từng lệnh làm gì, xem Commands. Để biết khi nào nên sử dụng lệnh nào, xem Workflows.

Lần chạy đầu tiên sạch sẽ

Kết hợp lại, đây là toàn bộ chuỗi với mỗi bước được gắn nhãn nơi nó xảy ra.

TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project
TERMINAL   $ openspec init
              (cài đặt các lệnh gạch chéo vào công cụ AI của bạn)

AI CHAT      /opsx:explore
              (tùy chọn: suy nghĩ về ý tưởng với AI trước)

AI CHAT      /opsx:propose add-dark-mode
              (AI soạn thảo đề xuất, đặc tả, thiết kế, tác vụ)

AI CHAT      /opsx:apply
              (AI xây dựng nó, kiểm tra các tác vụ)

AI CHAT      /opsx:archive
              (thay đổi được hợp nhất vào đặc tả của bạn và lưu trữ)

Hai bước terminal để thiết lập. Sau đó bạn sống trong trò chuyện. Đó là nhịp điệu.

Liên quan

• Bắt đầu: hướng dẫn đầy đủ cho thay đổi đầu tiên
• Commands: chi tiết về mọi lệnh gạch chéo
• CLI: chi tiết về mọi lệnh terminal
• Công cụ hỗ trợ: cú pháp và vị trí tệp theo từng công cụ
• FAQ: thêm các câu trả lời nhanh
• Xử lý sự cố: khắc phục khi các lệnh không hiển thị