jira-branch

name

jira-branch

description

딸깍 웹(ttalkkak-web, 프론트엔드) 레포 전용. git 브랜치를 새로 만드는 모든 요청에 사용한다 — "브랜치 파줘/만들어줘/따줘/세팅해줘", "develop에서 새 브랜치", "이 작업 이제 시작할게"가 여기 해당한다. 지라(TMT) 티켓·티켓 번호(TMT-75·#75), 기능/컴포넌트 이름(chip·radio 등), "진행 중인 내 티켓", "방금 만든 티켓" 중 무엇과 엮이든, 심지어 아무것도 지정하지 않아도 브랜치 생성 의도만 있으면 트리거한다. 이 스킬은 티켓을 특정해(없으면 티켓부터 생성) 규약대로 브랜치를 만들고, 티켓을 진행 중으로 옮기고, 브랜치를 티켓에 연결·기록하는 전체 흐름을 한 번에 처리한다. "브랜치"와 "티켓"이 한 요청에 같이 나오면 거의 항상 이 스킬이다. 트리거하지 않음: 이미 있는 브랜치로 체크아웃/이동, 커밋, PR 생성, 그리고 브랜치 없이 티켓만 조회·수정·생성하는 요청.

jira-branch — 티켓에서 브랜치까지, 한 번에

"이 작업 시작할게"라는 한마디를 올바른 브랜치 + 올바른 티켓 상태 + 추적 가능한 연결로 바꾸는 스킬이다. 매번 티켓 검색하고, 브랜치명 규약을 손으로 맞추고, 상태를 바꾸고, 어느 브랜치가 어느 티켓인지 기억하는 잡일을 없앤다.

범위: 이 스킬은 딸깍 웹(ttalkkak-web) 레포 전용으로, 이 레포의 프론트 브랜치 규약(<type>/#<번호>-<슬러그>, base develop)에 맞춰져 있다. 백엔드는 브랜치 컨벤션이 달라 그대로 쓸 수 없으므로 지금은 웹 레포에만 둔다. 컨벤션이 정리되면 team-tools 플러그인으로 승격해 팀 공용으로 확장할 수 있다.

세 가지 설계 원칙

이 스킬이 왜 이렇게 동작하는지 먼저 이해하면 나머지는 자연스럽게 따라온다.

1. 입력이 무엇이든 결과는 하나로 수렴한다. 티켓 키·기능 이름·빈손 — 사용자는 편한 대로 말하고, 스킬이 티켓을 특정하는 책임을 진다.
2. 본인은 묻지 않고 판별한다. "당신 누구세요"를 절대 묻지 않는다. 연결된 Atlassian 인증과 JQL currentUser()로 실행자 본인을 판별한다. 그래서 팀원 누구에게 공유해도 설정 없이 각자 자기 티켓 기준으로 동작한다. 남에게 할당하는 드문 경우에만 Jira 사용자 검색으로 account ID를 그때그때 조회한다 — 팀원 목록을 파일에 박아두지 않는다(공개 레포 PII).
3. 로컬은 자유롭게, 원격 쓰기는 신중하게. 브랜치 checkout·생성은 되돌리기 쉬우니 확인 없이 진행한다. 지라 티켓 생성·상태 전환·코멘트는 되돌리기 번거로운 외부 쓰기라 실행 전 한 번 확인받는다.

"연결(link)"이란

지라 티켓과 브랜치를 서로 알아볼 수 있게 엮는 것을 말한다. 원래 지라는 브랜치명·커밋에 티켓 풀키(TMT-75) 가 있으면 dev-panel에 자동으로 브랜치를 붙여준다. 하지만 이 레포 규약은 #75(숫자만)라 그 자동 연결이 안 걸린다. 그래서 이 스킬은 티켓에 코멘트로 브랜치명을 남겨 사람이 티켓만 봐도 작업 브랜치를 찾게 한다. 즉 여기서 "연결" = 자동 dev-panel 대신 코멘트로 브랜치를 기록하는 것.

레포 규약 (정본: 이 레포의 CLAUDE.md / architecture rule)

• 브랜치 <type>/#<번호>-<슬러그>, base develop. 번호 = TMT 티켓 키의 숫자부분. 예: TMT-75 [개발] Chip 공통 컴포넌트 → feat/#75-chip-component
• type = 커밋 type과 동일: feat fix refactor chore style deploy docs.
• GitHub Ruleset이 브랜치명을 검증한다 — 규약을 벗어나면 push가 막히므로, 만들기 전에 정규식으로 자체 검증한다: ^(feat|fix|refactor|chore|style|deploy|docs)/#[0-9]+-[a-z0-9][a-z0-9-]*$

대상 레포의 CLAUDE.md·.claude/rules/architecture.md에 규약이 있으면 그것이 우선이다. 위 값과 다르면 레포를 따르고 차이를 알린다.

워크플로우

1 — 티켓을 특정한다

입력 형태로 갈린다. TMT 참고값(cloudId 등)·담당자 지정은 references/tmt-reference.md.

입력	처리
티켓 키 (TMT-75·#75·75)	Jira 이슈 조회 기능으로 확정
기능 이름/설명 (chip-component)	내 활성 티켓 + summary 검색으로 매칭 → 있으면 확정, 없으면 2-b(티켓 생성)
없음	내 활성 티켓을 보여주고 사용자에게 선택받음

내 활성 티켓:

JQL: assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC
fields: summary, status, issuetype, updated
max results: 50

이름 매칭은 jql='project = TMT AND summary ~ "chip" ORDER BY updated DESC' 병행. 후보가 여럿이면 고르게 하고, 하나여도 "이 티켓 맞나요?"로 한 번 확정한다 — 엉뚱한 티켓에 브랜치를 엮는 게 가장 비싼 실수다.

2-b — 티켓이 없으면 먼저 만든다

매칭이 없으면 사용자에게 생성 여부를 확인하고 프로젝트 TMT에 만든다. team-tools:jira-creator가 제공되면 그 규칙을 따르고, 없으면 기본 타입 작업, 담당자는 연결된 Atlassian 인증의 본인 account ID, Decision Level은 세부 작업 기본값 L3(additional_fields={"customfield_10147":{"value":"L3"}})로 설정한다. 필수 커스텀 필드 오류(... is required)가 나면 Jira 이슈 타입 메타데이터를 조회해 누락 필드를 채워 재시도한다. 생성된 키로 3번을 잇는다.

3 — 브랜치 이름을 짓는다 (제안 → 확인)

type은 이슈에서 추정하되 확정은 사용자 몫: 버그→fix, 리팩터/구조개선→refactor, 세팅/설정/CI→chore, 그 외 개발(작업·스토리·에픽·[개발])→feat(기본).

슬러그는 한글 summary에서 영문 kebab을 제안하고 사용자가 확정한다(자동 번역이 어긋날 수 있어 확인 단계를 반드시 둔다): 소문자·영숫자와 -만, 태그/중복어(구현·공통·컴포넌트) 정리, 2~4단어. 예: [개발] Chip 공통 컴포넌트 구현 → chip-component.

조립한 이름을 위 정규식으로 검증한다.

4 — base를 최신화하고 브랜치를 만든다

되돌리기 어려운 실수를 막기 위해 순서대로:

1. 미커밋 변경 — git status --porcelain에 변경이 있으면 어떻게 할지 묻는다(새 브랜치로 가져가기 / git stash / 폐기). 임의로 버리지 않는다.
2. 중복 브랜치 — 같은 번호 브랜치가 이미 있으면(git branch -a | grep '#75') 새로 파는 대신 checkout을 제안한다.
3. develop 최신화 후 분기:

   git fetch origin
   git switch develop && git pull --ff-only   # ff 실패(로컬 갈라짐) 시 알리고 멈춤 — 임의 merge/rebase 금지
   git switch -c 'feat/#75-chip-component'
   

5 — 티켓에 반영한다 (외부 쓰기 — 실행 전 확인)

브랜치가 생겼으니 티켓을 작업 상태로 맞추고 흔적을 남긴다. 이미 만족하는 단계는 건너뛴다(중복 노이즈 방지).

1. 진행 중 전환 (아직 아니면): TMT 전역 ID 21로 전환한다. 참고 ID: 21=진행중, 2=검토중, 31=완료, 11=해야할일, 3=Blocked. 실패하면 Jira의 사용 가능한 상태 전환을 조회해 재확인한다.
2. 미할당이면 본인 할당: 연결된 Atlassian 인증의 account ID를 담당자로 설정한다.
3. 브랜치 기록 코멘트: Markdown으로 🌿 브랜치 `feat/#75-chip-component` 생성 (base develop). PR 생성 시 갱신.을 남긴다.

6 — 한눈에 보고한다

연결 티켓(키·요약·상태 변화), 브랜치명, base, 미커밋 변경 처리 결과, 다음 액션(예: 첫 커밋)을 한 번에 정리한다.

경계

• 연결된 Jira/Atlassian 도구가 없으면 재연결을 안내하고 멈춘다 — 우회하지 않는다. (본인 신원도 이 인증에서 나온다.)
• 규약 정규식을 통과 못 하는 이름은 만들지 않는다.

예시

티켓 키 지정 — TMT-75 브랜치 만들어줘 → 조회 → feat / chip-component 제안·확인 → develop 최신화 → feat/#75-chip-component → 진행 중 + 기록 코멘트.

이름만, 티켓 있음 — chip 컴포넌트 브랜치 파줘 → summary ~ "chip"로 TMT-75 발견 → "이 티켓 맞나요?" → 이후 동일.

이름만, 티켓 없음 — toast 컴포넌트 브랜치 → 매칭 없음 → "TMT에 티켓이 없어요. 만들까요?" → 작업 생성(본인 담당) → 새 키로 feat/#NN-toast-component.