역할이 다른 여러 에이전트가 동시에 뛰고, 파일 신호로 조율되고, 그 상태가 눈에 보이는 Claude Code 팀.
Codex로 쓰기 — 작업 공간 루트에서 두 줄:
git clone https://github.com/janjanjae/madang /tmp/madang bash /tmp/madang/codex/install.sh --restricted # 감독·폐쇄 환경용. 기본판은 옵션 없이
/tmp는 작업 공간 밖이라 IDE 파일 트리에 안 보일 수 있다 — 문서는cat /tmp/madang/codex/README.md로 보거나 Codex에게 "/tmp/madang/codex/README.md 읽고 설치해줘"라고 시킨다. 설치 후 순서·명령 모음:cat .codex/START.md(설치가 작업 공간에 복사) · 상세:codex/README.md
터미널 탭마다 페르소나를 가진 에이전트 세션을 띄우고(팀장 1 + 팀원 N), 브리프·컨펌을 파일로 주고받는 탭 모드 협업 시스템이다. 각 탭이 지금 뭘 하는지는 화면 위의 워커 오버레이(마당)가 보여준다 — 호박(컨펌 대기·논의)은 팀장이 처리하면 되는 상태, 적(사용자 대기)은 사용자 본인만 풀 수 있는 상태, 눈을 뜨고 있으면(안광 유지) 깨어서 활동 중, 눈 감음은 쉼이다.
기원. 이 팀은 2026년 7월 포켓몬 이름을 붙인 네 에이전트로 시작했다. 공개(2026-09)를 준비하면서 이름·그림·인사말을 전부 자작 마스코트로 바꿨다 — 남의 캐릭터 위에 브랜드를 쌓으면 잘될수록 남의 것이 되고, 확산 라이선스도 붙일 수 없어서다. 이 프로젝트는 포켓몬컴퍼니·닌텐도와 무관하며 그 상표·그림을 쓰지 않는다. 이름 바꾼 이야기는
plans/brand-strategy-2026-09-03.md.
혼자 Claude Code를 쓰면 두 가지가 자주 걸린다 — 긴 작업이 도는 동안 지금 뭘 하고 있는지 화면 밖에서는 안 보이고, 검증 없이 커밋이 바로 나간다. 이 시스템은 그 둘을 파일 신호로 푼다: 워커 오버레이가 각 세션의 상태를 항상 눈에 띄게 보여주고, 커밋 게이트 훅이 팀장의 APPROVE 없이는 커밋을 막는다. 역할을 나눠 병렬로 굴리는 건 그 위에 얹은 덤이다.
| 이름 | 세션 | 언제 부르나 | 인사 | |
|---|---|---|---|---|
| ⚪ | 도담 · 팀장 | /teamleader |
사람이 직접 대화 — 브리프 배분, 보고 git 교차검증, 허브 문서(TASKS/PROGRESS) 단일 작성 | — |
| 🔺 | 번뜩 | /solver |
깊이 — 하나의 어려운 문제를 끝까지. 핵심 슬라이스, 2회 실패한 버그, 통합·재현 불가·아키텍처급 | 번뜩! |
| ☁️ | 몽글 | /builder |
넓이 — 같은 모양의 독립 태스크 N개를 병렬로. 분신(몽글2·3)으로 나뉜다 | 몽글~ |
| 🟦 | 슥슥 | /sketcher |
시안 — 화면이 필요할 때. worktree 격리에서 프로토타입, 스크린샷 후보 → 확정안만 메인 반영 | 슥슥~ |
| 💬 | 조잘 | /narrator |
해설 — 사용자가 이해하고 싶을 때. 팀 문서를 감시하며 비개발자에게 쉽게 설명 (읽기 전용) | 조잘조잘! |
이름·인사말·이모지·색의 단일 원천은 claude/roster.json(스킨 표), 그림은 claude/assets/mascots/(CC BY 4.0, BRANDING.md).
- 탭 모드: 사람이 터미널 탭을 열어 팀원 세션을 기동(사람 개입은 탭당 시작 프롬프트 1회). 브리프는
.claude/team/briefs/{인스턴스}.md파일 폴링으로 자동 수령. - 컨펌 신호 프로토콜: 커밋 전 팀원이
.claude/team/confirm/{인스턴스}.request.md(CONFIRM/BLOCKED/DISCUSS) 작성 → 팀장이 백그라운드 감시로 감지·검증 →reply.md(APPROVE/FIX)로 응답. - 기술 주체성: 팀원은 공식문서로 브리프를 선검증하고, 세부 판단은 자율, 브리프와 충돌하면
DISCUSS로 논의. - 커밋 게이트 훅: 번뜩·몽글·슥슥 세션은 페르소나 frontmatter 훅으로
git commit을 차단 — 자기 인스턴스의 APPROVE reply 또는 팀장이 만든commit-waiver파일이 있을 때만 통과(슥슥[proto]실험 커밋은 예외). 허브 문서(TASKS/PROGRESS) 수정 차단 훅은 전 팀원 적용. ("훅이 강제, 스킬이 안내") - 프로젝트 애든덤: 프로젝트별 상시 특화는
{프로젝트}/.claude/team/agents/{이름}.md에 두면 기력회복 시 베이스 정의 위에 겹쳐 적용(델타만, 통째 오버라이드 금지). - 워커 오버레이
madang:.claude/team/파일 신호와 워커 세션 기록(모델이 실제로 산출한 턴)만 읽어 상태를 보여준다. 읽기 전용이라 워커 배관을 건드리지 않는다. 평소엔 글자가 없고, 사람이 행동해야 할 때만 말풍선이 뜬다.go-madang(프로젝트 루트) — 상세claude/tools/madang/README.md. - 상세 규칙:
claude/skills/teamleader/ways-of-working.md· 방향·로드맵·브랜드 결정:DIRECTION.md
세션 진입은 전부 /이름 명시 호출. 팀장 커맨드는 팀장 전용(disable-model-invocation).
페르소나 세션 (claude/skills/{이름}/ + claude/agents/{이름}.md)
| 스킬 | 한 줄 |
|---|---|
/teamleader |
팀장 모드 — 배분·보고 git 교차검증·허브 문서 단일 작성. 빈 프로젝트면 /start 안내 |
/solver |
번뜩 세션 시작 — 깊이(난제 하나를 끝까지 + 에스컬레이션 디버깅) |
/builder |
몽글 세션 시작 — 넓이(같은 모양 N개 병렬, 분신) |
/sketcher |
슥슥 세션 시작 — 시안(UX/UI 프로토타이핑, worktree 격리) |
/narrator |
조잘 세션 시작 — 해설(읽기 전용, 비개발자 눈높이) |
팀장 커맨드 (claude/skills/{이름}/)
| 스킬 | 한 줄 |
|---|---|
/start |
새 스토리/에픽 착수 — 팀 폴더 스캐폴딩 + Phase 설계 + 브리프 초안 + PROGRESS 초기화 |
/checkpoint |
PROGRESS.md 현행화 (체크포인트·세션 종료) |
/progress |
PROGRESS/TASKS 기반 상태 브리핑 (읽기 전용) |
/issue-fetch |
이슈 1회 조회 → .claude/stories/ 로컬 캐시 (읽기 전담) |
/issue-refine |
이슈 구체화·분할(착수 전) / 구현 기록·상태 전환(PR 머지 후) |
/issue-add |
버그(스프린트)·아이디어(백로그) 빠른 등록 |
/skill-audit |
스킬 인벤토리 전수 스캔 → ~/.claude/REGISTRY.md 현행화 (월 1회/스프린트 종료) |
이슈 커맨드 3종은 프로젝트의
.claude/team/tracker-config.md(트래커 종류·도메인·Key)를 읽어 동작 — 베이스엔 회사 정보 없음. 다른 프로젝트는 그 파일만 새로 쓰면 재사용.
팀장 구동 문서 (claude/skills/teamleader/): roster(명부) · ways-of-working(운영 규칙 — 규칙만; 변경 이력은 ways-of-working-changelog, 사고 경위·실측은 reference/incidents) · model-guide(모델 배분) · skill-guide(역할×시점 스킬 매핑).
방법 1 — 심링크 (주 사용 기기, 수정하며 쓸 때)
git clone https://github.com/janjanjae/madang.git && cd madang
./install.sh # ~/.claude에 심링크 생성 (~/.copilot은 있을 때만, 기존 파일은 .bak 백업)
echo 'source '"$PWD"'/claude/shell/go-functions.zsh' >> ~/.zshrc && exec zsh설치 스크립트는 심링크만 만든다 — go-solver·go-builder·go-madang 같은 명령은 위 마지막 한 줄로 생긴다. Copilot을 나중에 설치했으면 ./install.sh를 다시 실행한다(재실행 무해, ~/.copilot 심링크만 추가로 생긴다).
방법 2 — 플러그인 (다른 기기·클라우드 세션, 읽기 전용 사용)
/plugin marketplace add janjanjae/madang
/plugin install madang
플러그인 설치 시 커맨드는 /madang:start처럼 네임스페이스가 붙는다. 두 방법 병행 가능 — 같은 기기에선 심링크(로컬 파일)가 우선한다.
이후 ~/.claude/...를 편집하면 그대로 이 레포의 워킹트리 변경이 된다 — 커밋만 하면 팀 시스템이 버전 관리된다.
DIRECTION.md # 팀 시스템의 방향 (비전·설계 원칙·로드맵·브랜드 결정) — 여기부터 읽기
BRANDING.md # 이름·마스코트 사용 규칙 (CC BY 4.0)
LICENSE # 코드 MIT
.claude-plugin/ # 마켓플레이스 매니페스트 (플러그인 설치용)
claude/
roster.json # 스킨 표 — 이름·인사말·이모지·색의 단일 원천
assets/mascots/ # 마스코트 SVG (rest/smile/sleep × light/dark)
agents/ # 팀원 페르소나 (solver, builder, sketcher, narrator)
skills/ # 페르소나 세션 스킬 + teamleader(구동 문서 4종) + 팀장 커맨드 스킬
skills/teamleader/hooks/ # 커밋 게이트·허브 문서 보호·컴팩션 후 규칙 재주입 훅
shell/go-functions.zsh # 탭 기동 함수 go-solver / go-builder / go-sketcher / go-narrator / go-teamleader / go-madang
tools/madang/ # 워커 오버레이 (AppKit 단일 파일 Swift, swiftc만 있으면 빌드)
plans/ # 감사 리포트·설계 스냅샷 (결론은 DIRECTION으로 승격)
copilot/
skills/sync_claude_team/ # Claude → Copilot 단방향 설정 동기화 (manifest 기반 의미 번역)
codex/ # Codex판 마당 — 팀장 스킬·팀원 4종(TOML)·훅·작업 습관 스킬·install.sh
install.sh # ~/.claude 심링크 (~/.copilot은 있을 때만)
CONTRIBUTING.md # 커밋 규칙
.githooks/ # commit-msg 강제
.gitmessage # 커밋 템플릿
이 레포는 개인 AI 환경 4계층(내장 → 개인 → 베이스 → 오버레이) 중 베이스다 — 프로젝트 불문 팀 시스템. 개인 계층은 별도 비공개 레포, 프로젝트 특화는 각 프로젝트 .claude/(오버레이).
v0.5는 만든 사람 한 명이 매일 쓰는 상태 그대로 공개한 것이다. 알고 있는 한계부터 적는다.
현재 한계
- macOS + zsh 전제. 워커 오버레이는 AppKit(Swift) 단일 파일이라 macOS 전용이고,
go-*탭 기동 함수는 zsh 함수다. - 문서·스킬은 한국어. 영문은 아래 요약 한 절뿐이다.
- 커밋 게이트·
go-*명령은 심링크 설치(방법 1)에서만 동작한다. 훅이~/.claude/skills/teamleader/hooks/를 경로로 부르기 때문에, 플러그인 설치(방법 2)만 하면 스킬·페르소나는 쓸 수 있어도 게이트는 걸리지 않는다. - 탭은 사람이 연다. 세션이 죽으면 파일에서 상태를 복원할 수 있지만, 자동 재개·무인 운영은 아직 없다. 세션 간 신호는 파일 폴링이라 몇 초~15초 늦게 도착한다.
- 오버레이는 한 번에 한 프로젝트.
go-madang이 프로세스 이름으로 기존 오버레이를 종료하기 때문에 여러 프로젝트를 동시에 띄울 수 없다. /skill-audit은 만든 사람의 개인 환경(~/.claude/REGISTRY.md)을 전제로 한다.
공식 agent teams와의 관계. Claude Code에도 실험 기능 agent teams가 있다(기본 꺼짐, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). 리드 + 팀원 + 공유 태스크 리스트 + 메일박스라서, 브리프 전달·신호 배관은 마당과 겹친다. 마당은 그 위에서 다음 네 가지를 한다.
- 커밋 게이트 — 팀장이 git diff로 교차검증하고 APPROVE해야 팀원 커밋이 통과한다(공식 기능의 plan 승인은 리드 세션이 자동으로 내준다).
- 파일 기반 상태 — 브리프·보고·TASKS/PROGRESS가 파일이라 세션이 죽어도, 기기를 옮겨도 이어진다(공식 기능은 in-process 팀원이
/resume때 복원되지 않고, 세션당 팀 1개, 리드 고정). - 워커 오버레이 — 누가 나를 기다리는지 화면 위에서 바로 보인다.
- 사고 기록 → 규칙 — 실사고는
reference/incidents.md에 적고, 반복되면 규칙이나 훅으로 올린다.
v1 로드맵 (목표 2026-10-25)
- 컨펌 배관의 전송 계층을 공식 agent teams(메일박스·
TaskCompleted/TeammateIdle훅)로 부분 교체할지 검토한다. APPROVE/FIX/BLOCKED/DISCUSS 의미론과 커밋 게이트는 그대로 둔다. - 플러그인 설치에서도 커밋 게이트가 걸리게 한다.
- 오버레이 다중 프로젝트(이름 대신 PID로 종료).
/issue-refine을 착수 전 / 완료 후 두 명령으로 나눈다.- 소개 글.
코드는 MIT(LICENSE), 오리지널 마스코트(claude/assets/**)는 CC BY 4.0(BRANDING.md). 저작권자는 잔잔재(janjanjae).
madang ("courtyard" in Korean) is a Claude Code setup for running a team of agents with distinct roles in parallel terminal tabs: one lead plus four teammates — solver (depth: one hard problem at a time), builder (breadth: many similar tasks, with clones), sketcher (UI prototypes in isolated worktrees) and narrator (read-only explainer). Coordination is file-based: briefs, confirm requests and replies are plain Markdown under .claude/team/, and a commit-gate hook enforces the review protocol. A small always-on-top worker overlay renders each teammate's live state from those files and from the session transcripts, so you can tell at a glance who is waiting for you. Mascots are original and CC BY 4.0. Docs are in Korean; the roster table above maps the names.
git clone https://github.com/janjanjae/madang.git && cd madang
./install.sh
echo 'source '"$PWD"'/claude/shell/go-functions.zsh' >> ~/.zshrcCode is MIT; the original mascots are CC BY 4.0.
made by 잔잔재 (janjanjae) · 개인 운영 중 · 이슈·PR 환영, 단 페르소나 추가 PR은 받지 않는다(마스코트 일관성 유지 — 스킨 교체는 roster.json으로).