Claude Code로 코드 주석 자동 추가하기 — 함수에 설명을 붙여 문서화 시간을 줄이는 법

주석 없는 코드를 처음 열었을 때의 그 막막함, 개발자라면 누구나 안다. 함수 이름만 봐서는 뭘 하는지 알 수 없고, 결국 호출 스택을 세 단계씩 따라가며 코드 전체를 읽게 된다. Claude Code를 쓰면 이 문서화 작업을 명령어 한 줄로 끝낼 수 있다. 이 글은 코드 주석 자동 추가하기 — 함수에 설명을 붙이는 방법을 처음부터 따라할 수 있게 정리한다.

1. 왜 지금 이걸 봐야 하나

팀 코드베이스에서 가장 많이 듣는 말이 있다. "이 함수 뭐 하는 거예요?" 그리고 그 질문에 대한 대답은 항상 같다. "코드 읽어봐요."

주석이 없으면 코드를 읽는 데 시간이 걸리는 게 아니라, 맥락을 재구성하는 데 시간이 걸린다. 변수 이름이 v이고 함수 이름이 process라면 로직 전체를 처음부터 추적해야 한다. 하루 30분씩, 한 달이면 15시간이 그렇게 날아간다.

문제는 주석을 쓰는 게 귀찮아서가 아니다. 기능을 빠르게 만들어야 하는 상황에서 문서화는 항상 나중으로 밀린다. 그리고 나중은 대부분 오지 않는다. 3개월 뒤에 내가 짠 코드를 내가 못 읽는 상황이 그렇게 만들어진다.

Claude Code는 이 간극을 정확히 메운다. 파일을 건네면 함수 시그니처를 분석하고, 실제 로직을 추적해서 의미 있는 설명을 붙여준다. 단순히 파라미터 이름을 반복하는 게 아니라, 함수가 실제로 무슨 일을 하는지 언어로 풀어낸다.

2. 핵심 아이디어

결론부터 말하면 이렇다. Claude Code는 코드의 의미를 읽고, 그 의미를 주석으로 쓴다.

단순 도구들은 파라미터 이름을 그대로 복사해서 @param value — value 같은 무의미한 주석을 만든다. Claude Code는 실제 로직을 추적하기 때문에 다르다. 거래소 API 응답 객체에서 체결가와 수량을 파싱해 정규화된 형태로 반환 같은, 실제로 읽을 가치가 있는 설명이 나온다.

지원하는 주석 형식은 다음과 같다.

언어	스타일	특징
JavaScript / TypeScript	JSDoc	@param, @returns, @throws
Python	Google 스타일	Args:, Returns:, Raises: 섹션
Python	NumPy 스타일	과학 계산 코드에 많이 쓰임
Python	reStructuredText	Sphinx 자동 문서화 연동

팀 컨벤션에 맞춰 프롬프트에 형식을 지정하면 된다. PR 리뷰에서 스타일 지적이 나올 일이 없다.

3. 바로 따라하는 방법

설치나 설정이 따로 필요 없다. Claude Code가 이미 실행 중이라면 바로 쓸 수 있다.

JavaScript / TypeScript — JSDoc 추가

claude "utils/parser.js 파일의 모든 함수에 JSDoc 주석을 추가해줘. 파라미터 타입과 반환값 설명 포함."

실행하면 Claude가 파일을 열고 함수 하나씩 분석한 뒤, 각 함수 위에 JSDoc 블록을 붙인다. 50줄짜리 유틸 파일 기준으로 8초 안에 완료된다.

Python — Google 스타일 docstring 추가

claude "trade_calculator.py의 public 함수에 Google 스타일 docstring을 추가해줘. Args, Returns, Raises 섹션 포함."

_로 시작하는 private 함수는 건너뛰고 public 함수만 처리한다. 팀 규칙에 따라 "모든 함수" 혹은 "public 함수만" 으로 지정을 바꿔가며 쓰면 된다.

출력 예시 — 변환 전후 비교

주석 추가 전:

function parseTradeResponse(raw) {
  const price = raw.p * raw.multiplier;
  return { price, qty: raw.q, ts: raw.T };
}

주석 추가 후:

/**
 * 거래소 WebSocket 응답 객체에서 체결가와 수량을 파싱해 정규화된 형태로 반환한다.
 * 가격은 배율(multiplier)을 적용한 실제 거래 단가로 환산된다.
 *
 * @param {Object} raw - 거래소 WebSocket에서 수신한 원본 체결 데이터
 * @param {number} raw.p - 원시 체결가
 * @param {number} raw.multiplier - 거래소별 가격 배율
 * @param {number} raw.q - 체결 수량
 * @param {number} raw.T - 체결 타임스탬프 (Unix ms)
 * @returns {{ price: number, qty: number, ts: number }} 정규화된 체결 데이터
 */
