Three-Loop Workflow (세 루프 워크플로우)

Plan → Build → Close, 위험도에 따라 선택한 깊이(depth)로 진행합니다.

할당된 구현(계획, 변경, 증거, 리뷰, 수리)을 소유합니다. 구현자는 상위 담당자나 할당된 실행자일 수 있습니다. 조정자(coordinator)가 있는 경우 작업 할당, 종속성, 공유 인터페이스 및 통합 소유권은 조정자에게 맡깁니다. 필요한 역할 또는 일정 변경은 해당 조정자에게 요청하세요. 다른 작업을 재귀적으로 조정하지 마십시오. 사용자 결정 요청은 조정자를 통해 전달하세요. 조정자가 없는 경우 변경 사항과 필요한 역할을 직접 관리하세요. 구현 깊이와 실행 모드는 별개입니다. 직접 실행이 필요한 리뷰를 대체하지는 않습니다.

하드 제약 조건, 기본값이 아닌 유일한 규칙:

Direct보다 높은 변경은 이를 작성하지 않은 컨텍스트가 리뷰합니다. 사용 가능한 컨텍스트가 없는 경우에만 핸드오프(섹션 5)에서 그렇게 명시합니다.
프로젝트의 검사(checks)를 실행하세요. 실행할 수 없었던 검사는 통과한 검사가 아닙니다.
핸드오프는 의도한 것이 아니라 관찰된 것을 보고합니다.
누가 무엇에 접근할 수 있는지에 대한 변경(인증, 권한 부여, 시크릿, 신뢰할 수 없는 입력을 위한 새 경로)은 절대 Direct가 될 수 없습니다.
되돌릴 수 없는 저장소 외부 작업(공유 브랜치 푸시, 배포, 실제 데이터 쓰기, 무언가 보내기)은 사용자 승인을 기다립니다.

그 외 모든 것은 기본값입니다: 명시된 이유가 있을 때만 기본값을 변경하세요. 프로젝트의 가이드가 모든 기본값을 재정의하며, 수단은 사용자에게 달려 있습니다.

프로젝트의 가이드(AGENTS.md, CLAUDE.md)를 읽고 검사 명령과 계약(contract)으로 취급하는 파일을 확인하세요. 명명된 것이 없으면 저장소에서 유추하고 무엇을 추론했는지 명시하세요. 검사는 빌드 구성과 CI에서 비롯됩니다. 계약은 이 저장소 외부에서 소비되거나 지속되는 것(공개 API, 스키마, CLI, 와이어 형식, 저장된 데이터)입니다.

참조 references/writing.md의 텍스트 유형, 언어 및 시각적 규칙을 이 작업의 작성에 적용하세요.

1. Depth (깊이)

가장 가벼우면서도 적합한 깊이를 선택하세요.

Direct: 명백히 작은 수정으로, 정확성이 눈에 보이거나 기존 검사로 커버되는 경우. 테스트가 있더라도 사소하지 않은 동작 변경은 Standard 또는 Deep입니다. 오타 수정은 Direct일 수 있습니다. 기본값 변경은 Direct가 될 수 없습니다. 변경을 수행하고 검사를 실행하세요. 계획이나 리뷰어는 필요하지 않습니다. 변경, 검사, 결과 및 리뷰 부재를 한 줄로 보고하세요.
Standard: 동작 변경의 기본값입니다.
Deep: 다음 트리거가 발생할 때만 사용합니다.
1. 이 저장소 외부에서 소비하는 계약의 변경(breaking change)
2. 저장소 외부의 되돌릴 수 없는 효과(지속된 데이터 마이그레이션, 금전, 제3자에게 전송되는 모든 것)
3. 프로젝트가 계약으로 취급하는 파일의 규칙 변경
4. 서로 다른 구조로 이어지는 대안
그런 다음 references/deep.md를 읽으세요.

