OpenSpec

Bảng thuật ngữ ​

Tất cả các thuật ngữ của OpenSpec được tập trung tại một nơi, được định nghĩa bằng ngôn ngữ đơn giản. Đọc lướt qua một lần để hiểu nhanh hơn phần còn lại của tài liệu.

Các thuật ngữ được nhóm theo chủ đề, sau đó sắp xếp theo thứ tự bảng chữ cái trong mỗi nhóm.

Các danh từ cốt lõi ​

Spec. Một tài liệu mô tả cách hoạt động của một phần trong hệ thống của bạn. Spec được lưu trữ trong openspec/specs/, được tổ chức theo lĩnh vực (domain) và bao gồm các yêu cầu (requirements) và kịch bản (scenarios). Spec là câu trả lời đã được thỏa thuận cho câu hỏi "phần mềm này làm gì?". Xem Concepts.

Source of truth. Toàn bộ thư mục openspec/specs/. Nó chứa hành vi hiện tại và đã được thỏa thuận của hệ thống của bạn. Các thay đổi đề xuất việc chỉnh sửa nó; việc lưu trữ (archiving) áp dụng những thay đổi đó.

Change. Một đơn vị công việc, được đóng gói dưới dạng một thư mục con trong openspec/changes/<name>/. Một change chứa mọi thứ liên quan đến công việc đó: đề xuất, thiết kế, nhiệm vụ và các chỉnh sửa spec mà nó giới thiệu. Một change tương ứng với một tính năng hoặc một bản sửa lỗi.

Artifact. Một tài liệu bên trong một change. Các artifact tiêu chuẩn bao gồm proposal, delta specs, design và tasks. Chúng được tạo theo thứ tự phụ thuộc và hỗ trợ lẫn nhau.

Delta spec. Một spec nằm trong một change chỉ mô tả những gì đang thay đổi, sử dụng các phần ADDED, MODIFIED và REMOVED, thay vì viết lại toàn bộ spec. Đây là cơ chế giúp OpenSpec chỉnh sửa các hệ thống hiện có một cách sạch sẽ. Xem Concepts.

Domain. Một nhóm logic cho các spec, ví dụ như auth/, payments/, hoặc ui/. Bạn chọn các domain phù hợp với cách bạn tư duy về hệ thống của mình.

Bên trong một spec ​

Requirement. Một hành vi cụ thể mà hệ thống phải có, thường được viết kèm theo một từ khóa RFC 2119: "Hệ thống PHẢI hết hạn phiên sau 30 phút." Requirements nêu rõ cái gì (what), chứ không phải cách nào (how).

Scenario. Một ví dụ cụ thể, có thể kiểm thử được về một requirement đang hoạt động, thường ở dạng Given/When/Then. Scenarios làm cho một requirement có thể xác minh được: bạn có thể viết một bài kiểm thử tự động dựa trên một scenario.

RFC 2119 keywords. Các từ MUST, SHALL, SHOULD và MAY, mang ý nghĩa chuẩn hóa về mức độ nghiêm ngặt của một requirement. MUST và SHALL là tuyệt đối. SHOULD là khuyến nghị nhưng vẫn có ngoại lệ. MAY là tùy chọn. Tên gọi này bắt nguồn từ tài liệu tiêu chuẩn internet định nghĩa chúng.

Các artifacts ​

Proposal (proposal.md). Lý do (why) và nội dung (what) của một thay đổi: ý định, phạm vi và phương pháp tiếp cận tổng quan. Đây là artifact đầu tiên bạn tạo.

Design (design.md). Cách thức (how): phương pháp kỹ thuật, các quyết định kiến trúc và các tệp tin bạn dự định tác động. Tùy chọn cho các thay đổi đơn giản.

Tasks (tasks.md). Danh sách kiểm tra triển khai, có các hộp kiểm. AI sẽ xử lý danh sách này trong quá trình /opsx:apply và đánh dấu hoàn thành từng mục khi thực hiện.

Vòng đời ​

Archive. Hành động hoàn tất một change. Các delta specs của nó được hợp nhất vào các spec chính, và thư mục change được di chuyển đến openspec/changes/archive/YYYY-MM-DD-<name>/. Sau khi archive, các spec của bạn sẽ mô tả thực tế mới. Xem Concepts.

Sync. Hợp nhất các delta specs của một change vào các spec chính mà không archive change đó. Thường diễn ra tự động (khi archive sẽ gợi ý thực hiện), nhưng cũng có thể thực hiện riêng lẻ thông qua lệnh /opsx:sync dành cho các change kéo dài thời gian. Xem Commands.

Quy trình và lệnh ​

OPSX. Quy trình OpenSpec tiêu chuẩn hiện tại, được xây dựng xung quanh các hành động linh hoạt thay vì các giai đoạn cứng nhắc. Tất cả các lệnh slash của nó đều bắt đầu bằng /opsx:. Xem OPSX Workflow.

Slash command. Một lệnh bạn nhập vào cuộc trò chuyện của trợ lý AI, chẳng hạn như /opsx:propose. Slash command điều khiển quy trình. Chúng không phải là lệnh terminal. Xem How Commands Work.

