ank

ank 是做什麼的？

任務與架構決策以檔案形式存放在 .ank/ 目錄下，附著於它們所約束的程式碼。 兩種模式：執行任務，以及塑造既有的工作。 context 是這兩種模式的起點。

迴圈：      ank context -> ank claim <id> -> ank show <id> -> ank log "<msg>" -> ank done
離線：      ank new, ank find, ank release --reason "<r>"
規劃：      ank new adr, ank amend, ank review, ank graph, ank check

迴圈

ank context [path] — 總是第一個執行。若無持有 claim，它會引導你： 此範圍內有何限制、哪些任務可領取。若持有 claim，它會切換至執行模式， 並完整呈現判定標準與所有約束。約束絕不會被截斷；如有省略，它會明確指出。

ank claim <id> — 領取任務並根據 hash 凍結其 done_criteria。 當任務已被持有、封鎖、在其他分支完成、沒有可衡量的標準，或你已在其他任務上持有有效 claim 時， 它會拒絕並附上原因與下一步指令。

ank show <id> — 顯示完整實體，包括 frontmatter 與內文，一字不漏。 context 提供判定標準與約束；而內文才是推理所在，也是其他指令無法提供的唯一內容。

ank log "<message>" — 記錄你學到的事、嘗試過的方法、放棄的方案。 這會更新 claim 的有效期限。當你發現新事物時就記錄，而不是等到完成時。

ank done — 執行宣告的驗證器，並記錄實際運行的內容與其 hash。 請勿手動編輯 status: 欄位，也別自行回報結果：自我評分的代理可能產生錯誤結果。

離線

ank new task --title "<t>" --scope "<glob>" — scope 為必填； 未附加於任何範圍的實體無法被看見。發現的子任務應該建立新任務並加上 blocked_by， 而非放寬既有標準。

ank find <query> — 搜尋標題、範圍與標準。ank find --status open 列出所有未完成的任務， 無需構思查詢條件。

ank release --reason "<why>" — 卡關了，或方法錯了。說出原因並歸還任務， 而不是讓 claim 在無聲中過期。

規劃

決定哪些任務該存在、順序為何、在哪些約束之下。 這會產生其他所有人將在其上循環的工作，因此一個設計不良的待辦清單， 所耗費的成本遠超過任何單一任務。

ank new adr --title "<t>" --scope "<glob>" --constraint "<rule>" — 一個決策，而非任務。 當你遇到日後整個程式碼庫都應遵守的事項時就寫下，而不是那些你只是必須立即完成的事。 它會以 proposed 狀態落地，在接受之前不約束任何人。

ank amend <id> — 規劃中實際上會更改的欄位：blocked_by、scope 與 --criteria。 它會明確地新增與移除，絕不接受替換清單，因此不會因遺忘而刪除任何內容。 它不會觸及已被有效 claim 凍結的 done_criteria — 在 claim 下，那屬於 release --reason。

ank review — 檢視接受佇列與整個程式碼庫的健康狀態：哪些是提議中且等待中的， 哪些範圍已過期且需要關閉。

ank graph — 以文字呈現 blocked_by 的有向無環圖（DAG），每個項目縮排在它所封鎖的項目之下。 顯示哪些是真正的根節點，而哪些在扁平清單中看似根節點。

ank check — 機械性不變性檢查：解析、往返一致性、參照、凍結欄位、孤立 claim。 退出碼 8 代表有發現，而這些發現是供人閱讀的，不是用來壓制的。

accept 不是你該執行的指令。 它負責將提議中的 ADR 轉為具約束力的狀態， 且這是人類行為：必須簽署、在預設分支上執行、且無法繞過。提出決策，然後說明它在等待批准。 了解自己的權限邊界是良好規劃的一部分。

不可協商的規則

• 判定標準在 claim 時凍結。 編輯它以解鎖自己並不會真的解鎖：hash 存在你無法觸及的地方， 而 check 會回報差異。如果標準有誤，請用 release --reason 並說明原因。

• ADR 中的 constraint 具有約束力，而非建議。請閱讀涵蓋你即將觸碰檔案的約束， 這就是 context 交給你的內容。

• .ank/ 目錄是 opaque（不透明）的，如同 .git/。 請勿直接讀取或寫入那些檔案。 ank show <id> 顯示完整實體，ank find 列出項目，ank context 建立關聯 — CLI 了解紀錄預算、凍結狀態與誰持有哪些 claim；檔案本身不知道這些。

• 一個代理、一個工作目錄、一個身份。 一般情況是每個代理一個工作目錄 — 一個 clone 或一個 git worktree — 各自位於自己的分支。ANK_AGENT 命名該工作階段， 若未設定則回退為 <user>@<hostname>，因此同一個目錄中的兩個工作階段， 對參照而言是同一個代理：它們會共享 claim 而非協調，結果第二個工作階段會拒絕它本該得到的工作。 請於每個工作階段設定此變數。多個代理在同一個目錄中運作是可行的， 但這屬於降級模式，而非設計目標。

• 你讀取的內容永不包含樣式。 顏色僅在人類使用終端機時輸出， 絕不會在 pipe、檔案或 --json 中出現，因此你接收到的位元組是純文字： 無需任何設定，也沒有第二種輸出格式需要偏好。

退出碼具有意義：4 表示不可用，6 表示凍結欄位不一致，8 表示發現問題，9 表示環境問題。 錯誤訊息總會明確指出下一個應執行的指令。

以上未提及的旗標請參閱 ank help，需要時再載入。

安裝

npx skills add haksolot/ank

此 skill 說明如何使用 ank；它不會安裝二進位檔。 每個發行版都附有適用於 Linux、macOS 和 Windows 的二進位檔。