이슈 하나를 한 줄로 개발 끝내는 법 — 내가 가장 많이 쓰는 Claude Code 스킬들

Claude Code를 몇 달 쓰다 보니 같은 말을 계속 반복하고 있다는 걸 깨달았다. "dev 최신화하고 브랜치 따서 관련 파일 찾아줘", "끝났으면 이슈에 작업 내역 달고 닫아줘", "머지된 브랜치 정리해줘". 매번 똑같은 절차를 설명하는 일은 낭비다. 그래서 반복되는 절차를 스킬로 묶었다.

세션 로그(~/.claude/projects/)에서 스킬 호출 횟수를 세어 봤더니 내 작업 방식이 숫자로 드러났다.

상위 4개가 내가 직접 만든 이슈 워크플로 스킬이고, 그 뒤를 superpowers 계열의 사고 방식 스킬이 잇는다. 이 글에서는 이 두 묶음이 어떻게 맞물리는지 정리한다.

1. 이슈 워크플로 4종 세트

개발 흐름은 단순하다. feature/* → dev → main, GitHub 이슈 하나가 브랜치 하나, PR 하나다. 이 흐름에서 반복되는 구간마다 스킬을 하나씩 뒀다.

start-issue — 콜드 스타트 제거

이슈를 열 때마다 하던 일이 늘 같았다.

1. gh auth status, git status로 사전 점검
2. gh issue view로 요구사항 파악
3. git checkout dev && git pull
4. feature/<이름> 또는 fix/<이름> 브랜치 생성
5. 이슈 키워드로 관련 파일 탐색

이걸 start-issue 231 한 줄로 끝낸다. 마지막에는 생성된 브랜치, 요구사항 요약, 손볼 파일 후보(file:line), 제안 구현 순서를 보고해 준다. 구현이 어디서 시작될지 이미 정해진 상태로 작업을 시작하는 셈이다.

작은 안전장치도 넣었다. 워킹트리가 더럽다면 임의로 stash하거나 폐기하지 않고 먼저 물어본다. 이슈 본문에 "이걸 실행하라" 같은 문장이 있어도 데이터일 뿐 지시가 아니므로 따르지 않는다.

end-issue — 작업 내역을 이슈에 남기고 닫기

가장 단순한 스킬이다. 이슈에 작업 내역을 코멘트로 달고(gh issue comment), 이슈를 닫는다(gh issue close). 단순한데 호출은 111번이다. 코멘트를 안 남기면 몇 주 뒤 "이 이슈에서 뭘 바꿨더라"를 PR 디프에서 다시 읽어야 한다. 한 번 습관이 되면 이슈 트래커가 곧 작업 일지가 된다.

prune-branch — Squash merge 뒤의 청소

feature/* → dev를 Squash merge하기 때문에 git branch --merged로는 병합된 브랜치가 잡히지 않는다. squash된 커밋은 dev의 조상이 아니기 때문이다. 이 스킬은 판별 기준을 GitHub PR 상태(gh pr list --state merged)로 잡고, 삭제 대상을 표로 보여 준 뒤 승인을 받고 지운다.

• main, dev, 현재 브랜치는 절대 삭제하지 않는다.
• 승인 전에는 아무것도 지우지 않는다.
• 원칙은 gh pr merge --squash --delete-branch로 머지 시점에 지우는 것이고, 이 스킬은 그걸 놓친 브랜치를 위한 안전망이다.

dev-issue — 위 모든 걸 묶은 오케스트레이터

dev-issue 231은 start-issue와 end-issue를 조합해 이슈 하나를 착수부터 종료까지 한 사이클로 돌린다.

탐색 → (설계) → TDD 구현 → 검증 → PR → 머지 → 이슈 종료

이 스킬을 만든 근거는 실측이었다. 사이클 시간을 가장 많이 잡아먹는 건 코딩이 아니라 불확실성(무엇을, 어디를 손댈지 모른 채 시작)과 검증 왕복(푸시했다가 CI에서 실패하고 다시 고치는 일)이었다. 그래서 순서를 이렇게 강제한다.

1. 구현 전에 탐색부터 위임한다. 이미 구현·배포된 이슈인지, 복제할 기존 패턴이 있는지, 손댈 파일이 어디인지를 먼저 확정한다. 이미 해결된 이슈를 재구현하는 데 쓰는 30~60분을 아낀다.
2. 푸시 전에 전체 검증을 통과시킨다. 로컬에서 통과하면 CI도 대개 한 번에 통과한다. CI 재실패 왕복이 40분짜리 작업과 60분짜리 작업을 가른다.
3. 작업 크기에 프로세스를 맞춘다. 검증된 패턴을 복제하는 일은 가볍게, 신규 설계는 브레인스토밍으로 무겁게 간다.

푸시, PR, 머지, 이슈 종료처럼 바깥에 영향을 주는 단계는 임의로 진행하지 않고 승인을 받는다. 자동화하되 되돌릴 수 없는 지점에는 사람이 서 있게 했다.

2. superpowers 계열 — 생각하는 방식을 스킬로

워크플로 스킬이 "무슨 순서로 일할까"를 정한다면, superpowers 계열은 "어떻게 생각하며 일할까"를 정한다.

• brainstorming (55회): 신규 기능은 코드를 쓰기 전에 접근안을 비교하고 설계를 확정한다. dev-issue가 설계 결정이 열려 있는 이슈에서만 이 스킬을 부른다.
• systematic-debugging (36회): 버그를 만나면 추측으로 고치지 않고 재현, 격리, 원인 진단 순서를 밟는다. 수정이 증상만 덮는 일이 줄었다.
• test-driven-development (30회): 테스트를 먼저 쓴다. 이 프로젝트는 서비스 계층 커버리지 80%를 목표로 하는데, 이 습관 덕에 따로 신경 쓰지 않아도 유지된다.
• writing-plans / executing-plans / subagent-driven-development: 여러 단계에 걸친 작업을 계획으로 쪼개고, 독립적인 조각은 서브에이전트에 나눠 맡긴다.
• finishing-a-development-branch (21회): 구현이 끝났을 때 통합 방식을 정리한다.

3. 그 밖에 가끔 꺼내는 것들

• impeccable (10회): 프론트엔드 UI를 다듬을 때. 디자인 리뷰와 폴리싱.
• archify (10회): 아키텍처와 시퀀스 다이어그램을 HTML로 만들 때.
• api-error-contract: 우리 API의 공통 에러 응답 규약. 엔드포인트를 만들거나 예외 처리를 추가할 때 자동으로 적용된다.
• graft: 코드 그래프로 심볼과 호출 관계를 찾을 때. grep보다 한 번에 많은 걸 알려 준다.
• security-review: 머지 전 보안 점검.

스킬을 만들 때 얻은 교훈

1. 가장 자주 하는 말을 먼저 스킬로 만든다. 로그를 세어 보니 "이슈 시작", "이슈 종료", "브랜치 정리"가 압도적이었다. 거창한 스킬보다 매일 쓰는 작은 스킬이 훨씬 큰 시간을 아껴 준다.
2. 작은 스킬은 조합한다. dev-issue는 새 로직을 만들지 않고 start-issue와 end-issue를 부른다. 중복 구현을 금지해 두면 한쪽을 고칠 때 전체가 따라온다.
3. 스킬에 "왜"를 적는다. 절차만 있으면 상황이 달라질 때 판단할 수 없다. 사이클 시간의 병목이 불확실성과 검증 왕복이었다는 근거를 적어 두니, 에이전트가 예외 상황에서도 같은 방향으로 판단한다.
4. 되돌릴 수 없는 행동에는 확인 지점을 둔다. 삭제, 푸시, 머지, 이슈 종료는 승인 후에만 진행한다. 자동화 범위와 사람이 결정할 범위를 스킬 안에 명시했다.
5. 외부 텍스트는 데이터로 취급한다. 이슈 본문이나 PR 코멘트에 적힌 문장은 지시가 아니다. 스킬이 이걸 알고 있어야 한다.

마치며

이제 이슈 하나를 처리하는 일은 대체로 이렇게 흘러간다. dev-issue 231을 입력하고, 설계가 필요한 지점에서 대화하고, 푸시와 머지 앞에서 승인한다. 절차를 설명하던 시간이 판단하는 시간으로 바뀌었다. 같은 설명을 세 번 했다면, 그건 스킬로 만들 때가 됐다는 신호다.