codex에게 대용량 코드베이스를 인식 시키는 방법은 어떤게 있나요?

投稿した質問数 1

1

안녕하세요 박현준님,

좋은 질문입니다. 실제 대용량 코드베이스에서 Codex를 쓸 때 가장 많이 부딪히는 부분이 바로 이 지점입니다.

결론부터 말씀드리면, 10만 개 이상의 Java 파일을 한 번에 모두 컨텍스트에 넣어서 Codex가 전체를 “통째로 이해하게” 만드는 방식은 현실적으로 어렵습니다 ㅎㅎ. 그리고 실무에서도 (최소한 저는) 보통 그렇게 사용하지 않습니다.

대신 작업 단위를 작게 나누고, 필요한 범위의 코드만 점진적으로 읽히면서 진행합니다. 예를 들어 “전체 시스템을 이해해줘”가 아니라 “이 API가 호출되는 흐름을 찾아줘”, “이 클래스가 어디서 사용되는지 추적해줘”, “이 모듈에서 validation 로직을 수정해줘”처럼 범위를 좁혀서 접근합니다. 아니면 파일을 제시하고 거기에 질문을 하시면 됩니다.

AGENTS.md도 모든 폴더마다 만드는 것이 정답은 아닙니다. 자바 프로젝트처럼 depth가 깊고 파일 수가 많은 경우에는 각 폴더마다 문서를 유지하는 방식이 오히려 관리 비용이 커질 수 있습니다. 보통은 루트에 공통 AGENTS.md를 두고, 정말 중요한 모듈이나 규칙이 다른 영역에만 추가로 두는 방식이 더 현실적입니다.

AGENTS.md에는 소스 코드 전체 설명을 넣기보다는 다음과 같은 “작업 규칙”을 넣는 것이 좋습니다.

• 프로젝트 빌드 방법

• 테스트 실행 방법

• 패키지 구조의 큰 방향

• 코딩 컨벤션(여기에 예를 주시면 좋습니다)

• 수정 전 반드시 확인해야 하는 파일

• PR 작성 기준

• 건드리면 안 되는 영역

• 자주 쓰는 명령어

즉 AGENTS.md는 코드 전체의 최신 요약본이라기보다, Codex가 이 저장소에서 작업할 때 따라야 하는 가이드에 가깝습니다.

그리고 실제로는 Codex에게 코드 탐색을 시키면서 필요한 정보를 찾게 합니다. 예를 들어 Java 프로젝트라면 클래스명, 메서드명, 인터페이스 구현체, import, 호출 관계를 검색하게 하고, 관련 파일을 읽은 뒤 수정하게 하는 식입니다. 사람이 IDE에서 “Find Usage”나 “Go to Implementation”을 쓰는 것과 비슷하게, Codex도 한 번에 모든 것을 기억하는 것이 아니라 필요한 순간에 찾아가면서 작업하게 만드는 방식입니다.

대용량 코드베이스에서는 특히 다음 흐름이 좋습니다.

1. 먼저 작업 목표를 아주 구체적으로 준다.

2. Codex에게 관련 파일과 호출 흐름을 먼저 조사하게 한다.

3. 바로 수정하지 말고 수정 계획을 먼저 설명하게 한다.

4. 영향 범위가 맞는지 확인한 뒤 수정하게 한다.

5. 관련 테스트만 먼저 실행한다.

6. 마지막에 전체 빌드나 더 넓은 테스트를 돌린다.

예를 들면 이런 식입니다.

“이 프로젝트 전체를 분석해줘”보다는,

“OrderService에서 주문 취소 시 재고 복구가 어디서 처리되는지 찾아줘. 관련 클래스와 호출 흐름을 먼저 정리하고, 아직 코드는 수정하지 마.”

처럼 요청하는 것이 훨씬 효과적입니다.

그 다음에,

“방금 찾은 흐름을 기준으로, 취소 사유가 SOLD_OUT인 경우에는 재고 복구를 하지 않도록 수정 계획을 먼저 작성해줘. 테스트 대상도 같이 제안해줘.”

처럼 단계적으로 진행하는 방식입니다.

정리하면, 대용량 코드베이스에서 중요한 것은 “전체를 한 번에 컨텍스트에 넣는 것”이 아니라 “필요한 코드를 잘 찾게 하는 구조와 프롬프트”입니다. AGENTS.md는 그중 하나의 보조 장치이고, 모든 폴더에 억지로 만들 필요는 없습니다. 루트 중심으로 공통 규칙을 관리하고, 정말 복잡하거나 독립적인 모듈에만 추가하는 정도가 현실적입니다.

답변이 도움이 되었으면 좋겠습니다. 그리고 정말 좋은 질문 감사합니다.