Claude Code로 복잡한 페이지 디버깅하기 - 문서화 전략

English (N/A)
#Claude Code#AI#디버깅#문서화

Claude Code로 개발하다 보면 간단한 기능은 술술 잘 만들어주는데, 복잡한 페이지를 작업할 때는 버그가 계속 발생하는 경우가 있다. 이럴 때 정말 답답하다.

문제 상황

코드의 양이 방대해지면 Claude Code도 한번에 전체 구조를 파악하기 어려워한다. 그래서 안 되는 부분을 하나씩 찾아서 "이거 고쳐줘"라고 요청해도, 다른 곳을 건드리거나 엉뚱한 수정을 하면서 헤매는 경우가 많다.

이런 상황이 반복되면 시간만 계속 소모되고, 결국 직접 코드를 뜯어봐야 하는 상황이 온다.

해결책: 문서화 먼저

이런 경우에 효과적인 방법이 있다. 바로 기능을 최대한 자세하게 문서화 해달라고 요청하는 것이다.

Claude Code에게 현재 구현된 기능, 컴포넌트 구조, 데이터 흐름 등을 문서로 정리해달라고 하면 된다. 이렇게 하면 Claude Code 스스로도 전체 구조를 다시 파악하게 되고, 나도 현재 상태를 명확하게 이해할 수 있다.

문서 검토 요청하기

문서가 만들어지면 바로 수정에 들어가지 말고, 먼저 검토를 요청한다. 아래와 같은 프롬프트를 사용하면 좋다.

문서를 보고 설계원칙에 어긋난 부분이 있거나 개선이 필요한 부분이 있는지 검토해줘.

설계원칙은 아래와 같아.
1. 같은 기능이라면, 사람이 이해하기 쉽도록 최대한 간결한 아키텍처로 구현
2. 중복된 코드를 제거하고, 각 모듈이 분리된 역할을 수행하도록 클린코드 관점으로 설계
3. 코드를 읽어내려가면서 구현 흐름과 프로세스를 직관적으로 쉽게 이해할 수 있도록 코드 작성

이 세 가지 원칙은 사실 좋은 코드의 기본이다. 간결함, 모듈 분리, 가독성. Claude Code가 이 원칙에 맞춰 현재 코드를 점검하면, 구조적인 문제점들이 드러난다.

문제점 검토도 함께

설계원칙 검토와 함께 "문제가 될 만한 부분이 있는지"도 검토를 요청하면 좋다. 엣지 케이스나 예외 상황, 성능 이슈 등을 미리 파악할 수 있다.

왜 이 방법이 효과적인가

이 방법이 효과적인 이유는 Claude Code의 컨텍스트 관리와 관련이 있다. 복잡한 코드를 부분적으로만 보면서 수정하면, 전체 맥락을 놓치기 쉽다. 하지만 문서화 과정을 거치면 전체 구조가 명시적으로 정리되고, 이 문서를 기반으로 검토와 수정을 진행하면 훨씬 정확한 작업이 가능해진다.

결국 "급할수록 돌아가라"는 말처럼, 복잡한 버그를 만났을 때는 바로 수정에 뛰어들지 말고 한 발 물러서서 문서화부터 하는 게 더 빠른 길이다.

연관 포스트