사용자와의 모든 커뮤니케이션 및 검토 보고서는 한국어로 작성합니다.
HEAD와 사용자가 제공한 특정 기준점 사이의 diff를 두 개의 축으로 검토합니다.
- Standards: 코드가 이 저장소에 문서화된 작성 규칙을 따르고 있습니까?
- Spec: 코드가 원래의 이슈/명세서를 충실히 구현했습니까?
두 축 모두 병렬 하위 에이전트를 사용하여 서로의 맥락을 오염시키지 않도록 한 후, 본 스킬이 이들의 결과를 통합합니다.
Issue tracker는 이미 제공되어 있어야 합니다. 그렇지 않다면 사용자에게 /setup-matt-pocock-skills를 먼저 실행하라고 알리세요.
흐름
1. 기준점 확인
사용자가 말한 것이 기준점입니다 (커밋 SHA, 브랜치 이름, 태그, main, HEAD~5 등). 사용자가 지정하지 않았다면 물어보세요.
diff 명령어를 한 번 기록하세요: git diff <fixed-point>...HEAD (세 개의 점이므로, merge-base와 비교합니다). 동시에 git log <fixed-point>..HEAD --oneline으로 커밋 목록을 기록하세요.
계속하기 전에 기준점이 해석 가능한지 (git rev-parse <fixed-point>) 그리고 diff가 비어 있지 않은지 확인하세요. 잘못된 참조나 빈 diff는 여기서 실패해야 하며, 두 병렬 하위 에이전트에서 실패하지 않아야 합니다.
2. 명세(Spec) 출처 찾기
다음 순서에 따라 원본 명세를 찾으세요.
- 커밋 메시지의 이슈 참조 (
#123,Closes #45, GitLab의!67등). tracker 문서의 절차를 통해 가져옵니다. - 사용자가 매개변수로 전달한 경로.
docs/,specs/또는.scratch/아래에서 브랜치 이름이나 기능과 일치하는 명세 파일.- 아무것도 찾을 수 없다면 사용자에게 명세의 위치를 물어보세요. 사용자가 명세가 없다고 말하면 Spec 하위 에이전트는 건너뛰고 '사용 가능한 명세가 없음'으로 보고합니다.
3. 코딩 표준(Standards) 출처 찾기
저장소에서 코드 작성 방법을 문서화한 모든 파일을 검색합니다. CODING_STANDARDS.md나 CONTRIBUTING.md가 있다면 반드시 포함해야 합니다. Python 프로젝트의 경우 linter/formatter(ruff, black, mypy 등) 설정을 위해 pyproject.toml도 확인해야 하지만, 도구가 이미 강제하는 규칙은 다시 검토하지 않습니다.
저장소 문서화된 내용 외에도, Standards 축은 항상 아래의 나쁜 냄새 기준을 함께 사용합니다. 이는 《리팩터링》 3장의 Fowler 코드 나쁜 냄새 목록으로, 저장소에 아무것도 문서화되지 않았더라도 적용됩니다. 두 가지 규칙이 적용됩니다.
- 저장소 우선. 저장소에 문서화된 규칙이 항상 우선합니다. 기준에서 지적할 사항을 저장소 문서가 승인하는 경우, 해당 나쁜 냄새를 지적하지 않습니다.
- 항상 판단 문제. 각 나쁜 냄새는 태그가 붙은 경험 법칙(‘Feature Envy가 있을 수 있음’)이며, 엄격한 위반이 아닙니다. 여기의 다른 규칙과 마찬가지로, 도구가 이미 강제하는 것은 건너뜁니다.
각 나쁜 냄새는 '그것은 무엇인가 → 어떻게 고치는가' 형식으로 작성되며, diff에 대조합니다.
- 의미 없는 이름(Mysterious Name): 함수, 변수 또는 타입의 이름이 그것이 하는 일이나 담는 것을 설명하지 않습니다. → 이름을 다시 짓습니다. 정직한 이름을 생각해낼 수 없다면 설계 자체가 모호한 것입니다.
- 중복 코드(Duplicated Code): 동일한 논리적 형태가 이번 변경의 둘 이상의 블록이나 파일에 나타납니다. → 공통된 형태를 추출하고 양쪽에서 호출합니다.
- 기능 애정(Feature Envy): 메서드가 자신의 데이터보다 다른 객체의 데이터에 더 많이 접근합니다. → 메서드가 애정하는 데이터 쪽으로 이동시킵니다.
- 데이터 덩어리(Data Clumps): 동일한 몇 개의 필드나 매개변수가 항상 함께 나타납니다 (태어나려는 타입). → 이를 하나의 타입으로 묶고 그 타입을 전달합니다.
- 기본 타입 집착(Primitive Obsession): 기본 타입이나 문자열로 표현되는 도메인 개념이 실제로는 고유한 타입을 가질 가치가 있습니다 (예: 부품 번호를
str로, 금액과 통화를float로 표현). → 이 개념에 작은 자체 타입(예:dataclass)을 부여합니다. - 반복되는 조건문(Repeated Switches): 동일한 타입에 대해 동일한
match/if체인이 이번 변경에서 반복적으로 나타납니다. → 다형성을 사용하거나 두 곳에서 공유하는 조회 테이블을 사용합니다. - 산탄총 수술(Shotgun Surgery): 하나의 논리적 변경이 diff에서 여러 파일에 분산된 수정을 강제합니다. → 함께 변경되는 것들을 하나의 모듈로 모읍니다.
- 발산적 변경(Divergent Change): 하나의 파일이나 모듈이 관련 없는 여러 이유로 수정됩니다. → 분할하여 각 모듈이 단 하나의 이유로만 변경되도록 합니다.
- 추측성 일반화(Speculative Generality): 명세에 없는 요구 사항을 위해 추가된 추상화, 매개변수 또는 훅. → 삭제하고 인라인화합니다. 실제 요구 사항이 나타날 때까지 기다립니다.
- 메시지 체인(Message Chains): 호출자가 의존해서는 안 되는 긴
a.b().c().d()탐색. → 이 탐색을 첫 번째 객체의 메서드 뒤에 숨깁니다. - 중개자(Middle Man): 주로 하위 위임만 하는 클래스나 함수. → 제거하고 실제 대상을 직접 호출합니다.
- 거절된 유산(Refused Bequest): 서브클래스나 구현체가 상속받은 대부분을 무시하거나 재정의합니다. → 상속을 포기하고 컴포지션을 사용합니다.
4. 두 하위 에이전트를 병렬로 실행
두 하위 에이전트 호출을 동시에 실행하고(전경에서), 이들이 반환한 보고서를 통합합니다.
Standards 하위 에이전트에 대한 프롬프트에는 다음이 포함되어야 합니다.
- 전체 diff 명령어와 커밋 목록.
- 3단계에서 찾은 규범 출처 파일 목록과 3단계의 나쁜 냄새 기준 전체를 붙여넣습니다 (하위 에이전트는 다른 방법으로 이를 얻을 수 없습니다).
- 작업 설명: '한국어로 보고하고, 관련 파일/블록을 표시하십시오: (a) diff가 문서화된 규칙을 위반하는 모든 부분: 해당 규칙(파일 + 규칙)을 인용하십시오; (b) 발견한 기준 나쁜 냄새: 이름을 말하고 해당 블록을 인용하십시오. 엄격한 위반과 판단 문제를 구분하십시오: 문서화된 규칙 위반은 엄격할 수 있지만, 기준 나쁜 냄새는 항상 판단 문제이며 저장소 문서화된 규칙이 기준보다 우선합니다. 도구가 이미 강제하는 것은 건너뛰십시오. 400자 이내.'
Spec 하위 에이전트에 대한 프롬프트에는 다음이 포함되어야 합니다.
- diff 명령어와 커밋 목록.
- 명세의 경로 또는 이미 가져온 내용.
- 작업 설명: '한국어로 보고하십시오: (a) 명세가 요구하지만 누락되었거나 부분적으로만 구현된 요구 사항; (b) diff에서 요구되지 않은 동작(범위 확장); (c) 구현된 것처럼 보이지만 구현 방식이 잘못된 것처럼 보이는 요구 사항. 각 발견 사항에 대해 명세의 해당 텍스트를 인용하십시오. 400자 이내.'
명세가 없다면 Spec 하위 에이전트를 건너뛰고 최종 보고서에 그 사실을 명시하십시오.
5. 통합
두 보고서를 각각 ## Standards와 ## Spec 제목 아래에 원문 그대로 또는 약간 정리하여 배치합니다. 발견 사항을 병합하거나 재정렬하지 마십시오. 두 축은 의도적으로 분리되어 있기 때문입니다 ('왜 두 개의 축인가' 참조).
마지막으로 한 줄 요약: 각 축의 발견 사항 총 개수와 각 축 내에서 가장 심각한 문제(있는 경우). 축을 넘나드는 단일 승자를 선택하지 마십시오: 그것이 바로 두 축을 분리하여 방지하려는 재정렬입니다.
왜 두 개의 축인가
변경 사항은 한 축을 통과할 수 있지만 다른 축은 통과하지 못할 수 있습니다.
- 모든 규칙을 준수했지만 잘못된 것을 구현함 → Standards 통과, Spec 실패.
- 이슈가 요구한 것을 완전히 수행했지만 프로젝트 관례를 위반함 → Spec 통과, Standards 실패.
분리하여 보고함으로써 한 축이 다른 축을 가리는 것을 방지할 수 있습니다.