Claude Code Teams + Tmux 모니터링 시스템 구축 여정

Shin Jinseop·2026년 3월 26일

3/23 ~ 3/26, 4일간의 삽질과 안착 기록

Day 0 — 발견 (3/23 월)

한국어 블로그에서 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경변수 발견
Claude Code 공식 문서에서 Agent Teams 기능 확인 (/docs/en/agent-teams.md)
team-lead.md 에이전트 정의 작성 — Opus 모델, 50턴, PM/FE/BE/Doc 4개 에이전트 오케스트레이션

Day 1 — 첫 번째 팀 실행 & 삽질 시작 (3/24 화)

오전: teammateMode 설정 삽질

Claude Code 문서에서 teammateMode, terminalOutputMode 설정 방법 리서치
~/.claude/settings.json, settings.local.json 파일 위치 파악
dev-team 팀 생성 ("PRD 기반 개발팀 - tmux 테스트")
첫 실행: PM → FE + BE (병렬) → Doc 파이프라인으로 BDACS AML KYC 리디자인 PRD 처리
- team-output/ 에 technical-prd, fe-dev-spec, be-api-spec, dev-plan, final-report 생성 성공
- 에이전트 간 SendMessage로 태스크 완료 알림/의존성 추적 확인
- 문제: 에이전트들이 뭘 하고 있는지 실시간으로 보이지 않음 → 모니터링 필요성 인식

오후: 워크플로우 커맨드 정비

/team-dev 커맨드 구조 분석 및 정리
/team-fe-sprint 커맨드 발견 — 3가지 모드(A/B/C) 5개 에이전트 타입

Day 2 — 모니터링 시스템 구축 & 대삽질 (3/25 수)

오전: JSONL 로그 분석

Claude Code 세션 로그 구조 파악: 5가지 entry type (assistant, user, system, progress, file-history-snapshot)
5가지 hook event (SessionStart, PreToolUse, PostToolUse, PostToolUseFailure, Stop)
SubagentStart/SubagentStop 이벤트가 없는 것 확인 → 에이전트 추적을 위해 tool_use 엔트리를 직접 파싱해야 함

agent-monitor.py v1 구현

JSONL 세션 로그를 실시간 tail & 파싱
Agent 스폰, SendMessage(에이전트 간 통신), 진행 상태 추적
에이전트별 컬러코딩 (PM=마젠타, FE=시안, BE=노랑, DOC=초록)
--filter 플래그로 특정 에이전트만 필터링

agent-monitor.py v2 — 버그 연쇄

SendMessage, TaskCreate/Update, 파일 Read/Write/Edit 추적 추가
11개 에이전트 타입 스타일 정의
시작 시 최근 30개 이벤트 표시 → 실시간 모드 전환
f-string 백슬래시 에러 6건 연속 수정 — 딕셔너리 값 추출 패턴으로 전부 고침

/team-fe-sprint 대규모 리팩터링

"FE 실무팀" → "FE 사전 분석팀"으로 방향 전환
Mode C 삭제, 3모드 → 2모드로 단순화
코드 생성 에이전트 → 분석 에이전트로 교체 (as-is-analyzer, prd-analyzer, api-question-analyzer)
출력물: 코드 스펙 → As-Is 분석, PRD As-Is→To-Be 비교, API 사용현황, PRD 질문리스트

오후: tmux 대시보드 삽질의 연속

fe-sprint-monitor.sh 진화 과정:

v1: 2x2 그리드 레이아웃으로 첫 구현
tmux 패인 인덱싱 버그 — base-index가 시스템마다 달라서 패인이 빈칸으로 뜸
- base-index=0, pane-base-index=0 강제 설정 + 동적 윈도우 인덱스 감지로 수정
3패인 Mode A 최초 성공적 실행
터미널 감지 대삽질 — Ghostty/iTerm/Warp/Terminal.app 중 뭘 쓰는지 감지하는 복잡한 AppleScript 로직
- TERM_PROGRAM 변수로 Ghostty 확인했지만, 결국 Terminal.app 직접 호출로 단순화 (~50줄 삭제, 3줄로 교체)
에이전트 간 커뮤니케이션 이벤트 감지 함수 (is_communication()) 추가

agent-monitor.py v3

프로젝트 디렉토리 하드코딩 제거 → 최신 프로젝트 자동 감지
변수명 단순화, 패인 타이틀을 printf 이스케이프로 변경
고정 윈도우 사이즈 제거 → tmux 자동 사이즈

Day 3 — 범용화 & 안정화 (3/26 목)

오전: GoosLab 스타일 전면 재설계

fe-sprint-monitor.sh → GoosLab 스타일:

2x2 그리드 → 왼쪽 MAIN(45%) + 오른쪽 에이전트 세로 스택(55%) 으로 전면 변경
활성 패인 표시 (▸ bold / · dim), 컬러 보더, 팀 브랜딩 상태바

agent-monitor.py v4 — 대시보드 UI 업그레이드

컬러 헤더 바 (에이전트별 배경색)
--title/-t 인자로 커스텀 패널 헤더
에이전트 "생각중" 프리뷰 표시 (60자)
동시 감시 세션 6개 → 8개

범용 team-dashboard.sh 탄생

