菜单
이슈 단위로 스펙, 실행 계획, 수행 요약을 관리하는 워크플로우입니다. 이슈 작업, issue, 이슈 시작, 이슈 완료, 워크플로우 복구(--workflow-only), 이어하기, resume, 작업 재개(--resume), 이슈 정리, 작업공간 정리, 정리(--clear), audit 리포트 검토·피드백 후 승인 보정(--response) 시 사용합니다.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
현재 스킬 repo의 skill을 선택하여 Claude Code·Agents·Antigravity·Codex·Junie 경로(~/.claude/skills/ 등 5개)에 설치합니다. --all(전체 경로)·--clear(클린 재설치)·--self(self-install 부트스트랩) 옵션을 지원합니다. skill 설치, install skills, 스킬 배포, 스킬 재설치, self-install 시 사용합니다.
이슈 스펙 대비 구현 완료 여부를 독립 감사인 관점에서 검증합니다. 이슈 감사, issue audit, 구현 검증, 크로스체크 시 사용합니다.
대화 중 중요한 맥락(배경, 결정, 미결 사항, 다음 액션)을 `.ai/99_workspace/notes/` 아래 마크다운 파일로 저장합니다. 맥락 저장, context save, 임시 저장, 논의 스냅샷, 작업 메모 시 사용합니다.
PR 제목과 메시지를 정책(Conventional Commits 제목 + 이슈별 비즈니스/테크 관점)에 맞게 작성합니다. PR 작성, PR 메시지·설명 작성, pull request, 풀리퀘스트, PR 올리기 전 정리, 리뷰어용 설명 정리 시 사용합니다. 실제 PR 생성·제출이 아니라 메시지 텍스트 작성용입니다.
멀티 repo 워크스페이스 루트의 로비 `.ai/AI-CONTEXT.md`를 생성하거나 진단·재구성합니다. `ai-workspace`의 자매 스킬로, building 안내판(=lobby) 역할의 lean 라우터를 만듭니다. 로비, lobby, AI-CONTEXT.md, building 인덱스, 워크스페이스 안내판 작업 시 사용합니다.
프로젝트를 분석하여 README.md를 생성하거나 최신 상태로 재작성합니다. README.md가 없으면 템플릿에 따라 새로 작성하고, 이미 있으면 현재 프로젝트 구조에 맞게 재작성합니다. README 작성, README 갱신, readme sync, 리드미 최신화 시 사용합니다.
基于 SOC 职业分类
| name | issue-work |
| description | 이슈 단위로 스펙, 실행 계획, 수행 요약을 관리하는 워크플로우입니다. 이슈 작업, issue, 이슈 시작, 이슈 완료, 워크플로우 복구(--workflow-only), 이어하기, resume, 작업 재개(--resume), 이슈 정리, 작업공간 정리, 정리(--clear), audit 리포트 검토·피드백 후 승인 보정(--response) 시 사용합니다. |
이슈 단위로 스펙·실행 계획·수행 요약 파일을 생성하고 관리하는 워크플로우입니다.
.ai/ 구조가 이미 존재하면 해당 구조를 따릅니다.
구조가 없으면 필요한 디렉토리를 직접 생성합니다.issue-audit를 실행하고, 그 결과를 issue-<번호>-summary.md의 모델 기록·Task별 결과에 반영합니다. 구현 AI는 이 Task를 자동 실행·종료하지 않습니다..ai/10_rules/context-loading.md — 있으면 따르며, 이미 적재되어 있으면 재로딩하지 않습니다..ai/30_contract/index.md, .ai/40_domain/index.md, .ai/50_adr/index.md — 새 이슈 시작 시 훑어 spec의 "연관 문서" 후보 제안.ai/90_issues/active/ 하위 전체.ai/90_issues/
├── active/ ← 현재 진행 중인 이슈 디렉토리 (항상 읽음)
│ ├── issue-workflow.md ← 작업 절차 가이드 (컨텍스트 초기화 후에도 절차 유지)
│ └── issue-<번호>/
│ ├── issue-<번호>-spec.md ← 목표, 범위, 완료의 정의, 연관 문서
│ ├── issue-<번호>-plan.md ← 실행 Task 목록 + 완료 체크박스
│ └── issue-<번호>-summary.md ← 다음 작업, Task별 수행 결과
└── archive/ ← 완료 또는 종료된 이슈 디렉토리 (명시적 요청 시에만 읽음)
└── issue-<번호>/ ← 이슈 디렉토리 단위로 active에서 이관
AI 컨텍스트 적재 규칙:
active/ 하위 파일은 작업 시작 시 항상 읽는다.archive/ 하위 파일은 사용자가 명시적으로 언급하지 않는 한 읽지 않는다.active/ 안에 있는 기존 이슈 디렉토리를 모두 archive/로 이동한다.active/issue-workflow.md가 없으면 templates/issue-workflow-template.md를 참조하여 생성한다. 이미 있으면 템플릿과 내용을 비교해, 다르면 최신 템플릿으로 갱신(덮어쓰기)하고 동일하면 그대로 둔다. (템플릿이 SSoT이며 이 파일은 그 사본이므로, 템플릿 개선이 자동 반영된다.)active/issue-<번호>/ 디렉토리를 생성하고 이 skill 디렉토리의 templates/를 참조하여 3개 파일을 생성한다.
.ai/30_contract/index.md, .ai/40_domain/index.md, .ai/50_adr/index.md를 훑어 spec의 "연관 문서" 섹션 후보를 제안한다.| 파일명 | 참조 템플릿 | 역할 | 생명주기 |
|---|---|---|---|
active/issue-workflow.md | issue-workflow-template.md | 작업 절차 가이드 | 고정 — 최초 1회 생성, 이슈와 무관하게 유지 |
issue-<번호>-spec.md | issue-spec-template.md | 목표, 범위, DoD, 연관 문서 | 안정 — 작성 후 거의 변경 없음 |
issue-<번호>-plan.md | issue-plan-template.md | 실행 Task 목록 + 체크박스 | 가변 — Task 완료 시 체크, 실행 결과에 따라 Task 추가·수정·삭제 가능 |
issue-<번호>-summary.md | issue-summary-template.md | 다음 작업, Task별 수행 결과 | 누적 — Task 완료 시마다 갱신 |
issue-<번호>-plan.md의 해당 Task 체크박스를 체크한다.issue-<번호>-summary.md의 수행 결과를 갱신하고 다음 작업을 업데이트한다.[D]/[QD]/[ND])과 기록 형식은 spec·plan 템플릿을 따른다.issue-audit를 수행하는 교차모델 검증으로 고정한다. 이 Task는 사용자가 직접 수동 수행하며 구현 AI는 자동 실행·종료하지 않는다. 사용자가 audit 결과를 summary 모델 칸("벤더, 모델명" 형식)에 반영·기록한다(상세는 plan 템플릿의 고정 블록, 연계는 ## 관련 skill의 issue-audit 참조)..ai/99_workspace/issue-<번호>-audit-report.md)를 받으면 --response 옵션으로 검토한다 — 발견사항에 피드백 먼저, 항목별 승인 후에만 보정하며, 구현 AI가 리포트를 받자마자 자동 보정하지 않는다(상세는 ## 옵션의 --response).issue-<번호>-plan.md의 모든 Task 체크박스가 체크되었는지 확인한다.
issue-<번호>-summary.md 상단의 다음 작업을 ✅ 모든 작업이 완료되었습니다.로 업데이트한다.issue-<번호>/ 디렉토리를 active/에서 archive/로 디렉토리 단위로 이동한다.
이 이동은 PR 머지 전, 작업 브랜치에서 수행해 같은 PR에 포함한다 (머지 후 실행하면 main 직접 푸시가 된다).--clear 6단계와 동일).위 절차에 더해
99_workspace정리와 이슈 댓글 요약 등록까지 한 번에 수행하려면--clear옵션을 사용한다.
--workflow-onlyactive/issue-workflow.md만 생성한다. 이슈 파일은 생성하지 않는다.
active/issue-workflow.md를 내용 비교 없이 무조건 템플릿으로 덮어쓴다(강제 복구). 내용이 다를 때만 갱신하는 "새 이슈 시작 시" 흐름과 달리, 손상된 파일까지 강제로 되살린다.--resume중단된 이슈 작업의 컨텍스트를 복구하고 사용자에게 진행 여부를 확인한다.
.ai/90_issues/active/ 하위의 모든 파일을 읽는다 (디렉토리 포함 재귀 탐색)..ai/99_workspace/ 하위의 모든 파일을 읽는다 (이슈 작업 중 생성한 임시 파일 포함).--response교차모델 issue-audit이 만든 감사 리포트를 검토하고, 피드백 먼저 → 항목별 승인 → 승인분만 보정하는 게이트를 절차로 고정한다.
.ai/99_workspace/issue-<번호>-audit-report.md)를 받았을 때, 구현 AI가 리포트를 받자마자 자동 보정으로 넘어가지 않도록 "피드백 먼저, 실행은 승인 후"를 표준화한다. 자연어 지시로만 유지되던 흐름을 옵션으로 고정해 신규 세션·다른 모델에서도 재현되게 한다.issue-audit 실행)과 audit 리포트 검토·피드백·보정(= 이 옵션)을 구분한다. 이 옵션은 audit을 실행하지 않으며, 승인 없이 자동 보정하지 않는다.active/ 이슈 번호로 .ai/99_workspace/issue-<번호>-audit-report.md를 자동 탐색한다. 리포트가 여러 개면 목록을 제시해 선택받는다. 리포트가 없으면 그 사실을 알리고 중단한다.issue-<번호>-summary.md에 반영한다.--clear진행 중인 이슈를 마무리하고 작업공간을 비워 다음 이슈를 준비한다.
용도: 이슈 작업이 끝났을 때(완료 또는 중단·종료) 이슈 디렉토리 이관, 임시 파일 정리, 이슈 댓글 요약 등록을 한 번에 수행한다.
시점: 구현·리뷰가 끝나 PR 머지를 올리기 직전에 실행한다. archive 이관(git 파일 이동)을 머지 전 작업 브랜치에 포함시키기 위함이며, 머지 후 실행하면 이관이 main 직접 푸시가 되어 혼선이 생긴다.
동작: 이슈 디렉토리는 삭제가 아니라 archive/로 이관하며 비운다.
완료 확인: issue-<번호>-plan.md의 Task 체크박스를 확인한다.
미완료 Task가 있으면 목록을 보여주고 계속 진행할지 질의한다 (중단·종료 케이스).
summary 갱신: issue-<번호>-summary.md 상단의 다음 작업을 갱신한다.
완료 시 ✅ 모든 작업이 완료되었습니다., 중단·종료 시 종료 사유를 한 줄로 기재한다.
이슈 댓글 질의: summary의 Task별 수행 결과를 기반으로 작업내용 요약을 작성해 보여주고,
GitHub 이슈에 댓글로 등록할지 질의한다. 승인 시에만 등록한다.
대상 이슈 번호는 디렉토리명 issue-<번호>에서 앞자리 0을 제거해 사용한다 (예: issue-0015 → #15).
거절하거나 GitHub 연동 수단(gh CLI 등)이 없으면 건너뛰고 다음 단계를 진행한다.
이 댓글 등록은 git 변경이 아니므로 4단계 archive 이관과 타이밍이 분리되어 머지 전·후 어느 시점이든 가능하다.
archive 이관: issue-<번호>/ 디렉토리를 active/에서 archive/로 디렉토리 단위로 이동한다.
이 이동은 PR 머지 전, 작업 브랜치에서 수행해 같은 PR에 포함한다 (머지 후 실행하면 main 직접 푸시가 된다).
99_workspace 정리: .ai/99_workspace/ 하위 파일 목록을 재귀로 보여주고
(.gitkeep은 항상 보존, notes/는 context-save 산출물이므로 기본 보존 — 사용자가 요청할 때만 정리 대상에 포함),
보존할 파일은 archive/issue-<번호>/로 이동을 제안한다. 나머지는 삭제 확인 후 삭제한다.
경로 참조 갱신·검증: 4·5단계로 이동한 모든 파일(표준 3종 외 audit 리포트·하위 디렉토리·임의 md 포함)의 본문에서 이관으로 무효가 되는 경로 참조를 아래 규칙으로 재작성하고, 검증 스니펫으로 잔존 참조 0건을 확인한다.
./<파일명> 상대 링크로 재작성한다 (디렉토리 단위 이동에 안전).active/issue-<번호>/…, 99_workspace/…) 참조는 이관 후 위치 기준으로 재작성한다.../ 상대 링크는 이동 후 깊이 기준으로 재계산한다 (99_workspace/는 .ai 하위 1단, archive/issue-<번호>/는 3단).<옛 경로>, --clear로 이관).99_workspace/ 참조를 남기지 않는다 (99_workspace는 언제든 비워질 수 있음) —
내용이 중요하면 파일 자체를 archive로 이관해 ./ 참조로, 이력 서술이면 병기 문구로 전환한다.갱신 후 아래 스니펫 결과가 0건이면 통과한다. 1건 이상이면 AI가 건별로 판정한다 — 갱신 누락(진탐)은 위 규칙으로 보정하고, 옵션 동작을 설명하는 일반 서술 등 정당한 표기(오탐)는 유지한다.
grep -rnE '90_issues/active/|active/issue-[0-9]+|99_workspace/[A-Za-z0-9_.-]' .ai/90_issues/archive/issue-<번호>/ \
| grep -v 'active/issue-workflow\.md' \
| grep -v '작성 시점 경로는'
제외 2건의 근거 — active/issue-workflow.md는 이동하지 않는 상주 파일이라 참조가 항상 유효하고,
"작성 시점 경로는"은 표준 병기 문구 안의 옛 경로(의도된 이력 표기)다.
active/에 이슈 디렉토리가 여러 개면 1~4단계를 이슈별로 반복한 뒤 5단계를 1회 수행하고, 6단계는 이관한 이슈 디렉토리별로 수행한다.
## 이슈 완료 시절차는 이 옵션의 1·2·4·6단계에 포함된다.