AI에게 구현을 맡기면 생기는 문제 — 상상 설계, 겸사겸사 리팩토링, "잘 되는 것 같아요" — 를 이슈를 계약서처럼 써서 막는 Claude Code 워크플로우.
한국어 | English
핵심 루프는 슬래시 커맨드 3개, 여기에 네비게이터(/next)와 자동 반복 루프(/issue-loop)가 얹혀 있습니다:
/spec "기능 설명" (상위 모델 자동) /implement-issue 12 (세션 모델)
│ │
① 코드 읽고 검증 ④ 이슈 계약대로 구현
② 설계문서 작성 ⑤ 검증 명령어 자가 실행
③ 이슈 자동 등록 ──── GitHub Issues ─────▶ ⑥ PR 생성
│ │
└── /review-pr 15 12 (상위 모델·별도 세션) ◀──┘
⑦ 설계문서 대비 PR 판정
/next 위 루프에서 "다음 할 일"을 GitHub 상태로 자동 판단
/issue-loop 위 루프 전체를 서브에이전트로 자동 반복 (머지 판단은 사람)
- 시작하기 (5분)
- 커맨드 상세 가이드
- 기억할 규칙 3개
- Git 워크플로우와의 관계
- 자주 묻는 질문
- 이슈 본문 양식
- 프로젝트·마일스톤 연동
- 라벨 체계
- 어디까지 자동인가
- 커스터마이징
- 보안
- 구성 파일
적용할 저장소 루트에서:
curl -fsSL https://raw.githubusercontent.com/nlook-service/issue-template/main/install.sh | bash이 한 줄이 전부 설치합니다:
- 슬래시 커맨드 4개 (
.claude/commands/) +issue-loop스킬 (.claude/skills/) - GitHub 이슈 폼 + 설계문서 템플릿
- 라벨 13종 (
ai-task,size:S/M,review:approved/rejected등) - 자동 업데이트 워크플로우 (매주 월요일, 템플릿이 갱신됐으면 PR이 옴)
설치 후 안내대로 커밋하면 끝:
git add .github docs .claude && git commit -m "chore: issue-template 설치"업데이트도 같은 명령입니다. 다시 실행하면 변경된 파일만 갱신되고, 팀에서 수정한 파일은 덮어쓰지 않고
<파일>.new로 보존됩니다.
curl | bash가 꺼려지면 보안 섹션의 "설치 전 검토" 방법을 참고하세요.
| 설정 | 어디서 | 효과 |
|---|---|---|
| Actions의 PR 생성 허용 | 리포/조직 Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests" 체크 | 템플릿 업데이트가 매주 자동 PR로 도착 |
| 프로젝트 자동 연동 | 팀 프로젝트(Projects) → ⚙️ Settings → Workflows → Auto-add to project 켜고 필터 label:ai-task |
등록되는 모든 이슈가 자동으로 프로젝트에 추가 |
| 프로젝트 상태 자동 이동 | 같은 Workflows 화면에서 Item added → Todo, Item closed → Done, Pull request merged → Done 켜기 | 보드의 Todo·Done 칸이 자동으로 채워짐 |
| 프로젝트 "In Progress" 반영 | gh auth refresh -s project (gh 토큰에 project 스코프 부여, 1회) |
/implement-issue가 구현 시작 시 보드를 In Progress로 이동 — GitHub은 "작업 시작"을 감지 못 하므로 커맨드가 채움. 스코프 없으면 조용히 건너뜀 |
| 마일스톤 생성 | 리포 → Issues → Milestones (마감일 꼭 입력) | /spec이 이슈 등록 때 어느 마일스톤에 넣을지 물어보고 자동 연결 |
| 브랜치 보호 규칙 | 리포 Settings → Branches → main에 required checks 지정 | /issue-loop --unattended의 자동 머지에 CI 통과가 강제됨 |
인사이트는 공짜로 나옵니다. 커맨드가 이슈·PR에 메타데이터를 자동으로 심기 때문에 — 유형(
feat/bug/refactor)·크기(size:S/M) 라벨과 담당자·이슈 타입(Feature/Task/Bug)은/spec이, 라벨·마일스톤의 PR 승계는/implement-issue가, 리뷰 판정(review:approved/rejected) 라벨은/review-pr이 — 마일스톤 페이지에서 진행률, Projects → Insights에서 처리량 차트,label:review:rejected필터로 반려율을 별도 도구 없이 볼 수 있습니다.
$ claude
> /spec 토큰 만료 시 재로그인 없이 세션을 이어가는 refresh 토큰 갱신 기능
분해안을 승인하면 이슈가 등록됩니다. 그다음은 취향대로:
- 한 걸음씩 직접: 새 세션에서
/implement-issue 12→ 또 새 세션에서/review-pr 15 12→ 머지 - 다음 할 일만 자동 판단:
/next - 전부 자동 반복:
/issue-loop
/spec <기능 설명 또는 요구사항 문서 경로>
상위 모델(opus)로 고정 실행됩니다. 하는 일:
- 실제 코드 검증 — 요구사항과 관련된 코드를 직접 열어 파일:라인 근거를 수집합니다. 확인하지 못한 사실은 설계에 쓰지 않습니다 (상상 설계 차단). 동시에 UI 판정: 사람 눈에 보이는 표면의 모양 또는 표시 값의 의미가 바뀌는지를 감이 아니라 근거(파일:라인)와 함께 판정하고 기록합니다 — 'UI 없음'도 탐색 경로와 함께 기록됩니다.
- 설계문서 작성 + UI 시안 —
docs/design/<기능-슬러그>.md. "하지 않는 것" 최소 2개 필수. 화면이 바뀌는 기능이면 자급자족 HTML 시안(.design/<슬러그>/vN.html— 실제 코드 기반 AS-IS/TO-BE, 빈 상태 포함)을 함께 만듭니다. CLI 출력 같은 가벼운 표면은 before/after 텍스트와 출력 검증 명령으로 충분합니다 (시안 강제 없음). - 이슈 분해 — 각 이슈는 AI 세션 1개에서 끝나는 크기(파일 ~5개, diff ~300라인). 병렬 안전 규칙: 의존 없는 이슈끼리는 코드 앵커(수정 파일)가 겹치지 않게 분해 — 그래야 git worktree로 동시 진행해도 충돌이 없습니다.
- 사람 승인 — 분해안·마일스톤, 그리고 UI 시안을 확인받기 전에는 이슈를 등록하지 않습니다. 시안 피드백은 vN+1로 반복하되 상한 3회 — 코드를 쓰기 전에 그림으로 합의하고, 승인된 시안이 구현·리뷰의 계약이 됩니다.
- 이슈 등록 — 승인된 설계문서·시안을 먼저 커밋한 뒤(어느 세션·머신에서도 링크가 깨지지 않게), 상위 추적 이슈(
[Feature]) + 하위 이슈([Task][<슬러그> <순번>/<전체>])를 sub-issue 트리로 연결하고, 라벨·담당자·마일스톤·이슈 타입까지 자동 부착합니다.
제목의 [auth 2/3] 태그 덕에 이슈 목록에서 전역 번호와 무관하게 "어느 기능의 몇 번째 작업"인지 바로 보입니다.
/implement-issue <이슈 번호>
세션 모델을 그대로 사용합니다 (의도적으로 모델 미고정). 하는 일:
- 이슈 계약 읽기 —
[Feature]추적 이슈면 구현하지 않고 착수 가능한 하위 이슈를 안내합니다. 선행 이슈가 안 닫혔으면 중단합니다. - 앵커 검증 — 이슈의 코드 앵커가 실제 코드와 맞는지 확인. 설계 전제가 깨졌으면 구현하지 않고 이슈에 코멘트 +
needs-respec라벨을 남기고 중단합니다 (세션이 닫혀도 기록이 GitHub에 남음). - 계약대로만 구현 — 코드 앵커 파일만 수정, Non-goals는 절대 안 건드림, 인터페이스 계약 그대로.
- 검증 자가 실행 — 완료 기준의 검증 명령어를 직접 실행해 전부 통과시킵니다.
- PR 생성 —
Closes #N+ 검증 결과 + Non-goals 준수 확인을 본문에 포함. 이슈의 라벨·마일스톤을 PR에 승계합니다.
반려 후 재작업도 이 커맨드입니다. 같은 이슈로 다시 실행하면 열린 PR의 반려 사유(리뷰·코멘트)를 읽고, 새 PR을 만들지 않고 기존 브랜치에서 고쳐 push한 뒤 대응 내역을 코멘트로 남깁니다.
/review-pr <PR 번호> [이슈 번호]
상위 모델(opus)로 고정 실행. 반드시 구현과 다른 세션에서 실행하세요 — 구현한 세션은 자기 가정을 물려받아 자기 결함을 못 잡습니다.
일반 코드 리뷰("좋은 코드인가")가 아니라 계약 대비 검증("우리가 합의한 그 코드인가")입니다:
- 코드 앵커 범위 준수 / Non-goals 침범 (하나라도 걸리면 반려) / 인터페이스 계약 일치 / 엣지 케이스 반영 / 완료 기준 실제 통과 (의심되면 직접 재실행)
risk:high라벨 PR은 검증을 강화하고 판정과 무관하게 사람 리뷰를 함께 요구합니다.- 판정 전문을 PR 리뷰로 기록합니다 — 반려 사유가 세션과 함께 증발하지 않고, 재작업 세션이 읽고 고칩니다.
review:approved/review:rejected라벨도 부착합니다. - 1인 개발도 그대로 동작합니다. GitHub은 자기 PR의 승인/반려 리뷰를 거부하지만, 그 경우 판정 전문은 PR 코멘트로 남고 자동화의 상태 원본은 리뷰 상태가 아니라 라벨이므로 워크플로우에 영향이 없습니다.
- 머지는 승인 판정일 때만 사용자에게 묻습니다. 임의 머지는 하지 않습니다.
/next [상위 이슈 번호]
"다음 뭐 하지?"를 GitHub 상태에서 자동 도출합니다. 이슈 의존성과 PR 상태를 읽어 상태판을 출력하고:
[인증 리프레시] #10
1/3 ✅ #11 refresh 토큰 갱신
2/3 🔨 #12 세션 재사용 감지
3/3 ⛔ #13 만료 UI 처리 (2/3 대기)
- ✅ 완료 / 🔍 리뷰 대기 / 🔨 구현 가능 / 🔧 재설계 필요(
needs-respec) / ⛔ 블락 - 구현 차례면 그 자리에서 바로 구현을 시작하고, 리뷰 차례면 번호까지 채운
/review-pr명령을 알려줍니다. 이슈·PR 번호를 외울 필요가 없습니다. - 구현 가능 이슈가 여럿이면 git worktree 병렬 진행을 안내합니다 —
/spec의 병렬 안전 규칙 덕에 충돌이 없습니다. 무인 병렬 실행 대상은agent:auto라벨 이슈만입니다.
/spec → /implement-issue → /review-pr → 머지를 매번 세션을 열어 돌리는 대신, 루프 드라이버가 GitHub 상태를 읽고 각 걸음을 새 서브에이전트에 위임해 자동 반복합니다. 원본 원칙은 그대로 유지됩니다: 이슈 1개 = 세션 1개(걸음별 독립 서브에이전트), 리뷰는 구현과 다른 세션, 설계 승인과 risk:high 머지는 언제나 사람.
/issue-loop # 이어하기: GitHub 상태를 읽고 루프 시작/재개
/issue-loop "<기능 설명>" # 설계(분해안 승인은 사람)부터 시작해 루프까지
/issue-loop <상위 이슈 번호> # 특정 기능([Feature] 이슈)으로 범위 제한
/issue-loop --label <태그> # 그 태그가 붙은 이슈만 (ai-task와 AND)
/issue-loop --once # 한 걸음만 진행하고 종료
/issue-loop --status # 상태판 + 다음 계획만 출력 (실행 없음)
/issue-loop --max N # 걸음 수 안전상한 (기본: max(20, 이슈 수 × 4))
/issue-loop --unattended # 완전 무인 모드 (아래 참조)
/issue-loop --economy # 구현을 전부 sonnet으로 (리뷰·설계는 opus 유지)
/issue-loop --usage-guard N # 사용량 추정 N% 초과 시 걸음 경계에서 중단 (기본 90)
- 상태 수집 — 이슈·PR·라벨을 GitHub에서 다시 읽습니다 (GitHub이 상태 원본).
- 다음 행동 결정 — 우선순위: 리뷰 안 된 PR 리뷰 → 반려 PR 재작업 → 승인 PR 머지 게이트 → 착수 가능 이슈 구현. 착수 전 앵커 충돌 검사로 열린 PR과 파일이 겹치는 이슈는 보류합니다 (여러 기능 동시 진행 시에도 머지 충돌 방지).
- 서브에이전트 dispatch — 구현/리뷰/재작업을 각각 새 에이전트가 수행하고 한 줄 결과만 반환합니다. 상세 기록은 전부 GitHub(PR 본문·코멘트·리뷰)에 적재됩니다.
- 저널 기록 —
.claude/issue-loop/journal.md(자동으로 gitignore)에 걸음·체크포인트를 남깁니다.
| 기본 (감독) 모드 | --unattended (무인) 모드 |
|
|---|---|---|
| 대상 이슈 | 전부 (agent:assist는 착수 전 한 번 물음) |
agent:auto 라벨 이슈만 |
| 에이전트의 질문 | 사용자에게 전달 후 재개 | 해당 이슈 건너뛰고 에스컬레이션 기록 |
| 머지 | 결정은 사람, 실행은 루프 — 승인 PR이 생기면 물어보고 머지 | 강화 리뷰 통과 + CI green이면 자동 머지 |
risk:high PR |
사람 리뷰·머지 (루프는 보고만) | 동일 — 모드 무관 |
무인 모드의 강화 리뷰는 자동 머지의 품질 근거이므로 전 항목 의무입니다: ① 검증 명령 직접 재실행 ② 전체 테스트 스위트 실행 ③ 테스트 추가·갱신 확인 ④ 인터페이스 변경 시 문서 갱신 확인 ⑤ (수동) 완료 기준이 있으면 자동 머지 불가. 하나라도 미달이면 반려됩니다.
완전 무인으로 돌리는 순서 — 설계 분해안 승인만은 자동화하지 않으므로, 승인이 필요한 단계를 앞에 몰아두고 루프를 무인으로 돌립니다:
/spec "<기능 설명>" # ① 분해안 승인(사람) + 이슈 등록 — agent:auto 라벨 확인
/issue-loop --unattended # ② 이후 구현→리뷰→머지는 전부 무인
/issue-loop --unattended --economy --usage-guard 85 # 한도 절약 + 한도 근처 우아한 중단 조합
무인으로 돌려도 risk:high PR(사람 리뷰 필수)과 agent:assist 이슈(건너뜀)는 남습니다 — 종료 보고의 머지 대기열·에스컬레이션 목록으로 돌아와서 확인하세요.
| 조건 | 모델 |
|---|---|
size:S이고 risk:high 아님 |
sonnet |
size:M 또는 risk:high |
opus |
| 재작업 (반려 후) | opus — 한 번 실패한 작업은 승격 |
| 리뷰 · 설계 | opus 고정 — 어떤 경우에도 강등 안 함 |
--economy: 한도를 아끼고 싶은 날 구현을 전부 sonnet으로. 품질은 리뷰(opus)와 반려 2회 안전장치가 지킵니다.- opus 한도 소진 시: 구현은 sonnet으로 1회 폴백, 리뷰·설계는 폴백하지 않고 중단 — 품질 게이트를 낮추며 계속 도는 것보다 멈추는 게 낫습니다.
- 반려 2회 누적 이슈는 루프에서 제외하고 사람에게 에스컬레이션 (반려 무한 루프 방지). 횟수는 저널이 아니라 GitHub의
review:rejected라벨 부착 이력으로 셉니다 — 자기 PR에 반려 리뷰를 남길 수 없는 1인 개발에서도 정확히 동작합니다. --max걸음 상한 (기본max(20, 이슈 수 × 4)) — 정상 완주엔 안 걸리고 폭주만 막습니다.- 사용량 가드: ccusage가 있으면 매 걸음 전 5시간 블록 사용량을 추정해 임계(기본 90%) 초과 시 걸음 경계에서 우아하게 중단합니다. 도구가 없으면 조용히 건너뜁니다.
- 워킹트리에 에이전트가 만들지 않은 변경이 있으면 건드리지 않고 멈춥니다.
상태가 전부 GitHub(이슈·PR·라벨·브랜치)에 있으므로 /issue-loop 재실행이 곧 재개입니다. 사용량 한도로 끊겨도, 머신을 옮겨도(gh 인증만 있으면 CLI/웹 무관) 상태 수집부터 자연히 이어집니다. 저널은 반려 횟수·중단 지점 복원용 보조 기록입니다.
전체 규칙은 claude/skills/issue-loop/SKILL.md 참조.
- 이슈 1개 = 세션 1개. 이슈 3개면 구현 세션도 3개. (
/issue-loop는 이걸 서브에이전트로 자동 충족) - 리뷰는 반드시 새 세션에서. 구현한 세션은 자기 가정을 물려받아 자기 결함을 못 잡습니다.
- 모델은 신경 쓰지 마세요. 설계·리뷰는 커맨드가 상위 모델로 자동 전환하고, 구현은 세션 모델을 따릅니다.
이 템플릿이 브랜치 전략에 실제로 요구하는 것은 최소한입니다:
task/<이슈번호>-<슬러그> ──PR──▶ <기본 브랜치> (계약 대비 리뷰 후 머지, Closes #N)
- 이슈 1개 = 브랜치 1개 = PR 1개.
/implement-issue가 브랜치를 자동 생성하고 PR로 돌아옵니다. - PR의 base 브랜치는 템플릿이 정하지 않습니다. 커맨드는 리포의 기본 브랜치 기준으로 동작하므로, trunk-based(main 직행)든 git-flow(develop)든 release 브랜치든 조직의 전략 위에 그대로 얹힙니다.
- 머지 방식(squash/merge/rebase)도 조직 컨벤션을 따르면 됩니다. 이슈 1개 = PR 1개 구조라 squash와 궁합이 좋다는 것 정도만 참고하세요.
- CI는
/review-pr의 보완재입니다./review-pr은 "계약대로 만들었는가"를, CI는 "기계적으로 깨지지 않았는가"(테스트·타입체크·빌드)를 검증합니다 — 둘은 대체 관계가 아니므로 CI가 있다면 필수 체크로 함께 거세요. - 병렬 작업: 의존 없는 이슈끼리는 코드 앵커가 서로소이므로(
/spec의 병렬 안전 규칙) 어느 전략에서든 git worktree로 동시 진행이 안전합니다.
그 위의 선택은 팀 규모와 환경에 따라 다릅니다 — 참고용 일반론:
| 상황 | 일반적인 선택 |
|---|---|
| 1인·소규모, staging 없음 | trunk-based + 태그 릴리스 (git tag vX.Y.Z → 배포). staging 없는 develop은 테스트 장소가 아니라 머지 지연 장치가 되기 쉬움 |
| staging 환경 있음 | trunk-based + 환경 승격 — staging 자동 배포로 확인 후 태그로 production 승격 |
| 정기 릴리스·QA 조직 있음 | git-flow / release 브랜치 — 기본 브랜치를 develop으로 두면 템플릿은 수정 없이 그대로 동작 |
Q. 이슈 템플릿 파일만 넣으면 되나요?
아니요. 템플릿은 양식일 뿐이고, Claude가 그 양식대로 일하게 만드는 건 슬래시 커맨드입니다. install.sh가 둘 다 설치합니다.
Q. /issue-loop가 있는데 /next나 개별 커맨드는 왜 필요한가요?
루프는 개별 커맨드 위에 얹힌 자동화 레이어입니다. 특정 이슈 하나만 손보고 싶거나, 사람이 각 걸음을 지켜보고 싶거나, 루프가 에스컬레이션한 이슈를 수습할 때는 개별 커맨드를 씁니다. 루프가 중단돼도 개별 커맨드로 어디서든 이어갈 수 있는 것도 같은 이유입니다.
Q. 템플릿이 업데이트되면 어떻게 알 수 있나요? 자동 업데이트 워크플로우가 매주 확인해서 변경이 있을 때만 PR을 엽니다 (자동 머지 아님 — 리뷰 후 머지). 즉시 받고 싶으면 설치 명령을 다시 실행하세요.
Q. 커맨드 파일을 팀에 맞게 수정했는데 업데이트가 덮어쓰지 않나요?
안 덮어씁니다. 설치 시 기록한 체크섬(.claude/issue-template.lock)으로 수정 여부를 판별해, 수정된 파일은 최신본을 <파일>.new로 옆에 받아두고 경고만 합니다.
Q. 1인 개발인데요 — 자기 PR은 GitHub이 승인을 거부하지 않나요?
맞습니다, 그래서 승인/반려의 상태 원본을 GitHub 리뷰 상태가 아니라 라벨(review:approved/review:rejected)로 설계했습니다. 자기 PR이라 gh pr review --approve가 거부되면 판정 전문은 PR 코멘트로 남고, /issue-loop의 머지 게이트·반려 카운트는 전부 라벨(과 그 부착 이력)만 봅니다. 유일한 예외는 브랜치 보호 규칙으로 "승인 리뷰 1개 이상"을 강제한 리포입니다 — 이건 GitHub 정책상 1인 계정이 채울 수 없으므로, 루프가 시작 전에 감지해 경고하고 해당 PR 머지는 사람에게 넘깁니다 (보호 규칙을 완화하면 자동 머지도 가능).
Q. Feature보다 큰 묶음(Epic)이 필요하면요?
계층은 그대로 두고 이슈 하나만 손으로 얹으면 됩니다. [Epic] 제목의 이슈를 만들고 본문에 "추적용"이라 적은 뒤, /spec이 만든 [Feature] 이슈들을 sub-issue로 붙이세요 — GitHub sub-issue는 중첩되므로 Epic ⊃ Feature ⊃ Task 트리와 진행률이 그대로 보입니다. 커맨드는 수정할 필요 없습니다: /implement-issue·/issue-loop은 Task만 보고, "추적용" 문구 덕에 Epic이 구현 대상으로 잡히지도 않습니다. 여러 기능이 하나의 이니셔티브로 묶일 때만 만들고, 평소에는 Feature와 마일스톤으로 충분합니다.
Q. 왜 리뷰를 네이티브 코드 리뷰 대신 /review-pr로 하나요?
대체재가 아니라 보완재입니다. 네이티브 리뷰는 "좋은 코드인가"를 묻고, /review-pr은 "우리가 합의한 그 코드인가"를 묻습니다. 이슈 계약(Non-goals·앵커·완료 기준)은 네이티브 도구가 모르는 채점 기준이므로 둘 다 쓰는 게 정답입니다.
Q. 뭐가 좋아지나요?
| 문제 | 이 워크플로우의 해결 |
|---|---|
| 상상 설계 (없는 함수 참조) | 설계 전 파일:라인 근거 강제 — 검증 안 된 사실은 설계에 못 씀 |
| 겸사겸사 리팩토링으로 diff 폭발 | 이슈마다 Non-goals(하지 말 것) 필수 |
| "잘 되는 것 같아요" | 실행 가능한 검증 명령어 — AI가 직접 돌려 통과 확인 |
| 큰 작업 통째 위임 → 품질 급락 | 이슈 1개 = 세션 1개 크기로 강제 분해 |
| 이슈 파편화 | 상위 이슈 아래 sub-issue 트리 + 진행률 + 의존 순서 |
| 셀프 리뷰의 맹점 | 별도 세션 + 상위 모델이 계약 대비 리뷰 |
| 병렬 작업 시 머지 충돌 | 의존 없는 이슈는 코드 앵커 서로소 강제 — worktree 동시 진행 안전 |
| 반려 사유가 세션과 함께 증발 | 판정 전문을 PR 리뷰로 기록 — 재작업 세션이 읽고 고침 |
| 구현 중 설계 전제 깨짐이 묻힘 | 이슈 코멘트 + needs-respec 라벨로 GitHub에 적재 — /next가 표시 |
| UI가 필요한지 감으로 결정 → 구현 후 "이게 아닌데" | UI 판정 게이트 + HTML 시안 승인 — 코드 쓰기 전에 그림으로 합의, 승인 시안이 구현·리뷰의 계약 |
| 세션 열고 닫기 반복의 피로 | /issue-loop — 걸음별 서브에이전트로 자동 반복, 중단돼도 GitHub 상태로 재개 |
| 필드 | 필수 | 목적 |
|---|---|---|
| 목표 | ✅ | 구현 중 판단이 갈릴 때의 기준 |
| 하지 말 것 (Non-goals) | ✅ | scope creep 차단 — 제일 효과 큰 필드 |
| 코드 앵커 | ✅ | 파일:라인 단위 정확한 작업 위치 |
| 인터페이스 계약 | 시그니처/스키마를 코드로 | |
| 완료 기준 + 검증 명령어 | ✅ | AI가 스스로 실행해 통과 확인. 명령어로 못 재는 건 (수동) 표기 → 리뷰 때 사람 확인 |
| 엣지 케이스 | 설계 단계에서 내린 결정 | |
| 의존성 | 선행 이슈 번호, 설계문서·승인 시안 링크 (시안은 참조 전용) |
"이슈는 등록됐는데 프로젝트·마일스톤은 하나하나 수동 연동"하는 문제는 위 2단계 설정으로 사라집니다:
- 프로젝트: Auto-add 워크플로우(
label:ai-task)가 등록 즉시 자동 추가 — 커맨드 쪽 설정 불필요 - 보드 상태(Todo/In Progress/Done): Todo·Done은 GitHub 내장 워크플로우가 옮기고(2단계 설정), In Progress는 GitHub이 자동 감지할 신호가 없어
/implement-issue가 구현 시작 시 API로 직접 옮깁니다. gh 토큰에project스코프가 있을 때만 동작하고(gh auth refresh -s project), 없으면 보드만 안 움직일 뿐 구현·리뷰·머지는 그대로 진행됩니다 - 마일스톤:
/spec이 마감일 안 지난 마일스톤을 마감 임박 순으로 조회해 승인 단계에서 함께 확인 후--milestone으로 등록. 마일스톤이 없으면 묻지 않음 - 담당자:
/spec이 등록 시--assignee "@me"로 등록자 본인에게 자동 할당 (다른 담당자를 지정하면 그 사람으로) - 이슈 타입: 상위 이슈는
Feature, 작업 이슈는Task(버그 수정이면Bug)로 자동 지정. 웹 폼으로 등록해도Task타입이 붙음. 이슈 타입은 organization 리포 전용이라 개인 리포에서는 자동 생략
install.sh가 만들어주는 라벨 13종. 사람이 붙일 일은 없고 커맨드가 자동으로 붙입니다 — 라벨은 곧 필터 가능한 데이터가 됩니다. 원칙은 하나: 그 라벨로 필터링하는 소비자(커맨드·사람)가 있는 라벨만 만든다. 선행 이슈 완료 여부 같은 동적 상태는 라벨로 만들지 않습니다 — 시간이 지나면 거짓말이 되기 때문에 /next가 매번 실시간 계산합니다.
| 라벨 | 붙이는 주체 | 의미 · 용도 |
|---|---|---|
ai-task |
/spec |
AI 위임 작업 식별. Projects Auto-add의 필터 기준이라 이 라벨이 프로젝트 연동의 열쇠 |
feat / bug / refactor |
/spec |
작업 유형. 유형별 분포·비율 집계용 |
size:S / size:M |
/spec |
예상 diff 크기 (~100 / ~300라인). /issue-loop의 모델 라우팅 기준 |
size:L |
(붙이지 않음) | 300라인 초과 신호 — 이 라벨을 붙이는 대신 이슈를 더 분해하는 게 규칙 |
review:approved / review:rejected |
/review-pr |
리뷰 판정 기록. label:review:rejected 필터가 곧 반려율 지표 |
agent:auto / agent:assist |
/spec |
사람 개입 없이 끝까지 가능한가. 무인·병렬 실행 대상은 agent:auto만 — /next·/issue-loop가 이 기준으로 거른다 |
risk:high |
/spec |
인증·결제·마이그레이션 등 되돌리기 비싼 변경. 리뷰 강화 + 사람 리뷰·머지 필수 (루프도 건드리지 않음) |
needs-respec |
/implement-issue |
구현 중 설계 전제 깨짐. /next가 🔧 재설계 필요로 표시 — 계약 수정 후 라벨 제거하면 재착수 |
| 일 | 자동? | 담당 |
|---|---|---|
| 설계문서 작성·이슈 분해·등록 | 🤖 자동 | /spec (분해안 승인만 사람) |
| UI 판정·HTML 시안 생성 | 🤖 자동 | /spec (시안 승인 = 👤 사람 — 코드 전에 그림으로 합의) |
| 라벨·마일스톤·담당자·이슈 타입 부착 | 🤖 자동 | /spec (웹 폼 등록도 타입 Task 자동) |
| sub-issue 트리 연결·진행률 | 🤖 자동 | /spec → GitHub UI |
| 프로젝트 보드에 이슈 추가 | 🤖 자동 | Projects Auto-add 워크플로우 (label:ai-task) |
| 보드 상태 → In Progress | 🤖 자동 | /implement-issue가 구현 시작 시 API로 이동 (project 스코프 필요, 없으면 건너뜀) |
| 보드 상태 → Done | 🤖 자동 | Projects Item closed → Done, PR merged → Done 워크플로우 |
| 구현·검증·PR 생성 (라벨·마일스톤 승계 포함) | 🤖 자동 | /implement-issue |
| 반려 후 재작업 (반려 사유 읽고 기존 PR 업데이트) | 🤖 자동 | /implement-issue |
설계 전제 깨짐 기록 (needs-respec + 이슈 코멘트) |
🤖 자동 | /implement-issue |
| 리뷰 판정 + 판정 전문 PR 기록 + 판정 라벨 | 🤖 자동 | /review-pr (머지 결정만 사람) |
| 구현→리뷰→머지 반복 · 모델 라우팅 · 재개 | 🤖 자동 | /issue-loop (기본 모드는 머지 결정만 사람, 무인 모드는 강화 리뷰가 대신) |
| 템플릿 최신화 | 🤖 자동 | 주간 sync 워크플로우가 변경 시 PR (머지만 사람) |
마일스톤 생성, 분해안·UI 시안 승인, risk:high 리뷰·머지 |
👤 사람 | 의도적으로 남긴 판단 지점 |
사람에게 남는 건 판단(무엇을 만들지 승인, 코드 승인, 머지)뿐이고, 기록·연동·집계는 전부 자동입니다.
- 고정 모델 교체:
spec.md·review-pr.mdfrontmatter의model:값 수정 (기본 opus). 조직 허용 목록에 없는 값은 조용히 무시됨.implement-issue.md는 의도적으로 미지정 — 지정하면 상위 모델 세션이 강등되는 부작용 - 라벨·제목 접두어: 커맨드 파일의
gh issue create라인 수정 (상위 이슈[Feature], 작업 이슈[Task][<슬러그> <순번>/<전체>]). 순번 규칙을 바꾸려면spec.md4-2와next.md의 상태판 파싱을 함께 수정 - 이슈 크기 기준:
spec.md의 "파일 5개, 300라인 diff"를 팀에 맞게 조정 - 수정과 업데이트 공존: 수정한 파일은 업데이트가 덮어쓰지 않음 (
.new로 보존) - 자동 업데이트 끄기:
curl ... | ISSUE_TEMPLATE_NO_WORKFLOW=1 bash로 설치 (워크플로우 파일은 최초 1회만 설치되며 이후 팀 소유) - 특정 버전 고정 설치:
curl -fsSL .../install.sh | ISSUE_TEMPLATE_RAW=https://raw.githubusercontent.com/nlook-service/issue-template/<태그 또는 커밋> bash— 감사(audit)를 마친 시점의 커밋으로 고정 가능 - 조직 전체 적용: 조직
.github저장소에ISSUE_TEMPLATE/을 넣으면 전 리포에 이슈 폼 상속 - 다른 AI 도구: 커맨드 파일은 평문 마크다운이라 Cursor rules, Copilot instructions에도 이식 가능
이 프로젝트의 데이터 흐름과 권한은 의도적으로 단순합니다:
-
외부 전송 없음. 커맨드·스킬은 평문 마크다운 지시문이고, 실행되는 도구는 로컬
git과 본인이 인증한ghCLI뿐입니다. 텔레메트리·수집 코드가 없습니다. (유일한 예외는 명시적 opt-in인 Langfuse 통합 — 켜면 커맨드 인자가 제3자 SaaS로 전송되므로 해당 README의 경고를 먼저 읽으세요.) -
설치 전 검토:
curl | bash가 꺼려지면 받아서 읽고 실행하세요:curl -fsSL https://raw.githubusercontent.com/nlook-service/issue-template/main/install.sh -o install.sh less install.sh # 검토 bash install.sh설치되는 것은 마크다운·YAML 템플릿뿐이며, 전부 임시 디렉토리에 먼저 받은 뒤 반영하므로 다운로드 실패 시 아무것도 건드리지 않습니다. 특정 커밋으로 고정하려면
ISSUE_TEMPLATE_RAW를 사용하세요 (위 커스터마이징 참조). -
자동 업데이트 워크플로우: 액션을 커밋 SHA로 핀 고정했고, 권한은
contents: write+pull-requests: write로 한정되며, PR만 열고 자동 머지는 하지 않습니다. upstream을 신뢰하지 않으려면ISSUE_TEMPLATE_NO_WORKFLOW=1로 설치하세요. -
시각 렌더 비교는 선택 기능입니다.
/review-pr의 승인 시안 대비 검증은 로컬에 화면 캡처 도구가 이미 설치·인증돼 있을 때만 렌더 수준으로 동작하며, 이 템플릿은 어떤 도구도 설치하지 않습니다 — 도구가 없으면 정적 대조나 사람 확인 항목으로 강등될 뿐 워크플로우는 그대로 진행됩니다. -
무인 자동 머지의 가드레일:
--unattended의 자동 머지는 강화 리뷰 통과 +agent:auto+risk:high아님 + CI green을 전부 요구합니다. 여기에 브랜치 보호 규칙(required checks) 을 함께 켜는 것을 권장합니다 — 루프가 어떤 이유로 오판해도 GitHub이 최종 방어선이 됩니다. -
취약점 제보: 보안 문제를 발견하면 공개 이슈 대신 GitHub의 Private vulnerability reporting(Security 탭)으로 제보해 주세요.
issue-template/
├── install.sh # 설치 겸 업데이트 스크립트 (재실행 = 업데이트)
├── VERSION # 배포 버전 (배포 파일 수정 시 함께 올림)
├── design-doc-template.md # 설계문서 양식 (기능 1개당 1개)
├── github/
│ ├── ISSUE_TEMPLATE/
│ │ └── ai-task.yml # GitHub 이슈 폼 (웹에서 수동 등록용 안전망)
│ └── workflows/
│ └── issue-template-sync.yml # 주 1회 자동 업데이트 PR (최초 1회만 설치)
├── claude/
│ ├── commands/
│ │ ├── spec.md # [설계] 요구사항 → 설계문서 → 이슈 등록
│ │ ├── implement-issue.md # [구현] 이슈 번호 → 구현 → 검증 → PR
│ │ ├── review-pr.md # [리뷰] PR → 설계문서·이슈 계약 대비 판정
│ │ └── next.md # [네비게이터] 상태판 + 다음 할 일 자동 판단
│ └── skills/
│ └── issue-loop/
│ └── SKILL.md # [루프] 구현→리뷰→머지를 서브에이전트로 자동 반복
└── integrations/
└── langfuse/ # (선택) 커맨드 실행 trace 기록 — opt-in
- Langfuse — 커맨드 실행을 trace로 기록 (opt-in). 켜면 커맨드 인자가 제3자 SaaS로 전송되니 설치 전 해당 README의 경고를 읽으세요.
- design-from-code —
/spec의 UI 시안 제작을 위임할 수 있는 시안 스킬 (opt-in). 실제 컴포넌트 소스를 읽어 현재 화면을 충실히 재현한 위에 TO-BE를 그립니다. 산출물 계약(.design/<슬러그>/vN.html+meta.json)이 같아 설치돼 있으면/spec이 위임하고, 없어도/spec자체 규칙으로 워크플로우는 완결됩니다.
- Claude Code — 슬래시 커맨드 실행
- gh CLI — 이슈/PR 생성 (
gh auth login) - (선택) ccusage —
/issue-loop의 사용량 가드
이슈·PR 환영합니다. 배포 파일(install.sh의 FILES 목록에 있는 파일)을 수정할 때는 VERSION을 함께 올려주세요 — 소비 저장소의 주간 sync가 이 버전으로 업데이트 여부를 판단합니다.