issue-work

name	issue-work
description	이슈 단위로 스펙, 실행 계획, 수행 요약을 관리하는 워크플로우입니다. 이슈 작업, issue, 이슈 시작, 이슈 완료, 워크플로우 복구(--workflow-only), 이어하기, resume, 작업 재개(--resume), 이슈 정리, 작업공간 정리, 정리(--clear), audit 리포트 검토·피드백 후 승인 보정(--response) 시 사용합니다.

개요

이슈 단위로 스펙·실행 계획·수행 요약 파일을 생성하고 관리하는 워크플로우입니다.

관련 skill

• ai-workspace (권장): .ai/ 구조가 이미 존재하면 해당 구조를 따릅니다. 구조가 없으면 필요한 디렉토리를 직접 생성합니다.
• issue-audit (권장): 계획의 마지막 고정 Task(교차모델 검증)에서 사용합니다. 구현 모델과 다른 벤더 모델(Non-Anthropic 포함)로 사용자가 직접 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/ 하위 파일은 사용자가 명시적으로 언급하지 않는 한 읽지 않는다.

---

새 이슈 시작 시

1. active/ 안에 있는 기존 이슈 디렉토리를 모두 archive/로 이동한다.
2. active/issue-workflow.md가 없으면 templates/issue-workflow-template.md를 참조하여 생성한다. 이미 있으면 템플릿과 내용을 비교해, 다르면 최신 템플릿으로 갱신(덮어쓰기)하고 동일하면 그대로 둔다. (템플릿이 SSoT이며 이 파일은 그 사본이므로, 템플릿 개선이 자동 반영된다.)
3. 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 완료 시마다 갱신

---

작업 진행 중

