AI 코딩 도구한테 기능 수정 하나를 시켰는데 빌드가 터졌다. 맘대로 리팩토링을 해서 관련 없는 영향범위까지 다 건드려버린 거다. 신규 프로젝트에서는 잘 되던 놈이 기존 코드베이스 앞에서는 왜 이러는 걸까. 삽질 끝에 잡은 프로세스를 정리해 본다.
AI 코딩 도구, 어떻게 쓰고 있나
본론에 앞서 배경을 짧게 정리하면, AI한테 일 시키는 방식은 크게 두 가지다. 서비스 안에 LLM API를 연동해서 사용자한테 AI 기능을 제공하는 것(챗봇, 자연어 검색, 업무 자동화 등), 그리고 개발자가 AI 코딩 도구로 직접 코드를 시키는 것. 한 마디로 "내 대신 타자 좀 쳐라"다.
AI 코딩 도구는 다시 IDE 방식(Cursor, IntelliJ AI Assistant)과 CLI 방식(Claude Code, Gemini CLI)으로 나뉜다. Claude Opus 4.6과 GPT-5.3 Codex를 비교한 적이 있는데, IDE는 모델을 골라 쓸 수 있고 시각적 피드백이 좋다. CLI는 자율성이 높아서 멀티 파일 수정이나 대규모 작업에 유리하다. 특히 백엔드 개발에서 Cursor+IntelliJ, Claude Code+IntelliJ 조합을 어떻게 나눠 쓰는지는 별도로 정리해뒀다.
이 글에서 집중할 건 기존 코드베이스에 AI 코딩 도구를 쓸 때 얘기다.
AI 코딩 도구, 신규 프로젝트는 문제없다
신규 프로젝트는 쉽다. 기존 코드베이스가 없으니까 AI도 백지에서 시작한다. 충분히 설계하고 명확하게 시키면 꽤 괜찮은 결과물을 가져온다. 구조 설계를 먼저 확정하고 들어가는 게 포인트다.
기존 코드베이스에 AI 코딩 도구를 쓰면 왜 문제가 생기나
AI가 기존 맥락을 모르기 때문이다. 프로젝트의 구조, 컨벤션, 의존 관계를 모르는 상태에서 코드를 생성하니까 기존과 어울리지 않는 결과를 가져온다. 기존 컨벤션은 무시하고 본인(?)이 생각하는 "더 나은 구조"로 갈아엎어버리는 게 일상이다.
이건 나만 겪는 문제가 아니다. GitHub 블로그에서도 레거시 시스템에 AI를 적용할 때 "코드가 여러 저장소에 흩어져 있고, 문서화는 안 돼 있고, 의존성은 알 수 없고, 원래 만든 개발자는 없다"를 핵심 장벽으로 꼽았다.
AI 코딩 도구로 기존 프로젝트를 다룰 때 내가 잡은 프로세스
그래서 내 경우에는 바로 작업을 시키지 않는다. 이런 순서로 접근한다.
1단계: 기본 룰부터 세팅한다
협업 룰, 작업 룰을 먼저 잡는다. 코드 컨벤션, 커밋 규칙, 파일 구조 같은 기본적인 것들. Cursor의 .cursor/rules/나 Claude의 CLAUDE.md 같은 설정 파일로 세팅하면 대화가 바뀌어도 자동으로 적용된다.
2단계: 기존 코드베이스를 학습시킨다
이게 핵심이다. 바로 작업을 시키지 않고 먼저 프로젝트를 파악하게 한다.
- 프로젝트 전체 구조 — 디렉토리 구조, 모듈 간 관계
- 비즈니스 핵심 로직 — 도메인 로직이 어디에 어떻게 구현돼 있는지
- 기존 코딩 컨벤션 — 네이밍 규칙, 에러 처리 패턴, 로깅 방식
- 기존 코드 작성 패턴 — 비슷한 기능이 어떤 패턴으로 만들어져 있는지
학습한 내용은 마크다운이나 JSON 등 AI가 알아먹기 편한 형식으로 기록하게 한다.
3단계: 인덱스를 만든다
.cursorrules나 CLAUDE.md를 인덱스처럼 활용한다. "이 정보는 저기에 있고, 저 정보는 여기에 있어"라고 알 수 있게 정리하는 거다. 얼마 전 Cursor에서 릴리즈한 Skills가 정확히 이 역할이다. 특정 작업에 필요한 지식을 파일로 정리해두면, AI가 해당 작업을 할 때 자동으로 참고한다.
4단계: 수사망을 좁혀 간다
전체를 파악했으면 이제 내가 실제로 수정해야 하는 포인트로 점점 범위를 좁혀 간다.
예를 들어 배송일 정보 노출 기능을 수정해야 했을 때, 먼저 프로젝트 전체를 분석시키고 → 배송일 관련 비즈니스 로직을 파악시키고 → 영향범위를 정리시킨 다음에 → 그제서야 실제 개발을 시켰다. 이 과정 자체를 AI한테 시키면서 결과를 파일로 남긴다.
작업 전에는 항상 정리한 파일들을 참고하게 하고, 작업 후에도 작업 내용, 참고사항, 트러블슈팅을 히스토리로 관리하게 한다. 이렇게 하면 에이전트 세션이 바뀌어서 맥락이 끊기더라도 빠르게 복구할 수 있다.
AI 코딩 도구 학습 전후, 결과물은 이렇게 달랐다
위에서 말한 배송일 정보 기능이 딱 좋은 예다.
학습 전: 엉뚱한 파일을 메인 모듈로 바꿔버렸다. 파라미터를 프로세스 처음부터 끝까지 전부 추가해서, 내가 원하는 수정 범위보다 훨씬 넓은 영역을 건드렸다. 관련 없는 모듈까지 줄줄이 수정돼서 리뷰할 엄두가 안 났다.
학습 후: 딱 영향범위 내에서만 수정이 됐다. 기존 구조를 건드리지 않고, 변경이 필요한 파일만 정확하게 수정했다. 리뷰도 명확하고, 빌드도 바로 통과.
같은 AI, 같은 프로젝트, 같은 작업인데 결과가 이렇게 다르다. 차이는 딱 하나, AI가 기존 코드베이스의 맥락을 알고 있느냐 모르느냐다. AI 코딩 도구가 개발자 학습에 미치는 영향을 분석했을 때도 비슷한 결론이었다. 도구의 성능이 아니라 도구를 어떻게 쓰느냐가 결과를 결정한다.
AI 코딩 도구의 컨텍스트 관리, 아직 갈 길이 멀다
Cursor Skills가 나오면서 내가 직접 잡은 프로세스의 일부가 희석되긴 했다. 도구 자체가 컨텍스트 관리를 지원하기 시작한 거니까. 그래도 여전히 새 프로젝트에 이 프로세스를 적용하면 꽤 괜찮은 퀄리티를 보여준다.
최근 모델들의 컨텍스트 윈도우가 비약적으로 커진 것도 한몫한다. 프로젝트 전체 구조를 한 번에 이해시키는 게 가능해졌다. 그런데 토큰이 크다고 무조건 다 때려넣는 건 비효율적이다. 필요한 맥락만 정리해서 가져가면 토큰도 절약되고, 불필요한 정보가 안 섞이니까 정확도도 올라간다.
느낌적인 느낌이지만, 맥락이 작아지면 소모량이 줄어드는 건 당연하다. 아직 완벽하지는 않지만, 최소한 빌드가 터지는 일은 없어졌다.
자주 묻는 질문
Q. AI가 기존 코드를 엎어버리면 어떻게 복구하나?
Git이 있으니까 복구 자체는 문제 아니다. 핵심은 애초에 안 엎게 만드는 거다. 기본 룰에 "기존 코드 구조 변경 금지", "요청한 범위만 수정" 같은 제약을 명시하면 상당 부분 막을 수 있다. 그래도 가끔 뚫리니까 커밋 단위를 잘게 쪼개는 습관이 필요하다.
Q. 학습 파일은 얼마나 자주 업데이트해야 하나?
프로젝트 구조가 바뀌거나 새로운 패턴이 추가될 때마다 갱신하는 게 이상적이다. 현실적으로는 작업 후 트러블슈팅 내용을 히스토리에 쌓아가는 것만으로도 충분하다. 완벽하게 관리하려다 지치는 것보다 꾸준히 쌓는 게 낫다.
Q. 이 프로세스를 팀에 적용할 수 있나?
된다. .cursor/rules/는 버전 관리가 되니까 팀 전체가 같은 룰을 공유할 수 있다. "이 프로젝트에서는 이렇게 코딩한다"는 암묵지가 파일로 남으니 온보딩에도 도움이 된다.
출처
'Mechanic: IT 인터넷 > Mechanic, M-Tech' 카테고리의 다른 글
| 맥 외장하드 느림 해결 - Spotlight 인덱싱 제거와 디스크 유틸리티 검사 순서 (0) | 2026.02.23 |
|---|---|
| Claude Code Hooks 가이드 - 파일 저장할 때 자동으로 명령어 실행하는 방법 (0) | 2026.02.23 |
| Grabbit 크롬 확장 프로그램 - NotebookLM 소스 입력이 귀찮을 때 (0) | 2026.02.18 |
| FireShot 브라우저 스크롤 캡쳐 - 맥 기본 스크린샷 대신 쓰는 이유 (1) | 2026.02.15 |
| Spring Boot Security 커스텀 로그인 (2) - AOP로 사용자 정보 자동 바인딩 (0) | 2018.11.07 |
