mattac21/skills

품질 검토

대상: $ARGUMENTS

설계 및 테스트 품질에 대해 대상을 검토합니다. 결과를 보고하고 코드를 편집하지 마십시오.

1. 루브릭 로드

코드를 보기 전에 다음을 모두 읽으십시오:

• ~/.claude/CODING_STANDARDS.md가 루브릭입니다. 모든 발견은 해당 섹션 제목 중 하나를 인용합니다.
• design-vocabulary.md에는 결과를 표현하는 데 사용할 용어와 아래에서 이를 검증하는 테스트가 포함되어 있습니다.

또한 저장소의 AGENTS.md / CLAUDE.md가 있으면 읽으십시오. 해당 파일이 저장소가 표준에서 권장하지 않는 작업을 의도적으로 수행한다고 명시하는 경우, 모든 인스턴스를 표시하는 대신 보고서에 한 번 언급하십시오. 코드에서만 관찰되는 습관(모든 모듈이 환경을 읽고, 모든 테스트가 monkeypatch하는 경우)은 문서화된 선택이 아닙니다. 이를 따르는 새 코드는 여전히 발견 사항입니다.

2. 대상 확인

• 인수 없음: 기본 브랜치에 대한 현재 브랜치. git merge-base HEAD origin/main (또는 master), 그 다음 git diff <base>...HEAD 및 git diff HEAD의 커밋되지 않은 변경 사항.
• PR 번호 또는 URL: gh pr diff <n> 및 gh pr view <n> --json baseRefName,headRefName,files.
• 브랜치: git diff <base>...<branch>.
• 경로 또는 . (전체 저장소): diff 없이 해당 경로 아래의 기존 코드를 있는 그대로 검토합니다. 이것이 코드베이스 모드입니다.

3. 설계 판단에 충분히 읽기

변경 모드 (diff, 브랜치, PR)

diff만으로는 모듈이 깊은지 알 수 없습니다. 변경된 각 모듈에 대해 전체 파일을 읽고 해당 호출자와 테스트를 grep하십시오. 깊이, 소유권 및 중복은 호출 사이트에 대한 판단이므로 이를 살펴보십시오.

발견 사항을 변경 사항이 도입하거나 악화시키는 것으로 범위를 제한하십시오. diff가 접촉하는 코드의 기존 문제는 변경 사항이 이를 수정하기에 자연스러운 순간인 경우 범위 내에 있습니다. 접촉되지 않은 코드의 문제는 범위 밖입니다.

새 모듈은 코드베이스 모드에서와 같이 모듈 규모 검토를 받습니다: Types 및 Readability를 다른 섹션만큼 완전히 살펴보십시오. 새롭거나 실질적으로 다시 작성된 각 모듈에 대해, 판단하기 전에 각 함수와 해당 매개변수 및 반환 타입을 나열하고, 수락, 반환 또는 키를 읽는 타입화되지 않은 각 map, dict 또는 tuple과 각 단일 문자 이름을 기록하십시오.

Readability를 판단하기 전에 변경된 모든 소스 파일에 대해 언어의 일반적인 도구를 사용하여 순환 복잡성을 측정하십시오: 예를 들어 Python의 경우 radon cc -s, Go의 경우 gocyclo, JavaScript/TypeScript의 경우 eslint의 complexity 규칙, Rust의 경우 clippy의 cognitive_complexity, Java의 경우 PMD. 저장소 자체 도구가 있으면 이를 통해 실행하고, 그렇지 않으면 일회성 실행기(uvx, npx, go run)를 사용하십시오. 단락 boolean 피연산자를 계산하는 도구를 선호하십시오. 일부(예: ruff의 C901)는 이를 건너뛰고 최악의 함수를 과소평가합니다. 사용 가능한 도구가 없으면 루브릭에서 정의한 대로 결정 지점을 수동으로 계산하십시오. diff가 추가하는 함수가 10점 이상이거나, diff가 기존 함수를 10점 이상으로 밀어 올리거나 추가로 높이는 경우 후보입니다. 기존 함수의 경우 기본 버전도 점수를 매기십시오(git show <base>:<file>을 스크래치패드 파일에 쓰고 측정) 그래서 발견 사항이 변경 사항이 무엇을 추가했는지 말할 수 있습니다.

diff가 소스 약 150줄 이상을 추가하는 경우, 설계 섹션을 검토하는 동안 병렬로 두 개의 general-purpose 하위 에이전트를 시작하십시오. 각각 diff, 변경된 파일 목록 및 해당 섹션에 대한 4단계 검증 규칙을 제공하십시오: 하나는 Types, Readability 및 "비용이 발생하는 곳에서 불변 데이터로 기울이기"용, 다른 하나는 Testing용이며, 새 테스트 각각에 어설션 검사를 적용합니다. 유지하기 전에 각각이 반환하는 것을 확인하십시오.