• Task 완료 시 issue-<번호>-plan.md의 해당 Task 체크박스를 체크한다.
• Task 완료 시 issue-<번호>-summary.md의 수행 결과를 갱신하고 다음 작업을 업데이트한다.
• 완료 기준은 가능한 한 결정적 검증 단계(명령·테스트·스크립트)로 내린다 — 검증 레벨([D]/[QD]/[ND])과 기록 형식은 spec·plan 템플릿을 따른다.
• 계획의 마지막 Task는 구현 모델과 다른 벤더 모델(Non-Anthropic 포함)로 issue-audit를 수행하는 교차모델 검증으로 고정한다. 이 Task는 사용자가 직접 수동 수행하며 구현 AI는 자동 실행·종료하지 않는다. 사용자가 audit 결과를 summary 모델 칸("벤더, 모델명" 형식)에 반영·기록한다(상세는 plan 템플릿의 고정 블록, 연계는 ## 관련 skill의 issue-audit 참조).
• audit 리포트(.ai/99_workspace/issue-<번호>-audit-report.md)를 받으면 --response 옵션으로 검토한다 — 발견사항에 피드백 먼저, 항목별 승인 후에만 보정하며, 구현 AI가 리포트를 받자마자 자동 보정하지 않는다(상세는 ## 옵션의 --response).

---

이슈 완료 시

1. issue-<번호>-plan.md의 모든 Task 체크박스가 체크되었는지 확인한다.
   • 단, Task N(교차모델 audit)은 사용자가 직접 수행한 audit 결과와 audit 모델("벤더, 모델명")이 summary에 기록된 경우에만 완료로 간주한다. 구현 AI는 이 Task를 대신 완료 처리하지 않는다.
2. issue-<번호>-summary.md 상단의 다음 작업을 ✅ 모든 작업이 완료되었습니다.로 업데이트한다.
3. issue-<번호>/ 디렉토리를 active/에서 archive/로 디렉토리 단위로 이동한다. 이 이동은 PR 머지 전, 작업 브랜치에서 수행해 같은 PR에 포함한다 (머지 후 실행하면 main 직접 푸시가 된다).
4. 이동한 파일 본문의 경로 참조 갱신을 수행하고 잔존 참조 0건을 확인한다 (갱신 규칙·검증 스니펫은 --clear 6단계와 동일).

위 절차에 더해 99_workspace 정리와 이슈 댓글 요약 등록까지 한 번에 수행하려면 --clear 옵션을 사용한다.

---

옵션

--workflow-only

active/issue-workflow.md만 생성한다. 이슈 파일은 생성하지 않는다.

• 용도: 컨텍스트 초기화 후, 또는 가이드 파일이 유실·손상됐을 때 이슈 작업과 무관하게 작업 절차만 복구하고 싶을 때 사용한다.
• 동작: active/issue-workflow.md를 내용 비교 없이 무조건 템플릿으로 덮어쓴다(강제 복구). 내용이 다를 때만 갱신하는 "새 이슈 시작 시" 흐름과 달리, 손상된 파일까지 강제로 되살린다.

--resume

중단된 이슈 작업의 컨텍스트를 복구하고 사용자에게 진행 여부를 확인한다.

• 용도: 세션 종료, 컨텍스트 초기화 등으로 작업이 중단된 후 재개할 때 사용한다.
• 동작:
  1. .ai/90_issues/active/ 하위의 모든 파일을 읽는다 (디렉토리 포함 재귀 탐색).
  2. .ai/99_workspace/ 하위의 모든 파일을 읽는다 (이슈 작업 중 생성한 임시 파일 포함).
  3. 읽은 내용을 기반으로 현재 진행 상황을 사용자에게 요약 보고한다.
  4. 다음 작업을 이어서 진행할지 사용자에게 확인한 후, 승인 시에만 작업을 진행한다.

--response

교차모델 issue-audit이 만든 감사 리포트를 검토하고, 피드백 먼저 → 항목별 승인 → 승인분만 보정하는 게이트를 절차로 고정한다.

• 용도: Task N 교차모델 audit 리포트(.ai/99_workspace/issue-<번호>-audit-report.md)를 받았을 때, 구현 AI가 리포트를 받자마자 자동 보정으로 넘어가지 않도록 "피드백 먼저, 실행은 승인 후"를 표준화한다. 자연어 지시로만 유지되던 흐름을 옵션으로 고정해 신규 세션·다른 모델에서도 재현되게 한다.
• 경계: audit 수행(= 사용자가 타벤더 모델로 issue-audit 실행)과 audit 리포트 검토·피드백·보정(= 이 옵션)을 구분한다. 이 옵션은 audit을 실행하지 않으며, 승인 없이 자동 보정하지 않는다.
• 동작:
  1. 리포트 확보: 인자가 있으면 그 경로를 읽고, 생략하면 active/ 이슈 번호로 .ai/99_workspace/issue-<번호>-audit-report.md를 자동 탐색한다. 리포트가 여러 개면 목록을 제시해 선택받는다. 리포트가 없으면 그 사실을 알리고 중단한다.
  2. 피드백만 제시: 발견사항별로 동의 / 부분동의 / 반론, 위험도 재평가, 보정 시 영향 파일 목록을 제시한다. 이 단계에서는 파일을 수정하지 않는다.
  3. 처리 방향 표: 보정 대상과 처리 방향(반영 / 이관 / 보류)을 표로 정리해 보여준다.
  4. 항목별 승인 질의: 사용자에게 항목 단위로 실행 여부를 확인받는다.
  5. 승인분만 보정: 승인된 항목만 보정을 진행하고, 미승인 항목은 보류하거나 별도 이슈로 이관한다. 보정 결과는 issue-<번호>-summary.md에 반영한다.

--clear

진행 중인 이슈를 마무리하고 작업공간을 비워 다음 이슈를 준비한다.

• 용도: 이슈 작업이 끝났을 때(완료 또는 중단·종료) 이슈 디렉토리 이관, 임시 파일 정리, 이슈 댓글 요약 등록을 한 번에 수행한다.

• 시점: 구현·리뷰가 끝나 PR 머지를 올리기 직전에 실행한다. archive 이관(git 파일 이동)을 머지 전 작업 브랜치에 포함시키기 위함이며, 머지 후 실행하면 이관이 main 직접 푸시가 되어 혼선이 생긴다.

• 동작: 이슈 디렉토리는 삭제가 아니라 archive/로 이관하며 비운다.

  1. 완료 확인: issue-<번호>-plan.md의 Task 체크박스를 확인한다. 미완료 Task가 있으면 목록을 보여주고 계속 진행할지 질의한다 (중단·종료 케이스).

  2. summary 갱신: issue-<번호>-summary.md 상단의 다음 작업을 갱신한다. 완료 시 ✅ 모든 작업이 완료되었습니다., 중단·종료 시 종료 사유를 한 줄로 기재한다.

  3. 이슈 댓글 질의: summary의 Task별 수행 결과를 기반으로 작업내용 요약을 작성해 보여주고, GitHub 이슈에 댓글로 등록할지 질의한다. 승인 시에만 등록한다. 대상 이슈 번호는 디렉토리명 issue-<번호>에서 앞자리 0을 제거해 사용한다 (예: issue-0015 → #15). 거절하거나 GitHub 연동 수단(gh CLI 등)이 없으면 건너뛰고 다음 단계를 진행한다. 이 댓글 등록은 git 변경이 아니므로 4단계 archive 이관과 타이밍이 분리되어 머지 전·후 어느 시점이든 가능하다.

  4. archive 이관: issue-<번호>/ 디렉토리를 active/에서 archive/로 디렉토리 단위로 이동한다. 이 이동은 PR 머지 전, 작업 브랜치에서 수행해 같은 PR에 포함한다 (머지 후 실행하면 main 직접 푸시가 된다).

  5. 99_workspace 정리: .ai/99_workspace/ 하위 파일 목록을 재귀로 보여주고 (.gitkeep은 항상 보존, notes/는 context-save 산출물이므로 기본 보존 — 사용자가 요청할 때만 정리 대상에 포함), 보존할 파일은 archive/issue-<번호>/로 이동을 제안한다. 나머지는 삭제 확인 후 삭제한다.

  6. 경로 참조 갱신·검증: 4·5단계로 이동한 모든 파일(표준 3종 외 audit 리포트·하위 디렉토리·임의 md 포함)의 본문에서 이관으로 무효가 되는 경로 참조를 아래 규칙으로 재작성하고, 검증 스니펫으로 잔존 참조 0건을 확인한다.

     • 함께 이동한 파일 간 참조는 ./<파일명> 상대 링크로 재작성한다 (디렉토리 단위 이동에 안전).
     • 이관으로 무효가 되는 경로(active/issue-<번호>/…, 99_workspace/…) 참조는 이관 후 위치 기준으로 재작성한다.
     • ../ 상대 링크는 이동 후 깊이 기준으로 재계산한다 (99_workspace/는 .ai 하위 1단, archive/issue-<번호>/는 3단).
     • 작성 시점 맥락이 중요한 참조는 새 경로 뒤에 표준 병기 문구를 붙인다: (작성 시점 경로는 <옛 경로>, --clear로 이관).
     • archive 파일 본문에 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단계에 포함된다.