코드 품질 검사
최근에 작성된 코드에 대한 포괄적인 품질 검증입니다. 명세 준수, 계층 간 안전성, 그리고 커밋 전 검사를 결합합니다.
1단계: 변경 사항 식별
git diff --name-only HEAD
git status
2단계: 작업 산출물 및 적용 가능한 명세 읽기
현재 작업 산출물을 순서대로 읽습니다:
prd.mddesign.md(존재하는 경우)implement.md(존재하는 경우)
python3 ./.trellis/scripts/get_context.py --mode packages
변경된 각 패키지/계층에 대해 명세 인덱스를 읽고 해당 품질 검사 섹션을 따릅니다:
cat .trellis/spec/<package>/<layer>/index.md
참조된 특정 지침 파일을 읽으세요 — 인덱스는 포인터일 뿐, 목표가 아닙니다.
3단계: 프로젝트 검사 실행
프로젝트의 린트, 타입 검사 및 테스트 명령을 실행합니다. 진행하기 전에 모든 실패를 수정하세요.
4단계: 체크리스트 검토
코드 품질
- 린터가 통과했는가?
- 타입 검사기가 통과했는가?(해당하는 경우)
- 테스트가 통과했는가?
- 디버그 로깅이 남아 있지 않은가?
- 억제된 경고나 타입 안전성 우회가 없는가?
테스트 커버리지
- 새로운 함수 → 단위 테스트가 추가되었는가?
- 버그 수정 → 회귀 테스트가 추가되었는가?
- 변경된 동작 → 기존 테스트가 업데이트되었는가?
명세 동기화
-
.trellis/spec/업데이트가 필요한가?(새로운 패턴, 규칙, 교훈)
"버그를 수정했거나 명확하지 않은 무언가를 발견했다면, 미래의 내가 같은 문제를 겪지 않도록 문서화해야 할까?" → 예(YES)인 경우, 관련 명세 문서를 업데이트하세요.
범위 규율
- 작업이 요구하지 않은 코드 정리가 있었는가?
- 아직 존재하지 않는 사례를 위해 추가된 추상화, 설정 또는 확장 지점이 있었는가?
- 발생할 수 없는 상태를 위한 추측성 폴백이 있었는가?
- 승인 기준에 언급되지 않은 파일이 변경되었는가?
- 동작이 실제로 있는 곳에서 수정하는 대신 호출자에 우회 작업이 추가되었는가?
5단계: 계층 간 차원(해당하는 경우)
변경 사항이 단일 계층에 국한된 경우 이 단계를 건너뛰세요.
A. 데이터 흐름(변경 사항이 3개 이상의 계층에 걸친 경우)
- 읽기 흐름 추적이 올바른가: Storage → Service → API → UI
- 쓰기 흐름 추적이 올바른가: UI → API → Service → Storage
- 타입/스키마가 계층 간에 올바르게 전달되었는가?
- 오류가 호출자에게 적절히 전파되었는가?
B. 코드 재사용(상수 수정, 유틸리티 생성)
- 새 코드를 만들기 전에 유사한 기존 코드를 검색했는가?
grep -r "pattern" src/ - 동일한 값이 반복된다면, 그것은 호출자가 함께 변경되어야 하는 하나의 안정적인 개념을 나타내는가? 그런 경우에만 추출하세요 — 오늘 우연히 일치하는 두 개의 리터럴은 분리되어 있어야 합니다.
- 일괄 수정 후, 모든 발생 위치가 업데이트되었는가?
C. 임포트/의존성(새 파일 생성)
- 올바른 임포트 경로(상대 vs 절대)인가?
- 순환 의존성이 없는가?
D. 동일 계층 일관성
- 동일한 개념을 사용하는 다른 곳과 일관성이 있는가?
6단계: 보고 및 수정
발견된 모든 위반 사항을 보고하세요. 그런 다음:
- 기계적이고 국소적인 문제(린트 사소한 오류, 누락된 타입, 잘못된 임포트, 죽은 분기, 실패하는 단언) → 제자리에서 수정하고 프로젝트 검사를 다시 실행하세요.
- 설계나 판단과 관련된 문제(공유 개념 이름 지정, 모듈 경계 이동, 공용 인터페이스 변경, 동작 위치 재할당) → 증거와 권장 사항을 기록하고 중단하세요. 조용히 다시 작성하지 마세요.
수정이 현재 작업 범위를 벗어난 파일에 영향을 미치는 경우, 그렇게 말하고 변경을 확대하지 말고 중단하세요.