/moai todo NEW

다음에 할 일을 한 줄씩 쌓아 두는 백로그 대기열입니다. 칸반 보드의 backlog 컬럼에는 맡은 세션이 없어서 아무도 일을 밀어 넣지 못합니다. 그래서 카드를 보드에 들이는 일은 언제나 사람의 판단이고, /moai todo가 그 창구입니다.

정보

한 줄 요약: /moai todo는 “다음에 뭘 할지 적어 두는 줄"입니다. 항목을 넣고, 목록을 보고, 다 된 것을 지우고, 다음에 착수할 하나를 고릅니다. SPEC도 계획도 아니고, 고르는 순간에야 SPEC이 됩니다.

정보

슬래시 커맨드: Claude Code에서 /moai:todo를 입력하면 바로 실행됩니다. /moai만 입력하면 사용 가능한 모든 서브커맨드 목록이 표시됩니다.

백로그의 한 항목은 의도 한 줄입니다. SPEC도, 계획서도, 추정치도 아닙니다. 사람이 그 항목을 고르고 리드 세션이 plan 세션으로 디스패치할 때 비로소 SPEC이 됩니다.

대기열은 일부러 얇게 만들었습니다. SPEC이나 git 이력, 보드가 더 잘 기록할 것은 담지 않고, 사람이 다음에 무엇을 원하는가만 남깁니다.

