지난 기사에서는 주석에 대해 서로 다른 생각을 가진 『Clean Code』와 『A Philosophy of Software Design』의 저자 두 명(UB, John)의 논쟁을 살펴보고, 주석의 가치를 판단하는 기준에 대해 생각해 보았습니다.

지난번에는 "주석의 독자는 인간이다"라는 것을 전제로 했지만, 지금은 LLM(Claude나 ChatGPT의 기반이 되는 대규모 언어 모델 (Large Language Model))도 코드와 주석을 읽습니다.

이 기사에서는 다음 내용을 다룹니다.

• 주석은 LLM의 코드 이해를 돕는가
• 부패한 주석은 LLM에 어떤 영향을 주는가
• AI용 설정 파일(AGENTS.md / CLAUDE.md)에는 무엇을 써야 하는가
• 부패한 주석의 검출은 AI에게 맡길 수 있는가

주석이 LLM의 이해를 돕는지 여부를 직접 측정한 연구가 있습니다.

MITRE 연구 (2025)

Claude 3, GPT-4, Llama 3, Mixtral의 4개 모델을 대상으로, 주석의 유무에 따라 레거시 코드 (Legacy Code)의 이해도가 어떻게 변하는지를 퀴즈 형식으로 측정한 연구입니다.

기초 퀴즈에서는 주석이 있을 때 96%, 없을 때 84%로 주석이 있는 편이 정답률이 높았습니다 (응용 퀴즈에서는 있을 때 90%, 없을 때 84%. 저자들은 이를 "예비적인 결과"라고 명시함).

버그 자동 수정 연구 (ICPC 2026)

학습 시와 추론 시 모두 주석이 제공되었을 경우, LLM에 의한 버그 자동 수정의 정밀도가 최대 3배 개선되었다고 보고하고 있습니다.

RepoQA (2024)

리포지토리 (Repository)의 방대한 코드를 LLM에게 읽게 하여, "이 설명에 해당하는 함수는 무엇인가"를 찾아내게 하는 테스트입니다.

주석을 삭제한 코드의 스코어가 올라가는 모델이 많이 관찰되었습니다. 논문에서도 "모델은 주석이 없는 편이 코드를 더 잘 이해할 수도 있다"라고 보고하고 있습니다.

13개 모델 비교 연구 (2025)

범용 모델과 코드 특화형 모델 등 총 13종류에 동일한 코드를 주석이 있는 경우와 없는 경우로 읽게 하여, 이해 성적을 비교한 연구입니다.

주석에 의한 개선은 평균 +3.7%로, 통계적으로 유의미한 차이는 아니었습니다. CodeLlama 등 코드에 특화된 모델에 한해서는 주석이 없는 편이 더 좋은 성적을 거두었습니다.

요약하면 다음과 같습니다.

지난 기사에서 소개한 인간 대상 실험과 마찬가지로, 독자를 LLM으로 바꾸어도 효과는 갈리고 있습니다.

MITRE 연구 (2025)

정확한 주석이 있을 때 평균 73%였던 이해도는, 주석을 코드와 무관한 설명문으로 모두 교체했을 때 61%까지 떨어졌습니다 (대상은 타이머 처리 코드인데, 농구 경기 시뮬레이션 프로그램의 설명문을 붙인 경우). 주석란에 거짓이 있으면 코드 자체의 독해까지 악화됩니다.

다만, "주석의 20%만 부정확하게 교체하는" 현실적인 부패 방식에서는 영향이 거의 나타나지 않았습니다.

Comment Traps (FSE 2026)

GitHub Copilot과 Cursor를 대상으로, 컨텍스트 (Context) 중에 결함을 포함한 주석 처리된 코드(삭제되지 않고 주석 처리된 상태로 남겨진 오래된 코드)가 섞여 있으면, 생성되는 코드의 결함률이 최대 58.17%에 달했습니다.

자연어 주석이 아니라 주석 처리된 코드에 관한 이야기지만, "주석란에 방치된 오래된 정보가 새로운 코드에 결함을 가져온다"는 점에서 주석의 부패와 동일한 문제를 가지고 있습니다.

불일치 커밋 분석 (2024)

OSS의 커밋 히스토리 (Commit History)를 조사한 연구입니다. 코드를 변경했음에도 주석을 수정하지 않는 등, 코드와 주석의 불일치를 만든 변경은 그렇지 않은 변경에 비해 7일 이내에 버그를 유발할 확률이 약 1.5배 높았습니다.

이러한 데이터들은 UB와 John의 주장 모두를 뒷받침합니다.

• John (써야 한다): 주석은 LLM의 레거시 코드 이해를 돕는다
• UB (부패한 주석은 해롭다): 주석란의 거짓이나 주석 처리된 채 남겨진 오래된 코드는 LLM의 독해와 생성을 악화시킨다

