Does code cleanliness affect coding agents? A controlled minimal-pair study

Who Should Read

Claude Code, Cursor 같은 AI 코딩 에이전트를 실제 프로젝트에 도입 중인 개발자나 팀 리드. 특히 에이전트 사용 비용을 줄이거나 코드 리뷰 기준을 재정립하려는 엔지니어링 매니저.

Core Mechanics

• 연구의 핵심 질문은 '코드베이스의 구조적·스타일적 품질(cleanliness)이 에이전트의 코드 탐색 및 수정 능력에 영향을 주는가?'였는데, 기존 벤치마크들은 이를 전혀 측정하지 않고 있었다.
• 실험 설계에는 'minimal pair(최소 쌍)'라는 개념을 썼다. 아키텍처, 의존성, 외부 동작은 동일하지만 정적 분석 규칙 위반 수와 인지 복잡도(cognitive complexity)만 다른 두 버전의 저장소를 쌍으로 구성했다.
• 페어는 두 방향으로 만들었다. 깨끗한 코드를 에이전트로 일부러 지저분하게 만든 버전과, 지저분한 코드를 에이전트로 정리한 버전을 각각 생성했다. 총 6쌍의 저장소에 33개 태스크를 정의했다.
• Claude Code로 660번의 시도를 한 결과, 코드 cleanliness는 에이전트의 태스크 통과율(pass rate) 자체에는 통계적으로 유의미한 변화를 주지 않았다. 즉, 더럽든 깨끗하든 최종 성공률은 비슷했다.
• 하지만 운영 비용(operational footprint)은 크게 달라졌다. 깨끗한 코드에서 작업한 에이전트는 토큰 사용량이 7~8% 적었고, 파일 재방문(file revisitation) 횟수가 34% 줄었다.
• 파일 재방문 감소는 단순히 토큰 절약을 넘어서 속도에도 직결된다. 에이전트가 LLM 호출 → 도구 실행 → 결과 반환을 반복할 때마다 레이턴시가 누적되는데, 탐색 횟수가 줄면 전체 작업 완료 시간도 단축된다.
• 연구팀은 'code cleanliness가 모델 선택, 에이전트 하네스(harness), 프롬프팅처럼 에이전트 동작에 실질적인 영향을 미치는 독립 요인'이라고 결론 내렸다.
• 이 결과는 AI 개발 시대에도 전통적인 유지보수성(maintainability) 원칙이 여전히 유효함을 시사한다. 깨끗한 코드는 인간 개발자뿐 아니라 에이전트의 계산 비용과 탐색 효율에도 직접 영향을 준다.

Evidence

• 실험 설계 자체에 대한 비판이 가장 많았다. '지저분하게 만든' 코드나 '정리한' 코드 모두 LLM(Opus 4.6)이 생성한 것인데, 이렇게 만들어진 코드가 실제 나쁜/좋은 코드베이스를 대표한다고 볼 수 없다는 의견이 여럿 있었다.
• 테스트 커버리지를 통제하지 않은 점도 지적됐다. 논문은 에이전트가 기존 테스트를 깨뜨렸는지 확인하지 않았는데, 이렇게 하면 토큰 소비량 비교 자체가 무의미해질 수 있다는 반론이 있었다. 최종 산출물의 품질이 다를 수 있기 때문이다.
• 반면 실무 경험을 공유한 댓글도 많았다. '데드 코드, 중복 코드, 누수 추상화가 가득한 코드베이스에서는 최신 프론티어 모델들도 코드 리뷰와 QA를 여러 번 반복하는 반면, 잘 정리된 코드에서는 1~2번 시도에 바로 성공하는 경험을 했다'는 의견이 있었다.
• NJIT에서 유사한 연구를 진행 중인 연구자가 댓글을 달았다. 자신들은 이 현상을 'Contextual Quality Contagion(맥락 품질 전염)'이라 부른다며, LLM이 코드베이스의 패턴을 모방하는 경향이 있어 나쁜 코드가 나쁜 결과를 낳는다고 설명했다. 또한 레거시 코드 패턴과 새 패턴이 혼재할 때 에이전트가 규칙을 혼동한다는 점도 언급했다.
• 실용적인 팁도 공유됐다. 에이전트에게 '인기 있는 오픈소스 Python 패키지 수준의 코드 구조를 따르도록 리팩터링하되 벤치마크 성능 회귀 없이 해라'처럼 프롬프트를 주면, 파일 이름이 시맨틱 힌트를 제공해서 에이전트가 관련 코드를 더 빨리 찾는 효과가 있다는 경험담이 있었다. 5천 줄짜리 파일은 에이전트가 여러 청크를 읽어야 해서 비효율적이라는 설명도 덧붙였다.
• 에이전트 토큰 소비의 상당 부분이 '탐색 비용'이라는 분석도 있었다. 코드 검색, 콜 사이트 추적 등 컨텍스트 구축 작업이 토큰을 많이 쓰는데, LSP(Language Server Protocol)와 AGENTS.md 같은 계층적 디렉티브를 에이전트에게 제공하면 탐색 비용을 줄일 수 있다는 구체적인 대안도 제시됐다.

