OpenSpec

FAQ ​

Trả lời nhanh các câu hỏi phổ biến nhất. Nếu câu hỏi của bạn thực sự là kiểu "có gì đó bị hỏng", trang Xử lý sự cố phù hợp hơn. Nếu bạn muốn định nghĩa một thuật ngữ, xem Thuật ngữ.

Cơ bản ​

OpenSpec là gì, trong một câu? ​

Một lớp nhẹ giúp bạn và trợ lý lập trình AI của bạn đạt được thỏa thuận bằng văn bản về việc cần xây dựng gì, trước khi bất kỳ dòng mã nào được viết.

###Tại sao tôi lại muốn điều đó?

Vì trợ lý AI tự tin ngay cả khi chúng sai. Khi yêu cầu chỉ tồn tại trong một luồng chat, AI sẽ lấp đầy khoảng trống bằng phỏng đoán, và bạn chỉ phát hiện ra sau khi mã đã tồn tại. OpenSpec đưa thỏa thuận lên sớm hơn, nơi các sai sót dễ sửa hơn. Xem Tổng quan các khái niệm cốt lõi để biết đầy đủ.

Tôi có phải dùng nó cho mọi thứ không? ​

Không. Hãy dùng nó ở nơi mà thỏa thuận quan trọng, tức là hầu hết các công việc không đơn giản. Với một lỗi chính tả một ký tự, thủ tục có lẽ không đáng, và điều đó hoàn toàn ổn.

Tôi có thể dùng nó trên một codebase hiện có lớn, hay chỉ cho dự án mới? ​

Các codebase hiện có mới là mục tiêu chính. OpenSpec ưu tiên brownfield: bạn không cần tài liệu hóa toàn bộ ứng dụng ngay từ đầu. Bạn chỉ viết spec cho những gì mỗi thay đổi ảnh hưởng đến, và các spec của bạn sẽ được hoàn thiện dần theo thời gian quanh công việc bạn thực sự làm. Có một hướng dẫn chuyên biệt: Sử dụng OpenSpec trong Dự án Hiện có.

Nó có bị ràng buộc với một công cụ AI nào không? ​

Không. OpenSpec hoạt động với hơn 30 trợ lý, bao gồm Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex và nhiều hơn. Danh sách đầy đủ và chi tiết từng công cụ nằm trong Công cụ được hỗ trợ.

Chạy lệnh ​

Tôi nhập /opsx:propose ở đâu? ​

Trong chat của trợ lý AI của bạn, không phải trong terminal. Đây là điểm gây nhầm lẫn phổ biến nhất, vì vậy nó có trang riêng: Cách lệnh hoạt động. Tóm tắt: openspec ... chạy trong terminal, /opsx:... chạy trong chat.

Làm sao để "bắt đầu chế độ tương tác"? ​

Không có chế độ riêng nào để bắt đầu. Bạn mở trợ lý AI như bình thường và nhập một lệnh slash vào chat của nó. Lệnh slash chính là cách bạn "vào" OpenSpec. (Tính năng terminal tương tác thực sự duy nhất là openspec view, một dashboard để xem các spec và thay đổi.) Giải thích đầy đủ trong Cách lệnh hoạt động.

Tôi nhập lệnh slash và không có gì xảy ra. Tại sao? ​

Có khả năng cao là bạn đã nhập nó trong terminal thay vì chat AI của bạn, bạn dùng một cách viết mà công cụ của bạn không nhận, hoặc các lệnh chưa được cài đặt. Nếu các tệp bị thiếu — hoặc bạn chưa bao giờ thiết lập công cụ — hãy chạy openspec init; openspec update chỉ làm mới các tệp đã tồn tại. Sau đó khởi động lại trợ lý của bạn và dùng định dạng được in dưới mục "Getting started" — xem Cách gọi lệnh. Xử lý sự cố có danh sách kiểm tra đầy đủ.

Tại sao cú pháp là /opsx:propose ở một công cụ và /opsx-propose ở công cụ khác? ​

Mỗi công cụ AI hiển thị lệnh tùy chỉnh hơi khác nhau, và OpenSpec viết chúng theo cách công cụ của bạn tải tệp mà nó đã tạo. Tệp lệnh tên là opsx-propose.md được nhập là /opsx-propose; tệp nằm trong commands/opsx/ được nhập là /opsx:propose. Các công cụ dùng skills thay vì commands sẽ dùng tên skill — Codex cần $openspec-propose, Kimi Code /skill:openspec-propose. Dòng "Getting started" của openspec init đã in sẵn định dạng đúng cho các công cụ bạn chọn; bảng đầy đủ nằm trong Cách gọi lệnh.

Sự khác biệt giữa skill và command là gì? ​

