ait-native

本地快速上手

從一個小任務，走到可驗收的結果。

先用沒有第三方套件的任務清單範例試跑，再把同一套流程帶進自己的儲存庫。

試跑範例使用自己的儲存庫

建議的跨平台方式

從 PyPI 安裝

Wheel 支援 macOS、Linux 與 Windows。Python 負責安裝套件；ait 工作流本身是原生程式。

python -m pip install ait-native
改用 Homebrew、npm、apt 或發布封存檔

Homebrew · macOS 與 Linux

brew tap weita2026/ait-native
brew install ait-native

安裝 ait 和預設不啟動的 ait-server。

npm · 直接的 Node.js API

npm install --global @wa120/ait-native

安裝 JS/TS API、Node-API 元件與在程序內執行的 ait 命令，不含伺服器。

apt · Debian 與 Ubuntu

# 先加入已簽名的 stable 套件庫
sudo apt install ait-native

1.1.1 支援 amd64 與 arm64。設定套件庫。

AIT · 1.1.1

第一個 Task，有明確結果可以檢查。

先完成上方的 AIT 安裝，再用新資料夾試跑。此範例需要 Node.js 22 或更新版本，以及你自己的 coding agent。Node.js 只是範例的需求；agent 可能使用你的模型供應商帳戶。

下載範例 ZIP核對 SHA-256

  1. 1. 解壓縮，確認起點

    用檔案管理員解壓縮 ZIP，在解出的 ait-first-task 資料夾開啟終端機。起始的三項測試應全部通過，不需要執行 npm install。

    node --version
node --test tests/baseline.test.mjs

  2. 2. 初始化範例

    在這裡執行 ait init，再用 coding agent 開啟此資料夾。先請它閱讀產生的 AGENTS.md，再開始工作。

    將「你的名稱」替換成你要記錄在本地 Task 審查中的名稱。下方初始 Snapshot 會在任何 Task 啟動前記錄未修改的範例；這段準備只用於全新範例資料夾。

    ait init
ait config set --user-name "你的名稱"
ait snapshot create --message "Start the AIT example"
    查看初始化會修改的內容 →

  3. 3. 把這個需求交給 agent

    閱讀 AGENTS.md，依這個儲存庫的 AIT 工作流完成任務。在 src/tasks.mjs 新增 openTasks(tasks)：回傳一個新陣列，保留 done 不為 true 的任務、原始順序與任務物件，不修改輸入。維持 taskTitles 的既有行為，補上針對性測試。不要修改 checks/、移除既有測試或新增套件。完成 Task 前，執行既有測試與 node checks/first-task.mjs。

  4. 4. 回原始資料夾驗收

    agent 回報 Task finish 後，回到原始解壓縮資料夾執行下列兩項檢查。功能尚未實作前，驗收檢查預期會失敗。

    node --test tests/*.test.mjs
node checks/first-task.mjs

    功能案例通過時會印出 FIRST_TASK_ACCEPTED。也請檢視實際 Task finish 結果：Task 已完成、工作區已清理，且適用的綁定 sprint 項目已結案。功能驗收與工作流完成要分別確認。

卡住時怎麼辦

如果找不到 node 或 ait，先完成對應安裝。若 agent 沒讀 AGENTS.md，在已初始化的資料夾開新對話，請它先讀取該檔案。檢查失敗時，將結果交回同一個 Task，保留檢查並修正功能。衝突需要解決並重新檢查，才能完成工作。

下一步：試跑三個相容的並行 Task

使用全新解壓縮的範例並初始化。在這個儲存庫開三個獨立 agent 對話，各交辦一個需求；每個都要遵循 AGENTS.md、綁定自己的 sprint 項目，只在回傳的 edit_root 內工作，保留 checks/ 與既有測試，使用不同測試檔。需求 A 就是上方第一個需求。

開啟三個對話前，請重做上方完整初始化步驟，包含初始 Snapshot。

需求 B：在 src/labels.mjs 新增 taskCountLabel(count)，輸入為非負整數。1 回傳 "1 task"，其他回傳 "N tasks"。保留 boardTitle。在獨立檔案新增測試，執行既有測試並完成 Task。
需求 C：在 src/priority.mjs 新增 priorityRank(value)。high、normal、low 分別回傳 0、1、2；未知或未提供的值回傳 3。保留 priorityOrder。在獨立檔案新增測試，執行既有測試並完成 Task。

三個 Task 全部完成後，在原始資料夾執行下列命令，應看到 PARALLEL_TASKS_ACCEPTED。此練習涵蓋相容修改，不刻意製造衝突，也沒有量測吞吐量；請如實記錄實際發生的衝突、檢查失敗與人工介入。

node --test tests/*.test.mjs
node checks/parallel-tasks.mjs

儲存庫信任邊界

先看清楚 ait init 會改什麼。

請在 coding agent 要修改的儲存庫中執行。

cd <你的儲存庫>
ait init
  • 建立儲存庫本地的 .ait/ 狀態與 docs/sprints/。
  • 在 AGENTS.md 建立或更新一段有明確標記的工作流區塊。
  • 完整保留標記外的 AGENTS.md 內容；再次執行不會重複加入區塊。
  • 若沒有 CLAUDE.md，建立一個指向 AGENTS.md 的最小入口；既有檔案絕不覆寫。
  • 不啟動伺服器，也不把儲存庫資料送到任何地方。
日後若要移除儲存庫整合

AIT 1.1.1 刻意不提供一鍵移除儲存庫的命令。若歷史仍有價值，先保留 .ait/；只刪除 AGENTS.md 裡的標記區塊；只有在產生的 CLAUDE.md 仍僅含 AIT 指標時才移除它。Sprint Markdown 可能是使用者內容，絕對不要直接刪除整個 docs/sprints/。

既有專案請先依入門文件導入既有狀態並設定審查名稱；已由 AIT 管理的儲存庫，請沿用目前的 AGENTS.md。

範例成功後，在自己的專案挑選一個範圍清楚、方便審查的修改。

照平常的方式跟 coding agent 說

加一個無障礙的密碼顯示控制。
登入 API 不要動，並補上測試。

產生的儲存庫指示會要求 agent 記錄需求、開啟隔離 Task、跑檢查，再完成驗過的結果。你不必把需求翻成 AIT 命令。

檢查本地狀態

ait --version
ait status --json
{
  "ok": true,
  "line_name": "main",
  "workspace": { "status": "clean" },
  "next_action": null
}

現在交給 agent 一個真實任務。

檢視完成的修改，再在自己的專案選擇下一個小任務。

看完整工作流程查看發布狀態