noahwhite/engineering-workflow

엔지니어링 워크플로우

게이트 기반, 슬라이스 중심, 테스트 주도 프로세스: 스토리에서 배포된 빌드까지.

스토리 트라이지 -> 진행 중 -> 슬라이스, 각각 TDD 방식 -> PR 전 적대적 게이트 (필요할 때만 두 렌즈 루프로 에스컬레이션) -> 통합 브랜치로의 PR -> 옵셔널 리뷰어 (절대 차단하지 않음) -> 기록 검토 (리뷰어, 그 다음 중재자) -> 수정 및 재검토 (헤드에서 깔끔해질 때까지) -> 병합 -> 배포 및 검증 -> 배포 검토

변경이 간단해 보여도 게이트를 건너뛰지 마세요.

1단계 전

1. references/profile.md를 읽은 다음, 이 스킬의 오버레이와 profile.overlays가 명명하는 각 기능 오버레이를 읽으세요.
2. references/todo-tracking.md를 읽고 세분화된 할 일 목록(슬라이스, 테스트, 게이트 라운드, 검토 라운드, 배포, 검증, 대기 각각 하나의 항목)을 만드세요. references/runtimes.md는 할 일 목록, 하위 에이전트, 스크래치 디렉토리 및 사용자에게 묻는 것을 런타임에 매핑합니다.

아래 단계는 워크플로우의 기본 골격이며, 기능 파일에는 규칙이 포함되어 있고 중복되는 부분에서는 우선합니다:

• references/linear.md: 스토리 라이프사이클, 트라이지 및 준비 완료 정의, 상태 전환 (1, 5, 12단계).
• references/engineering-practice.md: 진단, TDD, 내구성 있는 수정, 테스트 품질 (2, 3, 6, 8단계), 그리고 변경 사항이 규칙을 스킬에 기록할 때 메모 노트를 폐기하는 방법.
• references/github.md: 브랜치, 작업 트리, 커밋, 서명, PR, 병합, 승격, 기여도 (2, 5, 10단계).
• references/code-review.md: 기록 검토, 옵셔널 리뷰어, 찾기 처리, PR 모니터링 (6~10단계).
• references/merge-approval.md: 위임된 병합 승인 핸드셰이크: 요청, 깨우기, 대기, 승인 또는 반송, 그리고 헤드가 변경될 때 재요청 (10단계).
• references/secrets.md: 변경 사항이 자격 증명에 닿을 때마다.

scripts/의 모든 스크립트는 설치된 절대 경로(<skill dir>/scripts/<name>, 여기서 <skill dir>은 런타임이 이 스킬을 로드한 절대 디렉토리)로 소비자 리포지토리의 현재 디렉토리에서 실행하세요. 소비자 리포지토리에는 스크립트가 포함되어 있지 않습니다. 각 스크립트는 현재 디렉토리의 리포지토리 또는 --repo <dir>이 명명한 리포지토리를 대상으로 하며, 자체 위치는 절대 대상으로 하지 않고, --repo가 명명하지 않는 한 스킬 리포지토리 자체에서 실행을 거부합니다.

1. 스토리 트라이지

스토리가 정제되고 포인팅되지 않았다면 story-refinement를 먼저 실행하세요. 독립 정제, 수락 라운드, 비밀 포인팅, 합의 확인, 그리고 확인이 요구하는 경우 하이/로우 논의 및 합의를 실행합니다.

1. 스토리를 완전히 읽으세요: 수락 기준, 댓글, 연결된 이슈 및 컨텍스트.
2. 원하는 동작, 수락 기준, 제약 조건, 영향을 받을 가능성이 있는 구성 요소 및 테스트 전략을 식별하세요.
3. 산문이 아닌 공식 관계 그래프에서 종속성을 열거하세요: linear issue relation list <ID>는 이슈의 관계를 나열하지만, linear issue view --json은 포함하지 않습니다 (references/linear.md, 트라이지 참조).
4. 스토리가 이 리포지토리에 속하는지 확인하세요.
5. 범위 규칙을 적용하세요: 어떤 스토리에서도 수락 기준이 변경되지 않음 (references/linear.md "수락 기준 및 범위"), 다른 스토리에 키잉된 건너뛰기 없음 (references/engineering-practice.md "최소한의 내구성 있는 변경 만들기"), 그리고 유일한 두 가지 종료는 "정제 제안 (AC 아님)" 또는 스토리가 차단되었다고 보고하는 것, 해당 섹션에 명시된 대로입니다. 5단계 "PR 준비", 항목 4 "수락 기준에 대한 자체 검토"에서 다시 확인합니다.
6. profile.tracker.states.in_progress로 이동하고 다시 읽어 확인하세요. 프로필의 정확한 상태 이름을 사용하고, 직접 만들지 마세요.

