issue-work

개요

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

관련 skill

• ai-workspace (권장): .ai/ 구조가 이미 존재하면 해당 구조를 따릅니다. 구조가 없으면 필요한 디렉토리를 직접 생성합니다.
• issue-audit (권장): 계획의 마지막 고정 Task(교차모델 검증)에서 사용합니다. 구현 모델과 다른 벤더 모델로 사용자가 직접 issue-audit를 실행하고, 그 결과를 issue-<번호>-summary.md의 모델 기록 표 최종 audit 모델 행(모델·effort)과 Task별 수행 결과(audit 발견 건수)에 반영합니다. 구현 AI는 이 Task를 자동 실행·종료하지 않습니다. 계획 종료 게이트 뒤의 계획 감사(issue-audit --plan)에도 같은 원칙을 적용합니다. 이슈마다 수행 여부를 선택하고("새 이슈 시작 시" 5단계), 수행하면 계획 모델과 다른 벤더 모델로 사용자가 직접 실행하며, 결과는 모델 기록 표 계획 audit 모델 행(모델·effort)과 계획 감사 줄에 반영합니다.

참조 문서

• 공통 규칙: .ai/10_rules/context-loading.md — 있으면 따르며, 이미 적재되어 있으면 재로딩하지 않습니다.
• 스킬 고유 추가 참조:
  • .ai/30_contract/index.md, .ai/40_domain/index.md, .ai/50_adr/index.md — 새 이슈 시작 시 훑어 spec의 "연관 문서" 후보 제안
  • .ai/70_ledger/index.md — 새 이슈 시작 시 훑어 "함께 해소 후보" 제안, 이슈 완료 시 원장 해소 기재·보류 항목 등재 (index 먼저 → 관련 항목 파일만 선택적으로)
  • .ai/90_issues/active/ 하위 전체
  • .ai/10_rules/writing-principles.md·.ai/10_rules/writing-principles-local.md — 있으면 산출물 작성 원칙으로 참조 (충돌 시 local 우선; 없으면 본문의 "산출물 접기 기준"이 기본값)
  • .ai/10_rules/testing-principles.md·.ai/10_rules/testing-principles-local.md — 있으면 테스트 실행 원칙으로 참조해 plan 작성 시 테스트 층·러너·실행 셸을 고른다 (우선순위는 local > testing-principles.md > 이 skill의 템플릿·절차; 없으면 현재 템플릿·절차 그대로)

---

디렉토리 구조