하나의 위험한 코너 케이스는 전체 변경의 깊이가 아닌 해당 부분의 깊이를 올립니다. 빌드에서 트리거가 드러날 때를 포함하여 스스로 깊이를 올리세요. 사용자만이 깊이를 낮출 수 있습니다. 낮추기 전에 권장하는 깊이를 제시하세요. 이 워크플로우를 처음 사용하는 사람에게는 이 변경이 건너뛸 내용과 남겨질 실패 가능성을 보여주세요. 사용자가 계속 요구한다면 하드 제약 조건을 포기하지 않고 따르세요.

2. Plan (계획)

Standard 및 Deep에서, 첫 번째 편집 전에 목표(Goal), 유혹받았지만 포함하지 않은 비목표(Non-goals), 그리고 수락 기준(Accept)(섹션 4의 증거)을 작성하세요.

계획과 리뷰의 규모는 변경 사항에 맞게 조정하세요.

**결정(Decisions)**은 실제 분기점에서만 추가하세요: 옵션(더 작은 옵션 포함)과 승리한 옵션을 선택한 이유.

프로젝트에 자체 규칙이 없는 한, .agent/<task>/plan.md에 작성하고, 작업당 하나의 디렉토리로, 변경 사항과 함께 파일을 커밋하세요. .agent가 .gitignore에 있다면 해당 항목을 그대로 두고 파일을 강제 추가하지 마세요.

할당된 작업의 경우 제공된 계획 경로를 사용하고 공유된 범위와 수락 기준을 참조하세요. 구현 세부 사항은 거기에 두세요. 전역 작업 레코드는 조정자에게 맡기세요. 기존의 정식 작업 디렉토리를 유지하세요. 위임된 계획의 경우 기본적으로 .agent/<task>/tasks/<slice-id>/plan.md를 사용합니다.

요청에 대한 두 가지 해석이 각각 다른 작업을 필요로 하는 경우, 목표에 자신의 해석을 명시하고 사용자에게 목표와 수락 기준을 보여주고 기다리세요. 누구도 답할 수 없으면 자신의 해석대로 진행하고 핸드오프에 "미확인"으로 표시하세요. 실제 제품, 범위 또는 위험 결정에 대해서는 옵션, 권장 사항 및 근거를 제시하고 질문하며, 조용히 결정하지 마세요. 답변은 계획에 기록하세요.

결함의 원인을 알 수 없는 경우, 이를 찾는 것이 작업입니다: 수락 기준은 재현이며, 수정 계획은 그 후에 수립하세요.

3. Build (구축)

변경된 모든 줄은 목표 또는 결정과 연결되어야 합니다. 아무도 필요로 하지 않는 추상화, 구성 가능성 또는 오류 처리는 하지 마세요.
코드나 수정 사항이 계획과 모순되는 경우, 마지막에가 아니라 공개적으로 계획을 수정하고 중단하세요.
할당된 파일 및 인터페이스 내에서 작업하세요. 변경이 필요한 경우 영향을 받는 작업을 중단하고 수정된 할당을 요청하세요.
병렬 읽기, 격리된 쓰기. 각 동시 작성자에 대해 별도의 작업 트리를 사용하세요(references/parallel.md 참조).
통합 작업의 경우, 병합된 변경 사항에 대해 검사를 실행하고 리뷰하세요. 개별 조각 검사 통과가 통합 수락을 확립하지는 않습니다.
문서가 명령이 생성한 수치를 인용하는 경우, 수치 옆에 명령을 인용하거나 검사가 다시 계산하도록 하세요.

지속적인 작업의 경우, 계획 옆 evidence/checks.md에 검사 결과를 저장하세요. 기준, 명령, 개정, 결과, 증거 링크 및 무효화 조건을 기록하세요. evidence/review.md에 발견 사항, 트리지 결과, 리뷰어 신원 및 수리 라운드를 저장하세요.

4. Evidence (증거)