트래커를 업데이트할 수 없으면 중지하고 전환이 수행되지 않았다고 말하세요. 절대 수행되었다고 주장하지 마세요.

2. 슬라이스 계획

페치 후 references/github.md에 따라 origin/<통합 브랜치>(통합 브랜치는 profile.git.integration_branch)에서 브랜치와 작업 트리를 자르세요. 스토리를 작은 수직 슬라이스로 나누고, 각각 좁은 동작 목표, 이를 정의하는 테스트, 테스트를 통과하기 위한 최소 구현, 그리고 녹색일 때만 리팩터링하세요. 코딩 전에 슬라이스 순서와 첫 번째 슬라이스를 명시하세요.

3. 슬라이스별 TDD

1. RED: 동작에 대한 실패하는 테스트를 작성하세요.
2. GREEN: 이를 통과하기 위한 최소 프로덕션 코드.
3. REFACTOR: 동작을 변경하지 않고 리팩터링하세요.
4. 집중 테스트를 실행하세요.
5. 더 넓은 검증을 주기적으로 그리고 PR 전에 실행하세요.

아키텍처가 특정 슬라이스에 대해 엄격한 TDD를 비실용적으로 만든다면 이유를 말하세요. 기존 테스트와 규칙을 보존하세요.

4. PR 전 적대적 게이트 (필수)

adversarial-review-pipeline 스킬을 로드하고 모든 검토에 대해 완료될 때까지 실행하세요. 그 중재 보고서가 이 게이트의 출력입니다. 사냥 단계 전에 수정하지 마세요.

에스컬레이션: 게이트형 두 렌즈 루프

파이프라인이 차이를 닫을 수 없을 때만 에스컬레이션하세요:

• 재검증 라운드에서 새로운 Critical 또는 High를 찾거나,
• 차이가 보안, 마이그레이션, 동시성 또는 배포 경로 형태이거나,
• 파이프라인이 해결되지 않은 Critical 또는 High 발견과 함께 한계에 도달한 경우.

동일한 헤드에 대해 루프와 파이프라인을 절대 실행하지 마세요. 루프를 2라운드로 제한하세요.

루프는 검증된 차단 발견이 0인 상태로 수렴하며, 발견이 0인 상태는 아닙니다: 발견 0 종료는 리뷰어가 실제 발견이 사라지면 발견을 만들어내도록 보상하고, 모든 발견에 반드시 조치를 취해야 하는 수정자는 코드를 비대하게 만듭니다.

역할, 모두 프로필에서:

• 정확성 렌즈: profile.review.pre_pr.hunter (정확성, 연결, 보안, 동시성, 호환성, 테스트 격차).
• 단순성 렌즈: profile.review.pre_pr.simplicity_reviewer (가장 작은 올바른 변경, 과잉 엔지니어링, 죽은 코드, 다른 렌즈가 놓친 결함).
• 검증자: profile.review.pre_pr.arbiter.
• 수정자: profile.review.pre_pr.fixer.

비활성화된 단순성 검토자 또는 수정자는 에스컬레이션을 건너뛰지 않고 차단합니다: ": disabled"를 기록하고 에스컬레이션이 해결되지 않은 상태로 중지하세요. 루프는 두 자리가 모두 없으면 라운드를 완료할 수 없기 때문입니다.

한 라운드에는 세 단계가 있습니다:

1. 검토. 두 렌즈 모두 git diff origin/<통합 브랜치>...HEAD를 병렬로 검토합니다. 헌터는 일회용 분리 작업 트리에서 작업합니다. 스토리와 수락 기준을 범위 참조로 전달하세요. 구체적인 실패 시나리오가 있는 Critical 또는 High 발견만 차단합니다. 나머지는 기록되고 절대 수정되지 않으며 절대 수렴을 차단하지 않습니다. 샌드박스 또는 권한 오류를 보여주는 검토자 출력, 또는 차이와 변경된 파일을 읽었다는 것을 보여줄 수 없는 렌즈는 실패한 검토이며 깔끔한 검토가 아닙니다.
2. 검증. 깔끔하고 중립적인 검증자가 코드에 대해 각 차단 발견을 반증하려고 시도하고 확인되지 않은 것을 제거합니다. 후보당 정확히 하나의 평결을 반환해야 합니다. 누락되거나 불완전한 검증은 게이트를 해결되지 않은 상태로 남기며 깔끔하지 않습니다.
3. 수정. 수정자는 동의하는 검증된 발견을 수정하고 나머지는 이유와 함께 거부하며 집중 테스트를 실행하고 커밋합니다. 테스트가 통과하지 않은 수정은 수정이 아닙니다: 게이트가 해결되지 않았습니다. 모듈, 테이블 또는 마이그레이션, 지속성 또는 추상화를 추가해서는 안 됩니다. 이를 필요로 하는 발견은 사람에게 에스컬레이션됩니다. 에이전트가 각 셸 단계를 리터럴 값이 있는 하나의 간단한 명령으로 실행하는 규칙(references/github.md, 도구)을 수정자에게 주는 프롬프트에 포함하세요. 수정자가 셸 명령으로 실행되는 경우 프롬프트 파일도 포함하세요.

