레거시 코드 Claude Code — 실전 세팅법

레거시 코드에서 Claude Code — 실전 세팅법

AI 코딩 도구를 "써봤는데 별로"라고 느꼈다면, 세팅을 안 한 것일 수 있다.

---

들어가며

라이브 서비스 중인 모바일 게임 — 파일 700개, 코드 18만 줄짜리 레거시 프로젝트에서 Claude Code를 2달째 쓰고 있다.

처음엔 매번 "우리 프로젝트는 이런 구조고, 이건 이래서 안 되고..." 를 새 대화마다 설명해야 했다. 그 시간이 아까워서 세팅을 시작했고, 지금은 새 대화를 열어도 바로 작업에 들어갈 수 있는 상태가 됐다.

이 글에서는 실제로 세팅한 구조와, 그것이 어떻게 효율을 바꿨는지를 공유한다.

---

0. Claude, Claude Code, Copilot — 뭐가 다른가

AI 코딩 도구가 많아서 헷갈린다. 내가 이해한 기준으로 정리하면:

일반 AI 챗봇 (ChatGPT, Claude.ai 등)

웹 브라우저에서 대화하는 형태. 코드를 복사해서 붙여넣고 "이거 뭐가 잘못됐어?" 라고 물어본다. 답은 잘 해주지만:

• 내 프로젝트 파일을 직접 읽거나 수정할 수 없다
• 매번 관련 코드를 복붙해야 한다
• 대화가 끝나면 다음에 다시 처음부터 설명해야 한다

GitHub Copilot

IDE에 통합되어 코드 자동완성을 해준다. 타이핑하는 중에 다음 줄을 제안하는 방식. 짧은 코드 완성에는 좋지만:

• 프로젝트 전체 맥락을 파악하기 어렵다
• "이 버그 원인을 찾아줘" 같은 복합 작업은 못 한다
• 파일을 넘나들며 분석하는 건 범위 밖

Claude Code (내가 쓰는 것)

에이전트형 코딩 도구다. IDE(VS Code) 안에서 동작하면서:

• 프로젝트 파일을 직접 읽고, 검색하고, 수정할 수 있다
• "이 버그 원인 찾아줘" → 관련 파일을 스스로 grep해서 추적한다
• CLAUDE.md 파일로 프로젝트 규칙을 기억시킬 수 있다
• Memory 시스템으로 대화가 끝나도 경험이 누적된다
• 커스텀 스킬(슬래시 커맨드)로 반복 작업을 자동화할 수 있다
• 터미널 명령어(SSH, SCP 등)도 실행할 수 있다

차이를 한 줄로 요약하면:

도구	핵심	비유
ChatGPT/Claude.ai	질문하면 답해주는 챗봇	검색 엔진
Copilot	타이핑하면 다음 줄 제안	자동완성
Claude Code	프로젝트를 이해하고 직접 작업하는 에이전트	옆자리 동료

나는 VS Code 확장으로 Claude Code를 쓰고 있고, 이 글의 모든 내용은 Claude Code 기준이다.

---

1. 핵심 개념: "매번 설명하는 시간"을 없애라

AI 코딩 도구의 가장 큰 비효율은 컨텍스트 전달이다.

매 대화마다 반복되는 것들:
- "우리 프로젝트는 클라이언트/서버/기획 데이터 삼각 구조야"
- "서버 코드를 직접 수정하지 말고 로컬에서 만들어서 전송해"
- "이 프레임워크에서는 새 필드를 쓰려면 선언부에 먼저 등록해야 해"
- "테스트는 이렇게 하고, 배포는 저렇게 해"

사람에게 온보딩 문서를 주듯이, AI에게도 "읽고 시작해" 문서를 만들 수 있다. Claude Code에서는 이걸 CLAUDE.md라는 파일로 제공한다.

---

2. 3계층 지식 설계

나는 지식을 3개 계층으로 분리해서 관리한다.

