1. 등록 — 이슈 화면에서 제목만 적어도 된다. 내용은 나중에 에이전트가 채운다.
2. todo → ready — 사람이 "이제 해도 된다"고 올린다. 선행 작업이 남아 있으면 올라가지 않는다.
3. claim — 에이전트가 Ready 큐에서 가져가 in-progress 로 바꾼다. 담당이 지정된 작업은 큐에 안 뜬다(사람 몫).
4. review — 에이전트가 산출물·인계 노트를 남기고 제출한다. 수용기준은 자동 검증된다.
5. done — 사람이 확인하고 닫는다. 이 단계가 내 차례 목록에 뜬다.

막힌 작업은 blocked 로 가고 대시보드 "주의 필요"에도 함께 보인다.

b3x 는 원격 HTTP MCP 서버다 — 리포를 클론하거나 빌드하지 않아도 주소 + 토큰만으로 붙는다. 토큰은 설정 화면에서 발급하고, 발급 직후 화면에는 아래 명령이 토큰까지 채워져 나온다. 여기 것은 형태만 보여준다.

--scope user 라 어느 리포에서든 쓸 수 있다. 등록한 뒤 /mcp 로 연결을 확인한다.

웹·앱에는 명령이 아니라 커스텀 커넥터로 등록한다: Settings → Connectors → Add custom connector → URL 에 위 서버 주소를 넣고 Connect → b3x 로그인·승인(OAuth). 이 방식은 토큰을 손으로 넣지 않는다. static headers(beta)가 켜져 있으면 Authorization: Bearer <발급한 토큰> 을 직접 넣어도 된다.

리포에서 make mcp-desktop 을 실행하고 토큰을 붙여넣으면 claude_desktop_config.json 에 자동 등록된다. Claude Code 도 make mcp-claude 로 같은 일을 한다 — 명령을 직접 치는 것보다 이쪽이 쉽다. Codex 는 아래 「Codex 연결」에 따로 있다.

붙고 나면 에이전트가 register_issue 로 이슈를 남기고 list_ready_tasks → claim_task → submit_result 로 이 화면의 작업을 직접 굴린다.

묻는 것이 둘이고 서로 독립이다 — ① 내 터미널의 Codex 를 b3x 에 붙이는 것, ② 나루가 Codex 로 세션을 띄우게 하는 것. 하나만 해도 그쪽은 동작한다.

리포에서 make mcp-codex 를 실행하고 설정 화면에서 발급한 토큰을 붙여넣으면 끝난다. 위 서버 주소를 stdio 브리지(npx mcp-remote)로 등록한다 — Codex 는 원격 HTTP MCP 를 직접 못 받아서 클로드와 방식이 다르다. 다시 실행하면 기존 등록을 지우고 새로 붙여 토큰이 갱신된다.

CLI 는 이미 나루 이미지에 들어 있다 — 따로 설치하지 않는다. 남는 것은 자격증명과 무엇을 Codex 로 돌릴지 둘뿐이다.

자격증명 — 둘 중 하나. 클로드는 환경변수 하나면 되지만 Codex 의 인증은 파일이라 자리가 다르다.

• 내 구독으로(권장) — 설정 › 일반의 「내 구독 토큰 (나루)」 카드에서 벤더 codex 를 고르고, codex login 뒤 생긴 ~/.codex/auth.json 의 내용 전체 또는 API 키 한 줄을 넣는다. 내가 등록한 이슈가 내 구독으로 돈다(사람마다 홈이 갈려 남의 이슈에 안 섞인다).
• 설치 공용으로 — .env 에 CODEX_API_KEY 를 넣거나, 나루 컨테이너에서 codex login 을 한 번 한다(영속 홈에 남아 재배포를 넘어 산다). .env 를 고쳤으면 make up-runner 로 나루를 갈아 끼워야 먹는다.

무엇을 Codex 로 돌릴까 — 세 자리이고 좁은 것이 이긴다.

1. 이슈 상세 「트랙별 벤더」 — 이 이슈의 이 트랙만(기획·수행·리뷰 각각).
2. 이슈 상세 「벤더」 알약 — 이 이슈는 통째로.
3. 설정 › 일반의 「트랙별 기본 벤더」 — 설치 전체의 기본값. 「리뷰는 코덱스로」면 여기 한 번이면 된다.

셋 다 비우면 예전대로 담당 이름으로 판정한다(사실상 claude). 바꾼 값은 다음 배차부터 적용된다 — 이미 뜬 세션의 CLI 는 안 바뀐다.