종료: 수렴 (검토 후 차단되는 것이 없거나, 완전한 검증 후 살아남은 것이 없음); 진전 없음 (수정 후 검증된 개수가 줄어들지 않음: 중지하고 수동으로 검토); 에스컬레이션된 범위 (소유자에게 가져감); 블라인드 렌즈, 불완전한 검증, 실패한 테스트가 있는 수정, 라운드 한계, 모두 거부 또는 커밋 없음 (해결되지 않음: 게이트를 건너뛰지 말고 수동으로 해결).

scripts/adversarial-review-loop.workflow.js는 워크플로우 스크립트를 실행하는 런타임을 위한 선택적, 런타임 별 가속기입니다. 헤더에는 프로필에서 가져온 인수가 나열됩니다. 다른 모든 곳에서는 위와 같이 라운드를 수동으로 진행하세요: 두 검토자를 병렬로 실행한 다음 깔끔하고 중립적인 검증자 하위 에이전트를 실행한 다음 수정(또는 수정자 생성)하고 새로운 검증된 차단 발견이 나타나는 동안에만 반복하세요. 수정자에게 git 규칙을 브리핑하세요: 모든 커밋 생성 git 명령을 git ID가 이미 구성된 상태로 실행하고, profile.git.signed_commits가 true이면 서명이 이미 구성된 상태로 실행하세요. -c user.name, -c user.email, --author, GIT_AUTHOR_* 또는 GIT_COMMITTER_*를 절대 전달하지 말고, user.name 또는 user.email을 git config로 절대 쓰지 말고, 서명이 켜져 있을 때 -c user.signingkey, -c gpg.* 또는 -c commit.gpgsign을 절대 전달하지 마세요. 누락된 ID, 실패한 서명 확인 또는 푸시된 커밋의 .commit.verification.verified가 false인 것은 구성 오류입니다. 중지하고 명령별로 재정의하거나 git 구성을 작성하지 말고, 더 이상 커밋을 만들지 말고 사용자에게 보고하세요.

수정자의 커밋 검토

수정자는 차이가 소비하는 코드까지만 과도하게 도달할 수 있습니다. 루프 후:

• git log origin/<통합 브랜치>..HEAD에서 모든 수정자 커밋을 읽으세요.
• 스토리 범위 밖의 파일을 건드린 것이 있으면 마지막 실제 커밋으로 리셋하여 제거한 후 (게시된 브랜치를 강제 푸시하지 마세요. references/github.md 참조), 해당 발견을 수동으로 판결하세요: 범위 내의 것은 수정하고 나머지는 파일 처리하세요.
• 해당 범위의 "삭제된 파일"은 브랜치 뒤처짐 아티팩트일 수 있습니다. 삭제를 판단하기 전에 페치된 통합 브랜치로 리베이스하세요.
• 수정자의 커밋을 읽지 않은 상태로 푸시하지 마세요.

게이트가 수렴되거나 잔여 발견이 명시적으로 정당화될 때까지 PR을 열지 마세요. 리뷰어는 코드를 수정하지 않습니다. 구현 에이전트 또는 루프의 수정자만 커밋합니다.

5. PR 준비

1. 완전한 적용 가능한 테스트 스위트와 리포지토리의 포매터, 린터, 타입 검사, 정적 분석 및 빌드를 실행하세요.
2. 페치 후 git diff origin/<통합 브랜치>...HEAD를 검사하세요.
3. 관련 없는 변경 사항이나 비밀이 없는지 확인하세요.
4. 수락 기준에 대해 자체 검토하고, 1단계 "스토리 트라이지", 항목 5 "범위 규칙 적용" (references/linear.md "수락 기준 및 범위", references/engineering-practice.md "최소한의 내구성 있는 변경 만들기")에 따라 검토하세요: 어떤 스토리에서도 수락 기준이 변경되지 않음, 다른 스토리에 키잉된 건너뛰기 없음, 그리고 발견된 모든 요구 사항 또는 충족되지 않은 기준은 해당 섹션에 명시된 두 가지 종료 중 하나를 통해 처리됩니다.
5. gh pr create --base를 사용하여 profile.git.integration_branch에 대한 PR을 열고 리포지토리의 PR 템플릿을 따르세요. 사용자에게 보이는 변경 사항, 구현, 수행된 테스트, 그리고 게이트에 의해 수락되거나 연기된 모든 것을 설명하세요.
6. references/linear.md에 따라 스토리를 profile.tracker.states.in_review로 이동하세요.