┌─────────────────────────────────────┐
│  1계층: 전역 설정 (CLAUDE.md)       │  ← 모든 프로젝트 공통
│  - 기본 규칙 (언어, 답변 스타일)     │
│  - 개발 환경 (서버, 경로, 도구)      │
│  - 프로젝트 개요 (기술 스택, 구조)   │
├─────────────────────────────────────┤
│  2계층: 프로젝트별 (CLAUDE.md)      │  ← 이 코드베이스에서만 적용
│  - 폴더 구조 / 아키텍처             │
│  - 코드 함정 모음 (실제 터진 버그)   │
│  - "이것만은 하지 마라" 금지 규칙    │
├─────────────────────────────────────┤
│  3계층: Memory (개별 파일)          │  ← 대화에서 누적된 경험
│  - 버그 해결 기록 (50건+)           │
│  - 피드백 (15건+)                   │
│  - 외부 참조 (빌드, 배포, 도구)      │
└─────────────────────────────────────┘

1계층: 전역 설정 — "너는 이런 환경에서 일한다"

# 전역 설정

## 기본 규칙
- 한국어로 답변
- 코드는 완성된 형태로 제공
- 서버 파일 수정 시 로컬에서 만들고 전송 방식 안내

## 프로젝트 개요
- 모바일 게임 2개 운영
- 클라이언트 + 서버 + 기획 데이터(Excel) 삼각 구조

10줄 남짓이지만, 이것만 있어도 "한국어로 답해줘", "우리 프로젝트는 모바일 게임이야" 같은 반복 설명이 사라진다.

2계층: 프로젝트별 — "이 코드에서 자주 터지는 함정들"

여기가 진짜 핵심이다. 실제로 버그가 터졌던 패턴을 기록해둔다.

## 해시 테이블 순회 순서 비보장
- 서버 응답을 for 루프로 순회하며 상태를 덮어쓰는 로직은 위험
- 서버가 순서대로 보내도 클라이언트에서 마지막 값이 무작위
- 해결: 순서 독립 연산(min/max/sum) 사용

## 디버그 로그에 nil 값 연결 시 에러
- Log('key=' .. value) — value가 nil이면 에러
- 에러 나면 그 뒤 모든 로직이 실행 안 됨
- 항상 tostring()으로 감싸기

## 클라이언트-서버 계산 동기화
- 클라이언트가 계산해서 서버로 보내는 값은 서버 로직과 동일해야 함
- 불일치 시 Mismatch 에러 발생

이렇게 적어두면 Claude가 코드를 수정할 때 "이 패턴은 위험하니 이렇게 하겠습니다" 라고 알아서 판단한다. 신입 개발자에게 온보딩 문서를 주는 것과 같다.

포인트: 이론적인 주의사항이 아니라, 실제로 프로덕션에서 터진 사례를 쓰는 게 중요하다. "이런 게 있을 수 있다"보다 "이것 때문에 실제로 3시간 날렸다"가 훨씬 효과적이다.

3계층: Memory — "대화에서 배운 것을 기억하기"

Memory는 대화가 끝나도 남는 기록이다. 4가지 타입으로 분류한다.

타입	역할	예시
project	특정 버그/기능의 해결 기록	"A 기능에서 nil 에러 → B 조건 추가로 해결"
feedback	AI의 작업 방식에 대한 피드백	"수정 전에 기존 패턴부터 grep해라"
reference	외부 시스템 참조 정보	"빌드는 Jenkins 잡 A로 실행"
user	사용자 프로필	"클라이언트 코드 위주로 작업"

각 메모리는 개별 파일이고, MEMORY.md라는 인덱스 파일이 목록을 관리한다.

# Memory Index

## Project
- [A 기능 nil 크래시](project_a_crash.md) — 3층 이상에서 nil, 파라미터 누락
- [B 이벤트 배너 사라짐](project_b_banner.md) — 필터 누락 + 완료 조건 수정
- [C 기능 리팩토링](project_c_refactor.md) — 머신별 함수 분리, 완료

## Feedback
- [기존 코드 패턴 확인](feedback_pattern.md) — 새 코드 전에 기존 패턴 먼저 grep
- [분석 과정 보여주기](feedback_reasoning.md) — 결론만 말하지 말고 소거법도 제시

---

