낯선 레거시 코드는 무겁게 느껴질 이유가 있다. 스타일이 오래됐거나 주석이 부족해서만이 아니다. 모든 줄이 동시에 중요해 보인다는 점이 진짜 문제다.

개발자들이 AI를 여기서 가장 많이 잘못 쓴다. 큰 파일을 통째로 붙여 넣고 “이거 뭐 하는 코드야?”라고 묻는다. 그러면 대체로 답은 넓고, 매끈하고, 믿기엔 비싼 요약이 된다.

더 좋은 시작은 더 큰 설명이 아니라 더 작은 질문 집합이다. AI는 코드 전체를 친절하게 설명할 때보다, 무엇부터 봐야 하는지 좁혀줄 때 훨씬 유용하다.

1. 처음부터 전체 설명을 시키지 않는다

전체 설명은 너무 많은 것을 한 번에 눌러 담는다. 지금 잡고 있는 버그나 변경과 상관없이 파일 전체에 대한 이야기부터 만들어낸다.

그렇게 얻은 설명은 그럴듯하지만, 여전히 중요한 건 남는다. 실행이 어디서 시작하는지, 어떤 부작용이 있는지, 외부 시스템과 어디서 맞닿는지 같은 핵심은 오히려 흐려질 수 있다.

2. 가장 좋은 첫 질문은 읽을 범위를 줄여준다

여기가 핵심이다. 레거시 코드를 읽을 때 가장 빨리 진전이 나는 순간은 설명량이 많아질 때가 아니라, 읽어야 할 표면이 줄어들 때다.

초반에는 세 질문이 대부분의 일을 한다.

• 진입점이 어디인가
• 이 코드가 만드는 부작용은 무엇인가
• 어떤 외부 의존성이나 데이터 경계를 건드리는가

이 질문이 중요한 이유는 무거운 파일 하나를 실행 지도 하나로 바꿔주기 때문이다. 진입점은 어디서 읽기 시작할지 알려주고, 부작용은 실행 뒤 무엇이 바뀌는지 알려주고, 외부 의존성은 파일 밖에서 숨어 들어오는 행동을 보여준다.

이 셋 없이 읽으면 팀은 줄 단위로 많이 읽고도 구조를 놓친다. 함수가 무슨 모양인지는 아는데, 어느 부분이 실제로 중요한지 모르고 끝난다.

AI는 여기서 직접적인 경계만 빠르게 그려줄 때 유용하다. “이 코드를 설명해줘”보다 “진입 경로와 부작용을 보여줘”가 훨씬 실전적이다.

3. 설명 질문보다 지도 질문을 던진다

좋은 프롬프트는 지도처럼 좁다.

이 파일을 기준으로 진입점, 부작용, 외부 의존성을 짧고 구조적으로 정리해줘. 전체 설명보다 먼저 읽어야 할 부분이 보이게 해줘.

파일이 특히 시끄럽다면 한 줄을 더 붙이면 좋다.

처음 읽을 때 무시해도 되는 함수와, 동작을 바꾸려면 먼저 봐야 하는 함수를 나눠줘.

4. 예시 하나만 떠올려도 읽는 순서가 달라진다

예를 들어 요청 검증, 캐시 처리, 데이터베이스 쓰기, 분석 이벤트 전송이 한 파일 안에 섞여 있는 서비스 코드가 있다고 하자. 위에서 아래로 읽으면 모든 줄이 똑같이 중요해 보인다.

반대로 진입점, 부작용, 의존성을 먼저 보면 구조가 갑자기 줄어든다. 실제로 중요한 건 export된 함수 하나일 수 있고, 헬퍼 함수 둘은 처음 읽을 때 무시해도 될 수 있고, 진짜 위험은 캐시 쓰기와 분석 이벤트 경계에만 몰려 있을 수 있다.

이 차이가 크다. 완독하려고 읽는 상태에서, leverage를 얻기 위해 읽는 상태로 바뀌기 때문이다.

5. 짧은 코드 읽기 틀 하나만 고정한다

복잡한 워크플로는 필요 없다. 작은 메모 틀 하나면 충분하다.

1. 진입점
2. 부작용
3. 외부 의존성
4. 처음엔 무시해도 되는 부분
5. 변경 위험이 높은 지점

틀이 좋아질수록 AI가 그럴듯하지만 쓸모 없는 전체 개요를 만들어낼 공간은 줄어든다.

무엇부터 시작할까

지금 작업 중인 낯선 파일 하나를 골라 AI에게 진입점, 부작용, 외부 의존성만 먼저 물어봐라. 그 뒤에도 파일이 똑같이 넓게 느껴진다면, 질문이 아직 충분히 좁지 않았던 것이다.