gyeolhwi
현재 디렉터리가 git 저장소
트래커 인증 통과 — ~/.issue/settings.json 의 provider.type 이 github 면 gh auth status, jira 면 baseUrl·projectKey·토큰. github 인증 실패는 gh-setup 스킬로 먼저 끝낸다
git, Node 18+
전체 흐름
flowchart TD
A[/"변경 요청 감지 또는 /issue-create"/] --> B{git repo + gh auth}
B -- 실패 --> B1[초안만 남기고 중단] --> Z0[종료]
B -- 통과 --> C[gate: 성숙도 신호 판정]
C -->|SKIP| Z1[조용히 종료 · 원래 요청 계속]
C -->|ASK| C1[AskUserQuestion: 이슈 등록할지 확인]
C1 -- 아니오 --> Z1
C1 -- 예 --> S
C -->|READY| S[요청 분해: 독립성 테스트]
S --> S1{분할안 승인?}
S1 -- 병합·분리 --> S
S1 -- 취소 --> Z0
S1 -- 승인 --> D
subgraph PER["항목마다 반복 (1~5건)"]
D[search: 유사 열린 이슈 검색] -- 유사 이슈 있음 --> D1[이 항목만 건너뜀]
D -- 없음 --> E{작업 성격 판정}
E -->|UI 변경| F1[frontend 항목 채우기]
E -->|서버 변경| F2[backend 항목 채우기]
E -->|둘 다| F3[양쪽 모두]
F1 --> G[labels 확인 후 초안 작성]
F2 --> G
F3 --> G
end
D1 --> H
G --> H{초안 N건 일괄 승인?}
H -- 일부 수정 --> G
H -- 취소 --> Z0
H -- 승인 --> I[create × N: 성격 라벨 + status:open · 실패는 건너뛰고 계속]
I --> M[unlabeled: 성격·상태 라벨 점검]
M -- 없음 --> J
M -- 있음 --> M1[제목·본문으로 라벨 제안]
M1 --> M2{일괄 적용 승인?}
M2 -- 아니오 --> J
M2 -- 예 --> M3[label: 이슈별 라벨 부착] --> J
J[다음 행동 4지선다]
J -->|착수| K[첫 번호로 issue-start 실행 · 나머지는 안내]
J -->|이슈 더 등록| A
J -->|라벨 정리| M1
J -->|종료| L[이슈 번호와 명령만 안내]
스크립트 경로
아래 중 존재하는 첫 번째 경로를 <skill> 로 쓴다. 하나도 없으면 각 레퍼런스의 인라인 절차를 그대로 수행한다.
.claude/skills/issue-create # 현재 프로젝트 (Claude Code)
.codex/skills/issue-create # 현재 프로젝트 (Codex)
~/.claude/skills/issue-create # 홈 설치
~/.codex/skills/issue-create # 홈 설치
<skill> 이 .claude/ 밑이면 실행 계열은 claude, .codex/ 밑이면 codex 다. 이 판별로 서브에이전트 모델을 고른다.
서브에이전트
전제 확인 · 중복 검사 · 성격 판정은 판정성 작업이라 값싼 모델에 맡긴다.
claude .claude/agents/issue-verifier.md (model: haiku)
codex .codex/agents/issue-verifier.toml (model = "gpt-5.6-luna")
없으면 migrate-skill-agent.sh --agent issue-verifier --target home --link --clone 으로 설치한다.
실패하면 기본 서브에이전트로 진행하고 "모델 고정 실패"를 한 줄 보고한다.
실행 순서
0단계 — 전제 확인
git rev-parse --show-toplevel
트래커 인증은 스크립트가 알아서 확인한다. create 를 뺀 모든 모드는 인증이 안 되어 있으면
exit 4 로 빠지면서 무엇을 채워야 하는지 알려 준다.
provider.type = github gh 인증. 실패하면 `gh-setup` 스킬로 설치·로그인을 끝낸 뒤 이어서 진행
provider.type = jira ~/.issue/settings.json 의 provider.jira (baseUrl·projectKey·email)
+ tokenEnv 가 가리키는 환경변수
gh-setup 이 없는 환경이면 그 사실을 알리고, 이슈 본문 초안만 마크다운으로 남긴 뒤 중단한다.
git 저장소가 아니면 그대로 중단한다.
1단계 — 성숙도 게이트
node <skill>/scripts/issue-create.mjs gate
VERDICT 에 따라 갈린다.
READY 바로 2단계로 진행
ASK AskUserQuestion 으로 한 번 확인. 아니면 종료
SKIP 아무 말 없이 종료하고 원래 요청을 그대로 수행
판정 기준은 references/maturity-gate.md. 사용자가 /issue-create 를 직접 호출했으면 이 단계를 건너뛴다.
2단계 — 요청 분해와 분할안 승인
references/split-requests.md 를 따른다. 요청 안에 독립 작업이 여러 개면 그만큼 나눈다.
독립성 테스트 따로 머지 가능 / 완료 기준 안 겹침 / 하나 취소돼도 성립 / 라벨 성격 갈림
넷 다 만족해야 쪼갠다. 하나라도 아니면 단일 이슈 + 체크리스트
상한 5개. 넘으면 묶을지 한 번 묻는다
작업이 하나뿐이면 이 단계를 건너뛰고 3단계로 간다. 여러 개면 제목 + 한 줄 요약 + 예상 라벨 목록만 보여주고 AskUserQuestion 으로 승인 / 병합 / 분리 / 취소를 받는다. 본문은 아직 쓰지 않는다.
3단계 — 항목별 중복 검사
확정된 항목마다 따로 돈다.
node <skill>/scripts/issue-create.mjs search "<항목 키워드>"
MATCHES 가 0 이 아니고 내용이 겹치면 그 번호와 제목을 보여주고, 그 항목만 빼고 나머지를 진행한다.
빠진 항목은 마무리 보고의 건너뜀 줄에 남긴다. 항목이 하나뿐이었다면 /issue-start #N 을 제안하고 종료한다.
겹치는지 애매하면 AskUserQuestion 으로 "기존 이슈에 붙일지 / 새로 만들지" 를 묻는다.
4단계 — 항목별 작업 성격 판정
issue-start 3단계와 같은 신호를 쓴다. 판정 결과가 본문 항목과 라벨을 결정한다.
frontend 신호 화면·버튼·레이아웃·반응형·깨짐, 스크린샷이 있는 요청
backend 신호 API·쿼리·성능·타임아웃·정합성·배치
both 사용자 플로우 전체를 다루거나 API 계약 변경이 화면에 영향
항목마다 성격이 다를 수 있다. 요청 전체로 뭉뚱그려 판정하지 않는다.
5단계 — 초안 작성과 일괄 승인
references/issue-draft.md 를 따른다. 저장소에 이슈 템플릿이 있으면 그것을 우선한다.
항목마다 초안을 채우고 전문을 한 번에 보여준 뒤, AskUserQuestion 으로 일괄 승인 / 일부 수정 / 취소를 받는다.
6단계 — 등록
references/create-and-handoff.md 를 따른다. 성격 라벨 없이 등록하지 않는다.
쓸 라벨이 저장소에 하나도 없으면 references/label-audit.md 의 라벨 생성 절차를 먼저 밟는다.
항목마다 create 를 따로 호출한다. 실패한 항목은 건너뛰고 계속 하고, 성공·실패를 모아 마지막에 한 번 보고한다.
status:open 은 등록 성공 직후 스크립트가 자동으로 붙인다. --label 로 직접 넘기지 않는다.
7단계 — 기존 이슈 라벨 점검
node <skill>/scripts/issue-create.mjs unlabeled --state open
출력은 두 축으로 나뉜다. UNLABELED_NUMBERS는 성격 라벨이 없는 이슈이고, NO_STATUS_NUMBERS는 진행 상태 라벨이 없는 이슈다. 둘 다 0 이면 그대로 넘어간다. 아니면 제목·본문과 PR·브랜치 상태를 읽어 제안 목록을 만들고 AskUserQuestion으로 한 번에 승인받아 붙인다. 세부는 references/label-audit.md.
8단계 — 다음 행동
references/next-actions.md 의 4지선다를 그대로 제시한다. "바로 착수" 를 고르면 첫 번호로 issue-start 를 이어서 실행하고 나머지 번호는 안내만 한다. 워크트리가 충돌하므로 여러 이슈를 동시에 착수하지 않는다.
마무리 보고
한 건일 때.
이슈 [#{issue_number} <제목>](<이슈 URL>)
라벨 <붙인 성격 라벨> + status:open
라벨 점검 성격 <n>건 확인 / <m>건 보정, 상태 <p>건 확인 / <q>건 보정
기본 브랜치 <base> (<판별 출처>)
요청 기록 .issue/{issue_number}/request.md
다음 <사용자가 고른 행동>
여러 건일 때.
이슈 #61 대시보드 기간 필터 추가 (enhancement)
#62 주문 목록 빈 렌더링 수정 (bug)
#63 레거시 export 스크립트 제거 (chore)
건너뜀 "알림 배지" — #48 과 중복
실패 없음
라벨 점검 성격 12건 확인 / 3건 보정, 상태 <p>건 확인 / <q>건 보정
요청 기록 .issue/{61,62,63}/request.md
다음 <사용자가 고른 행동> — /issue-start #61 (이후 #62, #63)
건너뜀 과 실패 는 해당 항목이 없으면 줄 자체를 뺀다.