3. Feedback Memory — "같은 실수를 두 번 안 하게 만드는 법"

3계층 중에서 체감 효과가 가장 큰 것이 feedback memory다.

AI가 실수할 때마다 기록해두면, 다음 대화에서 같은 실수를 안 한다. 사람으로 치면 "이전에 지적받은 코드리뷰 사항"을 계속 들고 다니는 것이다.

내가 실제로 쌓은 feedback 15개 (핵심만 추리면)

① "비슷한 이름 구분 안 하고 추측하지 마라"

문제: AI가 TaiyakiMachine과 TakoyakiMachine을 헷갈림
피드백: grep으로 실제 이름 대조 후 판단할 것

→ 이후로 비슷한 이름이 나오면 반드시 검색부터 한다.

② "새 필드 쓰기 전에 선언부를 확인해라"

문제: AI가 새 필드를 사용하는 코드를 제안했는데, 
      프레임워크 특성상 선언부에 필드 등록이 필요함. 빠뜨림.
피드백: self.새필드 쓰기 전에 class 선언부에 있는지 확인, 
       없으면 추가 코드도 함께 제안

→ 실제로 이 피드백 전에는 "unknown member" 에러가 자주 발생했는데, 기록 후에는 0번.

③ "새 코드 전에 기존 패턴부터 찾아라"

문제: 프로젝트에 이미 있는 중복 요청 방지 패턴(DummyModal)을 모르고 
      AI가 다른 방식으로 구현
피드백: 같은 기능 하는 코드가 프로젝트에 이미 있는지 먼저 확인

→ 프로젝트 컨벤션을 자동으로 따르게 됨.

④ "한 곳만 고치지 말고 동일 패턴 전수 확인"

문제: 복사된 코드가 여러 함수에 있는데 한 곳만 수정
피드백: 수정 후 동일 패턴이 다른 곳에도 있는지 grep 필수

⑤ "결론만 말하지 말고 과정을 보여줘"

문제: "여기가 문제입니다" 라고만 답함
피드백: 소거법 과정을 보여줘야 사람이 검증할 수 있다

피드백의 구조

잘 동작하는 피드백에는 3가지가 있다:

---
name: 기존 코드 패턴 확인
type: feedback
---

새 기능 코드 제안 전 기존 코드에서 동일 작업 패턴 반드시 확인.

**Why:** 프로젝트에 이미 확립된 패턴이 있는데 AI가 다른 방식으로 구현하면
코드 일관성이 깨지고 리뷰에서 지적당함.

**How to apply:** Channel:write 전후 처리, 에러 핸들링, 모달 차단 등
새 코드를 짜기 전에 grep으로 유사 구현을 먼저 찾을 것.

규칙 + 이유(Why) + 적용 방법(How) — 이 세 가지가 있어야 AI가 엣지 케이스에서도 스스로 판단할 수 있다. "이유"가 없으면 맹목적으로 따르다가 불필요한 상황에서도 적용하는 문제가 생긴다.

---

4. 커스텀 스킬 — "반복 작업을 슬래시 커맨드로"

Claude Code에서는 자주 쓰는 워크플로우를 슬래시 커맨드로 만들 수 있다. 나는 6개를 만들어서 쓰고 있다.

만든 스킬 목록

명령어	하는 일
/deploy	로컬 파일을 서버에 전송 + 서비스 재시작
/mac-server	서버 상태 확인 (포트별 서비스 정상 여부)
/mac-log	서버 로그 확인 + 에러 패턴 자동 분석
/log-svn	대화 내용에서 커밋 로그 자동 생성
/pr-status	PR 목록 확인 + 밀린 PR 정리
/save-md	대화에서 배운 내용을 memory에 자동 분류 저장

가장 시간 절약이 큰 것: /log-svn

코드를 수정하면서 Claude와 대화한 내용이 쌓여 있다. 대화 끝에 /log-svn을 치면:

1. 이번 대화에서 수정된 파일을 자동 감지
2. "정상 동작 확인됨" 표시된 것만 포함 (디버그 코드 자동 제외)
3. 클라이언트 / 서버 별도 커밋 메시지로 분리
4. 의존성이 있으면 경고 ("서버도 같이 배포해야 합니다")

