<div id="readability-page-1" class="page"><div aria-label="Content">
        <article itemscope="" itemtype="http://schema.org/BlogPosting">

  

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

<blockquote>
  <p><strong>The issue tracker built for coding agents and the humans steering them.</strong></p>

  <p>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.</p>

  <p>— <a href="https://github.com/kenn-io/kata">kata README</a></p>
</blockquote>

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

<h2 id="heading-이슈-트래커를-왜-붙이나">이슈 트래커를 왜 붙이나</h2>

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

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

<h2 id="heading-상태는-open--closed-둘뿐">상태는 open / closed 둘뿐</h2>

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

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

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

<h2 id="heading-이슈끼리-엮어서-순서를-만든다">이슈끼리 엮어서 순서를 만든다</h2>

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

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

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

<h2 id="heading-닫기는-완료-선언이다">닫기는 완료 선언이다</h2>

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

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

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

<h2 id="heading-pull-모델--부를-때만-움직인다">pull 모델 — 부를 때만 움직인다</h2>

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

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

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

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

<h2 id="heading-써-보니">써 보니</h2>

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

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

  </div>
</article>

      </div></div>

Seong-Uk's Blog

요즘 코딩할 때 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을 골랐다. 자동 훅으로 에이전트를 깨우지 않는다는 뜻이다.
내가 이슈에 코멘트로 지시나 질문을 쌓는다. 이 시점엔 아무 일도 안 일어난다.
필요할 때 Claude Code를 켜서 “kata 코멘트 확인하고 작업해”라고 부른다.
그제야 에이전트가 kata events, kata show로 새 코멘트를 읽고 반응한다.
작업이 끝나도, 판단이 필요한 일은 스스로 닫지 않는다. needs-review까지만 신호하고 내가 검증한 뒤 닫는다.
자동 훅(push 모델)을 일부러 안 쓴 이유는 단순하다. 에이전트가 내 코멘트 한 줄에 제멋대로 실행되는 게 무섭다. 지시를 쌓아두고 내가 부를 때 처리하는 편이, 통제권이 나한테 있어서 마음이 편하다.
누가 무엇을 했는지는 저자 이름으로 갈린다. 나는 000namc, Claude는 claude-namc-mba. 원장 이벤트에서 000namc created, claude-namc-mba closed처럼 한눈에 구분된다.
써 보니
거창한 도구는 아니다. 로컬에 뜨는 작은 장부 하나일 뿐이다. 그런데 사람과 에이전트가 같은 저장소를 만지기 시작하면, “지금 뭘 하고 있고 뭐가 남았는지”를 둘 다 볼 수 있는 곳이 하나쯤 있는 게 생각보다 크다. 특히 닫기에 증거를 요구하는 규약 덕에, 목록이 거짓말을 하지 않는다는 믿음이 생긴다.
이 글도 kata 이슈 하나로 시작했다. kata create로 태스크를 열고, 초안을 쓰고, needs-review로 검증을 기다리는 중이다. 작은 일 하나까지 장부에 남는 게, 지금은 꽤 마음에 든다.

kata, 사람과 에이전트가 같은 장부를 보는 이슈 트래커

댓글