HEAD와 사용자가 제공한 고정 지점 간의 diff에 대한 두 축 리뷰:
- Standards — 코드가 이 저장소의 문서화된 코딩 표준을 준수하는가?
- Spec — 코드가 원래 이슈 / PRD / 스펙을 충실히 구현하는가?
두 축은 병렬 서브 에이전트로 실행되어 서로의 컨텍스트를 오염시키지 않으며, 이 스킬은 각각의 결과를 종합합니다.
이슈 트래커가 제공되어 있어야 합니다 — docs/agents/issue-tracker.md가 없다면 /setup-matt-pocock-skills를 실행하세요.
프로세스
1. 고정 지점 설정
사용자가 말한 고정 지점(커밋 SHA, 브랜치 이름, 태그, main, HEAD~5 등)을 사용합니다. 사용자가 지정하지 않았다면 물어보세요.
diff 명령어를 한 번 캡처합니다: git diff <fixed-point>...HEAD (세 개의 점으로 머지베이스와 비교). 또한 git log <fixed-point>..HEAD --oneline으로 커밋 목록을 기록합니다.
더 진행하기 전에 고정 지점이 유효한지(git rev-parse <fixed-point>) 확인하고 diff가 비어 있지 않은지 확인하세요. 잘못된 ref나 빈 diff는 여기서 실패해야 합니다 — 두 개의 병렬 서브 에이전트 내부가 아닙니다.
2. 스펙 출처 식별
다음 순서로 원본 스펙을 찾습니다:
- 커밋 메시지의 이슈 참조(
#123,Closes #45, GitLab!67등) -docs/agents/issue-tracker.md의 워크플로를 통해 가져옵니다. - 사용자가 인수로 전달한 경로.
- 브랜치 이름이나 기능과 일치하는
docs/,specs/, 또는.scratch/아래의 PRD/스펙 파일. - 아무것도 찾을 수 없으면 사용자에게 스펙이 어디 있는지 물어보세요. 사용자가 없다고 말하면 Spec 서브 에이전트는 건너뛰고 "스펙을 사용할 수 없음"이라고 보고합니다.
3. 표준 출처 식별
코드 작성 방법을 문서화한 저장소 내 모든 자료(예: CODING_STANDARDS.md 또는 CONTRIBUTING.md).
저장소가 문서화하는 내용 외에도 Standards 축은 항상 아래 스멜 베이스라인 — 저장소에 문서화된 내용이 없더라도 적용되는 고정된 Fowler 코드 스멜 세트(Refactoring, 3장)를 함께 고려합니다. 두 가지 규칙이 이를 제어합니다:
- 저장소가 우선합니다. 문서화된 저장소 표준이 항상 우선하며, 베이스라인이 플래그를 지정할 내용을 지지하는 경우 해당 스멜은 무시합니다.
- 항상 판단의 문제입니다. 각 스멜은 레이블이 지정된 휴리스틱("가능한 Feature Envy")이며, 절대 엄격한 위반이 아닙니다. 그리고 여기의 다른 표준과 마찬가지로 도구가 이미 강제하는 것은 건너뜁니다.
각 스멜은 정의 → 수정 방법을 읽고 diff와 일치시킵니다:
- Mysterious Name — 함수, 변수, 또는 타입의 이름이 하는 일이나 담는 것을 드러내지 않습니다. → 이름을 바꿉니다; 정직한 이름이 떠오르지 않으면 디자인이 모호한 것입니다.
- Duplicated Code — 변경 사항 내 여러 청크나 파일에 동일한 로직 형태가 나타납니다. → 공유된 형태를 추출하여 양쪽에서 호출합니다.
- Feature Envy — 다른 객체의 데이터를 자신의 데이터보다 더 많이 접근하는 메서드. → 메서드를 해당 데이터가 있는 객체로 옮깁니다.
- Data Clumps — 동일한 몇 개의 필드나 매개변수가 계속 함께 다닙니다(생성되기를 기다리는 타입). → 하나의 타입으로 묶어 전달합니다.
- Primitive Obsession — 프리미티브나 문자열이 자체 타입을 가져야 할 도메인 개념을 대신하고 있습니다. → 개념에 자체적인 작은 타입을 부여합니다.
- Repeated Switches — 동일한
switch/if-cascade가 동일한 타입에서 변경 사항 전체에 걸쳐 반복됩니다. → 다형성으로 대체하거나, 두 사이트가 공유하는 하나의 맵으로 대체합니다. - Shotgun Surgery — 하나의 논리적 변경이 diff 내 여러 파일에 분산된 수정을 강제합니다. → 변경 사항을 하나의 모듈로 모읍니다.
- Divergent Change — 하나의 파일이나 모듈이 여러 관련 없는 이유로 편집됩니다. → 각 모듈이 한 가지 이유로만 변경되도록 분할합니다.
- Speculative Generality — 스펙에 필요하지 않은 추상화, 매개변수 또는 훅이 추가되었습니다. → 삭제합니다; 실제 필요가 나타날 때까지 인라인합니다.
- Message Chains — 호출자가 의존해서는 안 되는 긴
a.b().c().d()탐색. → 첫 번째 객체의 하나의 메서드 뒤에 탐색을 숨깁니다. - Middle Man — 주로 위임만 수행하는 클래스나 함수. → 제거하고 실제 대상을 직접 호출합니다.
- Refused Bequest — 상속받은 대부분을 무시하거나 재정의하는 서브클래스나 구현체. → 상속을 버리고 컴포지션을 사용합니다.
4. 두 서브 에이전트를 병렬로 실행
두 개의 Agent 도구 호출과 함께 단일 메시지를 보냅니다. 두 서브 에이전트 모두 general-purpose 서브에이전트를 사용합니다.
Standards 서브 에이전트 프롬프트 — 다음 포함:
- 전체 diff 명령어 및 커밋 목록.
- 3단계에서 찾은 표준 출처 파일 목록, 그리고 3단계의 스멜 베이스라인을 전체 텍스트로 포함 — 서브 에이전트는 다른 방법으로 접근할 수 없습니다.
- 브리핑: "보고서 — 관련 파일/청크별로 (a) diff가 문서화된 표준을 위반하는 모든 위치: 표준 인용(파일 + 규칙); 및 (b) 발견한 모든 베이스라인 스멜: 이름을 지정하고 청크를 인용합니다. 엄격한 위반과 판단 호출을 구분하세요 — 문서화된 표준 위반은 엄격할 수 있지만 베이스라인 스멜은 항상 판단 호출이며, 문서화된 저장소 표준이 베이스라인을 재정의합니다. 도구가 이미 강제하는 것은 건너뜁니다. 400단어 미만."
Spec 서브 에이전트 프롬프트 — 다음 포함:
- diff 명령어 및 커밋 목록.
- 스펙의 경로 또는 가져온 내용.
- 브리핑: "보고서: (a) 스펙에서 요청했지만 누락되었거나 불완전한 요구사항; (b) 요청되지 않았지만 diff에 있는 동작(범위 확장); (c) 구현된 것처럼 보이지만 구현이 잘못된 것으로 보이는 요구사항. 각 항목에 대해 스펙 라인을 인용합니다. 400단어 미만."
스펙이 없으면 Spec 서브 에이전트를 건너뛰고 최종 보고서에 이를 명시합니다.
5. 종합
두 보고서를 ## Standards 및 ## Spec 제목 아래에 있는 그대로 또는 약간 정리하여 제시합니다. 결과를 병합하거나 재순위를 매기지 마십시오 — 두 축은 의도적으로 분리되어 있습니다( 두 축을 사용하는 이유 참조).
한 줄 요약으로 끝냅니다: 축별 총 발견 건수, 그리고 각 축 내에서 가장 심각한 문제(있는 경우). 축 간에 단일 승자를 선택하지 마십시오 — 이것이 분리의 목적을 무효화하는 재순위 매기기입니다.
두 축을 사용하는 이유
변경 사항이 한 축은 통과하고 다른 축은 실패할 수 있습니다:
- 모든 표준을 따르지만 잘못된 것을 구현한 코드 → Standards 통과, Spec 실패.
- 이슈가 요청한 대로 정확히 구현했지만 프로젝트 규칙을 위반한 코드 → Spec 통과, Standards 실패.
별도로 보고하면 한 축이 다른 축을 가리는 것을 방지할 수 있습니다.