Cài đặt

Trước khi bắt đầu

• Cần biết: cách mở terminal và gõ lệnh; biết máy mình chạy Windows, macOS hay Linux
• Cần có: Python 3.11 trở lên, git (tùy chọn), và một công cụ AI lập trình đã cài
• Cần đang ở: thư mục mẹ nơi bạn muốn tạo dự án; mọi lệnh dưới đây gõ ở terminal

1. Kiểm tra điều kiện tiên quyết

Chạy hai lệnh sau để xem máy bạn đã có gì.

python3 --version

Kết quả mong đợi: in ra Python 3.11.x hoặc cao hơn. Nếu thấp hơn 3.11, cài bản Python mới trước khi đi tiếp.

git --version

Kết quả mong đợi: in ra git version 2.x.x. Nếu báo command not found, bạn vẫn đi tiếp được: git chỉ cần khi bạn dùng tiện ích mở rộng github.

2. Cài uv

uv là công cụ quản lý gói Python. Cách cài khác nhau theo hệ điều hành.

macOS và Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Kết quả mong đợi: script tải và cài uv, in ra dòng cuối dạng installed to /root/.local/bin/uv.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Kết quả mong đợi: script tải và cài uv vào %USERPROFILE%\.local\bin\uv.exe.

Windows bằng WinGet:

winget install --id=astral-sh.uv -e

Kết quả mong đợi: WinGet báo đã cài xong gói astral-sh.uv.

Sau khi cài, đóng terminal và mở lại, rồi xác nhận:

uv --version

Kết quả mong đợi: in ra uv 0.x.x.

3. Cài specify-cli

Chạy một lệnh duy nhất để cài Spec Kit ở dạng công cụ dùng chung cho mọi thư mục:

uv tool install specify-cli

Kết quả mong đợi: uv tải gói specify-cli từ PyPI và in ra Installed 1 executable: specify.

Cách cài thay thế

Nếu bạn không muốn dùng uv, hai cách sau cho kết quả tương đương. Chọn một cách.

pipx install specify-cli

Kết quả mong đợi: pipx cài specify-cli vào môi trường riêng và in ra installed package specify-cli.

pip install specify-cli

Kết quả mong đợi: pip cài specify-cli vào môi trường Python hiện tại và in ra Successfully installed specify-cli-.... Cách này cài vào môi trường hiện tại nên dễ xung đột gói hơn; uv tool và pipx cô lập công cụ nên được khuyến nghị trước.

4. Kiểm tra bản cài

specify version

Kết quả mong đợi: in ra số phiên bản, dạng specify 1.1.3. Tài liệu này được kiểm chứng với Spec Kit 1.1.3.

specify check

Kết quả mong đợi: liệt kê các công cụ và điều kiện mà Spec Kit cần, mỗi dòng kèm trạng thái đạt hay thiếu. Dùng kết quả này để biết còn thiếu gì trước khi khởi tạo dự án.

5. Khởi tạo dự án đầu tiên

Đặt tên dự án không dấu, không khoảng trắng. Thay ten-du-an bằng tên bạn muốn.

specify init ten-du-an --integration dsh

Kết quả mong đợi: Spec Kit tạo thư mục ten-du-an, chép các mẫu và script vào .specify/, và in ra danh sách skill đã cài. Với DeepSeek Harness, skill được cài vào .dsh/skills/ và gọi bằng cú pháp /speckit-<tên>, ví dụ /speckit-specify.

Nếu thư mục đã tồn tại và có tệp, Spec Kit sẽ cảnh báo về việc trộn tệp. Hãy sao lưu hoặc commit thay đổi trước, rồi thêm --force khi bạn đã chắc chắn.

6. Vào thư mục dự án

cd ten-du-an

Kết quả mong đợi: dấu nhắc terminal chuyển sang thư mục ten-du-an. Bạn có thể chạy ls -a (macOS/Linux) hoặc dir (Windows) để thấy hai thư mục .specify/ và .dsh/.

Từ đây, mọi việc khởi tạo đã xong. Bước tiếp theo không làm ở terminal nữa.

Kết quả

Sau khi hoàn thành trang này, bạn đã:

• Cài uv và specify-cli
• Xác nhận bản cài bằng specify version và specify check
• Tạo một dự án Spec Kit đã khởi tạo với tích hợp dsh
• Đang đứng trong thư mục gốc của dự án đó

Cách tự xác nhận: chạy specify version và thấy số phiên bản, rồi chạy ls -a trong thư mục dự án và thấy cả .specify/ lẫn .dsh/skills/. Trang kế tiếp là Dự án đầu tiên.

Lỗi thường gặp

Lỗi	Nguyên nhân	Cách khắc phục
command not found: uv	uv chưa cài, hoặc terminal chưa nạp lại biến môi trường	Đóng terminal và mở lại. Nếu vẫn lỗi, kiểm tra ~/.local/bin (macOS/Linux) hoặc %USERPROFILE%\.local\bin (Windows) đã có trong PATH chưa
command not found: specify	Chưa cài specify-cli, hoặc cài vào môi trường mà PATH không thấy	Chạy lại bước 3. Ưu tiên uv tool install specify-cli vì nó đặt lệnh vào thư mục công cụ chung
error: externally-managed-environment	pip từ chối cài vào Python do hệ điều hành quản lý	Dùng uv tool install specify-cli hoặc pipx install specify-cli thay cho pip
Permission denied khi cài	Không có quyền ghi vào thư mục hệ thống	Không dùng sudo. Cài trong thư mục người dùng bằng uv tool install hoặc pipx install, cả hai đều ghi vào thư mục của bạn
Failed to fetch hoặc lỗi mạng khi tải gói	Mạng bị chặn, cần proxy, hoặc môi trường nội bộ không ra được PyPI	Kiểm tra pip config list để xem proxy. Trong môi trường nội bộ, trỏ tới package index riêng của tổ chức rồi cài lại
Python 3.11 or higher is required	Python trên máy quá cũ	Cài Python 3.11 trở lên, hoặc để uv tự quản lý phiên bản Python cho bạn
Integration 'dsh' not found	Tên integration gõ sai	Chạy specify integration để xem danh sách tích hợp hợp lệ, rồi chạy lại specify init với đúng key

---

Nguồn tham chiếu: Installation GuidePhiên bản kiểm chứng: Spec Kit 1.1.3