9.4.3 AI 생성 코드의 가독성(Readability) 지표 측정 및 임계값 설정

AI가 생성한 코드가 문법적으로 완벽하고 타입이 안전하며 심지어 사내 린팅 룰까지 모두 통과했다고 가정하자. 그렇다면 이 코드는 인간의 코드 베이스에 병합될 자격을 갖춘 것인가?

결코 그렇지 않다. 가장 위험한 코드는 에러가 나는 코드가 아니라, **‘어떻게 동작하는지 인간의 뇌로 읽어낼 수 없는 코드(Unreadable Code)’**다. LLM은 종종 for 문 하나로 깔끔하게 끝날 로직을, map, filter, reduce가 5단으로 중첩된 람다(Lambda) 함수 도배질로 압축시키거나, 변수명을 a1, a2, temp_val 따위로 생성하여 코드의 인지적 복잡도를 우주 미아 수준으로 날려버리기도 한다.

이러한 코드는 당장은 잘 돌아갈지 몰라도, 3개월 뒤 인간 엔지니어가 디버깅을 위해 열어보았을 때 유지보수의 불가능성이라는 시한폭탄이 된다. 따라서 오라클 시스템은 주관적인 영역으로 치부되었던 ’가독성(Readability)’마저 정량적인 메트릭(Metric)으로 환산하여 통제해야 한다.

1. 인지적 가독성(Cognitive Readability) 메트릭의 정량화

가독성을 측정하기 위해 오라클은 기존의 복잡도 지표(Cyclomatic Complexity)를 넘어선, 인간 중심의 메트릭 알고리즘을 파이프라인에 이식해야 한다. 대표적인 것이 소나큐브(SonarQube) 등에서 활용하는 인지적 복잡도(Cognitive Complexity) 방식이다.

• 오라클 정적 분석기는 단순히 if 문의 갯수를 세는 것을 넘어, 조건문이 얼마나 깊게 중첩(Nesting)되었는지를 스캔한다. if문 안에 for문이 있고 그 안에 다시 switch문이 들어가는 식의 3-Depth 코드는 치명적인 가독성 감점을 받는다.
• 할당과 람다(Lambda)의 남용: 한 줄의 코드 코드 라인(LoC)에 단락 평가(&&, ||)나 삼항 연산자(? :)가 3개 이상 중첩될 경우, 코드의 수평적 복잡성(Horizontal Complexity)이 임계치를 넘은 것으로 판단한다. LLM은 똑똑해 보이려고 이런 One-liner 코드를 즐겨 쓰지만, 엔터프라이즈 오라클은 이를 ’나쁜 패턴’으로 규정하고 거부해야 한다.

2. 네이밍 컨벤션과 코멘트(Comment) 밀도의 수학적 검증

가독성의 절반은 이름 짓기(Naming)와 주석(Comment)에서 온다. 과거의 린터는 변수명이 카멜 케이스인지만 검사했다면, 현대의 지능형 오라클은 변수명의 ’의미론적 적합성’을 평가한다.

• 매직 변수/메서드 척결: data, info, process(), handle() 등 아무런 컨텍스트도 담고 있지 않은 모호한(Vague) 이름들이 연속적으로 발견될 경우, 오라클은 린트 스코어를 폭락시킨다.
• 문서화 밀도 측정(Documentation Density): 파이썬의 pydocstyle 같은 툴을 오라클에 통합하여, 선언된 클래스와 퍼블릭(Public) 메서드 모듈의 코드 라인 수 대비 Docstring(주석) 비율을 계산한다. 만약 LLM이 500줄 짜리 복잡한 비즈니스 로직을 짜놓고 단 한 줄의 주석도 달지 않았다면, 가독성 오라클은 “설명이 불충분함(Low Comment Density)“을 이유로 티켓을 반려한다.

3. 임계값(Threshold) 기반의 Hard Block 시스템

“코드를 가독성 있게 짜라“라는 말은 프롬프트에 백날 적어봐야 통하지 않는다. 시스템적으로 “가독성 점수가 70점 미만이면 빌드 파이프라인이 멈춘다“는 하드 블록(Hard Block) 체계가 필요하다.

• 오라클 아키텍트는 린터 플러그인(예: eslint-plugin-sonarjs)을 연동하여, 함수 하나당 최대 인지 복잡도가 15를 넘거나, 중첩 깊이(Max Depth)가 3을 초과하는 순간 Error 레벨로 파싱되도록 설정한다.
• 가독성 임계값을 넘나드는 코드가 감지되면, ओ라클은 이를 무작정 버리는 대신 LLM에게 리팩토링(Refactoring) 전용 프롬프트를 반송한다. “당신이 작성한 parse_data 함수의 인지 복잡도가 18점을 기록하여 한계치(15)를 초과했습니다. 이 덩어리 함수를 3개의 역할별 보조 함수(Helper Sub-functions)로 쪼개고, 복잡한 삼항 연산자를 명시적인 분기문으로 풀어서 재작성하십시오.”

AI 생성 코드의 가독성 제어는 인간과 기계 사이의 타협점(Trade-off)을 찾는 과정이 아니다. 기계(LLM)가 만들어낸 코드를 궁극적으로 책임지고 유지보수해야 할 주체는 결국 인간(Human)이라는 점을 각인시키기 위해, 기계의 코드 작성 방식을 철저히 인간의 인지 구조(Cognitive Structure)에 맞추어 깎아내는 냉혹한 역설계(Reverse Engineering) 작업이다.