프로젝트 지식이 거의 없는 상태에서 Cursor를 사용하여 거대한 레거시 코드베이스에 온보딩하는 방법

AI 코딩 어시스턴트(AI coding assistants)에 관한 대부분의 기사들은 코드를 더 빠르게 작성하는 것에 초점을 맞춥니다.

하지만 새로운 회사나 프로젝트에 합류했을 때, 진짜 문제는 코드를 작성하는 것이 아닙니다.

진짜 문제는 다음과 같습니다:

"이 시스템이 어떻게 작동하는지 전혀 모르겠다."

최근에 저는 수년간 개발되어 온 프로젝트에 합류했습니다. 코드베이스(codebase)는 여러 개의 리포지토리(repositories), 여러 서비스(services), 공유 라이브러리(shared libraries), 통합(integrations), 그리고 수많은 과거의 결정 사항들로 구성되어 있었습니다.

저의 첫 번째 생각은 이랬습니다:

"토큰(tokens)을 낭비하지 않고, 같은 질문을 반복하지 않으면서 어떻게 Cursor를 사용할 수 있을까?"

몇 차례의 실험 끝에, 저는 Cursor를 온보딩 엔지니어(onboarding engineer), 아키텍트(architect), 문서 작성자(documentation writer), 그리고 티켓 어시스턴트(ticket assistant)로 변모시키는 워크플로우(workflow)를 개발했습니다.

이 포스트에서는 정확한 설정 방법을 설명합니다.

대부분의 개발자가 범하는 실수

대규모 프로젝트에 합류할 때, 많은 개발자가 즉시 Cursor에게 다음과 같이 묻습니다:

프로젝트 전체를 분석해줘.

또는:

이 코드베이스를 설명해줘.

이는 보통 다음과 같은 결과를 초래합니다:

엄청난 토큰(token) 사용량
일반적이고 모호한 답변
컨텍스트(context) 상실
반복되는 분석
티켓(ticket)에 대한 이해도 저하

문제는 간단합니다:

Cursor는 전체 엔터프라이즈 시스템(enterprise system)을 영원히 기억할 수 없습니다.

코드베이스를 반복해서 스캔하는 대신, 지식 베이스(knowledge base)를 구축해야 합니다.

Cursor를 새로운 팀원처럼 대하라

새로운 엔지니어가 당신의 팀에 합류한다고 상상해 보세요.

당신은 그들에게 이렇게 말하지 않을 것입니다:

"50개의 리포지토리를 읽고 모든 것을 암기하세요."

대신 당신은 다음과 같은 것들을 만들 것입니다:

아키텍처 문서 (Architecture docs)
리포지토리 맵 (Repository maps)
서비스 관계 (Service relationships)
학습 계획 (Learning plans)

그것이 바로 Cursor에게도 필요한 것입니다.

1단계: 온보딩 미션 생성하기

Cursor에게 무작위로 질문하는 대신, 명확한 책임을 부여하세요:

시스템을 이해하라.
시스템을 문서화하라.
나에게 시스템을 가르쳐라.

저는 Cursor에게 다음과 같은 지침을 내리는 전용 온보딩 미션을 만들었습니다:

리포지토리(repositories) 탐색
아키텍처(architecture) 매핑
서비스 관계(service relationships) 문서화
학습 계획(learning plans) 생성
중앙 지식 베이스(central knowledge base) 구축

목표는 코드를 작성하는 것이 아니었습니다.

목표는 프로젝트를 이해하는 것이었습니다.

2단계: 중앙 지식 베이스(Central Knowledge Base) 구축

저는 다음과 같은 구조를 만들었습니다:

docs/onboarding/

가장 중요한 파일은 다음과 같습니다:

docs/onboarding/project-memory.md

이 파일에는 다음 내용이 포함됩니다:

리포지토리(Repository) 목적
아키텍처(Architecture) 노트
서비스 간 관계
비즈니스 도메인(Business domains)
코딩 컨벤션(Coding conventions)
중요한 발견 사항
자주 수정되는 파일

이를 프로젝트의 내부 위키(Wiki)라고 생각하세요.

3단계: 코딩 전 시스템 문서화

Cursor는 다음과 같은 파일들을 생성했습니다:

docs/onboarding/

repositories-overview.md
...

각 리포지토리별로:

docs/onboarding/<repo-name>/