Cả hai đều là tệp mà OpenSpec viết để trợ lý của bạn có thể chạy workflow. Skills (.../skills/openspec-*/SKILL.md) là tiêu chuẩn đa công cụ mới hơn; commands (.../commands/opsx-*) là các tệp slash theo từng công cụ cũ hơn. Bạn không cần phải chọn. Bạn chỉ cần nhập lệnh slash, và OpenSpec sẽ cài đặt loại mà công cụ của bạn sử dụng.

Workflow ​

Tôi nên bắt đầu từ đâu nếu không chắc cần xây dựng gì? ​

Với /opsx:explore. Đây là một đối tác tư duy không rủi ro, đọc codebase của bạn, liệt kê các phương án, và biến một vấn đề mơ hồ thành kế hoạch cụ thể, tất cả trước khi bất kỳ thay đổi hay mã nào tồn tại. Nó nằm trong profile mặc định, vì vậy luôn khả dụng. Khi kế hoạch rõ ràng, nó chuyển sang /opsx:propose. Đây là thói quen tốt nhất nên hình thành, vì nó ngăn một AI nhiệt tình xây dựng sai thứ mà nó tưởng là đúng. Xem Khám phá trước.

Luồng đơn giản nhất có thể là gì? ​

text
/opsx:explore (optional)   then   /opsx:propose <what you want>   then   /opsx:apply   then   /opsx:archive

Explore để suy nghĩ kỹ, propose để phác thảo kế hoạch, apply để xây dựng, archive để lưu trữ. Bỏ qua explore khi bạn đã biết chính xác mình muốn gì.

Sự khác biệt giữa /opsx:propose và /opsx:new là gì? ​

/opsx:propose là lệnh một bước mặc định: nó tạo thay đổi và phác thảo tất cả các artifact lập kế hoạch cùng lúc. /opsx:new là một phần của bộ lệnh mở rộng và chỉ tạo khung một thay đổi trống, để bạn tạo các artifact lần lượt với /opsx:continue (hoặc tất cả cùng lúc với /opsx:ff). Dùng propose trừ khi bạn muốn kiểm soát từng bước. Xem Lệnh.

core và profile mở rộng là gì? ​

Profile quyết định lệnh slash nào được cài đặt. Core (mặc định) cho bạn propose, explore, apply, update, sync, archive. Bộ mở rộng thêm new, continue, ff, verify, bulk-archive và onboard để kiểm soát chi tiết hơn. Chuyển bằng openspec config profile, sau đó áp dụng bằng openspec update.

Tôi có cần chạy /opsx:sync không? ​

Thường thì không. Sync hợp nhất delta specs của một thay đổi vào specs chính của bạn, và /opsx:archive sẽ đề xuất làm điều đó cho bạn. Chỉ chạy sync thủ công khi bạn muốn specs được hợp nhất trước khi lưu trữ, ví dụ với một thay đổi chạy lâu dài. Xem Lệnh.

Làm sao để sửa proposal, spec hoặc task sau khi đã bắt đầu? ​

Chỉ cần sửa tệp. Mọi artifact đều là Markdown thuần trong openspec/changes/<name>/, và không có giai đoạn bị khóa hay chế độ sửa đặc biệt. Sửa thủ công, hoặc nhờ AI của bạn chỉnh sửa ("cập nhật thiết kế để dùng hàng đợi"), rồi tiếp tục. AI luôn làm việc dựa trên nội dung tệp hiện tại. Hướng dẫn đầy đủ: Sửa và lặp lại một thay đổi.

Tôi có thể quay lại và thay đổi kế hoạch sau khi đã triển khai một phần không? ​

Có, bất cứ lúc nào. Workflow là linh hoạt, vì vậy xem xét và sửa không phải là giai đoạn bạn bị khóa. Sửa artifact, rồi tiếp tục. Nếu bạn muốn kiểm tra có cấu trúc rằng mã vẫn khớp với kế hoạch, hãy chạy /opsx:verify. Xem Sửa và lặp lại một thay đổi.

Tôi đã sửa mã thủ công. Làm sao để đồng bộ với spec? ​

Đồng bộ chúng trước khi lưu trữ, vì lưu trữ biến specs của bạn thành bản ghi sự thật. Nếu mã giờ đã đúng, cập nhật delta spec để khớp với những gì bạn đã phát hành; nếu spec đúng, tiếp tục xây dựng cho đến khi mã đồng thuận. /opsx:verify hiển thị các điểm không khớp. Xem Sửa và lặp lại một thay đổi.

Khi nào nên cập nhật một thay đổi hiện có so với bắt đầu một thay đổi mới? ​

Cập nhật khi đó là cùng công việc, được tinh chỉnh. Bắt đầu mới khi ý định thay đổi cơ bản hoặc phạm vi bùng nổ thành công việc khác. Có sơ đồ quyết định và ví dụ trong Quy trình.

Nếu phiên của tôi hết context, hoặc yêu cầu thay đổi giữa chừng triển khai thì sao? ​

