168,000줄의 주석을 삭제해봤더니, AI 에이전트는 아무것도 눈치채지 못했다

저희 소스 코드의 거의 3분의 1이 주석으로 이루어져 있었습니다. 저는 이 모든 주석을 삭제하고, AI 에이전트에게 두 버전의 코드베이스(주석 포함/제외)에 대해 각각 동일한 기능을 세 번씩 구현하도록 요청했습니다. 그 결과로 작성된 코드는 주석 유무와 관계없이 똑같이 훌륭했습니다.

만약 실제 코드베이스에서 에이전트를 사용하면서, 주석이 도움이 되는지, 속도를 늦추는지, 아니면 전혀 상관없는지 궁금하다면, 제가 알아낸 것이 있습니다.

왜 이런 실험을 했나

이 영상(23:07 부근)에서 Lauren은 에이전트가 코드에 주석을 작성하도록 허용하지 않는다고 언급합니다. 저희의 코드베이스는 그 반대입니다. 주석으로 가득 차 있으며, 대부분은 에이전트에 의해 작성되었습니다.

그래서 저는 궁금했습니다. 이 모든 주석들이 에이전트에게 도움이 되는 걸까요, 아니면 단순히 읽어야 할 추가 텍스트일까요?

실험 개요

주석을 모두 제거한 코드베이스 사본을 만들었는데, 총 약 168,000줄에 달했습니다. 그리고 동일한 작업을 같은 에이전트에게 두 사본(주석 포함/제외)에 대해 각각 세 번씩 수행하도록 요청하고 결과를 동일하게 확인했습니다. 이 실험은 작은 작업과 더 큰 작업, 총 두 가지 과제를 대상으로 진행되었습니다.

결과

모든 실행에서 모든 검사(lint, type checks 및 기존 테스트), 그리고 더 큰 작업의 경우 에이전트가 본 적 없는 숨겨진 테스트까지 통과했습니다. 별도의 AI 심사관은 어떤 사본에서 나온 결과인지 알지 못한 채 각 결과를 평가했습니다 (자세한 내용은 아래 참조).

작은 작업: 열려 있는 모든 창 타일링하기 (19점 만점)

더 큰 작업: 창을 항상 최상단에 유지하기 (23점 만점)

이 수치들은 세 번의 실행에 대한 평균값입니다. 점수 차이는 노이즈 범위 내에 있으며, 더 큰 작업의 경우 비용 역시 마찬가지였습니다. 작은 작업에서는 에이전트가 주석을 제외했을 때 약 22% 적은 토큰을 사용했는데, 이는 당연한 결과였습니다. 읽어야 할 내용 자체가 줄었기 때문입니다.

더 큰 작업에는 함정이 있었습니다. 고정된 상태(pinned state)는 페이지 새로고침에도 살아남아야 하며, 창 세션(window session)을 저장하는 PHP 함수는 알지 못하는 키를 모두 삭제합니다. 이것을 놓치면 기능은 새로고침할 때까지는 괜찮아 보입니다. 바로 주석이 도움이 될 것이라고 예상되는 종류의 문제입니다. 여섯 번의 실행 모두에서 주석 유무와 관계없이 이 문제를 발견했습니다.

한 번의 실행으로는 충분하지 않은 이유

제 첫 계획은 각 브랜치를 한 번씩 실행하는 것이었습니다. 다행히도 그렇게 하지 않았습니다.

더 큰 작업의 경우, 주석이 포함된 세 번의 실행은 각각 8.21M, 8.79M, 10.17M 토큰을 사용했습니다. 주석이 없는 세 번의 실행은 각각 7.01M, 9.70M, 10.64M 토큰을 사용했습니다.

만약 제가 각 브랜치에서 하나씩 실행 결과를 골랐다면, 상반된 두 개의 블로그 게시물을 작성할 수 있었을 것입니다. 10.64M과 8.21M을 비교하면, 주석을 제거하는 것이 에이전트에게 30% 더 많은 비용을 발생시킵니다. 7.01M과 10.17M을 비교하면, 에이전트를 31% 더 저렴하게 만듭니다. 같은 작업, 같은 코드, 같은 날입니다.

에이전트는 결정론적(deterministic)이지 않습니다. 따라서 하나를 측정하고 있다면 여러 번 실행해야 합니다.

제가 진행한 방식

에이전트: 높은 노력 수준(high effort)의 Claude Code with Opus 5.5를 사용했습니다. 모든 실행에서 동일한 모델과 설정을 사용했습니다.두 코드베이스: 메인 브랜치와 주석을 제거한 사본입니다. 둘 다 컴파일하여 결과 코드가 동일한지 확인했습니다. 남아있는 유일한 주석은 린트 지시문(lint directives)이나 플러그인 헤더처럼 도구가 작동하는 데 필요한 것들로, 약 800줄에 불과합니다.작업: 두 가지 실제 기능이며, 두 브랜치 모두 동일한 프롬프트를 사용했습니다.검사 항목: 프로젝트 자체의 린트(lint), 타입 검사(type checks) 및 테스트입니다. 더 큰 작업에서는 에이전트가 작업을 마친 후 제가 추가한 숨겨진 테스트도 포함되어, 코드를 작성하여 통과하는 것만으로는 안 되게 했습니다.심판: 별도의 Claude 세션이 각 변경 사항을 읽고 실행 전에 작성된 체크리스트에 따라 점수를 매겼습니다. (작동 여부, 프로젝트 컨벤션 준수 여부, 테스트 포함 여부 등). 변경 사항에는 무작위 이름이 붙었기 때문에 심판은 어떤 브랜치에서 왔는지 알 수 없었습니다.

실행: 작업당 브랜치별로 세 번씩 실행했으며, 시간대 영향이 양쪽 모두에게 동일하게 미치도록 브랜치를 교차했습니다.

저의 결론

에이전트에게는 코드 주석이 작성하는 코드의 품질에 아무런 차이를 만들지 않습니다. 도움이 되지도 않고, 해롭지도 않습니다.

따라서 코드를 읽는 사람들에게 어떤 역할을 하는지에 따라 주석을 유지하거나 삭제하세요. 에이전트를 위해서가 아닙니다.

이것이 주석이 효과가 전혀 없다는 것을 증명하는 것은 아닙니다. 저는 하나의 모델과 두 가지 태스크, 그리고 브랜치당 세 번의 실행으로 테스트했는데, 이는 큰 영향을 배제하기에는 충분하지만 작은 영향을 배제하기에는 부족합니다.

다음 내용: 주석은 아무 차이가 없었지만, 저희가 docs/ 폴더와 AGENTS.md 파일을 제거했을 때는 달랐습니다. 이것이 다음 게시물입니다.

부록: 데이터 및 링크

• 주석이 포함된 코드베이스
• 주석이 없는 코드베이스
• 실제로 무엇을 제거했는지 (GitHub에서는 일부만 보일 수 있습니다)
• 풀 리퀘스트로 제공되는 두 가지 소규모 태스크 실행: 주석 포함 PR 974 및 주석 미포함 PR 975
• 전체 결과, 모든 실행: 결과 페이지
• 실험 스크립트와 평가 기준(rubrics)을 보고 싶다면 모두 여기에 있습니다
• scc로 측정된 코드 라인 수

플러그인 소스 코드는 테스트, 문서(docs), 또는 도구링을 제외하고 플러그인에 포함되는 코드(src/, includes/, apps/ 및 CSS)를 의미합니다.