기존에는 커밋 메시지를 쓰면서 "아까 뭘 고쳤더라..." 하고 기억을 더듬었는데, 이제는 대화 기록이 그대로 커밋 로그가 된다.

습관이 된 것: /save-md

대화가 끝나면 /save-md를 친다. 그러면 AI가 대화 내용을 자동으로 분류한다:

• 코드 패턴/함정 → 프로젝트 CLAUDE.md에 추가
• 버그 해결 기록 → project memory 파일 생성
• 작업 방식 피드백 → feedback memory 파일 생성
• 외부 참조 (서버 경로, 도구 등) → reference memory 생성

이게 복리 효과를 만든다. 2달 동안 50건+의 project memory가 쌓였고, 비슷한 버그가 나오면 AI가 "이전에 비슷한 이슈가 있었는데..."라고 과거 기록을 참조한다.

스킬 작성 요령

스킬 파일은 마크다운 형식이다. 잘 동작하는 스킬의 공통점:

---
name: deploy
description: 파일을 서버에 전송 + 서비스 재시작
---

## 인수에 따른 동작
- 인수 없음: 변경 파일 자동 감지
- `all`: 전체 전송
- `trigger`: 특정 파일만 전송 + 재시작

## 실행 순서
1. 전송할 파일 결정
2. SCP 전송
3. 재시작 (필요한 경우만)
4. 상태 확인
5. 결과 보고

포인트:

• 인수별 분기를 명확하게 써야 한다 (안 그러면 매번 "뭘 배포할까요?" 물어봄)
• 실행 순서를 번호로 나열하면 빠뜨리는 단계 없이 진행
• 상태 확인을 마지막에 넣어야 "됐는지 안 됐는지" 확인까지 자동으로 해줌

---

5. 실제 효율 변화

버그 분석: 30분 → 1분

700개 파일에서 관련 코드를 찾는 작업.

예를 들어 "게임 내 판매 속도 계산이 어떻게 되는지 전부 추출해줘"라고 요청하면, Claude Code는 4개 에이전트를 병렬로 돌려서 50초 만에 관련 함수를 전부 찾아 정리해준다.

사람이 하면? 파일 하나씩 열어서 grep 하고, 호출 관계 추적하고... 최소 30분.

코드리뷰 대응: 분석+수정 5분

코드리뷰에서 "이 함수 호출될 때마다 Y값이 누적 감소하는 버그가 있다"는 지적을 받으면:

1. 리뷰 내용을 Claude에게 보여줌 (스크린샷도 가능)
2. 관련 코드 자동 분석 — 어디서 호출되는지, 왜 누적되는지
3. 수정안 제시 + 직접 수정
4. 비슷한 패턴이 다른 곳에도 있는지 전수 확인

이 전체가 5분 안에 끝난다.

크로스 프로젝트 지식 이전

동일 아키텍처 기반 프로젝트가 2개인데, A에서 "콘텐츠 확장" 작업을 했던 기록이 memory에 남아있다. B에서 같은 작업을 할 때:

• 기존: "그때 어디어디를 수정했었더라..." 기억에 의존 (빠뜨리기 쉬움)
• 현재: memory에 수정 파일 목록, 해결한 이슈, 주의사항이 전부 있음

"한번 한 작업은 두 번째부터 절반 시간에 끝난다" — 이것이 memory 시스템의 핵심 가치다.

---

6. 주의할 점 — AI를 맹신하면 안 되는 이유

2달 쓰면서 겪은 실패 사례들. 솔직하게 공유한다.

"프레임워크 규칙을 모른다"

AI가 문법적으로는 완벽한 코드를 짜더라도, 프로젝트의 프레임워크 규칙을 모르면 런타임에 터진다.

실제 사례: 새 변수를 사용하는 코드를 AI가 제안했는데, 우리 프레임워크는 선언부에 등록하지 않은 변수에 값을 대입하면 에러가 난다. AI가 이걸 빠뜨려서 실행하자마자 크래시.

