랜딩 검토 (Castle-Solutions/landing)

landing)은(는) 무엇을 하나요?

HEAD와 사용자가 제공한 고정 시점 간의 차이점을 2축으로 검토합니다.

• 표준(Standards): 코드가 이 저장소의 문서화된 코딩 표준을 따르고 있습니까?
• 명세(Spec): 코드가 원본 이슈/명세를 충실히 구현하고 있습니까?

두 축은 병렬 서브 에이전트로 실행되므로 서로의 컨텍스트를 오염시키지 않으며, 이 스킬이 그 결과를 종합합니다.

이슈 트래커가 제공되었어야 합니다. 제공되지 않았다면 사용자에게 /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가 비어 있지 않은지 확인합니다. 잘못된 참조나 빈 diff는 여기서 실패 처리해야 하며, 두 개의 병렬 서브 에이전트 내부에서 실패하지 않도록 해야 합니다.

2. 명세 소스 식별

다음 순서로 원본 명세를 찾습니다.

1. 커밋 메시지의 이슈 참조(#123, Closes #45, GitLab !67 등). 트래커 문서의 워크플로를 통해 가져옵니다.
2. 사용자가 인수로 전달한 경로.
3. 브랜치 이름이나 기능과 일치하는 docs/, specs/, 또는 .scratch/ 아래의 명세 파일.
4. 찾을 수 없는 경우 사용자에게 명세가 어디 있는지 묻습니다. 명세가 없다고 하면 명세 서브 에이전트는 건너뛰고 "명세를 사용할 수 없음"이라고 보고합니다.

3. 표준 소스 식별

저장소에서 코드 작성 방법을 문서화한 모든 파일을 검색합니다. CODING_STANDARDS.md 또는 CONTRIBUTING.md가 존재하면 반드시 목록에 포함되어야 합니다.

저장소가 문서화한 내용 외에도, 표준(Standards) 축은 항상 아래의 **냄새 기준선(smell baseline)**을 가지고 있습니다. 이는 마틴 파울러의 리팩터링 3장에 나오는 코드 냄새 목록으로, 저장소에 문서가 전혀 없어도 적용됩니다. 두 가지 규칙이 적용됩니다.

• 저장소가 재정의합니다. 문서화된 저장소 표준이 항상 우선하며, 저장소가 기준선이 플래그할 내용을 지지하는 경우 냄새를 억제합니다.
• 항상 판단의 문제입니다. 각 냄새는 레이블이 붙은 발견법("가능한 Feature Envy")이며, 엄격한 위반이 아닙니다. 여기의 다른 표준과 마찬가지로 도구가 이미 강제하는 모든 것은 건너뜁니다.

각 냄새는 정의와 수정 방법으로 구성되며, 이를 diff와 대조합니다.

• 수수께끼 같은 이름(Mysterious Name): 함수, 변수, 또는 타입의 이름이 무엇을 하는지 또는 무엇을 담고 있는지 드러내지 않음. → 이름을 바꾸십시오. 정직한 이름이 떠오르지 않는다면 설계가 불분명한 것입니다.
• 중복 코드(Duplicated Code): 동일한 로직 형태가 변경 사항 내 여러 헝크 또는 파일에 나타남. → 공유되는 형태를 추출하여 두 곳에서 호출하십시오.
• 기능에 대한 질투(Feature Envy): 자신의 객체보다 다른 객체의 데이터에 더 많이 접근하는 메서드. → 메서드를 질투하는 데이터가 있는 객체로 옮기십시오.
• 데이터 뭉치(Data Clumps): 동일한 몇 개의 필드나 매개변수가 계속 함께 다님(생성되기를 기다리는 타입). → 하나의 타입으로 묶어 전달하십시오.
• 기본 타입 집착(Primitive Obsession): 도메인 개념에 적합한 고유 타입 대신 기본 타입이나 문자열을 사용함. → 해당 개념에 작은 고유 타입을 부여하십시오.
• 반복되는 switch(Repeated Switches): 동일한 타입에 대해 동일한 switch/if-cascade가 변경 사항 전체에 걸쳐 반복됨. → 다형성으로 대체하거나 두 사이트가 공유하는 하나의 맵을 사용하십시오.
• 산탄총 수술(Shotgun Surgery): 하나의 논리적 변경이 diff의 여러 파일에 걸쳐 산발적인 수정을 강제함. → 관련 변경 사항을 하나의 모듈로 모으십시오.
• 발산적 변경(Divergent Change): 하나의 파일이나 모듈이 여러 관련 없는 이유로 수정됨. → 각 모듈이 하나의 이유로만 변경되도록 분할하십시오.
• 추측성 일반화(Speculative Generality): 명세가 필요로 하지 않는 추상화, 매개변수, 또는 훅이 추가됨. → 삭제하거나 실제 필요가 나타날 때까지 인라인 처리하십시오.
• 메시지 체인(Message Chains): 호출자가 의존해서는 안 되는 긴 a.b().c().d() 탐색. → 첫 번째 객체의 하나의 메서드 뒤에 탐색을 숨기십시오.
• 중개자(Middle Man): 주로 위임만 수행하는 클래스나 함수. → 제거하고 실제 대상을 직접 호출하십시오.
• 상속 거절(Refused Bequest): 상속받은 대부분을 무시하거나 재정의하는 서브클래스 또는 구현체. → 상속을 포기하고 합성을 사용하십시오.

4. 두 서브 에이전트를 병렬로 실행

두 서브 에이전트 호출을 함께, 포그라운드에서 실행하고 반환된 보고서를 종합합니다.

표준(Standards) 서브 에이전트 프롬프트에는 다음이 포함되어야 합니다.

• 전체 diff 명령어와 커밋 목록.
• 3단계에서 찾은 표준-소스 파일 목록. 3단계의 냄새 기준선도 전문을 붙여넣습니다.(서브 에이전트는 이에 접근할 수 없습니다).
• 지시사항: "파일/헝크별로 관련된 내용을 보고하십시오. (a) 문서화된 표준을 위반하는 모든 부분: 표준(파일 + 규칙)을 인용하십시오. (b) 발견한 기준선 냄새: 이름을 지정하고 헝크를 인용하십시오. 엄격한 위반과 판단 호출을 구분하십시오: 문서화된 표준 위반은 엄격할 수 있지만 기준선 냄새는 항상 판단 호출이며, 문서화된 저장소 표준이 기준선을 재정의합니다. 도구가 강제하는 모든 것은 건너뛰십시오. 400단어 미만."

명세(Spec) 서브 에이전트 프롬프트에는 다음이 포함되어야 합니다.

• diff 명령어와 커밋 목록.
• 명세의 경로 또는 가져온 내용.
• 지시사항: "보고: (a) 명세가 요청했지만 누락되거나 부분적으로만 구현된 요구사항; (b) 요청되지 않았지만 diff에 포함된 동작(범위 확장); (c) 구현된 것처럼 보이지만 구현이 잘못된 요구사항. 각 발견 사항에 대해 명세 라인을 인용하십시오. 400단어 미만."

명세가 누락된 경우 명세 서브 에이전트를 건너뛰고 최종 보고서에 이를 명시하십시오.

5. 종합

두 보고서를 ## 표준(Standards) 및 ## 명세(Spec) 제목 아래에 원문 그대로 또는 가볍게 정리하여 제시하십시오. 두 축은 의도적으로 분리되어 있으므로(왜 두 축인지 참조) 결과를 병합하거나 재순위화하지 마십시오.

각 축의 총 발견 건수와 각 축 내에서 가장 심각한 문제(있는 경우)를 요약하는 한 줄로 마무리하십시오. 축을 가로지르는 단일 승자를 선택하지 마십시오. 분리 목적이 바로 그 재순위화를 방지하는 것입니다.

왜 두 축인가

변경 사항은 한 축은 통과하고 다른 축은 실패할 수 있습니다.

• 모든 표준을 따르지만 잘못된 것을 구현한 코드 → 표준 통과, 명세 실패.
• 이슈가 요청한 대로 정확히 수행하지만 프로젝트 규칙을 위반한 코드 → 명세 통과, 표준 실패.

별도로 보고하면 한 축이 다른 축을 가리는 것을 방지할 수 있습니다.