| name | dev-bounce |
| description | 코드를 고치거나 새로 짜는 작업을 단계별 워크플로우로 진행한다. 버그 수정, 기능 구현, 리팩터링, 설정·의존성 변경, "이거 고쳐줘" / "이 기능 추가해줘" / "왜 안 되는지 보고 고쳐봐" 같은 요청에 파일을 건드리기 전 반드시 먼저 호출할 것. 계획 승인·검증 통과·커밋을 엔진이 강제하는데, 이 스킬로 작업을 시작해야만 그 강제가 걸린다 — 스킬 없이 바로 Edit/Write하면 아무 규칙도 적용되지 않은 채 진행된다. 질문·설명·코드 읽기만 하는 요청에는 쓰지 않는다. |
dev-bounce
작업을 스테이지 체인으로 진행한다. 각 단계에서 무엇을 하고 무엇이 금지되는지는
프로젝트의 workflow.yaml에 정의돼 있고, 엔진이 단계마다 지시를 주입한다.
이 문서에 워크플로우 내용은 없다. 시작 절차만 있다.
시작한 뒤에는 주입되는 지시를 따르면 된다.
물어야 하는데 물을 수단이 없을 때
이 문서는 몇 군데에서 AskUserQuestion으로 사용자에게 물으라고 한다.
그 도구가 없는 컨텍스트도 있다(서브에이전트, 위임 실행 등).
그럴 때는 추측해서 진행하지 말고 멈춘다. 선택지를 텍스트로 그대로 제시하고
사용자 답을 기다린다. 도구가 없다는 건 "알아서 하라"는 뜻이 아니다.
물어야 하는 것들은 전부 사용자만 답할 수 있는 것이기 때문이다 —
어느 모드로 갈지, 남의 작업과 병렬로 갈지, 이 규칙을 앞으로도 적용할지.
문구가 명확해 보여도(예: "앞으로 항상") 추측으로 진행하면
사용자가 원한 적 없는 영구 변경이 남는다. 되돌리는 비용이 묻는 비용보다 훨씬 크다.
Step 1 — 상태 확인
bouncer scan
항상 부른다. 0.01초짜리고, 세션 시작 때 주입된 정보는 그 사이 다른 세션이
작업을 시작했으면 이미 낡았을 수 있다.
STATE MINE <경로> <워크플로우> <단계> 이 세션이 이어서 할 작업
STATE OTHER <경로> <단계> <나이> 다른 세션이 잡고 있는 작업
STATE NONE 아무것도 없음
WORKFLOW <이름> <설명> 모드 선택지
OPTION <워크플로우> <단계> <id> <이름> 시작할 때 물어볼 선택 항목
| 결과 | 다음 |
|---|
MINE | 이미 진행 중이다. 요청이 그 작업의 연장이면 bouncer status로 남은 조건을 보고 이어서 한다. Step 2~4는 건너뛴다 |
OTHER만 있음 | 다른 세션이 작업 중이다. Step 2로 가되 Step 4에서 병렬 여부를 묻는다 |
NONE | Step 2 |
bouncer: command not found가 나오면 이 프로젝트에 ai-bouncer가 설치되지 않은 것이다.
스킬을 쓰지 말고 사용자에게 알린 뒤 평소대로 작업한다. 설치를 임의로 진행하지 않는다.
Step 2 — 요청이 개발 작업인지 판별
| 요청 성격 | 처리 |
|---|
| 질문·설명·코드 읽기 | 스킬을 쓰지 않고 그냥 답한다 |
| 계획을 세우려면 탐색이 먼저 필요 | 읽기 전용으로 탐색한다(수정 금지). 끝나면 Step 1부터 다시 시작한다 |
| 개발 의도는 있으나 무엇을 고칠지 불명확 | AskUserQuestion으로 구체화한다. "개발 작업으로 처리할까요?" 같은 확인 질문은 답이 뻔해서 사용자 시간만 쓴다 |
| 개발 요청 | Step 3 |
Step 3 — 모드와 옵션을 사용자에게 묻는다
Step 1의 WORKFLOW 줄을 그대로 AskUserQuestion 선택지로 만든다.
모드가 정해지면 그 모드의 OPTION 줄들을 스테이지별로 묶어 다시 묻는다
(multiSelect, 기본 전체 켜짐). 선택지가 4개를 넘으면 질문을 나눠서 여러 번 호출한다.
OPTION이 없으면 이 질문은 건너뛴다.
모드는 사용자가 고른다. 계획 단계가 번거롭다는 이유로 가벼운 모드를 대신 고르면
사용자는 자기가 원한 검증이 빠진 줄 모른 채 결과를 받는다. 그건 워크플로우 회피다.
AskUserQuestion을 쓸 수 없으면 위 "물어야 하는데 물을 수단이 없을 때"를 따른다.
Step 4 — 시작
bouncer start <모드> "<슬러그>" [--off <끈-항목-id>] ...
슬러그는 영문 소문자와 하이픈으로 짧게 쓴다 (payment-bug, add-oauth).
디렉토리 이름이 되므로 한글이나 공백을 쓰면 도구에 따라 정렬·경로 처리가 어긋난다.
Step 1에 OTHER가 있었으면 그냥 start하면 거부된다. 사용자에게 먼저 묻는다:
| 선택 | 처리 |
|---|
| 병렬로 진행 | bouncer start <모드> "<슬러그>" --parallel
별도 브랜치와 레포 밖 worktree가 만들어지고 base 브랜치가 이 시점에 기록된다.
끝나면 bouncer worktree finalize로 base에 FF 머지된다 |
| 기존 작업 이어하기 | 그 세션의 작업이므로 건드리지 않는다. 해당 세션에서 계속하라고 안내한다 |
Step 5 — 이후
엔진이 단계마다 지시를 주입한다. 그 지시를 따른다.
- 응답을 끝내려 할 때 조건이 안 맞으면 엔진이 사유를 알려주고 계속 진행시킨다
- 조건이 다 맞으면 자동으로 다음 단계로 넘어간다
- 단계는 스스로 넘길 수 없다.
state.json 수정은 차단된다
막혔을 때
hook이 차단했을 때 — 차단 사유에 무엇이 필요한지 적혀 있다. 그 조건을 충족시킨다.
우회로를 찾지 마라. 차단은 지금 그 행동이 이 단계에서 안전하지 않다는 뜻이고,
우회하면 사용자가 원한 검증이 빠진 채로 결과가 나간다.
bouncer run이 계속 실패할 때 — 출력을 읽고 원인을 고친 뒤 다시 실행한다.
같은 실패가 반복되면 접근이 틀린 것이다. 같은 수정을 반복하지 말고
다른 원인을 찾거나, 사용자에게 상황과 막힌 지점을 보고한다.
설정된 횟수를 넘기면 엔진이 알아서 사용자에게 판단을 넘긴다.
작업을 접어야 할 때 — bouncer cancel로 정리한다.
.active를 직접 지우면 상태가 어긋난 채로 남는다.
사용자가 "앞으로 항상 ~해라"라고 할 때
이번 작업 한정인지 앞으로 계속인지 먼저 구분한다. 잘못 판단하면
한 번짜리 요청이 영구 규칙이 되거나, 반복될 규칙이 매번 잊힌다.
| 사용자 말 | 해석 | 처리 |
|---|
| "이번엔 e2e까지 돌려" | 이번만 | 그냥 한다. yaml은 건드리지 않는다 |
| "작업 끝나면 CHANGELOG도 갱신해" | 애매 | 물어본다 |
| "앞으로 커밋 전엔 항상 린트 돌려" | 계속 | 물어본다 |
애매하거나 반복될 성격이면 AskUserQuestion으로 확인한다.
도구가 없으면 아래 선택지를 텍스트로 제시하고 답을 기다린다 — 문구가 명확해 보여도
확인 없이 workflow.yaml을 고치지 않는다. 그건 사용자가 요청한 적 없는 영구 변경이다.
❓ 이걸 워크플로우에 넣을까요?
○ 이번 작업만 — 지금 한 번만 수행
○ 워크플로우에 추가 — 앞으로 모든 작업에 적용 (workflow.yaml 수정)
"워크플로우에 추가"를 고르면:
- 어느 단계에 넣을지 정한다:
- "작업 끝나면 ~" →
finalize 앞 (커밋 전에 끝내야 할 정리)
- "커밋 전에 ~" →
finalize의 첫 step
- "구현하면서 ~" →
implement / "검증할 때 ~" → verify
- 성격이 뚜렷이 다른 묶음이면 새 스테이지로 만들고 체인 배열에 끼워넣는다
- 자동 검증이 가능하면
run, 사람 판단이 필요하면 inject로 쓴다.
강제할 것이면 blocking: true, 매번 물어볼 성격이면 optional: true
- 수정 전에 추가할 yaml을 사용자에게 그대로 보여주고, 승인을 받은 뒤에 고친다
- Edit 도구로
.claude/ai-bouncer/workflow.yaml을 수정한다
bouncer check로 검증한다. 실패하면 되돌린다- 다음 세션부터 적용된다고 알린다 (이번 작업의 규칙은 시작 시점에 고정돼 있다)
forbid를 약화시키는 방향(차단 해제)은 사용자가 명시적으로 요구할 때만 한다.
게이트가 귀찮다는 이유로 규칙을 무르면 그 규칙을 만든 이유가 사라진다.
명령
| 명령 | 용도 |
|---|
bouncer scan | 상태·모드·선택항목 (시작 전 1회) |
bouncer start <모드> "<슬러그>" | 작업 시작 |
bouncer status | 현재 단계와 남은 조건 |
bouncer run <step-id> | 검증 명령 실행 후 결과 기록. 명령 문자열은 엔진이 소유한다 |
bouncer done <step-id> | 사람 확인이 필요한 step 완료 처리 |
bouncer cancel | 작업 취소 |
bouncer worktree finalize | 병렬 작업을 base로 FF 머지하고 정리 |
bouncer check | workflow.yaml을 고친 뒤 유효한지 검사 |
하지 말 것
- 모드를 사용자 대신 고르기
- 물을 수단이 없다는 이유로 사용자 몫의 결정을 대신 내리기
state.json / .active / workflow.compiled.json 직접 수정- 검증 명령을 직접 타이핑해 실행하고 "통과했다"고 보고하기
→
bouncer run으로 해야 결과가 증거로 남는다. 직접 실행한 것은 기록되지 않아
엔진이 계속 미충족으로 판정한다
- 실패한 것을 통과로 보고하기
- 완료 후 사용자 지시 없이 새 작업 시작하기
