issue-flow — 분석가/개발자가 공유 이슈 트래커에서 협업하는 워크플로우

Issue Flow — 분석가 / 개발자가 공유 이슈 트래커에서 협업하는 워크플로우

활성화 계약 (Activation Contract)

issue-flow analyst [조건], issue-flow dev [도메인-규칙] [이슈-번호] 형식으로 사용합니다. analyst(분석가) 또는 developer(개발자) 작업, 클레임(claim), 워크플로우 상태 전환에 사용합니다. analyst 조건과 dev 도메인은 선택 사항입니다. 범위가 제한되면 해당 범위만 감사/구현하고, 그렇지 않으면 분석가는 전체 저장소를 감사하며 개발자는 선택된 이슈를 구현합니다. 저장소 지침을 먼저 읽고, 트래커 작업을 시작하기 전에 운영자 설정에 따라 선택된 트래커 바인딩만 로드하십시오. 도메인 구성 (인계, 우선순위, 라우팅 규칙), 런타임 노트 (호출, 위임, 팀 메커니즘), 안전 사고 (경쟁, 재할당, 인계, 실패 사유) 문서를 로드하십시오.

확정 규칙 (Hard Rules)

• Issue Flow는 역할, 상태, 클레임 및 전환을 소유합니다. 라우팅된 도메인은 가치, 우선순위, 증거 및 완료 기준을 소유합니다. 어느 쪽도 상대방의 정책을 임의로 만들지 않습니다.
• 분석가(적대적 리뷰어 포함)는 저장소 및 모든 외부 시스템에 대해 읽기 전용입니다. 단, 설정된 트래커 작업(아래 요구됨)은 예외입니다. 분석가는 브랜치/워크트리/커밋/PR을 생성하지 않으며, 마이그레이션, 동기화, 데이터베이스 쓰기, 배포 작업을 실행하지 않습니다. 분석가는 최대 하나의 증거 기반 이슈를 제출합니다. 리뷰는 변경 사항을 작성하지 않은 컨텍스트를 사용해야 합니다.
• <runtime>-<session-prefix> 형식의 실행 ID(run-id)를 생성하고 모든 쓰기 작업에 재사용합니다. 제한된 런타임 속성은 analyst:<runtime>/dev:<runtime> 레이블에, 무제한 실행 ID 속성은 텍스트에 기록합니다. analyst 레이블은 유지되고, dev 레이블은 해제 시 제거되지만 배포 시에는 유지됩니다.
• 큐를 확인하기 전에 이 실행에서 보유한 이슈를 재개합니다. 선택된 바인딩의 타임라인-조정된 클레임을 사용합니다. 가장 빠른 활성 클레임이 승리합니다. verify_claim을 첫 번째 저장소 쓰기 전, 모든 하트비트, 모든 비싸거나 되돌릴 수 없는 경계에서 실행합니다. 읽을 수 없는 제어 표면은 쓰기를 허용하지 않습니다.
• 정확히 하나의 상태(analysis, ready, in-progress, review, blocked, done)를 유지합니다. 바인딩의 워크플로우 상태가 권위적입니다. 설정된 모든 프로젝션이 업데이트되고 다시 읽혀지며, 트래커 종료 전에 done이 명시적으로 표시되어야 합니다.
• 선택된 바인딩은 ensure_states, create, list_state, claim, reclaim, verify_claim, heartbeat, transition, comment, last_activity, label, unassign, publish_version, close 작업을 맵핑해야 합니다. 실행 가능한 되돌릴 수 있는 작업을 사용하고 재구성하지 마십시오. 바인딩은 지원되지 않는 기능을 선언하고 실패 시 차단(fail closed)해야 합니다.
• 이슈 수락 기준, 라우팅된 도메인 규칙 및 저장소 규칙이 완료를 정의합니다. 누락된 게이트를 임의로 만들거나 이슈를 묵시적으로 재해석하지 마십시오.

결정 게이트 (Decision Gates)

상황	조치
분석가에게 조건 또는 제한된 diff/PR/이슈가 있는 경우	해당 범위만 적용 가능한 저장소 및 도메인 규칙에 따라 분석합니다.
분석가에게 조건이나 도메인이 없는 경우	도메인 구성의 자율 general 계약을 사용합니다. 가장 강력한 중복 제거된 결과만 제출하거나 아무것도 제출하지 않습니다.
도메인 경로가 기록된 경우	분석가는 왼쪽 규칙집을 로드하고, 개발자는 오른쪽 규칙집을 로드합니다. 구현 라우팅이 없으면 명시적으로 상태를 표시합니다.
런타임 메커니즘 또는 독립 컨텍스트 획득이 다른 경우	런타임 노트를 따릅니다. 런타임 제한은 메커니즘을 변경하지만 불변 속성은 변경하지 않습니다.
클레임, 재할당 또는 인계 안전에 대한 근거가 필요한 경우	활성 바인딩과 안전 사고를 따릅니다. 여기에 사고 내러티브를 복사하지 마십시오.
상태를 선택해야 하는 경우	잘못된 명세 -> analysis; 구현 가능하고 할당되지 않음 -> ready; 클레임된 빌드 -> in-progress; 빌드/게시됨 -> review; 빌드되지 않은 외부 대기 -> blocked (조건 및 해제자 표시); 병합 및 확인됨 -> done.