function parseTradeResponse(raw) {
  const price = raw.p * raw.multiplier;
  return { price, qty: raw.q, ts: raw.T };
}

주석 추가 후 자가 검증

주석이 달렸다고 끝이 아니다. 로직과 설명이 맞는지 바로 확인하는 게 좋다. 같은 세션에서 이어서 입력하면 된다.

claude "방금 추가한 주석 중 함수 로직과 불일치하거나 애매한 설명이 있으면 목록으로 보여줘."

Claude가 방금 수정한 내용을 기억하고 있기 때문에, 파일을 다시 지정하지 않아도 맥락을 이어서 검토한다. 검증까지 한 세션에서 끝난다.

4. 운영할 때 조심할 점

복잡한 도메인 로직은 한 번 더 읽어볼 것

Claude는 코드 패턴을 잘 읽지만, 비즈니스 도메인 지식은 코드에 명시된 것만 알 수 있다. 거래소마다 다른 수수료 계산 방식이나 특수한 정산 규칙이 있다면, 자동 생성된 설명이 표면적으로는 맞아 보여도 도메인 맥락이 빠진 채로 나올 수 있다. 중요한 함수는 생성 후 직접 한 번 읽어보는 게 안전하다.

private 함수 범위 지정

모든 함수 라고 지정하면 내부용 헬퍼 함수나 임시 함수까지 전부 처리된다. 팀 컨벤션상 private 함수에는 주석을 달지 않는다면 public 함수만 또는 export된 함수만 으로 범위를 좁혀서 요청한다.

대형 파일은 섹션으로 나눠서

1000줄 이상의 파일을 한 번에 처리하면 컨텍스트가 길어져서 뒷부분 함수의 주석 품질이 떨어질 수 있다. 파일을 기능 단위 섹션으로 나눠 요청하거나, 클래스/모듈 단위로 나눠서 진행하는 게 낫다.

git diff로 최종 확인

주석 추가가 끝난 뒤에는 git diff로 실제로 무엇이 바뀌었는지 확인한다. 주석만 추가되었는지, 기존 로직이 건드려지지 않았는지 한 번 훑어보는 게 좋다. 실수는 드물지만, 코드 변경이 섞여들어갈 가능성을 배제하는 습관이다.

git diff --stat        # 변경된 파일 수 확인
git diff utils/parser.js  # 실제 변경 내용 확인

자주 묻는 질문

주석 자동 추가는 어떤 상황에서 쓰는 게 좋을까?

레거시 코드를 처음 인수받았을 때, 온보딩 중인 팀원이 코드를 읽어야 할 때, 그리고 오래된 유틸 파일을 리팩토링하기 전 맥락을 정리할 때 효과가 크다. 새로 짠 기능 파일이라면 개발 직후 바로 쓰면 기억이 살아있는 상태에서 정확한 주석이 나온다.

적용하기 전에 무엇을 확인해야 할까?

팀의 주석 스타일 컨벤션을 먼저 확인한다. JSDoc인지, Google 스타일인지, 아니면 자체 형식이 있는지를 프롬프트에 명시해야 일관성이 유지된다. 또한 이미 주석이 달린 함수가 있다면 "기존 주석이 없는 함수만" 이라고 지정해서 중복을 피한다.

결과가 제대로 나왔는지 어떻게 검증할까?

두 가지 방법을 같이 쓴다. 첫째, 같은 세션에서 방금 추가한 주석 중 함수 로직과 불일치하는 설명을 보여줘 라고 바로 요청해 자가 검증을 돌린다. 둘째, git diff 로 변경 내용을 훑어보며 주석 외에 코드 로직이 바뀐 부분은 없는지 확인한다. 두 단계를 거치면 품질과 안전성을 동시에 잡을 수 있다.

마무리

주석은 미래의 나에게 보내는 메모다. Claude Code는 그 메모를 지금 당장 써준다. claude "파일에 JSDoc 추가해줘" 한 줄이면 문서화 시간 절반이 사라진다. 지금 열려 있는 파일에 바로 써보자.

다음 글에서는 Claude Code로 테스트 코드를 자동 생성하는 방법을 다룬다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 입문
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독