사용자 정의
선택적 개인 환경 설정: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md.
해당 파일이 존재하면 읽고 적용하고, 그렇지 않으면 스킬 기본값을 사용합니다. 개인 환경 설정만 해당됩니다. 저장소나 제품에 대한 사실은 해당 저장소(.claude/workflow-profile.sh 또는 도구 구성)에 속하며, 여기에 절대 두지 마세요.
CodeQuality은(는) 무엇을 하나요?
하나의 루프, 두 개의 렌즈. 루프는 항상 감지 → 하나의 항목 선택 → 테스트 뒤에서 수정 → 검증 → 반복입니다. 도구 렌즈는 스캐너가 플래그한 내용을 우선순위에 따라 기존 테스트를 보호막으로 삼아 수정합니다. 원칙 렌즈는 코드를 변경하기 어렵게 만드는 요소(갓 클래스, 중복, 테스트 불가능한 코어)를 SOLID/클린 코드 원칙 중 하나씩 수정하며, 설계 변경을 미리 보여주지 않고 적용하지 않습니다. 두 렌즈 모두 동일한 도구 목록을 읽고, 동일한 보고서 디렉토리에 쓰며, 동일한 품질 개선 보고서로 끝납니다.
두 가지 렌즈
| 도구 렌즈 | 원칙 렌즈 | |
|---|---|---|
| 드라이버 | 스캐너 출력 (summary.md) | Principles.md에 매핑된 설계 스멜 (smell-inventory.md, roadmap.md) |
| 작업 단위 | 하나의 발견: 하나의 규칙, 하나의 파일:라인 | 하나의 제한된 핫스팟에 하나의 원칙: 하나의 Extract, 하나의 클래스 분할, 하나의 의존성 역전 |
| 순서 | P0 보안 → P1 정확성 → P2 유지보수 | 레버리지 사다리(아래 참조), 저장소별 조정 |
| 자율성 | 수정 후 diff 표시 | 제안 → 확인 → 적용; 승인 전에는 아무것도 편집되지 않음 |
| 안전망 | 기존 테스트는 계속 통과 | 대상이 테스트되지 않은 경우 먼저 특성화 테스트 작성 |
| 지표 | 발견 수 감소, 도구 재실행 시 클린 | 중복률, 순환 복잡도, 함수 길이, 팬인/팬아웃, "이제 단위 테스트 가능" |
| 사용 시기 | 린트/타입/보안 부채, CI 빨간불, "스캐너를 만족시켜라" | 변경에 저항하는 코드, 개선 스프린트의 구조적 계층 |
루프
SCAN → SELECT → SAFETY NET → [PROPOSE → CONFIRM] → FIX → VERIFY → REPORT → REPEAT
└─ 원칙 모드에서는 필수, 도구 모드에서는 건너뜀 ─┘
워크플로 라우팅
| 트리거 | 워크플로 | 생성물 |
|---|---|---|
| "품질 도구 설치", "코드 품질 설정" | Workflows/Install.md | 도구 목록이 설치되고 확인됨 |
| "스캔", "기준선", "코드 품질 분석", "스멜 보고서", "무엇을 먼저 수정할까", "리팩터링 로드맵" | Workflows/Scan.md | summary.md (A), smell-inventory.md (B), roadmap.md (C) |
| "코드 품질 향상", "린트 수정", "품질 루프", "[발견] 수정" | Workflows/Loop.md 도구 모드 | 수정, session-log.md, 보고서 |
| "리팩터링", "SOLID 적용", "정리", "루프 시작" | Workflows/Loop.md 원칙 모드 | 수정, session-log.md, 보고서 |
| "이 저장소 정리" (한정어 없음) | Scan A + B + C, 이후 원칙 모드 Loop | 위의 모든 것 |
| "개선 스프린트", "개선 사이클" | IssueFlow Remediation이 브랜치, PR 및 병합을 소유; Scan이 사이클 범위 지정, Loop가 실행 | 사이클당 하나의 PR |
루프는 주어지지 않은 경우 자체적으로 모드를 선택합니다. 저장소에 roadmap.md가 없으면 도구, 있으면 원칙입니다. 사용자는 둘 중 하나를 강제할 수 있습니다.
도구 목록
Tools/tools.tsv는 이 스킬의 유일한 도구 목록입니다. 탭으로 구분되며, 언어 및 도구당 한 행: language category priority tool install run notes. language는 js | python | yaml, category는 lint | format | types | security | deadcode | duplication | complexity | deps | coverage, priority는 P0 | P1 | P2입니다. 두 스크립트 모두 이를 읽습니다. 워크플로는 도구를 인라인으로 나열하지 않습니다. 도구를 추가하거나 제거하려면 한 행을 편집하세요.
| 스크립트 | 목록에서 읽는 항목 | 수행 작업 |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lang ...] | 선택한 언어의 install 셀 | 언어 감지(package.json → js; pyproject.toml, requirements.txt 또는 *.py → python; *.yaml/*.yml → yaml); 저장소의 패키지 관리자(lockfile → npm/pnpm/bun)로 js 도구를 devDependencies에 설치, python 및 yaml 도구는 uv pip install 또는 pip로 설치; npm:/pip: 접두사는 채널을 재정의, -는 아무것도 설치하지 않음 |
Tools/run-quality-baseline.sh [--dry-run] [lang ...] | run 셀 | 모든 도구를 reports/codequality/<YYYY-MM-DD>-<HHMMSS>/에 실행, $OUT(보고서 디렉토리), $SRC(QUALITY_SRC_DIRS, 기본값 src(존재하는 경우) 또는 .), $PM 및 $NPX를 대체; 설치되지 않은 도구는 MISSING, 충돌하는 도구는 FAILED, 둘 다 실행을 중단하지 않음; 도구별 상태, 파싱된 이슈 수 및 P0/P1/P2 합계가 포함된 summary.md 작성; 보고서 경로 출력 |
run이 -인 행(커버리지 도구)은 설치되지만 기준선에서 실행되지는 않습니다. 커버리지는 Loop에서 대상 범위 내에서 측정됩니다. 모든 도구는 무료이며 로컬로 실행됩니다. npm audit, pip-audit 및 checkov는 취약점 데이터베이스에 대해서만 네트워크에 연결됩니다.
레버리지 사다리 (원칙 렌즈 기본 순서)
- 이름 — 읽을 수 없는 코드는 안전하게 변경할 수 없습니다. 저렴하고 모든 것을 차단 해제합니다.
- DRY / 중복 — 가장 낮은 위험으로 가장 많은 코드를 제거합니다. 숨겨진 추상화를 드러냅니다.
- 작은 함수 — 긴 메서드 → Extract; 함수당 하나의 추상화 수준.
- SRP — 둘 이상의 이유로 변경되는 클래스와 모듈을 분할합니다.
- OCP / DIP — 의존성을 역전시키고, 이음새를 추가합니다. 높은 영향, 더 높은 위험, 먼저 안전망.
- ISP / LSP — 두꺼운 인터페이스와 깨진 대체 가능성; 5단계의 이음새가 필요합니다.
Scan 파트 C는 실제 인벤토리에 따라 이 순서를 조정합니다(레버리지 = 영향 ÷ 위험; Principles.md 파트 3 참조).
불가침의 원칙
- 반복당 하나의 항목. 하나의 발견, 또는 하나의 제한된 대상에 하나의 원칙. 작고 검토 가능한 diff.
- 동작 보존. 구조는 변경되지만 동작은 변경되지 않습니다. 동작이 변경되어야 하면 중단하고 플래그를 지정하십시오. 그것은 수정이 아니라 기능입니다.
- 초록에서 초록으로. 변경 전후로 테스트가 통과합니다. 변경 후 빨간색은 되돌리기를 의미하며, 절대 앞으로 수정하지 않습니다.
- 특성화 테스트 먼저 수정할 라인이 테스트되지 않은 경우. 안전망 없음, 리팩터링 없음.
- 설계 변경 전 제안 (원칙 모드). 도구 모드는 직접 수정한 후 diff를 표시할 수 있습니다.
- P0 → P1 → P2 도구 발견의 경우, 언어를 넘어서, 언어별로가 아닙니다.
- 초록색을 얻기 위해 테스트나 린트 규칙을 약화시키지 마십시오. 오래된 테스트는 새로운 올바른 동작으로 이동합니다. 규칙은 코드에서 충족됩니다.
- 보이 스카우트, 범위 제한. 건드린 파일은 더 깨끗하게 남겨두되, 현재 항목을 넘어 범위를 확장하지 마십시오.
- 증거, 의견이 아닙니다. 규칙이나 원칙의 이름을 지정하고, 존재하는 경우 지표를 제시하십시오.
출력 아티팩트
모두 reports/codequality/ 아래에 있습니다(git 무시됨):
| 파일 | 작성자 |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + 원시 도구 출력 | run-quality-baseline.sh (Scan A) |
<YYYY-MM-DD>/smell-inventory.md | Scan B |
<YYYY-MM-DD>/roadmap.md | Scan C |
<YYYY-MM-DD>/session-log.md | Loop, 반복당 하나의 항목 |
<YYYY-MM-DD>/quality-report.md | Loop, 세션 종료 시 (아래) |
품질 개선 보고서 (필수)
모든 Loop 세션은 이 보고서로 종료되며, 어느 모드든지 상관없습니다. 이것은 코드 변경과 함께 제공되는 결과물이며, 작업이 IssueFlow를 통해 전달될 때 PR 또는 트래커 댓글의 본문입니다.
| 섹션 | 내용 |
|---|---|
| 요약 표 | 추가/제거/순 라인 수; 우선순위별 이슈 전 → 후; 제거된 데드코드 핫스팟; 테스트 전 → 후(개수, 모두 초록색) |
| 제거된 코드 | 파일, 내용, 라인, 위험 |
| 추가 또는 수정된 코드 | 파일, 내용, 라인, 목적 |
| 수정된 버그 | 심각도, 설명, 근본 원인 (발견된 경우에만) |
| 복잡도 델타 | 최대 및 평균 순환 복잡도 전 → 후, 핫스팟당 ASCII 막대 포함 |
| 연기됨 | 발견되었지만 범위를 벗어난 항목과 그 이유 |