확인 — 관측 › 운영의 세션 표에서 벤더 열이 codex 인지 본다. 리포에서는 make runner-check 가 인증을 먼저 확인해 준다.

알아 둘 것 — 아무도 자기 구독을 등록하지 않으면 모든 이슈가 system 한 계정으로 묶인다. 그러면 계정당 동시 상한이 사실상 전역 상한이 되어, 나루를 늘려도 세션이 안 는다.

묻는 것이 둘이다 — ① 나루가 Figma 를 열 수 있게 하는 것(OAuth 로그인), ② 시안을 어디에 그릴지 정하는 것(파일·페이지 주소). 둘 다 있어야 디자인 트랙이 돈다.

개인 액세스 토큰(PAT)은 원격 서버가 안 받는다 — Authorization: Bearer <PAT> 는 무조건 401 이다. 설정 › 일반의 「내 구독 토큰」 figma 칸은 로컬 Dev Mode 서버(Figma 데스크톱 앱)를 쓰는 설치용이고, https://mcp.figma.com/mcp 를 쓰면 OAuth 뿐이다.

나루는 대마다 홈이 갈린다 — 로그인도 대마다 한 번씩 한다(b3x-naru-1, b3x-naru-2 …). 나루를 늘리면 새로 생긴 대는 다시 로그인해야 한다.

• claude — 인증 URL 이 찍힌다. 브라우저에서 승인하고 리디렉트된 주소를 그 자리에 붙여넣으면 끝난다.
• codex — 콜백이 컨테이너 안 127.0.0.1:<임의포트> 라 브라우저에서 연결 실패로 뜬다. 정상이다. 주소창의 URL 을 통째로 복사해 docker exec b3x-naru-1 curl -s '<복사한 URL>' 로 친다(작은따옴표 필수 — & 가 먹힌다). 코드는 일회용이라 바로 친다.
• 로그인 창은 그대로 둔다 — Ctrl-C 하면 콜백을 받을 서버가 같이 죽는다.
• 확인 — docker exec b3x-naru-1 codex mcp list · docker exec b3x-naru-1 claude mcp list.

.env 의 B3X_FIGMA_MCP_URL 이 채워져 있어야 세션에 도구가 붙는다(고쳤으면 make up-runner). 비어 있으면 디자인 이슈가 도구 없이 떠서 시안 대신 글로 설명하고 blocked 로 끝난다.

• 프로젝트 수정 → 「화면 설계 파일」 — 팀 프로젝트에 만든 빈 파일의 주소. 드래프트(개인 초안)에 두면 다른 사람의 세션이 그 파일을 못 연다.
• 리포지토리 → 「화면 설계 페이지」 — 그 서비스의 화면들이 사는 페이지 주소(?node-id= 가 들어 있어야 한다).

비워 두면 프롬프트가 위치를 아예 말하지 않는다 — 세션마다 새 파일이 생긴다. 프로젝트별로 하나씩 켜면 된다.

• 표식은 제목 접두어 [디자인](또는 유형을 design 으로). 이 표식이 없으면 시안 없이 곧장 구현으로 간다 — 조용한 실패라 왜 시안이 안 나왔는지 알 수 없다.
• 구현 이슈는 그 디자인 이슈를 선행(dependsOn) 으로 건다. 그러면 구현 세션에도 Figma 도구가 붙어 시안의 간격·색을 직접 읽는다.
• 대상 리포 개수가 신호다 — 1개면 그 리포 페이지, 2개 이상이면 프로젝트 파일의 공통 페이지(_design-system), 0개면 세션이 되묻는다.
• 세션이 두 번 도는 것이 정상이다 — 시안 2~3안을 링크로 남기고 질문하며 blocked(선택 대기) → 사람이 고르면 ready 로 돌아와 확정하고 review.
• 구현이 머지되면 나루가 「Figma 페이지를 갱신할까요?」 를 묻는다. 자동 갱신은 안 한다 — 답하면 갱신 이슈가 생긴다.

사람 폴백 — 로그인이 안 됐거나 나루를 안 쓸 때는, Figma 커넥터가 붙은 대화형 Claude Code 세션에 이슈 상세의 「넘기기」 프롬프트를 붙여넣으면 된다. 같은 표식·같은 프롬프트라 결과가 나루가 돌린 것과 구분되지 않는다.