AI가 코드를 이해하게 만드는 방법

코드를 읽는 것과 이해하는 것은 다르다

AI 코딩 에이전트는 코드를 읽을 수 있습니다. 하지만 이해하는 것은 다른 문제입니다.

함수의 이름과 로직을 파악하는 것은 가능하지만, “이 함수가 어떤 비즈니스 규칙을 구현하는지”, “이 에러 코드가 어떤 상황에서 발생하는지”, “이 배치가 왜 새벽 3시에 도는지”는 코드만 봐서는 알 수 없습니다.

결과적으로 AI에게 코드 리뷰를 맡기면 문법적 피드백은 주지만, “이 변경이 정산에 영향을 줄 수 있다”는 수준의 판단은 하지 못합니다.

접근: 코드에서 메타데이터를 추출한다

우리는 소스코드의 구조와 맥락을 AI가 이해할 수 있는 형태로 변환하는 방법을 설계했습니다. 핵심 아이디어는 코드의 “왜”와 “맥락”을 별도의 메타데이터로 분리하는 것입니다.

4계층 메타데이터

계층	설명	포함 내용
시스템 맵	전체 아키텍처 조감도	서비스 목록, 의존 관계, 기술 스택
도메인 모델	핵심 엔티티와 규칙	엔티티 관계, 상태 전이, 비즈니스 규칙
API/플로우	주요 흐름	컨트롤러, 시퀀스, 이벤트, 배치
운영 컨텍스트	실행 환경 정보	설정값, 외부 연동, 배포 구조

메타데이터의 형식

AI가 잘 처리하는 형식은 정해져 있습니다. 필드가 5개 이하면 YAML, 비교가 필요하면 테이블, 순서가 중요하면 번호 리스트. 이 규칙을 일관되게 적용하면 AI의 해석 정확도가 올라갑니다.

비즈니스 규칙은 특히 구조화된 어설션(Structured Assertion) 형태로 작성합니다.

규칙: 주문 취소는 배송 시작 전에만 가능하다
조건: order.status in [PENDING, CONFIRMED]
위반 시: OrderCancelNotAllowedException
근거: 물류 비용 발생 후 취소 불가 정책

이렇게 작성하면 AI가 코드 리뷰 시 “이 변경이 주문 취소 규칙에 영향을 줄 수 있습니다”라고 경고할 수 있습니다.

CI/CD로 자동 유지

메타데이터는 코드와 함께 진화해야 합니다. 수동으로 관리하면 금방 낡아집니다.

우리가 설계한 방식은:

1. 코드 변경 시 — CI 파이프라인에서 변경된 파일의 메타데이터를 자동 갱신
2. PR 리뷰 시 — 메타데이터 변경 여부를 체크하여, 로직 변경인데 메타데이터가 안 바뀌었으면 경고
3. 정기 스캔 — 전체 코드베이스를 주기적으로 스캔하여 메타데이터 커버리지 측정

배운 것

완벽한 문서화보다 핵심 맥락만 있으면 된다

모든 코드에 메타데이터를 붙일 필요는 없습니다. 비즈니스 규칙이 복잡한 부분, 외부 연동이 있는 부분, 장애가 자주 나는 부분에 집중하면 20%의 메타데이터로 80%의 효과를 얻습니다.

AI의 맥락 창은 넓어졌지만, 구조화는 여전히 중요하다

100만 토큰 컨텍스트가 가능해져도, 구조 없이 던져주면 AI의 응답 품질이 떨어집니다. 잘 정리된 메타데이터 1페이지가 정리 안 된 코드 100페이지보다 낫습니다.

메타데이터는 사람에게도 유용하다

AI를 위해 만든 메타데이터가 신규 개발자 온보딩에도 효과적이었습니다. “시스템 맵 → 도메인 모델 → 내가 담당할 API”순서로 읽으면, 코드를 직접 읽기 전에 전체 맥락이 잡힙니다.