인간은 의심스러운 주석을 무시하고 읽을 수 있지만, LLM은 컨텍스트에 들어온 것을 무시할 수 없습니다. AI의 등장은 "좋은 주석을 쓰는 것"과 "부패시키지 않는 것" 둘 다 더욱 중요해졌다고 생각합니다.

2025년, AGENTS.md라는 공통 포맷이 공개되었습니다. 리포지토리 루트에 두는 코딩 에이전트 (Coding Agent)용 설명 파일로, 공식 사이트에서는 "에이전트를 위한 README"라고 설명하고 있습니다.

OpenAI(Codex), Google(Jules), Cursor 등 에이전트 개발사들이 관여했으며, 같은 해 12월에는 관리 주체가 Linux Foundation 산하의 Agentic AI Foundation으로 이전했습니다. 이때 이미 60,000개 이상의 OSS 리포지토리에서 사용되고 있었습니다.

모든 도구가 이 포맷을 사용하는 것은 아니며, Claude Code처럼 자체 파일을 사용하는 도구도 있지만, 역할은 같습니다.

그렇다면 이러한 종류의 파일에는 무엇을 작성해야 할까요? 또한 AI에게 어떤 주석을 달도록 시키는 것이 좋을까요? 각각에 대한 가이드라인이 있습니다.

• Anthropic의 가이드라인 (CLAUDE.md에 무엇을 쓸 것인가): 코드만으로는 추론할 수 없는 내용을 작성합니다. 예를 들어, 추론하기 어려운 빌드 명령어나 기본값에서 벗어난 코드 스타일 규칙 등이 해당됩니다. 반대로 '깨끗한 코드를 작성하라(write clean code)'와 같은 자명한 지시는 적지 않습니다.
• GitHub의 가이드라인 : 'WHY를 설명하는 데 필요한 경우에만 주석을 달고, WHAT은 설명하지 않는다'는 것입니다. 피해야 할 예시로 awesome-copilot 등이 언급됩니다.

(AI에게 주석을 어떻게 작성하도록 시킬 것인가)로는 // 카운터를 1 증가시킨다(Increment counter by one)와 같은 것이 제시되었습니다.

이 두 가지는 지난 기사에서 본 판별 기준과 동일합니다.

우리는 '코드를 읽으면 알 수 있는 것은 적지 않고, 코드에 넣을 수 없는 것을 적는다'는 관점을 AI용 설정 파일이라는 형태로 다시 배우고 있습니다.

그리고 지난 기사의 판별 기준 중 하나인 '부패하는가(腐るかどうか)'는 AGENTS.md나 CLAUDE.md의 한 줄 한 줄에도 적용됩니다. 예를 들어, CLAUDE.md에 작성된 빌드 명령어는 프로젝트 측에서 명령어가 바뀌어도 자동으로 업데이트되지 않기 때문에 방치하면 코드와 불일치한 오래된 정보가 됩니다. 이는 주석의 부패와 같은 구조입니다. 게다가, 이렇게 오래된 CLAUDE.md를 읽는 것은 부패한 정보를 무시할 수 없는 LLM에게는 문제입니다.

주석이 부패하는 것이 문제라면, 부패한 주석을 AI가 찾아내도록 할 수는 없을까요?

실제로 코드와 주석의 불일치를 탐지하는 연구는 활발합니다. C4RLLaMA(ICSE 2025)는 기존 도구인 DocChecker가 F1 스코어 74.3%를 달성했던 동일한 평가 조건에서 89.0%를 달성했으며, CCISolver(2025)는 다른 평가 데이터를 통해 89.54%를 보고했습니다.

일부 프로그래밍 언어는 주석이 부패하지 않도록 하는 메커니즘을 가지고 있습니다. Rust나 Python의 doctest는 주석 안에 작성된 사용 예시 코드를 실제로 실행하여, 작성된 대로 결과가 나오는지 확인합니다. 구현이 바뀌어 사용 예시가 오래되면 테스트가 실패하면서 알 수 있게 됩니다.

다만, doctest가 지킬 수 있는 것은 코드 예시에 한정되어 있어, '이 값은 밀리초 단위'와 같은 문장 주석이 코드와 어긋나도 탐지할 수는 없습니다.

C4RLLaMA나 CCISolver가 탐지하는 것은 '문장 주석과 코드의 불일치'입니다. doctest가 지킬 수 없었던 영역도 이 메커니즘으로 보호받을 수 있게 될지도 모릅니다.

• 주석이 LLM의 이해를 돕는지 여부는 연구에 따라 결과가 갈립니다
• 부패한 주석의 해악은 LLM의 독해와 생성 양쪽에서 측정되고 있습니다
• AGENTS.md / CLAUDE.md에 작성해야 할 것은 지난 기사의 판별 기준과 동일합니다.