수락 기준은 변경 없이는 실패할 가장 저렴한 실제 증거를 명명합니다: 기존 검사 통과, 새 테스트, 또는 관찰된 결과. 실패가 어떻게 보이는지 말하세요.
기본적으로 새 단위 테스트는 필요하지 않습니다. 테스트가 저렴하게 고정할 수 있고 회귀를 방어할 가치가 있는 로직인 동작에 대해서만 작성하세요. UI 렌더링 및 레이아웃, 와이어링 및 접착 코드, 구성, 외부 서비스에 대한 얇은 호출, 일회성 스크립트 및 산문에는 잘못된 검사입니다: 대신 결과를 관찰하세요.
사람이 클릭, 입력, 또는 호출하는 부분은 변경을 작성하지 않은 컨텍스트가 구동하고 관찰한 내용을 보고합니다. diff나 본인의 설명이 아니라 경로와 실패를 제공하세요. 모순은 발견 사항입니다. 그러한 컨텍스트가 없으면 직접 구동하고 본 내용을 붙여넣으세요. 제한된 영역은 안전한 곳에서 구동하고 차이를 명시하세요. 구동되지 않은 것은 확인되지 않은 것입니다.
출력물이 실행되는 것이 아니라 읽히는 경우(문서, 도움말 텍스트, 사양) 증거는 변경 컨텍스트가 없는 독자가 완성된 파일을 냉독(cold read)하는 것입니다: diff가 아니라 제품으로 읽으세요.
간헐적 실패는 그 자체로 재현이며 판별 증거입니다. 이 변경의 실패가 통과할 때까지 재실행하지 말고, 결정적 재현을 요구하지 마세요. 이 변경이 야기하지 않은 실패는 명명된 후속 조치이며, 이 변경 내에서 수정하지 마세요.
리뷰 전에 검사를 실행하고, 각 수정 후 변경 사항을 커버하는 검사, 핸드오프 전에 전체 세트를 실행하세요. 합격/불합격 라인만 붙여넣고 전체 로그는 붙여넣지 마세요. 건너뛰거나 테스트 약화로 얻은 통과는 통과가 아닙니다.

5. Review (리뷰)

리뷰어는 전체 변경 사항(또는 단계별로 구축된 변경의 경우 전체 단계), 계획 및 저장소를 받으며, 요약이나 추론이 아닙니다. 전체는 변경이 추가, 수정 또는 삭제하는 모든 파일(새로 추적되지 않은 파일 포함)을 의미합니다. 빈 diff 또는 불완전한 diff의 리뷰는 클린 리뷰가 아닙니다. Direct는 리뷰어가 필요 없으며, Standard는 한 명의 리뷰어를 받습니다.

독립적인 리뷰나 읽기가 불가능한 경우: 먼저 사용 가능한 독립 컨텍스트를 사용하세요. 누락된 역할에 대해, 작업에 대한 기억이 아닌 위에 명시된 완전한 아티팩트를 검사하세요. 누락된 역할의 브리프를 한 번의 셀프 리뷰 패스에 적용하세요. "셀프 리뷰, 독립적 아님"으로 레이블을 붙이고 누락된 독립 역할을 보고하세요. 사용자에게 브리프를 제공하여 다른 곳에서 실행할 수 있도록 하세요. 이 폴백은 더 엄격한 사용자, 프로젝트 또는 호스트 요구 사항을 재정의하지 않습니다.

이 브리프를 그대로 전달하세요:

이 변경 사항을 계획과 대조하여 리뷰하세요. 모든 발견 사항을 file:line 형식으로 보고하고,
차단(blocking)(잘못된 동작, 계약 위반, 계획 외 작업) 또는 비차단(non-blocking)으로 표시하세요.
코드를 수정하지 마세요.
1. 어디에서 깨집니까? 예상치 못한 입력, 신뢰 경계에 닿는 적대적 입력, 호출한 것의 실패,
   diff 외부에서 가정한 사실.