코드베이스 모드 (경로 또는 .)

경로 아래의 모든 것이 범위 내에 있지만, 발견 사항에 대한 기준은 범위의 크기에 따라 높아집니다. 단일 모듈 또는 작은 디렉토리(대략 소스 1,500줄 미만)는 모듈, 함수 및 네이밍 수준의 발견 사항을 얻습니다: Types 및 Readability를 다른 섹션만큼 완전히 살펴보십시오. 패키지 또는 전체 저장소는 주요 문제만 얻습니다: 코드베이스를 뒤로 잡아당기는 설계 결정 및 아키텍처 패턴. 사용자가 하나의 모듈로 판명되는 기능 또는 도구(예: "전체 CLI")를 지정하는 경우에도 동일하게 적용됩니다: 모듈 규모로 판단하십시오. 패키지 또는 저장소 규모의 각 후보에 대해 다음을 질문하십시오:

• 얼마나 많은 모듈, 테스트 또는 향후 변경 사항이 이에 대한 비용을 지불합니까? 하나의 함수에 국한된 비용은 이 규모에서 사소한 것입니다.
• 수정하면 이 저장소에서 새 코드가 작성되는 방식이 변경됩니까? 수정 사항이 호출자에 영향을 미치지 않는 몇 줄의 로컬 코드라면 삭제하십시오.
• 패턴입니까 아니면 일회성입니까? 개별 인스턴스는 패턴의 증거로만 계산됩니다.

주요 문제의 예: 소유 모듈이 없는 외부 시스템으로 모든 호출자가 인증 및 페이지 매김을 다시 수행합니다. 진입점에 융합된 정책 및 오케스트레이션으로 결정을 엔드 투 엔드로만 테스트할 수 있습니다. 저장소 레이아웃을 각각 알고 있는 모듈 간에 분할된 상태 소유권. 가져오기 시간에 빌드된 클라이언트 및 구성으로 실제 환경 없이는 아무것도 테스트할 수 없습니다. seam이 없기 때문에 전체적으로 내부를 패치하는 테스트 스위트. 긴 함수, 잘못된 이름의 변수, 삼켜진 단일 예외 또는 하나의 약한 어설션은 그 자체로 주요 문제가 아닙니다.

이러한 문제는 모듈에 걸쳐 있으므로 파일을 깊이 읽기 전에 맵을 빌드하십시오:

• 모듈(파일 또는 패키지) 및 각각이 대략 수행하는 작업, git ls-files <path> 및 각 모듈 상단을 훑어보기
• 주요 조각이 연결되는 방식: 무엇이 무엇을 호출하는지, 상태 및 데이터가 진입점, 모듈 및 외부 시스템 간에 이동하는 방식
• 각 외부 시스템(API, 데이터베이스, 큐, 파일 형식, 모델) 및 이에 직접 연결되는 모든 모듈
• 환경 또는 구성이 읽히는 모든 위치(os.environ, getenv, process.env, 플래그 구문 분석)
• 모듈 수준의 가변 상태 및 가져오기 시간 효과(모듈 범위에서 빌드된 클라이언트, 연결, 캐시, 잠금)
• 진입점 및 각 테스트 파일이 실행하는 모듈이 있는 테스트 디렉토리

grep은 대부분의 경우 충분합니다. 맵을 짧게 유지하십시오. 보고서의 일부가 아닌 작업 인덱스입니다.

범위가 작은 경우(대략 소스 3,000줄 미만), 맵에서 직접 검토하고 병렬로 두 개의 general-purpose 하위 에이전트를 시작하십시오. 각각 파일 목록 및 해당 섹션에 대한 4단계 검증 규칙을 제공하십시오. 하나는 루브릭의 Types, Readability 및 "비용이 발생하는 곳에서 불변 데이터로 기울이기" 섹션만 얻습니다. 다른 하나는 Testing 섹션만 얻고 모든 테스트에 어설션 검사를 적용해야 합니다. 이렇게 하면 해당 섹션이 이전 섹션 후에 남은 것보다 전체 주의를 기울일 수 있습니다. 유지하기 전에 각각이 반환하는 것을 확인하십시오. 그렇지 않으면 관련 모듈의 영역으로 분할하고 각 영역에 테스트를 제공하고 각 영역을 병렬로 시작된 general-purpose 하위 에이전트에 제공하십시오. 각각에 루브릭 경로, 어휘 경로, 맵, 파일 목록, 4단계 검증 규칙 및 위의 주요 문제 기준을 제공하고 아무것도 편집하지 말라고 지시하십시오. 자신의 영역만 보는 하위 에이전트는 로컬 사소한 문제로 표류하므로 해당 영역에서 보는 설계 패턴과 각각에 대한 증거(file:line)를 요청하십시오. 줄 수준 발견 사항 목록이 아닙니다. 모듈 간 문제는 맵에서 비롯되므로 직접 해결한 다음 하위 에이전트의 패턴과 결합하고, 다른 영역에서 볼 때 동일한 기본 결정인 패턴을 병합하고, 보고하기 전에 각각에 대한 증거를 다시 확인하십시오.

