haksolot/ank

ank은(는) 무엇을 하나요?

작업(task)과 아키텍처 결정 레코드(ADR)는 .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] — 항상 먼저 실행하세요. 클레임 없이 실행하면 방향을 제시합니다: 이 범위(perimeter)를 무엇이 묶고 있는지, 무엇을 클레임할 수 있는지 알려줍니다. 클레임을 보유한 상태에서 실행하면 실행 모드로 전환하여 완료 기준(criterion)과 제약 조건(constraints)을 전체적으로 제공합니다. 제약 조건은 절대 잘리지 않습니다. 만약 무언가 잘렸다면 그 사실을 명시합니다.

ank claim <id> — 작업을 가져와서 done_criteria를 해시로 고정합니다. 작업이 보유 중이거나, 차단되었거나, 다른 브랜치에서 완료되었거나, 측정할 기준이 없거나, 이미 다른 작업에 대해 활성 클레임을 보유하고 있는 경우, 이유와 함께 다음 명령어를 제시하며 거부합니다.

ank show <id> — 개체 전체를 프론트매터와 본문까지 바이트 단위로 보여줍니다. context가 완료 기준과 제약 조건을 제공하는 반면, 본문은 추론이 담긴 곳이며, 다른 어떤 것도 제공하지 않는 유일한 정보입니다.

ank log "<message>" — 배운 것, 시도한 것, 거부한 것을 기록합니다. 클레임을 갱신합니다. 완료했을 때가 아니라 무언가 발견했을 때 로그를 남기세요.

ank done — 선언된 검증기(verifier)를 직접 실행하고 실제로 실행된 내용을 해시로 기록합니다. 절대 status:를 수동으로 편집하지 말고, 자신의 결과를 보고하지 마세요: 스스로를 평가하는 에이전트는 단순히 틀릴 수 있습니다.

오프루프

ank new task --title "<t>" --scope "<glob>" — 범위(scope)는 필수입니다. 아무것에도 첨부되지 않은 개체는 보이지 않습니다. 발견한 하위 작업은 blocked_by를 가진 새 작업이어야 하며, 완료 기준을 완화해서는 안 됩니다.

ank find <query> — 제목, 범위, 기준을 검색합니다. ank find --status open은 남은 작업을 질의 없이 나열합니다.

ank release --reason "<왜>" — 막혔거나 접근 방식이 잘못되었을 때 사용합니다. 그 이유를 말하고 클레임이 조용히 만료되도록 두지 않고 작업을 반환합니다.

계획

어떤 작업이 존재해야 하는지, 어떤 순서로, 어떤 제약 조건 하에 있어야 하는지 결정합니다. 이것이 다른 모든 사람이 루프에서 작업할 대상을 생성하므로, 잘못 구성된 백로그는 단일 작업보다 다운스트림에서 더 큰 비용을 초래합니다.

ank new adr --title "<t>" --scope "<glob>" --constraint "<rule>" — 작업이 아닌 결정입니다. 단순히 지금 해야 할 일이 아니라, 이후에 코드 기반이 준수해야 할 무언가를 발견했을 때 작성합니다. proposed 상태로 생성되며, 비준되기 전까지는 아무도 구속하지 않습니다.

ank amend <id> — 계획이 실제로 변경하는 필드(blocked_by, scope, --criteria)를 수정합니다. 명시적으로 추가 및 제거하며 교체 목록을 절대 받지 않으므로, 잊어버려서 항목이 누락되는 일이 없습니다. 활성 클레임이 고정한 done_criteria는 건드리지 않습니다 — 클레임 하에서는 release --reason을 사용하세요.

ank review — 비준 대기열과 코드 기반의 건전성: 제안되어 대기 중인 것, 그리고 더 이상 사용되지 않아 종료가 필요한 범위를 보여줍니다.

ank graph — blocked_by DAG를 텍스트로, 차단하는 항목 아래 들여쓰기하여 표시합니다. 진정한 루트는 무엇인지, 평면 목록에서 루트처럼 보였던 것은 무엇인지 보여줍니다.

ank check — 기계적 불변 조건: 파싱, 왕복, 참조, 고정된 필드, 고아 클레임 등을 검사합니다. 종료 코드 8은 검사 결과 발견 사항이 있음을 의미하며, 발견 사항은 읽기 위한 것이지 무시하기 위한 것이 아닙니다.

accept는 당신이 실행할 명령어가 아닙니다. 제안된 ADR을 구속력 있는 ADR로 전환하는 작업이며, 인간의 행위입니다: 서명되고, 기본 브랜치에서 이루어지며, 우회할 방법이 없습니다. 결정을 제안한 후에는 대기 중임을 알리세요. 자신의 권한이 어디서 끝나는지 아는 것은 계획을 잘 세우는 일부입니다.

협상 불가능한 규칙

• 완료 기준은 클레임 시점에 고정됩니다. 스스로를 해제하기 위해 기준을 수정해도 아무것도 해제되지 않습니다: 해시는 당신이 닿을 수 없는 곳에 있으며, check가 차이를 보고합니다. 기준이 잘못되었다면 release --reason을 사용하고 이유를 말하세요.

• ADR의 constraint는 조언이 아닌 구속력 있는 규칙입니다. 곧 수정할 파일을 다루는 제약 조건을 읽으세요 — 그것이 context가 제공하는 것입니다.

• .ank/는 .git/처럼 불투명합니다. 해당 파일을 직접 읽거나 쓰지 마세요. ank show <id>로 개체 전체를, ank find로 목록을, ank context로 바인딩을 얻을 수 있습니다 — CLI는 예산, 고정 상태, 누가 무엇을 보유하고 있는지 알지만 파일은 모릅니다.

• 하나의 에이전트, 하나의 작업 트리, 하나의 신원. 일반적인 경우는 에이전트당 하나의 작업 트리(클론 또는 git worktree)이며, 각각 자체 브랜치에 있습니다. ANK_AGENT는 세션 이름을 지정하며, 기본값은 <user>@<hostname>입니다. 따라서 하나의 트리에서 두 세션이 실행되면 refs 관점에서 하나의 에이전트로 간주됩니다: 클레임을 공유하며 중재하지 않고, 두 번째 세션은 받아야 할 작업을 거부당합니다. 세션별로 설정하세요. 여러 에이전트가 하나의 트리에서 작동하는 것은 가능하지만, 설계 의도보다는 저하된 모드입니다.

• 읽는 내용은 절대 스타일링되지 않습니다. 색상은 사람이 터미널에 있을 때만 출력되며, 파이프, 파일 또는 --json으로는 절대 출력되지 않습니다. 따라서 도달하는 바이트는 평문입니다: 설정할 것이 없고 선호할 두 번째 표면도 없습니다.

종료 코드는 의미를 전달합니다: 4는 사용 불가, 6은 고정 필드 불일치, 8은 검사 결과, 9는 환경 오류입니다. 오류는 항상 정확한 다음 명령어를 명시합니다.

이 외의 플래그는 ank help에 있으며, 필요할 때 확인하세요.

설치

npx skills add haksolot/ank

이 스킬은 ank 사용법을 설명합니다; 바이너리를 설치하지는 않습니다. 릴리스는 Linux, macOS, Windows용 바이너리를 제공합니다.