브랜치 하나 따는 데 스킬 10KB 를 쓴다 — 내가 돌리는 워크플로우 설계

왜 브랜치 따는 데 문서가 필요한가

앞 글에서 설정이 3계층으로 갈린 과정을 썼다. 이번엔 그 위에서 실제로 매일 도는 워크플로우
하나를 처음부터 끝까지 뜯는다.

작업 브랜치를 만들고, 끝나면 PR 을 올려 머지하는 흐름이다. work-start 10,060B,
work-finish 13,238B. 합쳐서 23KB 다.¹

브랜치 하나 따는 데 23KB 가 과해 보인다. 그런데 이 팀의 git 흐름은 이렇다.

새 브랜치는 dev 가 아니라 eunseong 에서 딴다
dev 를 합칠 때 merge 가 아니라 rebase 를 쓴다
FE·BE 두 repo 에 같은 이름으로 브랜치를 만든다
PR 의 base 는 dev 가 아니라 eunseong 고정

전부 이 팀에만 있는 규칙이다. 일반적인 git 지식으로 추론하면 정확히 반대로 한다. 그래서
문서가 필요하다.

틀리는 지점을 먼저 적는다

이 스킬에서 가장 중요한 절은 절차가 아니라 “이 skill이 막는 것” 이다. 스킬 없이 하면
틀리는 지점을 여섯 개 나열해놨다.²

❌ dev에서 새 브랜치를 딴다 → eunseong에서 따야 한다
❌ merge로 dev를 합친다 → rebase여야 한다
❌ 로컬 eunseong을 origin/eunseong에 맞추는 단계를 건너뛴다
❌ 로컬 dev/eunseong을 직접 체크아웃·merge하며 보호 브랜치를 만진다
❌ 한쪽 repo에 eunseong이 없다고 dev에서 조용히 분기한다
❌ work-start 부른 그 프롬프트로 성급히 이름 짓는다

절차만 적으면 “왜 이렇게 하는지”가 안 남는다. 그러면 상황이 조금만 달라져도 일반적인
방식으로 되돌아간다. 틀리는 지점을 같이 적으면, 그 상황이 왔을 때 판단할 근거가 생긴다.

특히 다섯 번째가 중요하다. 한쪽 repo 에 eunseong 브랜치가 없을 때 조용히 dev 에서
분기하는 것이 가장 그럴듯한 오답이다. 없으면 만들어야 한다고 명시하지 않으면, 에러도 안
나고 조용히 틀린 브랜치가 생긴다.

정보가 없을 때는 멈춘다

설계에서 가장 많이 고민한 부분이다. 이 스킬은 2단계로 나뉘어 있고, 중간에 일부러 멈춘다.

Phase A 는 두 repo 의 eunseong 을 최신으로 맞추기만 한다. 브랜치는 안 만든다. 그리고
사용자에게 묻는다.

어떤 작업을 하실 건가요? 그 내용으로 FE·BE 두 repo 에 브랜치를 만들겠습니다.

왜 여기서 멈추나. 브랜치 이름의 근거가 아직 없기 때문이다.

브랜치 이름은 보통 diff 를 보고 짓는다. 그런데 작업 시작 시점에는 코드 변경이 없다. 근거가
될 수 있는 건 “무슨 작업을 할지 설명한 프롬프트” 하나뿐이다. 그게 아직 안 왔다.

여기서 멈추지 않으면 “work-start 해줘”라는 말만 보고 이름을 짓게 된다. 그 프롬프트에는
작업 내용이 없으므로 feature/work 같은 무의미한 이름이 나온다. 그래서 여섯 번째 금지
항목이 “성급히 이름 짓는다”다.

대신 예외를 하나 뒀다.

호출 프롬프트에 이미 작업 설명이 있으면 A-5 에서 멈추지 말고 곧바로 Phase B 로 넘어간다.

“LCA 결과 화면에 PDF 다운로드 버튼 만들 건데 work-start 해줘”라고 하면 근거가 이미 있다.
그때까지 멈추면 불필요한 왕복이 된다. 멈추는 이유가 “정보 부족”이므로, 정보가 있으면
멈추지 않는다.

명시하지 않은 것은 마음대로 채워진다

work-finish 는 8번 고쳐졌다. 그중 하나가 이 설계에서 배운 것 중 가장 값진 것이다.³

PR 생성 단계가 base 만 규정하고 draft 여부는 비워 둬서, 실제로는 사용자 요청 없이
--draft 가 붙은 PR 이 여러 건 올라갔다.

문서에 “draft 로 만들지 마라”고 안 썼다. 그냥 아무 말도 안 했다. 그런데 결과는 “안 붙음”이
아니라 “붙음” 이었다.

침묵은 기본값이 아니다. 명시하지 않은 자리는 그럴듯한 값으로 채워진다. 그래서 한 줄을
넣었다 — 정식 PR 로 생성하고 --draft 를 붙이지 않는다.

이건 프롬프트를 쓸 때 계속 나오는 문제다. “하지 마라”를 안 썼다고 안 하는 게 아니다.
금지를 안 적으면 금지가 아니다.

실패해도 되는 실패를 구분한다

work-finish 의 안전장치 절에는 중단 조건이 나열돼 있다. rebase 충돌, 빌드 실패, 머지 충돌
— 전부 멈춘다. 그런데 하나만 예외다.⁴

Jira 전환 실패(권한·네트워크·잘못된 키) → 중단하지 않는다.
git 흐름은 그대로 끝내고 완료 보고에 "티켓 전환 실패"로 남긴다.
Jira 때문에 머지된 코드를 되돌리지 않는다.