.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가 없으면 이 skill 디렉토리의 templates/issue-workflow-template.md를 참조하여 생성한다. 이미 있으면 템플릿과 내용을 비교해, 다르면 최신 템플릿으로 갱신(덮어쓰기)하고 동일하면 그대로 둔다. (템플릿이 SSoT이며 이 파일은 그 사본이므로, 템플릿 개선이 자동 반영된다.)
3. active/issue-<번호>/ 디렉토리를 생성하고 이 skill 디렉토리의 templates/를 참조하여 3개 파일을 아래 두 단계에 나눠 생성한다. 3-1에서는 spec만 만들고, plan·summary 파일은 3-2에서 만든다. spec은 요구사항 승인 게이트를 사이에 두고 두 번에 나눠 쓴다.
   • 3-1. 승인 전 (요구사항까지): spec 템플릿의 목표·요구사항(포함·제외)·연관 문서 후보까지 쓴다. 연관 문서 후보는 .ai/30_contract/index.md, .ai/40_domain/index.md, .ai/50_adr/index.md를 훑어 제안한다. 쓴 뒤 사용자에게 승인을 요청한다.
     • 승인 요청은 spec 파일 경로와 목표 한 줄·포함 목록·제외 목록만 대화에 제시하고 spec 전문을 대화에 출력하지 않는다 (--clear 3단계 댓글 승인과 같은 방식). 승인 대상은 파일이고, 같은 텍스트를 대화에 다시 만들면 응답만 늦어진다.
     • GitHub 이슈 본문에 근거가 없는 요구사항(작성 AI가 대화·추론으로 더한 항목)은 목록에서 따로 표시하고, 추가로 확정할지 제외할지 질의한다. 표시 없이 섞이면 사용자가 요청하지 않은 범위를 그대로 승인하게 된다.
     • 함께 해소 후보: 연관 문서 후보를 제안할 때 .ai/70_ledger/index.md도 훑어, 이슈 범위와 관련된 active/ 항목을 함께 해소 후보로 제시한다. 후보도 이슈 본문 근거 없는 요구사항처럼 목록에서 따로 표시하고 포함 여부를 질의한다. 포함하면 요구사항(R)에 넣고 R 문장 끝에 (함께 해소: K-<번호>)를 병기하며, 포함하지 않은 후보는 spec 어디에도 기록하지 않는다. 원장 index가 없으면 건너뛴다. 이 단계에서는 원장 상태를 바꾸지 않으며, 포함한 항목의 종결은 ## 이슈 완료 시 3단계의 원장 해소 기재가 맡는다.
     • 수정 요청을 받으면 spec을 갱신하고 같은 형식으로 다시 요청한다. 승인 전에는 완료의 정의·plan·summary를 쓰지 않는다.
   • 3-2. 승인 후: 승인받은 요구사항을 기준으로 spec의 완료의 정의·전제를 채우고 plan·summary를 쓴다. summary에는 모델 기록 표의 계획 모델 행의 모델과 effort를 이때 채운다(모델은 계획 감사가 벤더 차이를 확인하는 근거, 모델 ID와 effort를 읽는 위치는 ## 작업 진행 중의 수행 effort 규칙). 완료의 정의 그룹(### R<n>)과 plan Task의 대상 요구사항 필드는 승인받은 R 번호만 참조한다.
     • 테스트 층 표: .ai/10_rules/testing-principles-local.md가 있으면 plan Task 테스트 [D]의 러너 호출·출력 판독·실행 셸은 그 파일의 테스트 층 표와 실행 셸을 따르고, spec 완료의 정의 [D]의 인수 테스트 층은 층 표에서 고른다. 기기 확인 Task는 두지 않는다(실기기 확인은 이슈 진행과 무관하게 사용자가 요청할 때만 한다). 파일이 없으면 이 항목을 건너뛰고 템플릿 그대로 쓴다.
     • AC 정제: 이슈 본문에 - [ ] AC<n>: 또는 - [x] AC<n>: 형식 행이 1개 이상 있으면 AC가 있는 이슈다. AC가 있는 이슈는 완료의 정의를 새로 쓰지 않고 AC를 [D]/[QD]/[ND]로 정제한다. 등록 때부터 검증할 수 있는 AC는 그대로 가져가도 된다.
       • 출처 표기: spec 완료의 정의 항목마다 본문 끝에 출처 AC를 표기한다. 형식은 (AC<n>) 또는 (AC<n>, AC<m>)이고, (회귀 방지 항목)이 있으면 그 앞에 둔다.
       • 연결: 모든 AC가 1개 이상의 항목에 연결된다. 공통 회귀 방지 항목은 예외라 출처 표기 없이 두며, R 그룹 안의 회귀 방지 항목은 출처를 표기한다.
       • AC 없는 R: AC가 대응하지 않는 R의 항목은 (AC 없음: <사유>)로 적고 6단계 질의 대상이 된다. 사유에는 그 R의 근거(이슈 본문 범위 항목, 3-1 승인 등)를 적어, 계획 감사 관점 3이 확장 여부를 가를 수 있게 한다.
       • 번호 유지: AC 번호는 뒤에만 추가하고 다시 매기지 않는다. 이슈 본문·spec·PR이 같은 번호로 AC를 가리키기 때문이다.
       • AC가 없는 이슈는 지금 방식대로 승인받은 요구사항에서 완료의 정의를 쓰고 출처 표기를 하지 않는다. 빠진 AC는 6단계 질의에서 보강한다.
     • 변경 통제: 정제 중의 변경은 ## 작업 진행 중의 변경 통제를 따른다. 확장·완화로 분류한 변경은 질의·재승인 없이 spec에 반영하지 않는다.
4. plan 작성을 끝내기 직전에 plan 템플릿의 계획 종료 게이트(## Tasks 앞 고정 블록)를 수행한다. spec/plan만 보고 작성에 참여하지 않은 쪽이 구현할 수 있는지 자기점검하고, 문서에 없는 전제를 spec ## 전제 (Assumptions)에 남긴다. 발견이 없으면 그 섹션에 "없음" 한 줄을 남긴다.
5. 계획 종료 게이트를 지나면 계획 감사(issue-audit --plan) 수행 여부를 사용자에게 질의한다. 기본값 없이 이슈마다 사용자가 정하며, 구현 AI가 수행 여부를 스스로 판정하지 않는다.
   • 수행: 사용자가 계획 모델과 다른 벤더 모델로 issue-audit --plan을 직접 실행한다(구현 AI는 자동 실행하지 않는다). 리포트 .ai/99_workspace/issue-<번호>-plan-audit-report.md를 받으면 --response로 검토해 승인분을 spec·plan에 반영한 뒤 6단계로 진행한다. summary 모델 기록 표의 계획 audit 모델 행에 감사 모델("벤더, 모델명 (모델 ID)")과 effort(리포트의 감사 effort 줄 값)를, 표 아래 계획 감사 줄에 수행 · 발견 N건 · 보정 N건을 적는다.
   • 건너뜀: summary 모델 기록 표의 계획 audit 모델 행과 계획 감사 줄에 생략을 적고 6단계로 진행한다. 생략을 기록해 두어야 뒤에 감사가 없었다는 사실이 남는다.
6. 5단계 계획 감사 처리(수행이면 --response 반영까지)를 마친 뒤 Task 0 전에 이슈 본문 갱신 질의 대상인지 판정한다. 대상은 이슈 본문에 완료의 정의가 없거나 spec 완료의 정의에 (AC 없음: …) 항목이 있는 이슈다(AC 유무는 3-2 AC 정제의 판정을 따른다). 대상이 아니면 summary 이슈 본문 갱신 줄에 대상 아님을 적고 Task 0으로 진행한다. 대상이면 아래 순서로 질의하며, 사용자가 승인할 때만 이슈 본문을 바꾼다.
   • 대상 저장소: --create 3단계의 대상 저장소 규칙으로 정한다. 대상 저장소와 이슈 번호는 작은따옴표로 감싸고, 값 속 작은따옴표는 그 자리만 '\''로 바꾼다. gh를 쓸 수 없으면 --create 4단계와 같은 조건으로 GitHub MCP에 폴백하고 owner·repo를 대상 저장소로 넘기며, 폴백해도 아래 기준 본문 비교는 그대로 거친다.
   • 기준 본문: 초안을 쓰기 직전에 아래 명령으로 이슈 본문을 다시 받아 .ai/99_workspace/issue-<번호>-body-base.md에 둔다(디렉토리가 없으면 만든다). spec을 쓸 때 읽은 본문은 쓰지 않는다. 계획 감사 동안 GitHub에서 고친 내용이 초안에서 빠져 덮어쓰이기 때문이다. 조회가 실패하면 초안을 쓰지 않고 오류를 보고한 뒤 다시 시도할지 묻는다.