Hướng dẫn OpenSpec (2026): Từng bước phát triển phần mềm hướng đặc tả trong Claude Code

Nội dung trọng tâm: - OpenSpec là công cụ dòng lệnh miễn phí, yêu cầu tác nhân lập trình AI (coding agent) lập kế hoạch ngắn trước khi can thiệp vào mã nguồn: lý do thay đổi, các điều kiện cần đạt được sau thay đổi, phương thức xây dựng và các bước thực hiện. Các kế hoạch này tồn tại song song với mã nguồn dưới dạng thông số kỹ thuật (spec). - Công cụ được áp dụng khi chỉnh sửa một ứng dụng hiện có. Mỗi thay đổi được ghi nhận dưới dạng mức chênh lệch (delta) so với thông số kỹ thuật hiện tại; việc lưu trữ thay đổi sẽ tự động hợp nhất nội dung này, bảo đảm thông số kỹ thuật luôn chính xác mà không cần biên soạn lại thủ công. - Trong Claude Code, quy trình gồm ba lệnh: /opsx:propose để lập kế hoạch, /opsx:apply để triển khai trong phiên làm việc mới, và /opsx:archive để hợp nhất. Các tài liệu hướng dẫn sử dụng lệnh /openspec:proposal hiện đã lỗi thời. - Khâu quan trọng là quá trình kiểm tra giữa hai bước lập kế hoạch (propose) và triển khai (apply). Bản chênh lệch thông số kỹ thuật (spec delta) đóng vai trò là căn cứ cam kết để tác nhân lập trình thực hiện; việc đặt sai cấp độ tiêu đề kịch bản (scenario heading) có thể làm mất yêu cầu kỹ thuật mà không xuất hiện thông báo lỗi. - Không cần áp dụng công cụ này đối với các lỗi nhỏ trong một tệp hoặc các chỉnh sửa nội dung thuần túy. Việc tạo bốn tệp cho mỗi lần thay đổi làm phát sinh chi phí vận hành thực tế, và bản thông số kỹ thuật hợp nhất chỉ có giá trị khi được đưa vào sử dụng thực chất. OpenSpec hiện đạt khoảng 72.000 lượt gắn sao trên GitHub (Fission-AI/OpenSpec, tính đến ngày 17/10/2026). Vào tháng 1, dự án đã thay thế toàn bộ hệ thống lệnh gạch chéo (slash command). Đa số các tài liệu hướng dẫn hiện nay vẫn đề cập đến lệnh /openspec:proposal, vốn là lệnh không còn tồn tại. Trong quá trình thử nghiệm OpenSpec trên cơ sở mã nguồn Next.js, một thao tác làm sai lệch tiêu đề kịch bản đã được thực hiện có chủ đích: sử dụng ba dấu thăng (#) thay vì bốn tại quy tắc trả về mã lỗi 403 đối với thành viên. Lệnh openspec validate --strict vẫn báo cáo thay đổi hợp lệ. Hệ thống chỉ hiển thị một dòng thông tin (INFO) rất dễ bị bỏ sót và loại bỏ hoàn toàn kịch bản này; hệ quả là tác nhân AI sẽ xây dựng hệ thống khóa API mà không có quy tắc xử lý lỗi 403. Do đó, việc kiểm tra đối chiếu số lượng kịch bản trong từng bản chênh lệch với yêu cầu ban đầu trước khi chạy lệnh /opsx:apply là bắt buộc, bởi khâu đánh giá này là phần duy nhất trong quy trình mà OpenSpec không thể tự động hóa. Dưới đây là một trường hợp thay đổi thực tế đối với hệ thống khóa API cấp tổ chức, được thực hiện từ bước lập kế hoạch đến lưu trữ trong Claude Code trên nền tảng OpenSpec 1.14.3, đi kèm toàn bộ các tệp được khởi tạo và kết quả hiển thị trên giao diện dòng lệnh (về nguyên nhân thông số kỹ thuật bằng văn bản mang lại hiệu quả cao hơn câu lệnh nhắc thông thường, có thể tham khảo tài liệu hướng dẫn phát triển dựa trên thông số kỹ thuật). Tổng quan về OpenSpec trong một đoạn văn OpenSpec là công cụ dòng lệnh kết hợp hệ thống các lệnh gạch chéo nhằm duy trì một thư mục chứa thông số kỹ thuật song song với mã nguồn, đồng thời dẫn hướng mọi thay đổi qua bốn tệp ngắn gọn trước khi tác nhân AI viết mã: tệp đề xuất nêu rõ lý do, tệp chênh lệch thông số kỹ thuật nêu rõ các điều kiện cần đạt được, bản ghi chú thiết kế giải thích phương thức thực hiện, và danh sách tác vụ phân bổ các bước tiến hành. OpenSpec định danh bốn tệp này là các tạo phẩm (artifacts). Điểm khác biệt giữa công cụ này với thư mục chứa tài liệu yêu cầu sản phẩm (PRD) thông thường nằm ở cơ chế chênh lệch (delta). Thay đổi được mô tả dưới dạng các yêu cầu ĐƯỢC THÊM (ADDED), SỬA ĐỔI (MODIFIED), XÓA BỎ (REMOVED) hoặc ĐỔI TÊN (RENAMED). Khi công việc hoàn tất, lệnh openspec archive sẽ hợp nhất các bản chênh lệch này vào thông số kỹ thuật hiện hành. Nhờ đó, thông số kỹ thuật luôn duy trì tính cập nhật mà không cần viết lại thủ công, lý giải nguyên nhân dự án tự định vị là công cụ dành cho các cơ sở mã nguồn hiện có thay vì các dự án phát triển mới từ đầu. Công cụ này được phát hành theo giấy phép MIT, đóng gói dưới dạng một gói Node duy nhất, và cùng sáu luồng quy trình làm việc có thể cài đặt trên Claude Code, Codex, Cursor, Copilot cùng phần lớn các tác nhân lập trình khác, với cú pháp tên lệnh tương ứng trên từng nền tảng. Điều kiện tiên quyết: Node 20.19, Claude Code và cơ sở mã nguồn hiện có Toàn bộ quy trình dưới đây được triển khai trên cơ sở mã nguồn nội bộ: ứng dụng SaaS trên nền tảng Next.js 16 tích hợp Prisma, Clerk và REST API phân quyền cấp tổ chức, tương tự ngăn xếp công nghệ được mô tả trên trang khởi tạo Next.js SaaS. Thay đổi được áp dụng là hệ thống khóa API cấp tổ chức, đồng nhất với ví dụ trong hướng dẫn phát triển dựa trên thông số kỹ thuật. Các câu lệnh được thiết kế cho môi trường giao diện dòng lệnh macOS và Linux; trên hệ điều hành Windows, các lệnh openspec hoàn toàn tương tự và chỉ có lớp vỏ bao quanh chúng có sự thay đổi. OpenSpec yêu cầu Node.js phiên bản 20.19 trở lên và một dự án đã có sẵn mã nguồn, do một kho lưu trữ (repo) trống sẽ không cung cấp dữ liệu cho bước đề xuất phân tích. npm install -g @fission-ai/openspec@latest openspec --version # Homebrew cũng có thể sử dụng, song thường chậm hơn npm một bản vá brew install openspecCài đặt công cụ này trên phạm vi toàn hệ thống (global). Tài liệu hướng dẫn không đề cập đến cú pháp npx nên định dạng này không được đưa vào. Các bản vá lỗi được phát hành gần như hằng tuần, do đó việc chạy lệnh openspec version --check là cần thiết trước khi thực hiện theo bất kỳ tài liệu hướng dẫn nào, kể cả tài liệu này; bên cạnh đó, Homebrew thường cập nhật chậm hơn npm một bản vá. Hệ thống cũng cần phiên bản Claude Code hiện hành: nếu các lệnh đã tồn tại trên ổ đĩa nhưng mục /opsx: không hiển thị nội dung sau khi thiết lập, giải pháp theo tài liệu hướng dẫn là cập nhật Claude Code và khởi động lại. Hai lưu ý đối với các khối nội dung dưới đây: Kết quả đầu ra của dòng lệnh được trích xuất từ quá trình thực thi và được lược bớt để giữ lại các dòng trọng tâm, loại bỏ các dòng trạng thái chờ (spinner), đường dẫn tuyệt đối và liên kết ở chân trang. Bốn tệp kế hoạch được tạo lập dựa trên các tệp mẫu mà CLI cung cấp cho tác tử (agent) và đã được kiểm tra bằng lệnh openspec validate, do cách diễn đạt của tác tử có sự khác biệt trong mỗi lần chạy. Quy mô phát triển của công cụ: Đạt khoảng 2,9 triệu lượt tải xuống qua npm trong 30 ngày qua, tăng từ khoảng 81.000 lượt vào tháng 1/2026 (theo số liệu thống kê lượt tải của npm, tháng 10/2026). Số lượt tải xuống bao gồm cả các quy trình CI và máy chủ sao lưu (mirror), do đó số liệu này phản ánh số lượt cài đặt thay vì số lượng lập trình viên thực tế.Bước 1: Lệnh openspec init và sáu lệnh được cài đặt Chạy lệnh init tại thư mục gốc của kho lưu trữ và khai báo các công cụ được sử dụng. Nếu không có tham số --tools, hệ thống sẽ đưa ra câu hỏi tương tác; trong khi đó, nếu chạy trong một tập lệnh (script), hệ thống sẽ sử dụng các công cụ tự động nhận diện được. cd acme-saas openspec init --tools claudeOpenSpec Setup CompleteCreated: Claude Code 6 skills and 6 commands in .claude/ Config: openspec/config.yaml (schema: spec-driven)Getting started: Start your first change: /opsx:propose "your idea"Nội dung đầu ra đầy đủ tiếp tục liệt kê sáu quy trình làm việc tùy chọn và hiển thị hai liên kết; các phần này đã được lược bớt. Toàn bộ cấu trúc được tạo ra, theo danh sách từ lệnh find, bao gồm: sáu tệp lệnh trong .claude/commands/opsx/, sáu kỹ năng (skills) tương ứng và một thư mục openspec/ chứa một tệp cấu hình cùng hai thư mục trống. Đơn vị phát triển dự án cho biết lệnh và kỹ năng của một quy trình làm việc đều mang chỉ dẫn như nhau và dự kiến các lệnh sẽ dần bị loại bỏ, do đó kỹ năng sẽ là thành phần tiếp tục được duy trì trong năm tới. find openspec .claude -type f | sort .claude/commands/opsx/apply.md .claude/commands/opsx/archive.md .claude/commands/opsx/explore.md .claude/commands/opsx/propose.md .claude/commands/opsx/sync.md .claude/commands/opsx/update.md .claude/skills/openspec-apply-change/SKILL.md .claude/skil