Explore (/opsx:explore). Lệnh "đối tác suy nghĩ". Nó đọc codebase của bạn, so sánh các tùy chọn và làm rõ một ý tưởng mơ hồ thành một kế hoạch cụ thể, mà không tạo ra bất kỳ artifact nào hay viết mã. Điểm bắt đầu được khuyến nghị bất cứ khi nào bạn gặp vấn đề nhưng chưa có kế hoạch. Xem Explore First.

CLI. Chương trình openspec bạn chạy trong terminal. Nó thiết lập dự án, liệt kê và xác thực các change, mở dashboard và archive. Đây là nửa terminal của OpenSpec. Xem CLI.

Skill. Một thư mục chứa hướng dẫn (.../skills/openspec-*/SKILL.md) mà trợ lý AI của bạn tự động phát hiện và tuân thủ. Skills là tiêu chuẩn đa công cụ đang nổi lên để cung cấp quy trình OpenSpec cho trợ lý của bạn.

Command file. Tệp lệnh slash dành cho từng công cụ (.../commands/opsx-*). Cơ chế phân phối cũ hơn, vẫn được hỗ trợ song song với skills. Bạn hiếm khi cần chạm vào các tệp này trực tiếp.

Profile. Tập hợp các lệnh slash được cài đặt trong dự án của bạn. Core (mặc định) bao gồm propose, explore, apply, update, sync, archive. Bộ expanded thêm vào new, continue, ff, verify, bulk-archive, onboard. Thay đổi profile bằng cách sử dụng openspec config profile.

Delivery. Việc OpenSpec cài đặt skills, command files, hoặc cả hai cho các công cụ của bạn. Được cấu hình toàn cục và áp dụng bằng lệnh openspec update.

Tùy chỉnh ​

Schema. Định nghĩa về các artifact mà một workflow có và cách chúng phụ thuộc vào nhau. Mặc định tích hợp sẵn là spec-driven (proposal → specs → design → tasks). Bạn có thể fork nó hoặc tự viết schema của mình. Xem Customization.

Template. Một tệp Markdown nằm trong một schema, định hình cách AI tạo ra nội dung cho một artifact cụ thể. Chỉnh sửa template sẽ thay đổi ngay lập tức kết quả đầu ra của AI mà không cần biên dịch lại.

Project config (openspec/config.yaml). Cài đặt cho từng dự án: schema mặc định, context: được đưa vào mọi yêu cầu lập kế hoạch, và các rules: cho từng artifact. Cách dễ nhất để dạy OpenSpec về stack và quy ước của bạn. Xem Customization.

Context injection. Đưa thông tin nền tảng của dự án vào trường context: của config.yaml để nó được tự động thêm vào mọi artifact mà AI tạo ra. Đáng tin cậy hơn là hy vọng AI đọc một tệp riêng biệt.

Dependency graph. Đồ thị có hướng được hình thành bởi các mối quan hệ requires: của artifact. Đó là một DAG (đồ thị có hướng không chu trình: các mũi tên chỉ trỏ về phía trước, không bao giờ tạo vòng lặp), và OpenSpec sử dụng nó để biết bạn có thể tạo artifact tiếp theo là gì.

Enablers, not gates. Nguyên tắc rằng các phụ thuộc giữa các artifact cho thấy những gì trở nên khả thi tiếp theo, chứ không phải những gì bắt buộc tiếp theo. Bạn có thể xem xét lại và chỉnh sửa bất kỳ artifact nào bất cứ lúc nào. Xem Core Concepts at a Glance.

Phối hợp across repos (beta) ​

Các thuật ngữ này chỉ áp dụng nếu việc lập kế hoạch của bạn trải rộng trên nhiều repo. Chúng đang trong giai đoạn beta. Hầu hết người dùng có thể bỏ qua chúng. Xem Stores User Guide.

Store. Một repo độc lập có nhiệm vụ duy nhất là lập kế hoạch. Nó có cùng cấu trúc openspec/ mà bạn đã quen thuộc (specs và changes) cộng thêm một tệp định danh nhỏ. Bạn đăng ký nó trên máy của mình một lần, theo tên, và sau đó bất kỳ lệnh OpenSpec nào cũng có thể hoạt động trên nó từ bất kỳ đâu.

Reference. Một khai báo trong openspec/config.yaml của một repo mã nguồn, chỉ ra một store mà repo đó sử dụng. References chỉ đọc: repo giữ gốc của riêng mình, và openspec instructions sẽ có một chỉ mục các spec của store được tham chiếu, mỗi spec đi kèm với lệnh chính xác để lấy nó.

Working context. Những gì openspec context tập hợp cho repo hiện tại: gốc OpenSpec của nó cộng với mọi store mà nó tham chiếu, mỗi store đều có cách lấy dữ liệu. Đây là câu trả lời cho câu hỏi "tôi đang làm việc với những gì?".

Workset. Một tập hợp các thư mục cá nhân, cục bộ trên máy, bạn mở cùng lúc (một store cùng với các repo mã nguồn bạn làm việc). Được tạo rõ ràng bằng lệnh openspec workset create; không có đường dẫn cục bộ nào trong số đó được commit vào repo lập kế hoạch chia sẻ.

Xem thêm ​