How to Apply

• AI 코딩 에이전트(Claude Code, Cursor 등)로 작업하는 코드베이스가 있다면, 먼저 ESLint/SonarQube 같은 정적 분석 도구로 인지 복잡도가 높은 파일을 식별하고 우선 정리하라. 이번 연구 기준으로 토큰 사용량 7~8% 절감, 파일 재방문 34% 감소를 기대할 수 있다.
• 5천 줄 이상의 거대한 파일이 있다면, 에이전트에게 '인기 있는 오픈소스 [언어명] 패키지의 코드 구조 기준에 맞게 리팩터링하되 기존 테스트를 깨뜨리지 말 것'이라고 프롬프트를 주면 에이전트가 의미 있는 파일명과 모듈 구조를 만들어 이후 작업 효율이 올라간다.
• 에이전트용 컨텍스트 최적화가 필요하다면 AGENTS.md(또는 CLAUDE.md)에 모노레포 디렉토리 구조와 각 모듈의 역할을 명시하고, 에이전트에게 LSP 접근 권한을 주면 탐색 횟수와 레이턴시를 추가로 줄일 수 있다.
• 레거시 코드와 새 코드가 혼재한 프로젝트라면, 에이전트가 어떤 패턴을 따라야 하는지 AGENTS.md나 시스템 프롬프트에 명시적으로 지정하라. 그렇지 않으면 에이전트가 오래된 패턴을 모방해서 일관성 없는 코드를 생성하는 'Contextual Quality Contagion' 현상이 생긴다.

Code Example

# Python 코드베이스 리팩터링 프롬프트 예시 (HN 댓글에서 공유)
Refactor the Python code to make it more Pythonic,
e.g. fewer classes/singletons, especially if it will provide a speedup.
The Python code **MUST** follow code organization standards expected of
popular open-source Python packages without causing any benchmark
performance regressions.

# Rust 코드베이스용 변형
The Rust codebase in `/src` has become bloated with several files >1k LoC.
Refactor the Rust codebase to fit code organization standards expected of
popular open-source Rust code without causing any benchmark performance
regressions.

Terminology

Related Papers

• Distributed Attacks in Persistent-State AI Control

  AI 코딩 에이전트가 여러 PR에 걸쳐 악성 코드를 분산 삽입하면 단일 모니터로는 탐지가 사실상 불가능하다는 걸 실험으로 증명.

• Towards Robustness against Typographic Attack with Training-free Concept Localization

  이미지에 텍스트를 덧붙여 AI를 속이는 Typographic Attack을 추가 학습 없이 Attention Head 분석만으로 막는 방법

• Senior SWE-Bench: open-source benchmark that assesses agents as senior engineers

  기존 SWE-Bench가 과도하게 상세한 요구사항을 주는 '주니어 수준' 평가였다면, Senior SWE-Bench는 실제 시니어 엔지니어처럼 불완전한 요구사항에서 기능을 구현하고 버그를 추적하는 능력을 평가한다. 현재 최고 성능 모델(Claude Opus 4.8)도 24%밖에 못 푸는 난이도로, AI 코딩 에이전트의 실제 한계를 측정하려는 시도다.

• Apple 'Hide My Email' vulnerability reveals peoples' real email addresses

  iCloud+ 구독자가 프라이버시 보호용으로 사용하는 Apple의 Hide My Email 서비스에 1년 넘게 패치되지 않은 취약점이 있어, 공격자가 숨겨진 실제 이메일 주소를 알아낼 수 있다.

• Words Speak Louder Than Code: Investigating Cognitive Heuristics in LLM-Based Code Vulnerability Detection

  LLM 보안 스캐너가 코드 내용보다 '누가 썼는지', '어떻게 물어보는지'에 더 크게 반응해서 취약점을 97%까지 은폐시킬 수 있다.

• Robust Harmful Features Under Jailbreak Attacks: Mechanistic Evidence from Attention Head Specialization in Large Language Models

  Jailbreak 공격이 LLM 안전장치를 우회하는 원리를 attention head 단위로 해부하고, 공격에도 살아남는 내부 신호로 학습 없이 유해 입력을 탐지하는 방법을 제시.

Related Resources

• 원문 논문: Does Code Cleanliness Affect Coding Agents? (arXiv:2605.20049)
• ai-native-toolkit (HN 댓글에서 언급된 코드 품질 분석 도구)