주석 16만 8천 줄을 지워도 AI 에이전트가 쓴 코드 품질은 그대로였다

한 개발자가 자신의 코드베이스에서 주석을 전부 걷어낸 뒤, 같은 AI 코딩 에이전트에게 같은 기능을 두 버전에서 각각 세 번씩 구현하게 했다. 사라진 주석은 약 16만 8천 줄. 결과는 양쪽이 사실상 같았다. 주석은 에이전트가 쓰는 코드의 품질을 끌어올리지도, 떨어뜨리지도 않았다.

실험에 쓰인 에이전트는 Claude Code에 Opus 5.5를 high effort로 설정한 것이었고, 모든 실행에서 모델과 설정을 동일하게 유지했다. 과제는 두 개였다. 작은 과제는 열린 창을 모두 타일링하는 기능으로 19점 만점, 큰 과제는 특정 창을 항상 위에 고정하는 기능으로 23점 만점이었다. 검증은 프로젝트 자체의 lint, 타입 체크, 기존 테스트로 이뤄졌고, 큰 과제에는 에이전트가 존재를 모르는 숨은 테스트가 추가로 붙었다. 채점은 별도의 Claude 세션이 맡았는데, 각 변경사항에 무작위 이름을 붙여 어느 브랜치에서 나온 코드인지 알 수 없게 만들고 사전에 작성한 체크리스트로 평가했다.

점수 차이는 노이즈 범위 안이었다. 비용도 큰 과제에서는 유의미한 차이가 없었다. 작은 과제에서는 주석이 없는 쪽이 토큰을 약 22% 덜 썼는데, 읽을 텍스트 자체가 줄었으니 당연한 결과다.

큰 과제에는 함정이 하나 있었다. 고정된 상태가 페이지 새로고침 후에도 살아남아야 하는데, 창 세션을 저장하는 PHP 함수가 자신이 모르는 키를 조용히 버리는 구조였다. 이걸 놓치면 기능은 멀쩡해 보이다가 새로고침하는 순간 깨진다. 주석이 있었다면 도움이 됐을 법한 지점이지만, 주석이 있는 실행과 없는 실행 여섯 번 모두 이 함정을 찾아냈다.

토큰 사용량은 훨씬 시끄러웠다. 큰 과제에서 주석이 있는 세 번의 실행은 8.21M, 8.79M, 10.17M을 기록했고, 주석이 없는 세 번은 7.01M, 9.70M, 10.64M을 썼다. 각 브랜치에서 한 번씩만 골라 비교했다면 서로 정반대되는 결론을 담은 글 두 편을 쓸 수 있었을 것이다. 10.64M과 8.21M을 맞대면 주석 제거가 30% 더 비싸지고, 7.01M과 10.17M을 맞대면 31% 더 싸진다. 같은 과제, 같은 코드, 같은 날의 결과다.

실험 환경은 이렇게 구성됐다. 메인 브랜치와 주석을 제거한 사본을 만들고, 양쪽을 컴파일해 산출물이 동일한지 확인했다. 남겨둔 주석은 lint 지시자나 플러그인 헤더처럼 도구가 요구하는 약 800줄뿐이다. scc로 측정한 줄 수는 전체 저장소가 765,491줄에서 597,332줄로, 플러그인에 실제로 포함되는 소스 코드는 408,527줄에서 280,421줄로 줄었다.

이 실험은 한 영상에서 누군가 자신들은 에이전트가 코드에 주석을 쓰지 못하게 한다고 언급한 데서 출발했다. 문제의 코드베이스는 정반대여서 주석이 넘쳤고, 그중 대부분을 에이전트가 직접 작성한 상태였다. 그렇다면 이 주석들이 에이전트에게 도움이 되는지, 아니면 그저 읽어야 할 텍스트를 늘리는지가 궁금해진 것이다.

실무적으로 얻을 결론은 단순하다. 주석을 남길지 지울지는 에이전트가 아니라 코드를 읽는 사람에게 무엇을 해주는지를 기준으로 정하면 된다. 에이전트를 위해 주석을 유지해야 할 이유는 이번 측정에서 나오지 않았다.

다만 이 결과가 주석의 효과가 정확히 0이라는 증명은 아니다. 모델 하나, 과제 둘, 브랜치당 세 번이라는 표본으로는 큰 효과를 걸러낼 수 있을 뿐 작은 효과까지 배제하지는 못한다. 참고로 같은 저자는 다음 글에서 주석은 차이가 없었지만 docs/ 폴더와 AGENTS.md를 제거했을 때는 달랐다고 예고했다.