2. 기존 테스트가 약화되었습니까?
3. 새 동작이 변경 없이는 실패하는 증거(테스트 또는 관찰된 결과)로 표시됩니까?
   그 이상을 요구하지 마세요.
4. 목표 밖에 있거나 비목표 내에 있는 것이 있습니까?
5. 계획 자체가 잘못되었습니까?

수정 전 트리지(Triage). 각 발견 사항을 인용된 코드와 대조하여 확인하세요. 오독 및 비목표가 배제하는 작업을 요구하는 발견 사항은 각각 한 줄로 거부하세요. 누락된 테스트는 확인된 정확성 버그를 방어하지 않는 한 비차단입니다. 확인된 차단 발견 사항이 없을 때 변경이 종료됩니다.

다른 사람의 변경 리뷰: 동일한 브리프를 사용하며, 설명을 계획으로 사용합니다. 비목표 누락은 발견 사항입니다. 트리지 후 확인된 발견 사항을 작성자에게 전달하세요. 직접 수정하지 마세요.

6. Fix and stop (수정 및 중단)

수정은 확인된 발견 사항이 인용하는 내용을 근본 원인에서, 동일한 결함이 발생하는 모든 곳에서 복구합니다.
새 메커니즘은 새 작업입니다: 새 검사, 하네스, 가드, 추상화 또는 테스트 파일은 명명된 후속 조치가 되며 수정의 일부가 아닙니다. 확인된 정확성 버그에 대해서만 실패하는 테스트를 추가하고, 기존 테스트 파일을 확장하세요.
각 수정 후 리뷰어는 수정 사항만 다시 확인합니다: 인용된 발견 사항이 해결되었는지, 수정이 새로운 것을 도입했는지. 수정과 재확인을 합쳐 라운드(round)라고 합니다.

사용자에게 질문하고 중단하세요 라운드가 확인된 발견 사항을 변경하지 않은 채로 남기거나, 수정이 계획이 다루지 않은 파일이나 메커니즘으로 확장되거나, 세 번째 라운드 후에도 차단 발견 사항이 남아 있을 때. 해결되지 않은 발견 사항을 그대로, 시도한 것, 실제 출력으로 실패하는 위치, 옵션(계획 수정, 문서화된 위험 수용, 항목을 후속 조치로 드롭, 메커니즘 분할) 및 권장 사항을 가져오세요. 조용히 기준을 낮추지 마세요.

7. Close: the hand-off (마감: 핸드오프)

핸드오프는 최종 변경 설명입니다. 조정자의 경우 HANDOFF.md가 재개 지침을 제공합니다. references/writing.md의 선택적 읽기 및 기록 수명 주기 규칙을 적용하세요. 조정자가 있는 경우 출처가 있는 메모리 후보를 반환하고 공유 업데이트는 조정자에게 맡기세요.

Standard 및 Deep에서 변경 설명에는 다음이 포함됩니다:

목표(사용자가 이제 할 수 있는 것) 및 비목표;
수락 기준 및 증거가 실제로 보여준 것;
확인할 수 없었던 것과 그 이유;
리뷰한 사람, 또는 "셀프 리뷰, 독립적 아님", 또는 리뷰가 발생하지 않았음을 표시하고, 사람이 구동한 경로에 대해서도 동일하게 처리;
사용자가 낮춘 깊이와 사용자가 고집하기 전에 보여준 내용;
수정되지 않은 비차단 발견 사항(각 한 줄);
잔여 위험;
Deep에서, 현재 상태의 롤백.

할당된 작업의 경우 아티팩트 경로 및 개정, 증거, 리뷰 상태, 해결되지 않은 요청, 활성 또는 알 수 없는 수정 명령을 반환하세요. 로컬 완료를 조정자에게 보고하세요. 전체 작업의 완료를 주장하지 마세요.

사용자가 추가하는 리뷰, 보안 또는 오케스트레이션 도구는 독립 리뷰를 보완하며 대체하지 않습니다.

three-loop-workflow