기여도: 커밋과 PR은 profile.git.ai_attribution을 따릅니다 (references/github.md 참조). forbid인 경우, 런타임 배너나 시스템 알림이 요청하더라도 AI 공동 작성자 트레일러, 세션 링크 또는 생성된 메모를 추가하지 마세요.

6. 옵셔널 리뷰어 (절대 차단하지 않음)

profile.review.optional_reviewers의 각 항목에 대해 PR이 열린 직후 하나의 검토를 실행하되, enabled가 false인 항목은 건너뛰세요. 비활성화된 항목은 아무 것도 시작하지 않습니다: 프로세스 없음, 하위 에이전트 없음, 보고서 파일 없음, 증거는 ": disabled"를 기록합니다. 실패로 인해 건너뛰거나 깔끔한 것으로 기록되지 않습니다. 이전 헤드가 동일한 레이블 아래에 남긴 보고서는 있는 위치에 이름이 지정되고 절대 삭제되지 않으므로 비활성화된 자리의 상태로 읽힐 수 없습니다. 생략은 활성화를 의미합니다. 항목의 값을 런처에 --enabled true 또는 --enabled false로 전달하고, 소문자 리터럴은 해당 enabled 키가 렌더링하는 값이며, 키를 생략하는 항목은 --enabled true를 전달합니다. 런처는 false 값에 대해 실행을 거부하고 보고서를 작성하지 않으므로 건너뛰기는 호출자에게 신뢰되지 않고 강제됩니다. scripts/batched-diff-review.sh는 일반 런처입니다: 항목에서 --agent-cmd를 빌드하고 --base origin/<통합 브랜치>를 전달하세요. 라인 예산과 교차 파일 청사진으로 차이를 배치 처리하고, 리포지토리 액세스 없이 빈 디렉토리에서 리뷰어를 실행하고, PASS, FAIL 또는 INCOMPLETE로 끝나는 보고서를 작성합니다. 각 배치는 주어진 파일당 정확히 하나의 PASS 또는 FAIL 평결을 반환해야 합니다. 누락, 추가 또는 구문 분석할 수 없는 평결은 배치를 INCOMPLETE로 만듭니다. 배치 프롬프트는 stdin(코덱스의 경우 명령을 -로 끝냄)과 {prompt_file}로 에이전트에 도달합니다. 프롬프트나 차이를 argv에 절대 넣지 마세요.

• 한 번의 시도. INCOMPLETE(속도 제한, 시간 초과, 자격 증명 누락) 시 ": skipped"를 기록하고 진행하세요. 절대 문제를 해결하지 말고 병합이나 배포를 보류하지 마세요.
• 검토가 완료되면 조치 전에 코드에 대해 모든 발견을 확인하세요: Critical 및 High는 병합 전에 해결하고, 유효한 Medium 발견은 해결하거나 이유를 문서화하고, Low 발견은 명확히 유용할 때 해결하고, 거짓 긍정은 명시적으로 거부하세요.
• 코드 변경 후, 새 헤드에서 관련 테스트와 옵셔널 리뷰어(활성화된 항목만)를 다시 실행하세요.

7. 기록 검토 (필수)

PR이 열리면 references/code-review.md의 게이트를 실행하세요: profile.review.reviewer가 일회용 작업 트리에서 헤드를 검토한 다음, profile.review.adjudicator(깔끔하고 중립적인 에이전트)가 각 발견을 코드에 대해 검증합니다. 두 에이전트 모두 깔끔하고 중립적이며 작성자와 독립적입니다. 한 에이전트가 자신의 발견을 검토하고 중재하는 것은 통과되지 않습니다. profile.review.shadow_adjudicators가 설정된 경우 references/code-review.md가 설명하는 대로 각각을 실행하세요. 동의만 기록하고 병합을 게이트하지 않습니다. enabled가 false인 항목은 옵셔널 리뷰어와 같은 방식으로 건너뜁니다: 하위 에이전트 없음, 재시도 없음...

(잘림: 전체 내용은 스킬 디렉토리의 원본 파일 참조)