이게 설계 판단이다. 모든 실패를 똑같이 다루면 안 된다.

빌드 실패는 진행하면 안 되는 실패다. 깨진 코드가 머지된다. 반면 Jira 티켓 상태 전환 실패는
부수 효과다. 코드는 이미 정상적으로 머지됐고, 티켓 상태는 나중에 손으로 바꾸면 된다.
여기서 멈추거나 되돌리면 부수적인 것 때문에 본질을 훼손한다.

기준은 “이 실패가 본 작업의 정확성에 영향을 주는가”다. 안 주면 기록만 남기고 진행한다.

문서를 따라가 봐야 구멍이 보인다

가장 최근 수정은 성격이 다르다. 8월 25일에 Jira 연동을 붙인 뒤, 독립적으로 감사를 한 번
돌렸다. 문서를 순서대로 따라가면서 실제로 도는지 확인하는 작업이다.

네 건이 나왔다.⁵

지적	무엇이 문제였나
재사용 경로 도달 불가	전환 트리거가 “PR 생성 직후”라, 기존 PR 을 이어받으면 그 단계에 영영 안 닿았다
순서가 뒤집힘	티켓 키 추출이 PR 본문 작성보다 뒤에 있어 본문에 링크를 넣을 수 없었다
조건이 명령문 뒤에	완료 타이밍 조건이 명령문 뒤 인용구에 있어 읽는 순서상 뒤집혔다
결과 누락	완료 보고 템플릿에 “전환 실패” 항목이 없었다

전부 논리는 맞는데 순서가 틀린 것이다. 읽으면 말이 되는데 따라가면 안 되는 문서였다.
이런 건 눈으로 읽어서는 안 보인다. 실제로 한 단계씩 밟아봐야 나온다.

특히 첫 번째가 무섭다. 수동으로 연 PR 을 이어받는 경로에서는 티켓이 진행 중 → 완료로
건너뛰었다. 에러가 나지 않으므로 아무도 모른다. 트리거를 “PR 번호 확보 직후(생성·재사용
무관)”로 바꿔 고쳤다.

뺀 것도 설계다

8월 13일에는 단계를 지웠다. PR 을 올린 뒤 봇 리뷰가 달릴 때까지 10초 간격으로 최대 3분
기다리고, 봇 코멘트를 읽어 조치하던 두 단계다.

그전에 대기 시간을 5분 → 3분으로 줄인 적이 있다. 그래도 안 맞아서 결국 통째로 뺐다.

이유는 단순하다. 대기가 값을 못 했다. 3분을 기다려도 봇이 늘 유의미한 걸 잡는 게 아닌데,
그동안 흐름 전체가 멈춰 있다. 지금은 PR 생성 다음이 바로 병합이다.

지우면서 딸려 나온 것들이 있다. 단계 번호 7·8 → 5·6, 안전장치의 “봇리뷰 타임아웃” 조항,
완료 보고의 봇 조치 항목. 그리고 하나는 지우지 않고 근거만 바꿨다.

병합 전 mergeable 재확인의 근거를 “대기 중” → “0-C 재최신화 이후”로 교체
(대기가 없어져 기존 문구가 성립하지 않음. 재최신화와 병합 사이에도 eunseong 이 움직일
수 있으므로 재확인 자체는 유지)

대기가 사라졌으니 “대기하는 동안 바뀔 수 있다”는 근거는 무효다. 그런데 재확인 자체는 여전히
필요하다 — 재최신화와 병합 사이에도 시간이 흐르기 때문이다. 근거가 무효가 됐다고 결론까지
버리면 안 된다. 근거만 갈아 끼웠다.

정리하면

23KB 짜리 워크플로우에서 실제로 값을 하는 건 절차 목록이 아니었다.

장치	하는 일
“막는 것” 목록	그럴듯한 오답을 미리 지목한다
2단계 분리	근거가 없을 때 이름을 짓지 않게 한다
draft 금지 한 줄	침묵이 기본값으로 해석되지 않게 한다
Jira 예외	본질과 부수를 나눠 다르게 실패시킨다

공통점은 전부 사후에 붙었다는 것이다. draft 는 잘못된 PR 이 여러 건 올라간 뒤에, Jira
예외는 연동을 붙인 뒤에, 감사 지적 네 건은 문서를 실제로 따라가 본 뒤에 나왔다.

그래서 이 스킬을 처음부터 23KB 로 쓸 수는 없었다. 7월에 만들 때는 훨씬 작았고, 여덟 번
고쳐지며 이만큼이 됐다. 틀린 경험이 없으면 “막는 것” 목록을 쓸 수가 없다.

다음 글에서는 이렇게 쌓인 규칙들을 내가 다시 검증했을 때 무엇이 틀렸는지 다룬다.

~/dotfiles/claude/profiles/company-mac/skills/work-start/SKILL.md, work-finish/SKILL.md. company-pro 프로파일에도 동일 파일이 있다. ↩
work-start/SKILL.md “이 skill이 막는 것 (skill 없이 하면 틀리는 지점)” 절. ↩
커밋 f74bb30 (2026-08-04) “work-finish 에 정식 PR 생성 명시 (–draft 금지)”. ↩
work-finish/SKILL.md “분기 & 안전장치” 절. 커밋 6e3909d (2026-08-25) 로 Jira 연동과 함께 추가. ↩
커밋 e47aed4 (2026-08-25) “work-finish Jira 연동의 감사 지적 4건 수정”. ↩