zh

傻瓜协调工具

任务和架构决策就在你的仓库里，通过一个任何编程智能体都能调用的 CLI 访问。

npm install -g @haksolot/ank
npx skills add haksolot/ank
阅读快速上手GitHubDiscord

开源，Apache-2.0。支持 Linux、macOS 和 Windows。

~/auth-service
ank context src/auth/

CONSTRAINTS (1 active)
  ADR-06d2  Opaque sessions rather than stateless JWT

TASKS (1)
  TASK-820d  [open] Migrate auth to opaque sessions

> ank claim TASK-820d to start

ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD

ank context

TASK-820d  Migrate auth to opaque sessions

DONE_CRITERIA
  The auth tests pass and no reference to jwt.verify remains in src/auth/

CONSTRAINTS (1 active)
  ADR-06d2  Do not introduce self-contained JWTs for user auth. Every session goes through the Redis store.

ank log "jwt.verify removed from session.ts"
logged LOG-6b0f39d7a4c1 on TASK-820d259af6a7

ank done
running: auth-tests ... ok (0.0s)
running: no-jwt ... ok (0.0s)
proof recorded: auth-tests@94a1f671c577 -> local/e3b0c44298fc@9c45c50  (scope/18d14da584ab)
proof recorded: no-jwt@791cc818d0ad -> local/e3b0c44298fc@9c45c50  (scope/18d14da584ab)
TASK-820d259af6a7 -> done

真实输出，取自快速上手文档。它的测试套件会在每次改动时用二进制重新执行这些命令。

适配你已经在用的智能体

ank 是一个命令行工具。任何能运行 shell 命令的智能体都能跑完这个循环，没有 shell 的客户端则通过 MCP 使用同样的动词。

  • Claude Code
  • Codex
  • Cursor
  • OpenCode
  • Gemini CLI
  • GitHub Copilot
  • Cline
  • Amp
  • pi
  • Antigravity
  • Goose
  • Kiro
  • Roo Code
  • Kilo Code
  • Windsurf
  • Qwen Code
  • Mistral Vibe
  • OpenHands
  • Junie
  • Devin

一条命令就能把 skills 装进它检测到的这些智能体，以及另外三十多种。

你的智能体读得到代码，读不到讨论串

智能体可以读你代码的每一行，却读不到你的任务跟踪器、你的 wiki，也读不到你们决定“会话绝不能用自包含 JWT”的那条讨论串。没有任何东西能阻止下一个会话写出一个来。

ank 把这些决策和工作放在 .ank/ 里，用 glob 挂到它们所约束的代码上。智能体开工前运行 ank context src/auth/，规则就会随任务一起送到。

就是仓库里的普通 markdown 文件，像其他改动一样走代码评审。不用运行任何服务器：claim 就是 git ref。

六个动词

智能体需要的完整循环。其余的动词用 ank help 查看。

  1. ank context <path>

    这个范围受什么约束，有哪些任务可以领取。永远是第一条命令。

  2. ank claim <id>

    领取一个任务，并冻结它的完成标准。

  3. ank show <id>

    实体的全部内容：frontmatter、正文和日志。

  4. ank log "<message>"

    边做边记下你学到的东西。写日志本身就会续期 claim。

  5. ank done

    运行声明好的验证器，并记录证明。

  6. ank release --reason "<why>"

    交还任务，并说明原因。

背后的三个理念

每一条都是工具本身的性质，而不是要求你遵守的约定。

靠 scope，不靠层级

约束和工作是两个平面，只通过 glob 相连。去年写下的规则会约束今天新建的工作；glob 可以对照文件系统检查，标签做不到。没有 epic，没有父任务，也没有需要同步维护的汇总。

ank new adr --title "Opaque sessions rather than stateless JWT" \
    --scope "src/auth/**" \
    --constraint "Do not introduce self-contained JWTs for user auth. Every session goes through the Redis store."
created ADR-06d29e727d24 Opaque sessions rather than stateless JWT

标准在 claim 时冻结

领取任务时，它的 done_criteria 会按哈希冻结，存放在编辑文件的人够不着的地方。为了给自己解围去改标准，什么也解不开：ank check 会把不一致显示出来。每个身份同一时间只能持有一个 claim，而 claim 是 git ref：两个智能体同时去抢一个任务，只有一个能拿到。

ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
ank claim 51c2
error[7]: human:marie holds a live claim on TASK-820d259af6a7 (expires in 30m)
  -> ank release --reason "<why>"   (a second session on this machine sets its own ANK_AGENT)

没有人能自己宣布完成

自己汇报结果的智能体完全可能是错的。ank done 亲自运行验证器，并记录实际运行的内容及其哈希。没有可运行内容的任务，需要你亲手交给它一份证明；而每一次拒绝，都会给出解决它的那条命令。

ank claim 51c2
claimed TASK-51c2a0f6d418 say-in-the-readme-what-a-session-is-now -> HEAD
ank done
error[5]: proof required to move TASK-51c2a0f6d418 to done
  -> ank done --proof commit:<sha>

它不是什么

  • 不是任务跟踪器。 没有迭代周期、估点、速率，也没有路线图。

  • 不是 wiki。 只放对智能体可执行或具有约束力的内容。

  • 不是安全边界。 它防的是偏移，不是攻击者。

ank 用 ank 构建

它自己的仓库就跑在这个循环上。根目录下的 .ank/ 存放着它的代码必须遵守的 ADR 和构建它的那些任务，文档也按 id 引用这些决策。

版本号刻意停在 0.x：循环和退出码已经有规范，存储格式还没有。

在 GitHub 上查看它的 .ank/

安装 ank

两条命令。支持 Linux、macOS 和 Windows，需要 git 2.34 或更高版本。

npm install -g @haksolot/ank
npx skills add haksolot/ank
阅读快速上手其他安装方式