4. 각 섹션에 대해 검토

표준을 순서대로 살펴보십시오: Modules, State, Types, Dependencies and configuration, Errors, Readability, Testing. 각 후보 발견 사항에 대해 유지하기 전에 검증하십시오:

• 얕은 모듈 또는 통과: 삭제 테스트를 적용하십시오. 호출자의 이름을 지정하고 어떤 복잡성이 호출자에 다시 나타날지 말하거나, 아무것도 나타나지 않음을 보여주십시오.
• 자리를 차지할 자격이 없는 추상화: seam에서 어댑터 수를 세십시오. 테스트 fake가 계산됩니다. 뒤에 숨겨진 것이 없는 하나의 어댑터는 발견 사항입니다. 두 개는 실제 seam입니다.
• 누락된 추상화: 반대 방향도 동일하게 확인하십시오. 하나의 모듈 내부 및 모듈 간에 세 곳 이상에서 인라인으로 처리된 관심사를 찾으십시오.
• 누락된 소유자 / 중복된 관심사: 각 관심사가 작성된 각 위치(file:line)를 나열하십시오. "여러 곳에 나타남"이 아닙니다.
• 소유자가 없는 개념: 개념이 표현, 구문 분석 또는 빌드된 모든 위치(file:line)와 같은 유형의 매개변수가 다른 의미를 가진 채 나란히 있는 서명을 나열하십시오. 식별자는 개념으로 계산되며 구조화된 데이터만이 아닙니다. 동일한 프리미티브로 전달된 다른 종류의 이름 및 ID(소스 및 대상 리포지토리 이름, 브랜치 이름 및 참조, 두 종류의 ID)가 주요 포착 사례입니다. 그런 다음 어떤 종류의 소유자가 적합한지 말하십시오. 호출자가 개념을 보유하고 전달하는 경우 해당 유형을 권장하십시오. 호출자가 개념으로 무언가를 수행하기만 하면 되는 경우 작업을 수행하는 모듈 내부에 숨기는 것을 권장하십시오. 도메인 유형이 기본값이 아닙니다.
• 순서 제약 조건 또는 수동으로 빌드된 키/경로/ID: 호출자가 시퀀싱 또는 구성을 수행하는 것을 보여주십시오.
• 공유 가변 상태, 로드 시간 효과, 깊은 구성 읽기: 전역 변수 또는 가져오기 시간 호출의 이름을 지정하고 차단하는 테스트 또는 두 번째 구성을 지정하십시오.
• 스냅샷 쓰기: 읽기, 장기 실행 단계 및 쓰기 백을 보여주십시오.
• 불변 데이터가 더 나은 가변 데이터: 가변성에 구체적인 비용이 있는 경우에만 보고하십시오. 예상치 못한 변경을 보는 두 번째 보유자, 안전하지 않은 캐시 또는 키, 또는 값이 생성된 위치에서 멀리 떨어진 변경을 보여주십시오. 자체 코드를 통해 변경하는 하나의 소유자가 있는 가변 구조는 발견 사항이 아닙니다. 불변 버전이 성능 비용이 드는 경우, memoize 또는 공유할 항목과 해당 캐시가 있는 위치를 말하십시오.
• 표현할 수 있는 잘못된 상태: 절대 발생해서는 안 되는 상태의 이름을 지정하고 이를 허용하는 유형(함께 설정해야 하는 선택적 필드, 부울 조합, 몇 가지 허용된 값이 있는 문자열)을 보여주십시오. 이로 인해 존재하는 가드 또는 None 검사를 나열하십시오(file:line). 불가능하게 만드는 형태를 제안하고 해당 변경 사항이 삭제하는 가드를 말하십시오.
• 개념으로서의 Dict 또는 Tuple: 읽힌 키와 이를 읽는 모든 함수(file:line) 및 dict가 빌드된 모든 위치를 나열하십시오. 리포지토리의 기존 스타일(pydantic 모델 또는 dataclass, TypeScript 인터페이스, Go 구조체, 리포지토리가 이미 사용하는 모든 것)로 레코드 유형을 제안하고 코드가 사용하는 필드만 보유하며 페이로드가 구문 분석되는 위치를 말하십시오.
• 외부 시스템을 소유한 모듈: 해당 함수가 모듈 전역 변수 또는 호출별 환경 읽기를 통해 자격 증명, ID, 기본 URL 또는 캐시를 공유하는지, 테스트가 여러 함수를 패치하는지 확인하십시오. 그렇다면 시작 시 빌드되고 전달되는 도메인 명명된 메서드가 있는 클라이언트 클래스를 권장하고 fake가 대체할 패치의 이름을 지정하십시오.
• 누락된 문서 주석: 문서 주석이 없는 각 중요 함수(file:line)와 서명이 말하지 않는 문서 주석이 말해야 할 내용(대체, 오류 모드, 접촉하는 상태, 입력 모양)을 나열하십시오. 모듈당 하나의 Readability 발견 사항으로 그룹화하십시오.
• 단일 문자 이름: 제안된 이름과 함께 각각(file:line)을 나열하는 하나의 그룹화된 Readability 발견 사항으로 보고하십시오. 이는 Readability 상한을 향해 하나의 발견 사항으로 계산되며, 삭제 이유가 아닙니다.
• 삼켜진 오류: 로그 줄만 기록하는 동안 변경되는 결과로 실패에서 경로를 보여주십시오.
• 여러 의미를 가진 이름: grep하고 각 사이트에서 보유하는 항목을 나열하십시오.
• 수준 또는 객체를 숨기는 이름: 모호하게 읽히는 호출 체인 또는 호출 사이트를 보여주고 대체를 제안하십시오.
• 둘 이상의 작업을 수행하는 함수: 한 문장 요약을 작성해 보십시오. 작성할 수 없으면 이를 막는 분기, try 블록 또는 모드 매개변수를 인용하십시오.
• 너무 복잡한 함수: 복잡성 측정의 각 후보에 대해 점수를 제공한 다음 순서대로 실행되는 단계를 나열하십시오(입력 필터링, 가져오기, 클레임, 유효성 검사, 빌드, 생성, 기록, 알림, ...) 해당 줄 범위 및 각 단계의 실패 규칙과 함께. 분할을 단계 또는 결정당 하나씩, 서명이 있는 명명된 함수로 제안하고 각 추출된 조각이 패치 없이 테스트 가능하게 만드는 것을 말하십시오. 일반적으로 결정은 순수 함수가 되고 원래는 명명된 단계의 짧은 시퀀스로 읽힙니다. 함수당 하나의 발견 사항입니다. 20 이상은 설계 발견 사항과 함께 순위가 매겨집니다. 11~20은 Readability 상한을 향해 계산되지 않는 Readability 발견 사항입니다. 함수가 진입점이거나 리포지토리에 더 큰 함수가 있기 때문에 분할을 삭제하지 마십시오.
• 테스트 어설션: 어설션이 실패하게 만드는 제품 버그의 이름을 지정하십시오. 할 수 없으면 그것이 발견 사항입니다. 매개변수화된 또는 테이블 기반 사례의 경우 각 입력을 코드를 통해 추적하고 사례 이름이 지정된 동작에 도달하는 부분을 말하십시오. 구별되는 입력이 이전 분기에 의해 소비되는 경우 해당 동작을 다루지 않으며, 이에 대한 테스트가 존재하더라도 마찬가지입니다. 마찬가지로 fixture 또는 fake가 각 가드 또는 거부 경로를 트리거할 입력을 실제로 생성할 수 있는지 확인하십시오. 절대 그럴 수 없으면 가드는 테스트되지 않았습니다.
• 테스트 더블: 테스트가 무엇에 관한 것인지 말한 다음 더블이 해당 경계 외부에 있는지 또는 제품 논리를 재구현하는지 말하십시오.
• 내부를 패치하는 테스트: 실제 수정 사항이므로 빼내야 하는 결정 또는 전달해야 하는 의존성을 지적하십시오.
• 발견 사항의 수정 사항에서 제안된 seam 또는 포트: 도메인에서 명명된 작업(close_ticket(id))을 제공하고 전송 동사(get/post/put)가 아닙니다. 요청만 전달하는 포트는 삭제 테스트를 실패하고 해당 fake는 라우팅을 다시 구현해야 합니다. 보고하기 전에 제안된 각 seam을 삭제 테스트에 대해 확인하십시오.

Testing에 이전 섹션과 동일한 깊이를 제공하십시오. 이전 섹션이 많은 발견 사항을 생성하더라도 마찬가지입니다. 위의 모든 Testing 검사를 각 테스트 파일에 대해 실행하십시오: 각 어설션에 대해 실패하게 만드는 제품 버그의 이름을 지정하십시오. 실패하는 어설션이 없는 보안 관련 동작(수정, 인증 검사, 승인 게이트)은 설계 발견 사항과 함께 순위가 매겨집니다.

구체적으로 만들 수 없는 것은 삭제하십시오. 표준이 다루지 않는 스타일 nit은 삭제하십시오. 품질 문제에서 직접 따르지 않는 한 여기서 정확성 버그를 보고하지 마십시오(예: 데이터를 잃는 스냅샷 쓰기). 한 줄로 언급하고 /code-review를 가리키십시오.