순환 복잡도 스킬이란?
cyclomatic-complexity는 기존 코드의 과도한 분기를 줄이도록 설계된 Claude 스킬입니다. 특히 정상적으로 작동하지만 깊게 중첩된 조건문, 수많은 의사 결정 경로 또는 사람이 유지 관리하기 어려운 함수가 누적된 AI 생성 코드에 유용합니다.
이 스킬은 Claude가 구조화된 프로세스를 따르도록 안내합니다. 함수별 복잡도를 측정하고, 가장 문제가 큰 핫스팟을 식별한 다음, 해당 핫스팟을 리팩터링하고, 동작을 검증한 뒤, 변경 전후의 복잡도 값을 요약합니다.
압축된 표현식이나 영리한 한 줄 코드로 점수만 낮추는 대신, 이 스킬은 의사 결정 로직을 명확하고 의미 있는 이름을 가진 함수로 이동합니다. 목표는 복잡도 측정값을 낮추는 것뿐 아니라 유지 관리성도 향상하는 것입니다.
주요 기능
- 함수별 측정: Radon, ESLint, gocyclo, Lizard 또는 수동 계산을 사용해 복잡도를 측정할 수 있습니다.
- 프로젝트 인식 임계값: 프로젝트 린터에 이미 설정된 복잡도 제한을 따릅니다.
- 핫스팟 우선순위 지정: 코드를 무차별적으로 변경하지 않고 가장 복잡한 함수부터 리팩터링합니다.
- 검증된 리팩터링 패턴: 가드 절, 함수 추출, 조회 테이블 및 명명된 조건식을 사용합니다.
- 지표 조작 방지: 복잡도를 밀도 높은 구문 속에 숨기지 않고 이해하기 쉬운 단위로 재구성합니다.
- 명확한 보고: 모든 리팩터링이 변경 전후 복잡도 보고서로 마무리됩니다.
설치
Claude Code에 설치
프로젝트의 플러그인 마켓플레이스를 추가한 다음 스킬을 설치합니다.
/plugin marketplace add saurabhkumar8112/cyclomatic-complexity-skill
/plugin install cyclomatic-complexity@cyclomatic-complexity-skill설치가 완료되면 Claude Code는 관련 리팩터링, 정리 및 코드 검토 요청에 이 스킬을 활성화할 수 있습니다.
Claude.ai에 설치
- 저장소의 Releases 섹션을 열고
.skill파일을 다운로드합니다. 또는skills/cyclomatic-complexity폴더를 ZIP 아카이브로 만들 수 있습니다. - Claude.ai를 열고 Settings, Capabilities, Skills로 이동합니다.
- 다운로드한 스킬 파일 또는 ZIP 아카이브를 업로드합니다.
Claude API로 설치
API 기반 워크플로에서는 Claude Skills API를 통해 스킬을 업로드합니다. 현재 업로드 및 구성 절차는 API 가이드를 따르세요.
기본 사용법
요청이 리팩터링, 정리 또는 코드 검토와 관련된 경우 이 스킬이 자동으로 실행됩니다. 더 세밀하게 제어하려면 스킬 이름을 명시하고 Claude가 검토할 파일을 지정하세요.
cyclomatic complexity 스킬을 사용해 parser.py를 리팩터링해 줘
이 직접적인 요청은 의도한 워크플로와 대상 파일을 모두 명확히 지정합니다. 그러면 Claude는 복잡도를 측정하고, 가장 문제가 큰 함수를 찾은 뒤, 적절한 리팩터링 패턴을 적용할 수 있습니다.
집중적인 코드 검토 요청
작업을 복잡도 중심의 검토로 요청할 수도 있습니다.
cyclomatic complexity 스킬을 사용해 parser.py를 검토해 줘. 함수별 복잡도를 측정하고 가장 문제가 큰 핫스팟부터 리팩터링해 줘.프로젝트에 린터 임계값이 이미 정의되어 있다면 저장소에서 해당 구성을 유지하세요. 그러면 스킬이 프로젝트의 기존 기준을 따를 수 있습니다.
리팩터링 프로세스 이해하기
- 각 함수 측정: 스킬은 Radon, ESLint, gocyclo 또는 Lizard와 같은 지원되는 분석기 중 적절한 도구를 사용합니다. 수동 계산도 가능합니다.
- 프로젝트 임계값 확인: 기존 린터 제한이 구성되어 있으면 해당 제한이 우선 적용됩니다.
- 핫스팟 순위 지정: 복잡도가 가장 높은 함수를 먼저 처리합니다.
- 가독성 있는 변환 적용: 필요에 따라 가드 절을 도입하고, 함수를 추출하며, 조회 테이블을 만들거나 복잡한 조건식에 이름을 붙입니다.
- 동작 검증: 리팩터링은 기존 동작을 유지해야 하며, 사용 가능한 테스트 모음으로 이를 검증합니다.
- 결과 보고: 최종 응답에 변경 전후의 복잡도를 표시합니다.
출력 읽기
리팩터링이 완료되면 다음과 유사한 보고서가 포함됩니다.
## Complexity report
| Function | Before | After |
|----------|--------|-------|
| parseOrder | 14 | 4 |
Extracted: validateHeader, resolveDiscount
Behavior verified: existing test suite passes이 예시에서는 parseOrder의 복잡도가 14에서 4로 감소했습니다. 보고서에는 추출된 함수인 validateHeader와 resolveDiscount도 명시되어 있으며, 기존 테스트가 통과했다는 내용도 기록되어 있습니다.
추출된 함수 목록이 중요한 이유는 숫자가 낮아졌다는 사실만으로 코드의 유지 관리가 쉬워졌다고 증명할 수 없기 때문입니다. 명확한 이름은 책임이 어디로 이동했는지 보여 주고, 검토자가 새로운 구조를 이해하는 데 도움을 줍니다.
스킬에서 사용하는 리팩터링 기법
가드 절
가드 절은 유효하지 않거나 예외적인 조건을 초기에 처리합니다. 이를 통해 중첩을 줄이고 주요 실행 경로를 더 쉽게 따라갈 수 있습니다.
함수 추출
하나의 함수가 여러 의사 결정이나 책임을 수행하는 경우, 스킬은 일관성 있는 부분을 의미 있는 이름을 가진 함수로 이동할 수 있습니다. 이를 통해 복잡도가 의도를 전달하는 단위로 분산됩니다.
조회 테이블
알려진 입력을 알려진 결과에 매핑하는 반복적인 분기문은 조회 테이블로 대체할 수 있습니다. 이 스킬은 단순히 코드를 줄이기 위해서가 아니라 명확성이 향상되는 경우에 이 접근 방식을 사용합니다.
이름이 지정된 조건식
복잡한 조건은 비즈니스 규칙을 설명하는 이름의 함수에 배치할 수 있습니다. 이렇게 하면 의사 결정 지점을 더 읽기 쉽게 만들고 불투명한 조건 표현식을 피할 수 있습니다.
고급 팁
범위를 좁게 시작하기
대규모 코드베이스에서는 파일 하나 또는 이미 알려진 문제 영역 하나부터 시작하세요. refactor parser.py와 같이 범위가 명확한 지시를 사용하면 스킬이 작업 경계를 분명히 파악할 수 있고 결과 보고서를 검토하기도 쉬워집니다.
린터 설정을 사용 가능하게 유지하기
프로젝트에 자체 복잡도 임계값이 있다면 Claude가 작업을 수행할 때 관련 설정이 포함되어 있는지 확인하세요. 이 스킬은 관련 없는 표준을 임의로 적용하지 않고 프로젝트에서 정의한 제한을 따르도록 설계되었습니다.
최악의 문제 지점부터 요청하기
복잡도가 가장 높은 함수를 우선 처리하면 유지 관리성에 가장 큰 영향을 줄 수 있는 곳에 노력을 집중할 수 있습니다. 또한 이미 단순한 함수에 불필요한 변경을 가하는 일도 피할 수 있습니다.
점수뿐 아니라 이름도 검토하기
최종 수치뿐 아니라 추출된 함수와 조건식의 이름도 확인하세요. validateHeader와 resolveDiscount 같은 이름은 책임을 명확히 설명합니다. 측정 점수가 낮아졌더라도 모호한 헬퍼 함수 이름을 사용하면 리팩터링의 유용성이 떨어집니다.
테스트를 안전성 확인 수단으로 사용하기
복잡도를 줄이더라도 동작은 유지되어야 합니다. 기존 테스트 스위트를 사용할 수 있는 상태로 유지하고 최종 보고서에 테스트 통과 여부가 기록되는지 확인하세요. 더 나은 복잡도 점수를 얻기 위해 정확성을 희생해서는 안 됩니다.
지표 조작을 유도하는 요청 피하기
가능한 한 낮은 점수를 요구하기보다 읽기 쉽고 유지 관리 가능한 변경을 요청하세요. 이 스킬은 교묘한 한 줄짜리 코드에 결정을 숨기는 방식을 명시적으로 피하므로, 프롬프트에서도 명확성과 장기적인 유지 관리성을 강조해야 합니다.
결론
순환 복잡도 스킬은 Claude가 분기가 많은 코드를 개선할 수 있도록 반복 가능한 워크플로를 제공합니다. 복잡도를 측정하고, 프로젝트 임계값을 따르며, 가장 문제가 큰 함수를 우선 처리하고, 읽기 쉬운 리팩터링 패턴을 적용하며, 동작을 검증한 뒤, 변경 전후를 구체적으로 보여 주는 보고서로 마무리합니다. 이 프로젝트는 Apache 2.0 라이선스로 배포됩니다.