Đây là lúc specs chứng minh giá trị. Vì kế hoạch nằm trong tệp (không chỉ trong lịch sử chat), bạn có thể xóa context, bắt đầu phiên AI mới, và tiếp tục với /opsx:apply; nó đọc các artifact và tiếp tục từ task chưa đánh dấu đầu tiên. Nếu yêu cầu thay đổi, sửa các artifact để khớp với thực tế mới và tiếp tục. Giữ context window sạch cũng cho kết quả tốt hơn; hãy xóa nó trước khi triển khai.

Tôi có nên commit thư mục openspec/ vào git không? ​

Có. Các spec, thay đổi đang hoạt động và archive của bạn là một phần lịch sử dự án. Commit chúng như bất kỳ mã nguồn nào khác. Đặc biệt, archive trở thành bản ghi bền vững về lý do hệ thống của bạn hoạt động như vậy.

Specs và thay đổi ​

Điều gì nằm trong spec so với design? ​

Spec mô tả hành vi quan sát được: hệ thống làm gì, đầu vào, đầu ra và các điều kiện lỗi của nó. Design mô tả cách bạn sẽ xây dựng nó: phương pháp kỹ thuật, quyết định kiến trúc, thay đổi tệp. Nếu việc triển khai có thể thay đổi mà không thay đổi hành vi quan sát được bên ngoài, nó thuộc về design, không phải spec. Khái niệm đi sâu hơn.

Delta spec là gì? ​

Spec chỉ mô tả những gì đang thay đổi, sử dụng các phần ADDED, MODIFIED và REMOVED, thay vì phát biểu lại toàn bộ spec. Đây là cách OpenSpec xử lý các sửa đổi trên hệ thống hiện có một cách sạch sẽ. Xem Khái niệm.

Các thay đổi đã lưu trữ nằm ở đâu? ​

Vào openspec/changes/archive/YYYY-MM-DD-<name>/, với tất cả các artifact thay đổi được bảo quản. Thay đổi được chuyển khỏi danh sách đang hoạt động của bạn. Một thay đổi khai báo rõ retire_capabilities: true cũng có thể xóa một spec capability chính khi nó xóa yêu cầu cuối cùng của capability đó.

Cấu hình và tùy chỉnh ​

Làm sao để nói cho AI biết về tech stack của tôi? ​

Đặt nó trong openspec/config.yaml dưới context:. Văn bản đó được tiêm vào mọi yêu cầu lập kế hoạch, vì vậy AI luôn biết stack và quy ước của bạn. Xem Tùy chỉnh.

Tôi có thể tạo specs bằng ngôn ngữ khác tiếng Anh không? ​

Có. Thêm chỉ thị ngôn ngữ vào context: của cấu hình. Đa ngôn ngữ có các đoạn mã copy-paste cho nhiều ngôn ngữ.

Tôi có thể thay đổi chính workflow không? ​

Có, với custom schemas. Schema định nghĩa các artifact nào tồn tại và chúng phụ thuộc vào nhau như thế nào. Fork mặc định bằng openspec schema fork spec-driven my-workflow, sau đó sửa nó. Xem Tùy chỉnh.

Mô hình, quyền riêng tư và nâng cấp ​

Tôi nên dùng mô hình AI nào? ​

OpenSpec hoạt động tốt nhất với các mô hình suy luận cao. README đề xuất các mô hình như Codex 5.5 và Opus 4.7 cho cả lập kế hoạch và triển khai. Cũng giữ context window sạch: xóa nó trước khi triển khai để có kết quả tốt nhất.

OpenSpec có thu thập dữ liệu không? ​

Nó thu thập thống kê sử dụng ẩn danh: chỉ tên lệnh và phiên bản. Không có tham số, đường dẫn, nội dung hay dữ liệu cá nhân, và nó tự động tắt trong CI. Tắt bằng export OPENSPEC_TELEMETRY=0 hoặc export DO_NOT_TRACK=1.

Làm sao để nâng cấp? ​

Hai bước. Nâng cấp package (npm install -g @fission-ai/openspec@latest), sau đó chạy openspec update trong mỗi dự án để làm mới các skills và commands đã tạo.

Làm sao để gỡ cài đặt OpenSpec? ​

Không có lệnh gỡ cài đặt, vì nó chỉ là một package toàn cục cùng các tệp trong dự án của bạn. Xóa package (npm uninstall -g @fission-ai/openspec), và tùy chọn xóa thư mục openspec/ cùng các tệp công cụ đã tạo. Hướng dẫn từng bước, bao gồm những gì an toàn để giữ, nằm trong Cài đặt: Gỡ cài đặt.

Nhận hỗ trợ ​

Tôi hỏi câu hỏi hoặc báo lỗi ở đâu? ​

Tài liệu này sai hoặc gây nhầm lẫn. Tôi làm gì? ​

Hãy nói cho chúng tôi biết, hoặc sửa nó. Các PR tài liệu được chào đón và trân trọng. Mở một issue hoặc gửi pull request.