실행 단계 (Execution Steps)

낯선 프로젝트에서 각 역할의 첫 번째 트래커 쓰기 전에 선택된 바인딩의 ensure_states를 실행합니다. 그런 다음 해당 바인딩의 실행 가능한 작업 및 읽기백을 사용하고 재구성하지 마십시오. 라우팅, 규모 검증, 큐 분할 또는 자동 대체를 위해 도메인 구성을 로드합니다. 호출, 읽기 전용 적용, 독립 컨텍스트 획득 또는 런타임 제한을 위해 런타임 노트를 로드합니다. 클레임, 재할당, 인계 또는 실패 사유가 필요한 경우에만 안전 사고를 로드합니다. 저장소 규칙이 격리 또는 통합을 완전히 정의하지 않는 경우에만 저장소 배포를 로드합니다.

분석가 (Analyst)

1. 저장소 및 비-트래커 외부 시스템을 읽기 전용으로 유지합니다. analysis 상태에서 가장 오래된 것부터 처리하고, blocked를 검사합니다. 해제된 조건을 증거와 함께 ready로 이동하고, 여전히 유지되는 조건에는 날짜를 표시하며, 보류 중인 결정을 위해 누군가가 얼마나 기다리고 있는지 기록합니다.
2. 왼쪽 도메인 규칙집에 따라 제한된 범위만 분석합니다. 조건이나 도메인이 없으면 자율 general 계약을 사용합니다. 증거와 중복을 확인한 후, 가장 방어 가능한 결과 하나만 유지하거나 살아남은 결과가 없음을 보고합니다.
3. 큐에 있는 결과와 새 결과의 필드, 경로, 규모 및 본문 계약을 검증합니다. 큐에 있는 작업의 경우 누락된 인계 자료를 comment로 추가하고 동일한 완전한 항목만 전환합니다. 대체 항목을 생성하지 마십시오. 새 결과의 경우 분석가 이슈 템플릿을 채우고 analyst:<runtime> 및 run-id 속성과 함께 create합니다. ready 또는 정확한 누락 조건과 해제자를 포함한 blocked를 사용합니다. 그런 다음 구현하거나 할당하지 않고 중지합니다.

분석가가 생성하는 결과

개발자가 분석을 다시 수행하지 않고 작업을 시작할 수 있는 이슈입니다. 개발자가 당신의 추론을 다시 도출해야 한다면, 분석은 아무 가치가 없습니다.

## 일반 사용자를 위한 설명

> [!NOTE]
> 한두 문장, 평이한 언어, 전문 용어 없음, 파일 경로 없음, 메트릭 없음 — 이 이슈가 무엇에 관한 것인지, 이 줄을 넘어 읽지 않을 사람을 위한 설명입니다. 운영자 구성이 이 설치에 대해 지정한 언어로 작성됩니다 (이 파일 끝에 있는 표 참조). 헤더 자체는 위의 고정된 리터럴 제목입니다 — 항상 영어, 항상 정확히 그 문구, 이슈마다 바꾸지 않습니다. `> [!NOTE]`는 GitHub의 기본 알림 구문입니다 — 테두리와 색상이 있는 콜아웃으로 렌더링되며, 이것이 핵심입니다: 기술적인 내용으로 가득한 이슈에서 시각적으로 절대 놓칠 수 없어야 합니다.

이것은 `## Problem` 앞에 이슈의 첫 번째 항목입니다.

## 문제 (Problem)
무엇이 잘못되었거나 누락되었으며, 어떻게 알게 되었는지. 주장이 아닌 증거:
파일:줄 참조, 측정된 숫자, 로그, 재현 단계.

## 중요한 이유 (Why it matters)
방치할 경우의 영향. 영향을 명시할 수 없으면 솔직히 말하십시오 — 문서화된 "낮은 영향, 완전성을 위해 제출"은 정직하며 개발자가 우선순위를 낮출 수 있게 합니다.

## 제안된 접근 방식 (Proposed approach)
설계. 고려한 대안과 이를 기각한 이유. 확신이 없으면, 어떤 부분이 불확실하고 무엇이 이를 해결할지 말하십시오.