팀별 전용 스크립트 → 하나의 범용 스크립트로 통합
프리셋 지원: fe-sprint(3), fe-sprint-full(4), dev-team(4)
커맨드라인으로 커스텀 에이전트도 지정 가능
에이전트 수에 따라 분할 비율 자동 조정 (2개=50%, 3~4개=55%, 5+개=60%)
리팩터링 후 "can't find window: 0" 경고 9건 — 비치명적이라 그대로 둠

오후: 실전 투입

fe-sprint 팀으로 KYC 리노베이션 PRD 실제 분석 수행
T1(As-Is) → T2/T3/T4 병렬 실행으로 5개 분석 문서 생성 완료
4주 스프린트 계획, 5개 Critical Blocker + 10개 Clarification Point 도출

삽질 요약 — 뭐가 힘들었나

카테고리	문제	해결
로그 파싱	SubagentStart/Stop 이벤트 없음	tool_use 엔트리에서 Agent 타입 직접 파싱
Python	f-string 안에 딕셔너리 접근 시 백슬래시 에러 6건	값을 변수로 추출 후 f-string 사용
tmux 인덱싱	base-index 시스템마다 달라서 패인 빈칸	base-index=0 강제 + 동적 윈도우 감지
터미널 감지	Ghostty/iTerm/Warp 분기 AppleScript 50줄	Terminal.app 직접 호출 3줄로 교체
tmux 경고	"can't find window/pane" 경고 반복	sleep 딜레이 + 비치명적이라 수용
워크플로우 방향	코드 생성 팀 → 사전 분석 팀으로 전환	Mode C 삭제, 에이전트 역할 전면 교체

최종 아키텍처

사용자
  └─ /team-fe-sprint (Command)
       ├─ TeamCreate → fe-sprint 팀 생성
       ├─ team-dashboard.sh → tmux 4-pane 대시보드
       │    ├─ MAIN (전체 활동 스트림)
       │    ├─ @as-is-analyzer
       │    ├─ @prd-analyzer
       │    └─ @api-question-analyzer
       └─ Agent(team-lead) → 오케스트레이션
            ├─ T1: As-Is 분석 (순차)
            ├─ T2: PRD As-Is→To-Be (병렬)
            ├─ T3: API 사용현황 + 질문 (병렬)
            └─ T4: 스프린트 계획 (순차)

핵심 파일 위치

파일	역할
`.claude/commands/team-dev.md`	범용 개발팀 워크플로우
`.claude/commands/team-fe-sprint.md`	FE 스프린트 분석 워크플로우
`.claude/agents/team-lead.md`	팀 리드 오케스트레이터
`.claude/scripts/agent-monitor.py`	실시간 에이전트 활동 모니터 (v4)
`.claude/scripts/team-dashboard.sh`	범용 tmux 대시보드 런처
`.claude/scripts/fe-sprint-monitor.sh`	FE 전용 tmux 대시보드 (레거시)
`.claude/teams/*/config.json`	팀 설정 파일

생성된 팀 인스턴스

팀 이름	설명	날짜
`dev-team`	PRD 기반 개발팀 - tmux 테스트	3/24
`fe-sprint`	FE 사전 분석팀 - KYC 개편 PRD	3/25
`fe-sprint`	FE 사전 분석팀 - KYC 리노베이션 (재생성)	3/26

핵심 교훈

모니터링이 핵심이다: Claude Code의 에이전트 활동은 JSONL 로그에 기록되지만, SubagentStart/Stop 같은 전용 이벤트가 없어서 tool_use 엔트리를 직접 파싱해야 했음 — 이게 모니터링 시스템의 가장 큰 기술적 허들
4일간의 진화: "에이전트가 뭘 하는지 안 보여" → JSONL 파싱 → tmux 대시보드 → GoosLab 스타일 → 범용 스크립트. 문제 인식에서 범용 도구까지 4일
방향 전환이 중요했음: 처음엔 "코드 생성 팀"이었는데, 사전 분석 없이 바로 코드를 뽑으면 질이 안 나온다는 걸 깨닫고 "사전 분석팀"으로 전환한 게 실전 투입 성공의 열쇠

Shin Jinseop

이전 포스트

디자인시스템 도입 가이드

다음 포스트

Claude Code Teams + Tmux 모니터링 시스템 구축 여정

3/23 ~ 3/26, 4일간의 삽질과 안착 기록

Day 0 — 발견 (3/23 월)

Day 1 — 첫 번째 팀 실행 & 삽질 시작 (3/24 화)

오전: teammateMode 설정 삽질

오후: 워크플로우 커맨드 정비

Day 2 — 모니터링 시스템 구축 & 대삽질 (3/25 수)

오전: JSONL 로그 분석

agent-monitor.py v1 구현

agent-monitor.py v2 — 버그 연쇄

/team-fe-sprint 대규모 리팩터링

오후: tmux 대시보드 삽질의 연속

agent-monitor.py v3

Day 3 — 범용화 & 안정화 (3/26 목)

오전: GoosLab 스타일 전면 재설계

agent-monitor.py v4 — 대시보드 UI 업그레이드

범용 team-dashboard.sh 탄생

오후: 실전 투입

삽질 요약 — 뭐가 힘들었나

최종 아키텍처

핵심 파일 위치

생성된 팀 인스턴스

핵심 교훈

디자인시스템 도입 가이드

page-dep-map: React/Next.js 코드베이스를 읽는 4가지 방법

0개의 댓글