해결: feedback memory에 "새 필드 쓰기 전에 선언부 확인 필수"를 기록한 후, 이 실수는 완전히 사라졌다.

→ 교훈: AI가 실수하면, 화내지 말고 feedback으로 남겨라. 한번 기록하면 그 실수는 반복되지 않는다.

"기존 패턴을 무시한다"

프로젝트에 이미 확립된 코딩 패턴이 있는데, AI가 "자기 스타일"로 구현하는 경우가 많다.

실제 사례: 네트워크 요청 시 중복 클릭을 방지하는 패턴이 프로젝트에 20곳+ 있었는데, AI는 이걸 모르고 다른 방식으로 구현했다. 코드리뷰에서 "기존 패턴을 써라"고 지적받음.

해결: "새 코드 전에 기존 패턴 먼저 grep" 피드백 추가.

"버그 수정은 OK, 신규 기능은 가이드만"

내가 정한 원칙:

• 버그 수정 → AI가 직접 코드 수정 OK ("고쳐줘")
• 신규 기능 → AI는 어디를 어떻게 수정하면 되는지 가이드만 제공 ("알려줘")

이유: 신규 기능은 기획 의도를 이해해야 하고, 코드 주인의식을 유지해야 하기 때문. AI가 "완성된 코드"를 뱉어내면 오히려 이해하지 못한 채 복붙하게 되는 위험이 있다.

---

7. 시작 가이드 — 오늘부터 적용할 수 있는 것

Step 1: CLAUDE.md 만들기 (10분)

프로젝트 루트에 CLAUDE.md 파일을 만들고, 이것만 적어라:

# 프로젝트 개요
- [기술 스택 한 줄]
- [폴더 구조 간략히]

# 주의사항
- [실제로 터졌던 버그 패턴 1~3개]
- [이 프로젝트에서만 적용되는 규칙]

이것만 있어도 "우리 프로젝트는..." 설명이 사라진다.

Step 2: 실수할 때마다 feedback 남기기

AI가 실수하면 바로 기록:

---
name: 실수 내용
type: feedback
---

규칙.
**Why:** 왜 이게 문제인지.
**How to apply:** 어떤 상황에서 이 규칙을 적용하는지.

3~5개만 쌓여도 "이 AI 나한테 맞춰졌다"는 느낌이 확실히 온다.

Step 3: 반복 작업을 스킬로 (필요할 때)

"이거 매번 같은 순서로 하는데..." 싶은 작업이 있으면 스킬로 만들면 된다.
배포, 커밋 로그 작성, 상태 확인 등.

Step 4: 대화 끝에 /save-md 습관

이건 복리 효과다. 처음엔 느끼기 어렵지만, 1달 지나면 "이 AI가 우리 프로젝트를 꽤 잘 안다"는 상태가 된다.

---

세팅 전/후 비교

상황	세팅 전	세팅 후
새 대화 시작	"우리 프로젝트는..." 5분 설명	바로 작업 시작
코드 수정 제안	프레임워크 규칙 몰라서 크래시	함정 패턴 자동 회피
비슷한 버그 재발	"이거 전에도 있었는데..."	memory에서 과거 해결법 참조
AI 실수	매번 같은 지적 반복	feedback 한번이면 끝
커밋 로그 작성	수동으로 10분	/log-svn으로 30초
서버 배포	수동으로 5단계	/deploy로 한번에

---

마무리

Claude Code의 진짜 가치는 "코드를 짜주는 것"이 아니다. 프로젝트를 이해하고, 내 작업 방식을 학습하고, 실수에서 배우는 것이다.

그리고 그 학습은 자동으로 일어나지 않는다. CLAUDE.md를 쓰고, feedback을 남기고, memory를 쌓는 — 내가 투자한 시간만큼 돌아온다.

18만 줄 레거시에서 2달간 쌓은 기록:

• CLAUDE.md: 전역 1개 + 프로젝트별 2개
• Memory: project 50건+, feedback 15건+, reference 5건+
• 커스텀 스킬: 6개
• 해결한 버그: 40건+

처음 10분 — CLAUDE.md 하나 만드는 것부터 시작해보길 권한다.