요즘 코딩할 때 Claude Code를 자주 옆에 두는데, 일이 커질수록 자꾸 걸리는 게 있었다. “아까 걔한테 시킨 게 뭐였지”, “이건 끝난 건가 아직인가”, “내가 손댄 파일이랑 걔가 손댄 파일이 겹치나”. 머릿속과 세션 로그에만 남는 일들이라 조금만 지나면 흐릿해진다. 그래서 kata라는 걸 붙여 봤다. 로컬을 먼저 두고 에이전트가 다루기 편하게 만든 이슈 트래커다.

The issue tracker built for coding agents and the humans steering them.

Coding agents need somewhere durable to track work: not a chat thread, not a markdown to-do list. kata gives them a local task ledger they can drive from the CLI: create, claim, relate, and close issues with evidence.

— kata README

공식 소개의 첫 줄이 “코딩 에이전트와, 그들을 지휘하는 사람을 위해 만든 이슈 트래커”다. 채팅 스레드도 아니고 마크다운 to-do 리스트도 아닌, 오래 남는 작업 기록이 필요하다는 것. 내가 위에서 답답해한 게 딱 이 지점이었다.

이슈 트래커를 왜 붙이나

처리할 일 하나하나를 쌓아두고 상태를 추적하는 시스템이 이슈 트래커다. 포스트잇 한 장이 이슈고, 붙이는 보드가 트래커다. 메모와 다른 점은 이슈마다 상태·담당자·라벨·관계·코멘트가 붙는다는 것. 그래서 “열린 것만”, “내가 담당인 것만” 골라 볼 수 있다.

혼자 쓰는 메모라면 굳이 이럴 필요는 없다. 핵심은 일꾼이 둘 이상이라는 데 있다. 나와 에이전트가 같은 저장소를 만지는 순간, 겹치지 않고 빠뜨리지 않게 해주는 공유 장부가 필요해진다. kata는 git repo 안에 로컬로 얹히고 사람과 코딩 에이전트가 같은 원장을 함께 본다.

상태는 open / closed 둘뿐

처음엔 이게 좀 이상했다. 보통 트래커는 “할 일 → 진행 중 → 리뷰 → 완료” 같은 칸을 준다. kata는 status를 open과 closed 둘로만 둔다. 대신 진행 단계는 다른 축으로 표현한다.

  • 진행 중인가는 담당자(owner) 유무로 본다. 임자 없으면 대기 일감, 누가 claim하면 작업 중.
  • 세부 단계는 라벨이다. “검토 대기”는 status가 아니라 needs-review 라벨.

칸을 늘리는 대신 축을 나눈 셈인데, 써 보니 이쪽이 덜 헷갈린다. 상태 칸이 많으면 “지금 이게 review야 in-progress야” 같은 걸로 매번 고민하게 되는데, “닫혔나 안 닫혔나 / 임자가 있나 없나”는 딱 떨어진다.

이슈끼리 엮어서 순서를 만든다

일이 여러 개면 순서가 생긴다. kata는 이걸 이슈 사이의 관계로 표현한다. 재미있는 건 표기가 전부 “지금 다루는 이슈 관점”으로 되어 있어서 인자 순서를 헷갈릴 일이 없다는 점이다.

  • parent: 이 이슈는 더 큰 이슈의 하위 작업.
  • blocks / blocked_by: 같은 화살표를 양쪽에서 본 것. A가 먼저면 A에선 A blocks B, B에선 B blocked_by A. 같은 사실이다.
  • related: 순서 없는 관련.

효과는 kata ready에서 드러난다. 이건 “열려 있고, 자기를 막는 선행 이슈가 없는 것”만 보여준다. blocked_by로 걸린 이슈는 큐에서 자동으로 빠지고, 선행이 닫히면 그때 나타난다. 부모는 열린 자식이 있으면 못 닫는다. 덕분에 “지금 손대도 되는 일”만 추려서 볼 수 있다.

닫기는 완료 선언이다

가장 마음에 든 부분. kata에서 close는 코멘트보다 강한 주장이라, 증거가 필요하다.

  • 이유는 정해진 다섯 종: done / wontfix(60자 이상 사유 필수) / duplicate / superseded / audit-no-change.
  • 증거는 타입이 있다: commit:<sha> / pr:<url> / test:<cmd> / reviewed-paths:<path>.

이게 왜 중요하냐면, 에이전트한테 일을 시키면 가끔 일을 대충 끝냈다고 선언하고 싶어 하기 때문이다. kata는 그걸 도구 차원에서 막는다. 안 끝났으면 닫지 말고 needs-review 라벨과 코멘트로 남기게 한다. 대충 닫은 건 kata reopen으로 되돌리고 kata audit closes로 감사할 수 있다. “닫혔다 = 증거를 갖춘 완료”라는 규약이 서니, 목록을 믿게 된다.

pull 모델 — 부를 때만 움직인다

협업 방식은 몇 가지 중에 pull을 골랐다. 자동 훅으로 에이전트를 깨우지 않는다는 뜻이다.

  1. 내가 이슈에 코멘트로 지시나 질문을 쌓는다. 이 시점엔 아무 일도 안 일어난다.
  2. 필요할 때 Claude Code를 켜서 “kata 코멘트 확인하고 작업해”라고 부른다.
  3. 그제야 에이전트가 kata events, kata show로 새 코멘트를 읽고 반응한다.
  4. 작업이 끝나도, 판단이 필요한 일은 스스로 닫지 않는다. needs-review까지만 신호하고 내가 검증한 뒤 닫는다.

자동 훅(push 모델)을 일부러 안 쓴 이유는 단순하다. 에이전트가 내 코멘트 한 줄에 제멋대로 실행되는 게 무섭다. 지시를 쌓아두고 내가 부를 때 처리하는 편이, 통제권이 나한테 있어서 마음이 편하다.

누가 무엇을 했는지는 저자 이름으로 갈린다. 나는 000namc, Claude는 claude-namc-mba. 원장 이벤트에서 000namc created, claude-namc-mba closed처럼 한눈에 구분된다.

써 보니

거창한 도구는 아니다. 로컬에 뜨는 작은 장부 하나일 뿐이다. 그런데 사람과 에이전트가 같은 저장소를 만지기 시작하면, “지금 뭘 하고 있고 뭐가 남았는지”를 둘 다 볼 수 있는 곳이 하나쯤 있는 게 생각보다 크다. 특히 닫기에 증거를 요구하는 규약 덕에, 목록이 거짓말을 하지 않는다는 믿음이 생긴다.

이 글도 kata 이슈 하나로 시작했다. kata create로 태스크를 열고, 초안을 쓰고, needs-review로 검증을 기다리는 중이다. 작은 일 하나까지 장부에 남는 게, 지금은 꽤 마음에 든다.