## 수락 기준 (Acceptance criteria)
확인 가능한 진술. "더 빠름"은 기준이 아닙니다. "X로 측정한 p95가 200ms 미만"이 기준입니다. 변경되지 말아야 할 것 (불변 속성, 바이트-동일 출력)을 포함하십시오.

## 범위 외 (Out of scope)
개발자가 여기서 명시적으로 하지 말아야 할 것. 이것은 위의 어떤 문단보다도 범위 확장을 더 안정적으로 방지합니다.

## 증거 (Evidence)
실행된 명령, 읽은 파일, 측정된 숫자. 리뷰어가 분석을 반복하지 않고 확인할 수 있을 만큼 충분해야 합니다.

개발자 (Developer)

1. 큐를 확인하기 전에 이 실행에서 보유한 이슈를 기록된 상태에서 재개합니다. 그렇지 않으면 review에서 할당되지 않은 것을 ready보다 먼저 처리하고, 게시된 작업을 클레임하기 전에 배포 차단기를 다시 확인합니다.
2. ready 상태에서 유효한 후보를 안정적인 도메인과 선언된 규모별로 분할하고, 각 파티션 내에서만 순위를 매기고, 가장 오래된 파티션 헤드를 선택합니다. 선택된 도메인은 선택을 가장 높은 순위의 가장 오래된 항목으로 제한합니다. 유효한 규모 계약이 있는 후보가 없을 때만 가장 오래된 우선 방식을 사용합니다.
3. 실행 ID와 기간(horizon)으로 claim한 다음 서버-타임스탬프된 타임라인을 조정합니다. 가장 빠른 활성 클레임이 승리합니다. 패자는 댓글을 달고, 해제하고, 다시 선택합니다. 코드 변경이 in-progress와 새로운 게시/검토/CI 주기를 요구하지 않는 한, 클레임된 리뷰 작업을 review에 유지합니다. ready 작업의 경우 dev:<runtime>과 함께 in-progress로 한 번 전환하고 두 번째 클레임 이벤트는 없습니다.
4. 계획하기 전에 경로의 오른쪽 구현 규칙집을 로드합니다. 없으면 적용되는 것이 없음을 명시하고 작성된 수락 기준에 따라 구축합니다. 저장소 규칙을 따르고, 격리/통합 정책이 없는 경우 저장소-배포 폴백을 사용합니다. 첫 번째 브랜치/워크트리/파일 쓰기 직전에 클레임을 확인하고 격리된 체크아웃에서 구현합니다.
5. 게시하기 전에 갱신(renew)하고, 공유 검토 대상을 게시하거나 재사용한 다음 review로 전환합니다. 리뷰 위임(Review delegation)이 이 실행을 승인하는 경우에만 독립 컨텍스트를 획득합니다. 그렇지 않으면 별도로 시작된 검토를 요청합니다. 동일한 정확한 헤드/베이스에 대한 검토 평결과 녹색 CI를 요구합니다. 모든 푸시는 둘 다 무효화합니다. 차단된 배포는 review에 남겨두고, 실패한 시도로 변경된 로컬 상태를 복원하고, 정확한 차단기를 기록한 후 우회하지 않고 할당을 해제합니다. 충돌하는 저장소 규칙은 별도의 이슈를 받습니다.
6. 각 되돌릴 수 없는 경계에서 갱신합니다. 리뷰되고, 녹색이며, 현재 헤드/베이스 ID가 일치할 때만 병합합니다. 병합-커밋 경로의 경우, 전달된 SHA의 정확한 부모가 리뷰된 베이스와 헤드여야 합니다. 다른 구성된 전략은 해당 바인딩-선언된 동등한 토폴로지와 모든 전달된 SHA 게이트를 요구합니다. 각 변경된 버전에 대해 불변의 주석이 달린 태그와 필수 릴리스를 게시하고 원격으로 확인합니다. 다시 갱신하고 done으로 전환한 후, 리뷰/CI/테스트/측정값/PR/전달 SHA/게시물을 실행 ID와 함께 기록하고 닫습니다. 인계 시 모든 증거를 보존합니다: 잘못된 명세는 analysis로, 구축되지 않은 외부 대기는 blocked로, 구축되었으나 배달할 수 없는 작업은 review로, 유용한 부분 진단은 ready로 이동합니다.

최종 리타이어먼트 구역까지 유지되는 상세 리뷰 게이트