flowchart TD
    Add["/moai todo 설명
항목 추가"] --> Queue["백로그 대기열"]
    Queue --> Pick["리드의 질문 채널에서
사람이 하나 선택"]
    Pick --> Plan["plan 세션으로 디스패치
여기서 SPEC 저작"]
    Plan --> Spec["SPEC ID를 항목에 기록"]

# 항목 추가
> /moai todo "인증 미들웨어의 오류 경로 정리"

# 대기열 보기
> /moai todo

항목을 제거하거나 다음 카드를 고르는 동사는 슬래시 표면에 없습니다. 그 두 가지는 아래의 터미널 CLI(moai todo done, moai todo next) 또는 리드 세션을 통한 선택이 담당합니다.

그 밖의 인자 형태는 설명으로 취급합니다. /moai todo CI 캐시 불안정 해결은 오류가 아니라 항목 추가입니다 — 잘못 알아들었을 때의 대가가 사람이 한 줄 지우는 것뿐이기 때문입니다.

대기열은 .moai/state/kanban/backlog.json에 저장됩니다. 프로젝트 안에만 있고 커밋되지 않습니다.

{
  "version": 1,
  "items": [
    {
      "id": "t1",
      "text": "인증 미들웨어의 오류 경로 정리",
      "added_at": "<RFC3339 시각>",
      "spec_id": null,
      "state": "queued"
    }
  ]
}

파일은 원자적으로 씁니다(임시 파일에 쓰고 이름을 바꿉니다). 쓰는 도중 죽어도 대기열이 잘리지 않게 하기 위해서입니다. 파일이 없으면 오류가 아니라 빈 대기열이고, 형식이 깨진 파일은 보고만 하고 손대지 않습니다 — 여기 담긴 사람의 의도는 다시 만들어 낼 수 없는 유일한 값이기 때문입니다.

선택은 리드 세션의 질문 채널을 통해 사람이 합니다. 리드가 대기열을 선택지로 띄우는데, 오래된 것부터 한 항목에 하나씩, 도구가 허용하는 네 개까지 보여 주고 나머지는 본문에 요약해 아무것도 가려지지 않게 합니다. /clear 뒤 첫 수로 대기열을 제시할 때도 같은 방식이고, 터미널에서 후보만 확인하고 싶을 때는 moai todo next(인자 없음)가 같은 목록을 읽기 전용으로 출력합니다.

주의

고르는 주체는 사람입니다. 미리 선택해 두지 않고, 추정한 우선순위로 순서를 바꾸지 않으며, “맨 위 것부터 시작"을 기본값으로 붙이지 않습니다. 대기열이 비었으면 비었다고 말하고 멈춥니다 — 빈 백로그는 정상 상태이지, 일을 지어내라는 신호가 아닙니다.

여러 카드를 한 번에 승인할 수도 있습니다. 카드를 지목하거나, 대기열이 빌 때까지 순서대로 진행하라고 말하는 방식입니다. 이것도 사람의 선택이며, 한 장씩 대신 한 번에 했을 뿐입니다. 리드는 승인된 순서대로 카드를 들이고 다시 묻지 않습니다. 다만 그 승인이 허락하는 범위는 딱 그것뿐입니다 — 대기열에 항목을 더하거나, 순서를 바꾸거나, 승인 범위 밖의 판단이 필요해진 카드를 대신 결정하는 근거가 되지는 않습니다.

카드를 고른 뒤에는 이렇게 이어집니다.

1. 고른 항목을 moai todo next <n> [--spec <SPEC-ID>] 한 번의 잠긴 쓰기로 picked로 표시합니다. 식별자를 이미 알고 있으면 이때 함께 붙입니다.
2. 칸반 디스패치 규약에 따라 plan 세션으로 넘깁니다. 카드는 plan 컬럼에 들어가고, SPEC 저작은 여기가 아니라 거기서 일어납니다.
3. 고를 때 식별자를 몰랐다면, 알게 된 뒤 moai todo next <n> --spec <SPEC-ID>를 다시 실행해 항목에 붙입니다. 이후 부착을 자동으로 해 주는 경로는 없습니다 — 디스패치와 후속 부착 모두 리드 세션이 수행하는 지시이지, 대기열이 스스로 하는 일이 아닙니다.

/moai todo는 평범한 단일 세션에서도 그대로 동작합니다 — 그냥 대기열이기 때문입니다. 다만 디스패치는 하지 않습니다. 동반 세션이 없으면 지시할 상대가 없으므로, 대기열을 읽고 쓰는 것까지가 전부이고 나머지는 사람이 직접 진행합니다.

• 작업 관리 도구가 아닙니다. 우선순위도, 담당자도, 마감도, 의존 관계도 없습니다. 그런 것이 필요한 일은 이슈 트래커나 SPEC의 몫입니다.
• 보드가 아닙니다. 카드가 어느 컬럼에 있는지는 리드 세션과 SPEC 상태가 쥐고 있지, 이 파일에 있지 않습니다.
• 진행 중인 일의 원본이 아닙니다. 카드에 SPEC이 생긴 뒤로는 SPEC 산출물이 기준이고, 백로그 항목은 그것을 가리키는 표식일 뿐입니다.
• 저절로 채워지지 않습니다. TODO 주석이나 열린 이슈, 감사 결과를 도구가 알아서 긁어 오지 않습니다. 항목을 넣는 것은 사람입니다.

같은 대기열을 터미널에서도 조작할 수 있습니다. 슬래시 커맨드 /moai todo는 Claude Code 대화창에서, 터미널 CLI moai todo는 셸에서 부르는 별개의 표면입니다 — 이 둘은 같은 파일을 다루지만 문법이 다릅니다.

# 항목 추가 — 발급된 id와 대기열 위치를 한 줄로 출력
$ moai todo add "인증 미들웨어의 오류 경로 정리"

# 대기열 보기 (id · 상태 · 본문)
$ moai todo list

# 구조화된 레코드로 보기
$ moai todo list --json

# 항목 제거 — 번호(t4)나 명시적 id 둘 다 받습니다
$ moai todo done 4

# 대기 중인 항목을 오래된 것부터 출력 (읽기 전용)
$ moai todo next

# 항목 하나를 고른 것으로 기록 — SPEC 식별자도 함께
$ moai todo next 4 --spec SPEC-AUTH-001

CLI는 프롬프트를 띄우지 않습니다. 인자와 플래그를 받고 한 줄을 출력하며, 오류는 stderr로 — 스크립트와 CI에서 안전하게 쓸 수 있는 형태입니다.

두 표면은 같은 저장 계층을 공유합니다. 변경은 대기열 파일 옆의 잠금 파일(backlog.lock)을 잡은 뒤, 같은 디렉터리의 임시 파일에 쓰고 이름을 바꾸는 원자적 쓰기로 반영되며, 읽기는 잠금 없이 일어납니다. 항목 id는 잠금 안에서 파일에 남은 최고 수위 표시(last_seq)에서 발급되므로, 제거된 항목의 id는 다시 쓰이지 않습니다.

정보

설치된 바이너리: CLI는 main에 반영된 상태로 배포됩니다. 이미 설치된 moai 바이너리는 재설치해야 이 명령을 얻습니다.

• 칸반 모드 — 백로그에서 나간 카드가 흘러가는 보드
• /moai 통합 명령 — 서브커맨드 전체 지도
• /moai plan — 고른 카드가 SPEC이 되는 단계