【Claude Code 활용】 코드베이스 탐색을 맡기기

Claude Code의 탐색 능력

Claude Code는 코드베이스 전체를 파악한 후 작업을 시작하는 습관을 가지고 있습니다.

전형적인 탐색 흐름은 다음과 같습니다.

list_files (디렉터리 구조 파악)
↓
read_file (관련 파일 내용 확인)
...

이 흐름을 지시하지 않아도 자발적으로 수행하기 때문에, "기존 코드와 일관된 스타일로 새로운 코드를 작성한다"는 작업을 자연스럽게 실행할 수 있습니다.

실제로 맡겨 보았다: 기존 코드를 읽고 구현하기

agent01의 Step 06에서는 search_text (grep에 상당하는 도구)를 구현했습니다.

Claude Code는 구현 전에 src/tools/file_tools.py를 읽고, 동일한 코딩 스타일로 src/tools/search_tools.py를 생성했습니다. 구체적으로 다음과 같은 점이 자동으로 통일되었습니다.

• EXCLUDE_DIRS의 상수 정의 패턴
• Path를 사용한 경로 조작
• 에러 발생 시의 반환값 형식 (f"에러: ..." 형식)
• docstring 스타일 (Google 스타일)

def search_text(
    query: str,
    directory: str,
    ...

file_tools.py에 맞춰 EXCLUDE_DIRS를 상수로 정의하였고, 결과 형식도 파일:행번호: 행 내용으로 통일되어 있습니다.

CLAUDE.md를 통한 탐색의 효율화

CLAUDE.md에는 코딩 규약이 기재되어 있습니다.

## 코딩 규약
### 기본 방침
- Python 3.11 이상의 구문을 사용한다
...

이 규약을 CLAUDE.md에 적어둠으로써, Claude Code는 처음에 CLAUDE.md를 읽고 이후의 구현에서 이 규약을 준수했습니다. "기존 코드를 참조한 뒤 작성한다"는 탐색 플로우와 결합함으로써 프로젝트 전체의 일관성이 자연스럽게 유지됩니다.

깨달은 점

"먼저 읽어주세요"라는 한마디가 중요: 세션 시작 시 "PROGRESS.md와 AGENT_SPEC.md를 읽어주세요"라고 전달하는 것만으로도 Claude Code는 프로젝트의 문맥을 빠르게 파악합니다. 이 한마디가 없으면 기존 설계를 무시한 구현이 생성되는 경우가 있었습니다.

긴 세션은 새로운 세션으로 나누는 것이 정밀도를 높임: 한 세션에서 많은 작업을 수행하면 컨텍스트(Context)가 길어져 응답 정밀도가 떨어질 수 있습니다. Step 단위로 세션을 구분하고, 매번 "PROGRESS.md를 읽는 것"부터 시작하는 운용 방식이 안정적이었습니다.

탐색의 부산물로 설계 미스가 발견됨: Claude Code가 기존 코드를 읽는 과정에서 설계상의 모순(도구 이름의 표기 불일치 등)을 지적해 주는 경우가 있었습니다. 이는 코드 리뷰의 부수적인 효과로서 유익했습니다.

요약

Claude Code는 자발적으로 코드베이스를 탐색한 후 구현합니다. CLAUDE.md에 규약을 적어둠으로써 탐색 결과를 활용한 일관된 코드를 생성할 수 있습니다. "읽고, 이해하고, 작성한다"는 사이클을 자동으로 돌려주기 때문에 기존 코드와의 스타일 불일치가 일어나기 어렵습니다.

다음 회차

B4에서는 Claude Code의 차이점(diff) 확인 및 적용 플로우에 대해 소개합니다. 기존 파일을 망가뜨리지 않고 변경을 가한 경험을 전달해 드리겠습니다.

시리즈 링크 (Series B)

기사	제목
B1	Claude Code란·도입 및 초기 설정
...

Discussion