Quy trình ưu tiên đặc tả
Xác định yêu cầu trước khi viết mã.
OpenSpecPhát triển dựa trên đặc tả cho trợ lý AI
Một đặc tả nhẹ nhàng để xây dựng và quản lý các dự án trợ lý AI.
Chào mừng bạn. Đây là nơi tập hợp mọi thứ về OpenSpec.
OpenSpec giúp bạn và trợ lý lập trình AI của bạn đồng thuậ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. Bạn mô tả thay đổi, AI phác thảo một đặc tả ngắn và danh sách tác vụ, cả hai cùng xem một kế hoạch chung, và sau đó công việc được thực hiện. Không còn cảnh phát hiện giữa chừng rằng AI đã xây dựng sai thứ cần thiết.
Nếu bạn chỉ đọc hai trang, hãy đọc hai trang này:
/opsx:propose (gợi ý: trong chat AI của bạn, không phải trong terminal). Điều này làm hầu hết mọi người bối rối ít nhất một lần.Trang thứ hai quan trọng hơn bạn tưởng. OpenSpec có hai phần: một công cụ dòng lệnh bạn chạy trong terminal, và các lệnh slash bạn gửi cho trợ lý AI của mình. Biết được cái nào là cái nào giúp bạn tránh được khoảnh khắc bối rối phổ biến nhất.
Thói quen tốt nhất nên xây dựng đầu tiên: khi bạn không chắc cần xây dựng gì, hãy bắt đầu với
/opsx:explore. Đây là một người bạn đồng hành tư duy không rủi ro, đọc mã của bạn, cân nhắc các phương án, và làm rõ một ý tưởng mơ hồ thành một kế hoạch cụ thể trước khi bất kỳ tài liệu hay mã nào tồn tại. Hướng dẫn Khám phá trước trình bày lý do.
Tôi hoàn toàn mới. Bắt đầu với Bắt đầu, sau đó lướt qua Tổng quan các khái niệm cốt lõi. Khi có điều gì đó cảm thấy bí ẩn, FAQ và Bảng thuật ngữ ở ngay gần đó.
Tôi có vấn đề nhưng chưa có kế hoạch. Đây là trường hợp phổ biến, và nó có một câu trả lời riêng: Khám phá trước. Sử dụng /opsx:explore để suy nghĩ cùng AI trước khi cam kết bất cứ điều gì.
Tôi có một codebase lớn hiện có. Bạn không cần tài liệu hóa tất cả. Sử dụng OpenSpec trong dự án hiện có cho thấy cách bắt đầu với mã thực tế, mã brownfield mà không cần "sôi cả đại dương".
Tôi chỉ muốn nó hoạt động. Cài đặt, chạy openspec init, sau đó đọc Cách các lệnh hoạt động để lệnh slash đầu tiên của bạn đến đúng nơi. Hoặc giao việc thiết lập cho trợ lý của bạn bằng mẫu prompt cài đặt có trợ giúp AI.
Tôi học qua ví dụ. Trang Ví dụ & Công thức hướng dẫn qua các thay đổi thực tế từ đầu đến cuối: một tính năng nhỏ, một sửa lỗi, một refactor, một cuộc khám phá.
AI vừa phác thảo một kế hoạch — giờ thì sao? Đọc nó. Đánh giá một thay đổi cho thấy bước rà soát hai phút để phát hiện sai hướng khi chi phí còn thấp, và Viết đặc tả tốt bao quát những gì tạo nên một kế hoạch đáng phê duyệt.
Tôi làm việc theo nhóm. OpenSpec trong nhóm cho thấy cách một thay đổi được ánh xạ vào một nhánh và một pull request, và cách các thành viên nhóm đánh giá kế hoạch trước khi có mã.
Tôi chuyển từ quy trình cũ. Hướng dẫn di chuyển giải thích điều gì đã thay đổi và tại sao, và cam kết công việc hiện có của bạn vẫn an toàn.
Tôi muốn điều chỉnh nó theo quy trình của nhóm mình. Tùy chỉnh bao quát cấu hình dự án, schema tùy chỉnh và ngữ cảnh chung.
Có thứ gì đó bị hỏng. Xử lý sự cố tập hợp các lỗi mà mọi người thực sự gặp phải, kèm theo cách sửa.
| Tài liệu | Nội dung cung cấp |
|---|---|
| Bắt đầu | Cài đặt, khởi tạo và chạy thay đổi đầu tiên từ đầu đến cuối |
| Khám phá trước | Sử dụng /opsx:explore để suy nghĩ về một ý tưởng trước khi cam kết |
| Cách các lệnh hoạt động | Nơi lệnh slash chạy, "chế độ tương tác" nghĩa là gì, terminal so với chat |
| Tổng quan các khái niệm cốt lõi | Toàn bộ mô hình tư duy trên một trang: specs, changes, deltas, archive |
| Cài đặt | npm, pnpm, yarn, bun, Nix, một prompt giao việc thiết lập cho trợ lý AI của bạn, và cách xác minh nó đã hoạt động |
| Tài liệu | Nội dung cung cấp |
|---|---|
| Quy trình làm việc | Các mẫu phổ biến và khi nào nên dùng mỗi lệnh |
| Ví dụ & Công thức | Hướng dẫn đầy đủ về các thay đổi thực tế, có thể copy-paste |
| Viết đặc tả tốt | Một yêu cầu và kịch bản mạnh trông như thế nào, và cách xác định kích thước thay đổi phù hợp |
| Đánh giá một thay đổi | Bước rà soát hai phút trên kế hoạch đã phác thảo trước khi viết mã |
| OpenSpec trong nhóm | Cách các thay đổi khớp với nhánh, pull request và đánh giá |
| Sử dụng OpenSpec trong dự án hiện có | Áp dụng OpenSpec trên codebase brownfield lớn |
| Chỉnh sửa & Lặp lại trên một thay đổi | Cập nhật tài liệu, quay lại, đối chiếu các chỉnh sửa thủ công |
| Lệnh | Tham khảo cho mọi lệnh slash /opsx:* |
| CLI | Tham khảo cho mọi lệnh terminal openspec |
| Tài liệu | Nội dung cung cấp |
|---|---|
| Khái niệm | Giải thích chi tiết về specs, changes, artifacts, schemas và archive |
| Quy trình OPSX | Tại sao quy trình linh hoạt thay vì khóa theo giai đoạn, cùng với tìm hiểu sâu kiến trúc |
| Bảng thuật ngữ | Mọi thuật ngữ được định nghĩa tại một nơi |
| Tài liệu | Nội dung cung cấp |
|---|---|
| Tùy chỉnh | Cấu hình dự án, schema tùy chỉnh, ngữ cảnh chung |
| Đa ngôn ngữ | Tạo tài liệu bằng các ngôn ngữ khác ngoài tiếng Anh |
| Công cụ được hỗ trợ | 30+ công cụ AI mà OpenSpec tích hợp, và vị trí các tệp được đặt |
| Góc cộng đồng | Các dự án và tài nguyên được xây dựng với và cho OpenSpec |
| Tài liệu | Nội dung cung cấp |
|---|---|
| FAQ | Trả lời nhanh cho các câu hỏi phổ biến nhất |
| Xử lý sự cố | Cách sửa cụ thể cho các lỗi cụ thể |
| Hướng dẫn di chuyển | Chuyển từ quy trình cũ sang OPSX |
| Tài liệu | Nội dung cung cấp |
|---|---|
| Stores: Hướng dẫn người dùng | Lập kế hoạch trong repo riêng khi công việc của bạn trải dài qua nhiều repo hoặc nhóm |
| Hợp đồng Agent | Các bề mặt CLI có thể đọc bằng máy mà agent sử dụng |
1. Cài đặt npm install -g @fission-ai/openspec@latest
2. Khởi tạo cd your-project && openspec init
3. Khám phá (trong chat AI của bạn) /opsx:explore ← tùy chọn, nhưng là thói quen tuyệt vời
4. Đề xuất (trong chat AI của bạn) /opsx:propose add-dark-mode
5. Xây dựng (trong chat AI của bạn) /opsx:apply
6. Lưu trữ (trong chat AI của bạn) /opsx:archiveBước 1 và 2 diễn ra trong terminal của bạn. Phần còn lại diễn ra trong chat của trợ lý AI của bạn. Sự phân chia đó là điều duy nhất đáng ghi nhớ, và Cách các lệnh hoạt động giải thích chính xác tại sao. Bước 3 là tùy chọn, nhưng bắt đầu với /opsx:explore khi bạn không chắc chắn là thói quen đáng hình thành nhất.
openspec feedback "your message" gửi phản hồi trực tiếp từ terminal của bạn (nó mở một GitHub issue).Phát hiện điều gì đó trong tài liệu này không đúng, lỗi thời hoặc gây nhầm lẫn? Đó là một lỗi. Mở một issue hoặc PR. Cải thiện tài liệu là một trong những đóng góp có giá trị nhất bạn có thể thực hiện.