overview.md
...

목표는 간단했습니다:

같은 것을 두 번 배우지 않는 것.

4단계: 워크스페이스 전체 스캔 중단하기

토큰(Token)을 절약하는 가장 큰 기술 중 하나는 다음과 같습니다:

절대로 이렇게 하지 마세요:

워크스페이스 전체를 분석해줘.

대신 이렇게 하세요:

먼저 project-memory.md를 읽어줘.

영향을 받는 리포지토리만 분석해줘.

이 단 한 가지의 변화가 컨텍스트(Context) 사용량을 극적으로 줄였습니다.

5단계: Cursor 규칙(Rules) 설정

저는 프로젝트 규칙을 추가했습니다:

코드를 분석하기 전에:

1. 온보딩 문서를 먼저 읽을 것.
...

이제 Cursor는 자동으로 이 워크플로우를 따릅니다.

6단계: 재사용 가능한 기술(Skills) 생성

긴 프롬프트(Prompt)를 반복해서 작성하는 대신, 저는 Cursor Skills를 만들었습니다.

/ticket

새로운 티켓(Ticket)이 도착했을 때 사용합니다.

역할:

프로젝트 메모리 읽기
영향받는 리포지토리 식별
현재 동작 설명
구현 계획(Implementation plan) 수립
리스크 평가

아직 코딩은 하지 않습니다.

/implement

계획이 승인된 후에 사용합니다.

역할:

변경 사항 설명
필요한 파일만 수정
기존 패턴 준수
영향 최소화

/review

구현 후에 사용합니다.

역할:

아키텍처 준수 여부 검토
엣지 케이스(Edge cases) 확인
에러 핸들링(Error handling) 검토
하위 호환성(Backward compatibility) 검증

/update-docs

티켓 완료 후에 사용합니다.

역할:

프로젝트 메모리 업데이트
아키텍처 문서 업데이트
새로운 발견 사항 기록

/audit

주기적으로 사용합니다.

역할:

온보딩 커버리지(Onboarding coverage) 측정
문서화되지 않은 리포지토리(Repositories) 탐색
지식 격차(Knowledge gaps) 식별

/learn

매일 사용합니다.

역할:

다음으로 중요한 모듈 선정
요청 흐름(Request flows) 설명
데이터베이스 상호작용(Database interactions) 설명
통합(Integrations) 사항 설명
시스템을 점진적으로 학습

나의 일일 워크플로우 (My Daily Workflow)

온보딩할 때:

/continue

학습할 때:

/learn

진행 상황을 확인할 때:

/audit

티켓이 도착했을 때:

/ticket

승인 후:

/implement

머지(Merging) 전:

/review

완료 후:

/update-docs

가장 큰 이점 (The Biggest Benefit)

대부분의 개발자는 Cursor를 코딩 어시스턴트(Coding assistant)로 사용합니다.

저는 Cursor를 프로젝트 지식 어시스턴트(Project knowledge assistant)로 사용하기 시작했습니다.

그것이 모든 것을 바꾸었습니다.

반복해서 다음과 같이 묻는 대신:

이 코드는 어디에 있나요?

저는 다음과 같이 묻기 시작했습니다:

시스템이 이미 알고 있는 것은 무엇인가요?

그 결과:

더 빠른 온보딩
더 나은 아키텍처 이해
더 적은 토큰(Token) 사용량
더 나은 티켓 분석
일관된 문서화
더 적은 컨텍스트 손실 (Context loss)

마치며 (Final Thoughts)

만약 여러분이 여러 개의 리포지토리(Repositories)가 있고 도메인 지식(Domain knowledge)이 거의 없는 상태에서 거대한 레거시 프로젝트에 합류한다면, 코드 생성부터 시작하지 마세요.

지식을 구축하는 것부터 시작하세요.

Cursor를 다음과 같이 사용하세요:

시스템 매핑 (Map the system)
시스템 문서화 (Document the system)
시스템 학습 (Teach the system)
지식 베이스 유지 관리 (Maintain the knowledge base)
그 다음에 코드 작성

여러분의 문서화가 성숙해지면, Cursor는 단순한 AI 코딩 어시스턴트에 머물지 않습니다.

Cursor는 여러분의 팀만큼이나 프로젝트를 잘 이해하는 장기적인 엔지니어링 파트너가 됩니다.