새 회사에 입사했거나, 몇 달 방치됐던 프로젝트를 다시 열었거나, 오픈소스에 기여하려고 낯선 저장소를 클론했을 때. 폴더 수십 개에 파일 수백 개가 펼쳐지면 "일단 어디서부터 봐야 하지?" 하는 막막함이 먼저 옵니다. 이때 Cursor AI 개발 도구를 코드 자동완성이나 함수 생성용으로만 써 왔다면, 정작 가장 도움이 될 상황에서 절반만 쓰고 있는 셈입니다. 고치는 것보다 먼저 필요한 건 '파악'이고, Cursor는 그 파악을 도와주도록 만들어진 도구입니다.
왜 '고치기'보다 '파악'이 먼저인가
낯선 코드베이스에서 가장 흔한 실수는, 이해가 끝나기 전에 AI에게 곧바로 수정을 시키는 것입니다. 어떤 함수가 어디서 호출되는지, 이 설정값이 어떤 흐름을 타는지 모르는 상태에서 "이 버그 고쳐줘"라고 하면, AI가 그럴듯하게 코드를 바꿔놓아도 그게 맞는지 판단할 근거가 나에게 없습니다. 결국 검토 없이 받아들이게 되고, 엉뚱한 곳이 틀어집니다.
예를 들어 볼까요. 결제 관련 버그를 잡으라는 요청을 받았다고 합시다. 이름에 payment가 들어간 파일이 대여섯 개인데, 어느 것이 실제 결제 승인을 처리하고 어느 것이 화면 표시용인지 모르는 상태입니다. 이때 무작정 첫 번째 파일을 열어 고치기 시작하면, 정작 승인 로직은 다른 파일에 있어 한참을 헤매게 됩니다. 반대로 "결제 승인은 어디서 일어나?"를 먼저 물어 구조를 잡으면, 손댈 파일을 처음부터 정확히 고를 수 있습니다.
그래서 순서를 뒤집어야 합니다. 먼저 코드베이스의 지도를 머릿속에 그리고, 그다음에 손을 대는 것이죠. 다행히 이 '지도 그리기' 단계야말로 AI 에디터가 사람보다 빠르게 도와줄 수 있는 영역입니다. 문서가 부실하고 주석이 없어도, 코드 자체를 근거로 설명을 만들어 주기 때문입니다.
Cursor로 코드베이스를 읽는 3가지 축
Cursor에서 '수정'이 아니라 '이해'를 위한 기능은 크게 세 가지로 나눌 수 있습니다. 이 세 축을 구분해서 쓰는 것만으로도 낯선 프로젝트 진입 속도가 확 달라집니다.
1) Ask 모드 — 파일을 건드리지 않고 물어보기
Cursor에는 코드를 직접 수정하는 Agent 모드 외에, 읽기 전용으로 동작하는 Ask 모드가 있습니다. Ask 모드는 코드베이스를 검색해 질문에 답하고, 코드를 설명하고, 접근 방법을 정리해 주지만 파일을 쓰지는 않습니다. 즉 "이 인증 로직이 어떻게 흘러가지?", "이 모듈은 어디서 쓰여?" 같은 질문을 마음 놓고 던질 수 있습니다. 실수로 코드가 바뀔 걱정이 없으니, 아직 구조를 모르는 초반 탐색 단계에 가장 잘 맞습니다.
Cursor 공식 문서에서도 Ask 모드를 코드를 수정하지 않고 코드베이스를 탐색·질문하는 용도로 안내합니다(자세한 동작은 Cursor 공식 문서 참고). 낯선 레거시 모듈이나 복잡한 의존 관계를 파악할 때, 사람에게 물어보기 전에 먼저 Ask에게 물어보는 습관을 들이면 진입 시간이 크게 줄어듭니다.
2) @ 멘션으로 질문 범위를 좁히기
막연하게 "이 프로젝트 설명해줘"라고 하면 답도 막연해집니다. Cursor는 질문에 컨텍스트를 명시적으로 붙일 수 있는 @ 멘션을 제공합니다.
- @codebase — 저장소 전체를 대상으로 하는 교차 파일 질문. "결제 처리는 어느 파일들에 걸쳐 있어?"처럼 넓게 물을 때 씁니다.
- @file — 특정 파일 하나로 범위를 한정. "이 파일이 하는 일을 한 부분씩 설명해줘."
- @folder — 특정 하위 디렉터리로 한정. "이 폴더 안의 모듈들이 어떻게 나뉘어 있어?"
처음에는 @codebase로 큰 그림을 잡고, 관심 가는 영역이 좁혀지면 @folder → @file로 점점 초점을 좁혀 가는 식입니다. 범위를 좁혀 물을수록 답이 구체적이고 정확해집니다. 반대로 저장소 전체를 대상으로 한 질문은 답이 넓고 두루뭉술해지기 쉬우니, 큰 그림을 한 번 잡은 뒤에는 되도록 범위를 지정해 묻는 편이 좋습니다.
3) 인덱싱이 끝나야 답이 정확하다
Cursor는 열려 있는 파일만 보는 게 아니라, 저장소 전체를 임베딩으로 색인해 둡니다. 덕분에 파일 간 관계를 가로질러 답할 수 있습니다. 규모가 큰 저장소는 처음 한 번 인덱싱하는 데 시간이 좀 걸리고, 이후에는 바뀐 부분만 갱신됩니다. 프로젝트를 막 열었을 때 답이 부실하게 느껴진다면, 인덱싱이 아직 진행 중일 수 있으니 잠깐 기다렸다 다시 물어보는 편이 낫습니다. (기능·명칭은 본 글 작성 시점 기준이며, Cursor 버전 업데이트에 따라 달라질 수 있습니다.)
실전: 낯선 프로젝트 첫 30분 워크플로우
위 세 축을 실제 순서로 엮으면 이렇게 쓸 수 있습니다. 새 저장소를 열었을 때 그대로 따라 해 볼 만한 흐름입니다.
- 전체 지도부터. Ask 모드에서 @codebase 이 프로젝트의 전체 구조와 핵심 진입점(entry point)을 알려줘라고 물어 큰 그림을 잡습니다.
- 실행 흐름 따라가기. "사용자가 로그인하면 어떤 파일들을 거치는지 순서대로 설명해줘"처럼, 기능 하나의 흐름을 끝까지 훑습니다. 구조보다 흐름이 이해에 더 도움이 될 때가 많습니다.
- 관심 영역 좁히기. 내가 손댈 부분이 정해지면 @folder, @file로 좁혀 해당 코드만 자세히 설명받습니다.
- 가설 검증. "이 값이 바뀌면 어디에 영향이 가?"처럼, 수정 전에 파급 범위를 먼저 물어 확인합니다.
- 그다음에 수정. 구조가 머릿속에 들어온 뒤에야 Agent 모드로 넘어가 실제 변경을 맡기고, 결과 diff를 검토합니다.
핵심은 1~4단계를 건너뛰지 않는 것입니다. 이해에 쓰는 10~20분이 아깝게 느껴져도, 그 시간이 잘못된 수정으로 날리는 시간을 줄여 줍니다.
AI의 설명도 그대로 믿지는 말 것
한 가지 주의할 점이 있습니다. Ask 모드가 내놓는 설명은 코드를 근거로 하지만, 언제나 100% 정확하지는 않습니다. 특히 비슷한 이름의 함수가 여럿이거나, 오래된 코드와 새 코드가 섞여 있으면 AI가 엉뚱한 쪽을 지목하기도 합니다. 그래서 중요한 판단(어느 파일을 고칠지, 어떤 값이 어디에 영향을 주는지)은 AI의 설명을 힌트로 삼되, 실제 코드에서 한 번 눈으로 확인하는 습관이 안전합니다. AI가 "이 함수가 호출된다"고 하면, 그 호출 지점을 직접 클릭해 확인하는 식입니다. 파악을 빠르게 하되, 근거는 코드에 두는 것이 핵심입니다.
결론
Cursor AI 개발 도구의 진짜 힘은 코드를 '대신 써 주는' 데만 있지 않습니다. 낯선 코드베이스를 빠르게 이해하도록 도와주는 데 있습니다. 읽기 전용 Ask 모드로 안전하게 묻고, @codebase·@folder·@file로 범위를 좁히고, 인덱싱이 끝난 뒤 정확한 답을 받는 것 — 이 세 가지만 습관으로 만들면, 남이 짠 코드 앞에서 막막했던 시간이 눈에 띄게 줄어듭니다. 오늘 낯선 저장소를 하나 열어, "고치기 전에 먼저 물어보기"부터 시작해 보세요.
라벨: Cursor, 커서 AI, AI 코딩, 코드베이스 파악, Ask 모드, AI 에디터, 개발 생산성, AI도구, 개발자 도구
댓글 없음:
댓글 쓰기