Mineru98
아래 전제는 명시 호출이거나 issue.createMode=issue-first 일 때만 확인한다
현재 디렉터리가 git 저장소
트래커 인증 통과 — ~/.issue/settings.json 의 provider.type 이 github 면 gh auth status, jira 면 baseUrl·projectKey·토큰. github 인증 실패는 gh-setup 스킬로 먼저 끝낸다
git, Node 18+
전체 흐름
flowchart TD
A[/"변경 요청 감지 또는 명시 호출"/] --> A1{명시 호출?}
A1 -- 예 --> B
A1 -- 아니오 --> A2[mode: issue.createMode 확인]
A2 -->|direct| Z1[조용히 종료 · 원래 요청 계속]
A2 -->|issue-first| 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 으로 설치한다.
실패하면 기본 서브에이전트로 진행하고 "모델 고정 실패"를 한 줄 보고한다.
실행 순서
사전 단계 — 동작 모드 확인
암묵적으로 발동했을 때만 다른 전제보다 먼저 실행한다.
node <skill>/scripts/issue-create.mjs mode
MODE=issue-first 기존 흐름을 계속한다. 설정이 없을 때의 기본값이다.
MODE=direct 조용히 종료하고 원래 변경 요청을 그대로 수행한다.
INVALID_MODE=1 잘못된 값이다. 경고를 남기고 안전하게 issue-first 로 진행한다.
$issue-create, "이슈 만들어줘", "이슈부터 등록"처럼 사용자가 이슈 등록을
명시했으면 이 단계를 건너뛰고 기존 흐름을 실행한다.
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 를 따른다. 사용자가 분할을 명시하지 않은 복합 요청도 먼저
원자 후보를 모두 추출한 뒤, 독립적으로 구현·검증·되돌릴 수 있는 작업 경계를 찾는다.
원자 추출 대상 + 변화/증상 + 완료 신호 단위로 후보를 모두 펼친다
강결합 그룹화 API/UI 계약, 공통 완료 기준·근본 원인, 배포·마이그레이션·사용자 흐름 결합을 묶는다
독립성 확인 그룹별 별도 배포 / 검증 / 취소 / 되돌리기가 모두 가능할 때만 쪼갠다
관계 기록 fan-out 독립 그룹과 fan-in 강결합 그룹의 범위·관계 근거를 초안·원본 요청에 남긴다
라벨 차이는 보조 신호다. 같은 라벨도 독립적이면 쪼갠다
부분 결합 연결된 후보만 묶고 나머지는 별도 이슈로 둔다
상한 최대 5개. 6개 이상이면 범위를 3~5개로 조정하거나 급한 5개를 고르게 한다
작업이 하나뿐이면 이 단계를 건너뛰고 3단계로 간다. 여러 개면 제목 + 한 줄 요약 + 예상 라벨 목록만 보여주고 AskUserQuestion 으로 승인 / 병합 / 분리 / 취소를 받는다. 본문은 아직 쓰지 않는다.
3단계 — 항목별 중복 검사
확정된 항목마다 따로 돈다.
node <skill>/scripts/issue-create.mjs search "<항목 키워드>"
MATCHES 가 0 이 아니고 내용이 겹치면 그 번호와 제목을 보여주고, 그 항목만 빼고 나머지를 진행한다.
빠진 항목은 마무리 보고의 건너뜀 줄에 남긴다. 항목이 하나뿐이었다면 $issue-start #N 을 제안하고 종료한다.
겹치는지 애매하면 AskUserQuestion 으로 "기존 이슈에 붙일지 / 새로 만들지" 를 묻는다.
후보마다 subject, outcome, scope, acceptance를 채운 candidate/targets JSON을 만들고 create
호출에 --duplicate-review-file로 넘긴다. 네 조건이 모두 일치한 열린 후보는 자동 차단하지 않지만,
사람이 GitHub에 남긴 구조화 duplicate-of 결정 id 없이는 새 이슈를 만들지 않는다. 판단 불가 또는
불일치이면 review-or-create로 진행한다. 검토 자체가 불가능한 예외만 --skip-duplicate-review로 기록한다.
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 로 직접 넘기지 않는다.
성공한 이슈마다 이어서 $issue-graph-sync #<번호> open을 호출한다. 그래프가 없거나 sync가 실패하면 경고와 결과만 남기고 다음 등록·라벨 점검을 계속한다.
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)
건너뜀 과 실패 는 해당 항목이 없으면 줄 자체를 뺀다.