AI 시대에 Javadoc은 불필요해질까?

최근 Claude Code나 GitHub Copilot을 사용하다 보면 이런 목소리를 들을 때가 있습니다.

AI가 코드를 읽을 수 있다면 Javadoc은 필요 없는 것 아닌가?

저도 한때는 그렇게 생각했습니다.

하지만 실제로 AI를 개발에 활용하면서 느낀 점은, Javadoc의 가치는 떨어지지 않았다는 것입니다.

오히려 용도가 변하여, 이전보다 더 중요해지는 상황이 늘어나고 있습니다.

기존의 Javadoc은 주로 API 이용자를 위한 문서였습니다.

예를 들어 다음과 같은 용도입니다.

• API 설명
• 인자(Argument) 설명
• 반환값(Return value) 설명
• 사용 예시 기재

하지만 AI가 코드를 작성하는 시대가 되면, 단순한 인자 설명의 가치는 상대적으로 낮아집니다.

왜냐하면 AI는 메서드 이름이나 타입 정의(Type definition)를 통해 어느 정도 추측할 수 있기 때문입니다.

반면에 AI가 어려워하는 것은 다음과 같은 정보입니다.

• 왜 그 처리가 필요한가
• 어떤 비즈니스 규칙(Business rule)을 지켜야 하는가
• 어떤 전제 조건(Precondition)이 있는가
• 무엇을 망가뜨려서는 안 되는가

즉,

설계 의도나 비즈니스 규칙을 전달하기 위한 Javadoc

이 중요해지고 있습니다.

AI는 코드를 읽을 수 있습니다.

하지만 설계자의 의도까지는 읽을 수 없습니다.

예를 들어 다음 코드입니다.

public void approve(Order order) {
...
}

인간이라면,

• 가승인인가?
• 최종 승인인가?
• 누구나 승인 가능한가?
• 취소된 주문은?

등을 생각합니다.

하지만 AI는 거기까지 추측할 수 없습니다.

결과적으로,

동작하는 코드는 만들지만, 비즈니스적으로 잘못된 코드를 생성하는

경우가 있습니다.

여기서 중요해지는 것이 Javadoc입니다.

Javadoc은 인간을 위한 문서에서,

AI에게 설계 컨텍스트(Context)를 전달하는 매체

로 진화하고 있습니다.

자주 보이는 것은 이것입니다.

/**
* 주문을 승인합니다.
*
...

이것은 거의 코드와 동일한 정보입니다.

AI에게도 인간에게도 가치가 높지 않습니다.

설계 의도나 비즈니스 규칙을 적으면 가치가 생깁니다.

/**
* 주문을 승인한다.
*
...

이 정도로 작성되어 있으면, Claude Code나 Copilot은 상당히 높은 정밀도로 의도를 이해할 수 있습니다.

실질적으로 Design by Contract의 정보를 제공하고 있는 상태입니다.

여기서 등장하는 것이 Design by Contract (계약에 의한 설계) 입니다.

Design by Contract에서는 주로 다음을 정의합니다.

종류	내용
Preconditions	호출 전에 충족해야 하는 조건
...

예를 들어 주문 승인 처리라면,

• Preconditions: 주문 상태가 PENDING이어야 함
• Postconditions: 주문 상태가 APPROVED가 됨
• Invariants: 승인된 주문은 재승인할 수 없음

이 됩니다.

AI는 코드로부터 비즈니스 규칙을 추측하는 것을 어려워합니다.

하지만 계약으로서 명문화되어 있다면, 그것을 전제로 코드 생성이나 리뷰를 수행할 수 있게 됩니다.

최근에는 Javadoc 자체도 진화하고 있습니다.

Java 23에서는 Markdown 형식의 Javadoc이 정식 지원되었습니다.

예를 들어 다음과 같이 기술할 수 있습니다.

/// 주문을 승인한다
///
/// ## Preconditions
...

기존의 HTML 태그 중심의 기술보다 압도적으로 읽기 쉬워졌습니다.

인간뿐만 아니라 AI에게도 이해하기 쉬운 포맷입니다.

Claude Code를 사용하다 보면 알 수 있듯이, AI는 코드뿐만 아니라 주변 정보도 적극적으로 참조합니다.

특히 다음 정보는 생성 결과에 큰 영향을 미칩니다.

• Javadoc
• README
• ADR (Architecture Decision Record)
• 설계서
• 테스트 코드

그중에서도 Javadoc은 소스 코드와 가장 가까운 곳에 존재합니다.

즉 AI에게는,

설계자가 코드에 심어놓은 가장 신뢰할 수 있는 컨텍스트

가 됩니다.

실제로 Claude Code에 구현 요청을 할 때도,

Javadoc이 충실한 코드베이스와 그렇지 않은 코드베이스 사이에는 생성 품질에 큰 차이가 납니다.

제가 최근 의식하고 있는 것은, Service 클래스의 공개 메서드에 설계 의도를 적는 것입니다.

@Service
public class RefundService {
/**
...

이 정보는 코드로부터 추측할 수 없습니다.

하지만 AI에게는 극히 중요한 컨텍스트가 됩니다.

또한 리뷰 시에도,

• 계약 위반 (Contract violation)
• 업무 규칙 위반 (Business rule violation)
• 불변 조건 파괴 (Breaking invariants)

를 검출하기 쉬워집니다.

제가 추천하는 우선순위는 다음과 같습니다.

• 설계 의도 (Design intent)를 작성한다
• 업무 규칙 (Business rule)을 작성한다
• 불변 조건 (Invariant)을 작성한다
• 사전 조건 (Precondition)을 작성한다
• 사후 조건 (Postcondition)을 작성한다

반대로,

/**
* 고객을 가져온다
*...

와 같이 코드를 읽으면 알 수 있는 설명은 우선순위를 낮춰도 문제없습니다.

AI 시대에 가치가 높은 것은,

"무엇을 하는가"가 아니라 "왜 그렇게 하는가"

이기 때문입니다.

AI 시대가 되었다고 해서 Javadoc이 불필요해지는 것은 아닙니다.

오히려 역할이 바뀌었습니다.

기존의 Javadoc은 API 이용자를 위한 것이었습니다.

앞으로의 Javadoc은,

• 설계 의도 (Design intent)
• 업무 규칙 (Business rule)
• 불변 조건 (Invariant)
• 디자인 바이 컨트랙트 (Design by Contract)

를 AI에게 전달하기 위한 설계 문서로서 기능합니다.

Claude Code나 Copilot이 코드를 작성하는 시대이기에 더욱,

"코드를 설명하는 Javadoc"이 아니라, "설계를 설명하는 Javadoc"

을 작성하는 가치가 높아지고 있는 것이 아닐까요?

본 기사는 JJUG CCC 2026 Spring에서 얻은 배움을 바탕으로 정리 및 고찰한 내용입니다.