6. 게시된 변경 사항을 작성하지 않은 컨텍스트에서 리뷰하도록 하고, 최신 PR 헤드에 대한 녹색 CI를 요구합니다. 리뷰 전에 헤드 및 베이스 SHA를 캡처하고, 평결 아티팩트가 둘 다 명시적으로 이름을 지정하도록 요구합니다. 부동 "승인"은 특정 개정 또는 diff에 대한 증거가 아닙니다. 구성이 이를 승인하는 경우 직접 해당 컨텍스트를 얻습니다 — 하위 에이전트 또는 팀원; 그렇지 않으면 PR을 별도로 시작된 분석가 실행에 넘기고 이슈에 기다리고 있다고 말합니다. 구성이 결정하는 것은 누가 검토를 시작하는지이며, 검토가 실행되는지 여부는 아닙니다. 모든 푸시는 이전 평결 및 CI 결과를 무효화합니다. 변경된 부분을 다시 리뷰하고 필수 검사가 다시 완료될 때까지 기다립니다.

   리뷰, CI 또는 배포가 차단되면 거기서 멈추고 review에 남겨둡니다. 빌드되고 게시되었지만 배송할 수 없는 작업 — 리뷰어가 변경을 요청, 검사 실패, 필요한 기본 승인을 별도 ID로 제공할 수 없음, 권한 누락, 두 프로젝트 규칙이 서로 모순됨 —은 배송을 기다리는 완료된 작업이며, 이것이 정확히 review가 의미하는 바입니다. done으로 이동하지 마십시오. 그 상태는 배송되었음을 의미합니다. 차단기를 우회하지 마십시오. 배송을 위해 우회하는 규칙은 아무 의미도 없게 됩니다.

   차단기를 정확히 주석으로 남기십시오 — 무엇이 거부했는지, 그 대상이 무엇을 기대하는지, 프로젝트가 대신 요구하는 것이 무엇인지. 그런 다음 할당을 해제하여 다른 행위자가 배송을 완료할 수 있게 하십시오. 시도 중에 변경한 로컬 상태를 복원하십시오.

   두 프로젝트 규칙이 서로 모순되어 발생하는 차단기는 별도의 이슈를 받을 자격이 있습니다. 다음 작업에서, 그 다음 작업에서도 동일한 문제가 발생할 것이며, 각 실행이 처음부터 다시 진단할 것입니다. 하나의 제출된 결과는 반복되는 세금을 누군가가 한 번 결정할 수 있는 것으로 바꿉니다.

7. 필요한 CI가 녹색인 후 리뷰된 PR 헤드만 병합하고, 버전 태그를 게시한 다음 close합니다. 병합 직전에 클레임을 갱신하고, 리뷰된 헤드/베이스 == CI 헤드/베이스 == 현재 헤드/베이스를 요구하며, 병합을 리뷰된 헤드 SHA에 바인딩하고 어느 쪽이든 이동했다면 거부합니다. 구성된 병합 전략을 사용하십시오. merge commit은 브랜치 경계와 PR 계보를 보존하는 반면, 스쿼시와 리베이스는 의도적으로 해당 정보를 버립니다. 병합 후 전달된 SHA를 검색하고 정확히 리뷰된 베이스와 리뷰된 헤드를 부모로 가지고 있는지 확인하십시오. 명령 플래그만으로 토폴로지 보존을 주장하지 마십시오. 병합 큐는 구성된 방법이 동일한 토폴로지를 보장하는 경우에만 적격합니다. 프로젝트가 정확한 전달된 SHA에 CI를 요구하는 경우, 해당 병합 후 게이트를 기다리십시오.

저장소에서 작업하기 — 기본 흐름

저장소의 규칙이 항상 우선합니다. 다른 것보다 먼저 에이전트 지침(AGENTS.md, CLAUDE.md 또는 이에 상응하는 파일)을 읽고 따르십시오. 다음은 아무것도 규정하지 않는 저장소를 위한 폴백이며, 일부만 규정하는 저장소를 위한 최소 기준입니다 — 결코 경쟁 표준이 아닙니다.

이전 폴백 — 커밋 기록을 규칙으로 사용 — 은 여기까지 확장되지 않으며, 그 이유를 말할 가치가 있습니다. git 로그는 커밋 메시지가 어떻게 작성되는지 알려줍니다. 두 에이전트가 체크아웃을 공유할 수 있는지, 1시간 전에 확인된 브랜치가 다른 사람이 병합한 후에도 여전히 유효한지 알려주지 않습니다. 이러한 답변은 병렬 작업이 자체적으로 손상되는지 여부를 결정하므로, 이 스킬은 답을 알 이유가 없는 도메인에 맡기는 대신 제공합니다.

1. 기본 트리에서 작업하지 마십시오. 개발자의 경우 기본 브랜치는 읽기 전용입니다: 편집, 커밋 금지. 가정하지 말고 첫 번째 변경 전에 확인하십시오:

git branch --show-current   # main / master -> 중지, 먼저 브랜치 생성

기본 브랜치에 이미 커밋했지만 푸시하지 않은 경우, 커밋을 브랜치로 이동하고 리셋하십시오. 이미 푸시했다면 강제 푸시하지 마십시오 — 되돌리고 제대로 다시 수행하십시오.

...