클로드 코드로 파이썬 자동매매 프로그램을 만들면서 계속 겪은 문제가 하나 있었습니다.
버그 하나 고쳐달라고 했는데, 돌아온 변경 내역(diff)을 열어보면 요청한 부분 말고도 열 줄 스무 줄이 같이 바뀌어 있습니다. 주석 표현이 다듬어져 있고, 안 쓰는 것처럼 보이는 함수가 지워져 있고, 들여쓰기 스타일이 바뀌어 있습니다. 하나하나 보면 나쁜 변경은 아닌데, 제가 요청하지 않은 변경입니다.
자동매매 코드에서 이건 꽤 위험합니다. 한 줄 잘못 바뀌면 그대로 실거래 손실로 이어집니다. 매번 바뀐 줄을 전부 손으로 확인하다 보면, AI한테 맡겨서 아낀 시간을 검토하는 데 그대로 다시 쓰게 됩니다.
이 문제를 정리해준 글이 있었습니다. Andrej Karpathy가 LLM이 코딩할 때 반복적으로 저지르는 실수를 관찰해서 올린 내용이고, 이걸 다른 개발자가 CLAUDE.md 파일 형태로 정리해 공개했습니다. 적용해보니 바뀌는 줄이 눈에 띄게 줄었습니다.
변경 내역(diff)이 뭔가
개발 용어가 익숙하지 않은 분을 위해 짚고 넘어가겠습니다. 변경 내역은 코드에서 바뀐 부분만 뽑아 보여주는 화면입니다. 클로드 코드가 파일을 고치면 이런 형태로 보여줍니다.
df = fdr.DataReader(code, start, end)
- if df['Volume'].mean() > 100000:
+ if df['Volume'].tail(20).mean() > 100000:
signals.append(code)-로 시작하는 줄 : 지워진 줄+로 시작하는 줄 : 새로 들어간 줄- 기호 없는 줄 : 바뀌지 않은 부분
여기서 - 와 + 가 적을수록 좋습니다. 제가 요청한 것만 딱 바뀌었다는 뜻이니까요.
CLAUDE.md가 뭔가
프로젝트 폴더에 CLAUDE.md라는 파일을 두면, 클로드 코드가 세션을 시작할 때마다 이 파일을 자동으로 읽습니다. 매번 "이렇게 해줘"라고 설명할 필요 없이, 한 번 적어두면 계속 적용됩니다.
C:\claude\내프로젝트\
├── CLAUDE.md ← 여기에 두면 끝
├── breakout.py
└── backtest.py파일 하나 만들어서 넣어두는 게 전부입니다. 별도 설정도, 명령어도 없습니다.
직접 쓰기가 막막하면 클로드 코드에 /init이라고 입력해 초안을 만들게 할 수도 있습니다. 그렇게 나온 파일을 열어서 제 규칙으로 고쳐 쓰면 됩니다.
4가지 원칙
1. 코딩 전에 생각하라
AI가 가장 흔하게 저지르는 실수가 이겁니다. 요청이 애매하면 물어보는 대신 알아서 해석을 하나 정하고 그냥 달립니다. 그러고 나면 결과물이 제가 원한 것과 다른데, 이미 코드는 다 쓰여 있습니다.
그래서 규칙으로 못박아 뒀습니다. 가정은 명시적으로 말할 것, 해석이 여러 개면 전부 제시할 것, 불확실하면 멈추고 질문할 것. 더 간단한 방법이 있으면 말하고, 필요하면 반박할 것.
2. 단순함을 우선하라
스크리너에 거래량 필터 하나 추가해달라고 했는데, 필터 설정을 JSON으로 관리하는 클래스가 딸려 오는 식입니다. 나중에 확장할 걸 대비했다는 건데, 저는 확장할 계획이 없었습니다.
기준은 이렇게 잡았습니다. 요청받지 않은 기능 금지, 한 번만 쓰는 코드에 추상화 금지, 일어날 수 없는 상황에 대한 예외처리 금지. 200줄 썼는데 50줄로 될 것 같으면 다시 씁니다.
스스로 물어볼 것 — "시니어 엔지니어가 이걸 보고 과하게 복잡하다고 할까?"
3. 외과수술식으로 수정하라
제가 제일 필요했던 항목입니다. 요약하면 꼭 건드려야 하는 것만 건드리고, 자기가 만든 것만 치운다는 것입니다.
인접한 코드나 주석을 멋대로 개선하지 않고, 망가지지 않은 걸 리팩토링하지 않고, 제 스타일이 마음에 안 들어도 기존 스타일을 따릅니다. 관련 없는 죽은 코드를 발견하면 삭제하지 말고 언급만 합니다.
대신 자기가 만든 뒷정리는 합니다. 이번 수정으로 안 쓰이게 된 import나 변수는 지웁니다. 원래부터 있던 죽은 코드는 그대로 둡니다.
판단 기준은 딱 한 줄입니다. 바뀐 모든 줄이 제 요청과 직접 연결되어야 합니다.
4. 목표 주도로 실행하라
"작동하게 해줘"라고 하면 매 단계마다 제가 개입해야 합니다. 반면 성공 기준을 명확히 주면 알아서 될 때까지 돌립니다.
"검증 추가" → "잘못된 입력에 대한 테스트를 쓰고, 통과시켜라"
"버그 수정" → "버그를 재현하는 테스트를 쓰고, 통과시켜라"
"X 리팩토링" → "리팩토링 전후로 테스트가 통과하는지 확인하라"백테스팅 코드처럼 검증이 중요한 작업에서는 이 항목 하나로 왕복 횟수가 확 줄었습니다.
전체 파일 (복사해서 쓰세요)
제가 쓰고 있는 CLAUDE.md 전문입니다. 그대로 복사해서 프로젝트 폴더에 저장하시면 됩니다.
# CLAUDE.md
LLM이 코딩할 때 흔히 저지르는 실수를 줄이기 위한 행동 지침. 프로젝트별 지침과 함께 병합해서 사용할 것.
**트레이드오프**: 이 지침은 속도보다 신중함에 무게를 둔다. 사소한 작업에는 판단에 따라 유연하게 적용할 것.
## 1. 코딩 전에 생각하라
**추측하지 마라. 혼란을 숨기지 마라. 트레이드오프를 드러내라.**
구현하기 전에:
- 네가 세운 가정을 명시적으로 말하라. 불확실하면 질문하라.
- 해석이 여러 개 가능하면 모두 제시하라 — 조용히 하나를 고르지 마라.
- 더 간단한 방법이 있으면 말하라. 필요할 때는 반박하라.
- 뭔가 불명확하면 멈춰라. 무엇이 헷갈리는지 짚어라. 물어라.
## 2. 단순함을 우선하라
**문제를 푸는 최소한의 코드만. 추측성 코드는 금지.**
- 요청받지 않은 기능은 추가하지 마라.
- 한 번만 쓰는 코드에 추상화를 만들지 마라.
- 요청하지 않은 "유연성"이나 "설정 가능성"을 넣지 마라.
- 일어날 수 없는 상황에 대한 에러 처리를 하지 마라.
- 200줄을 썼는데 50줄로 될 수 있다면, 다시 써라.
스스로 물어라: **"시니어 엔지니어가 이걸 보고 과하게 복잡하다고 할까?"** 그렇다면 단순화하라.
## 3. 외과수술식으로 수정하라
**꼭 건드려야 하는 것만 건드려라. 네가 만든 것만 치워라.**
기존 코드를 수정할 때:
- 인접한 코드, 주석, 서식을 멋대로 "개선"하지 마라.
- 망가지지 않은 것을 리팩토링하지 마라.
- 네 스타일과 다르더라도 기존 스타일을 따르라.
- 관련 없는 죽은 코드를 발견하면 — 삭제하지 말고 언급만 하라.
네 수정이 고아 코드를 만들었다면:
- 네 수정으로 인해 안 쓰이게 된 import/변수/함수는 제거하라.
- 기존에 있던 죽은 코드는 요청받지 않는 한 제거하지 마라.
**테스트: 바뀐 모든 줄은 사용자의 요청과 직접 연결되어야 한다.**
## 4. 목표 주도로 실행하라
**성공 기준을 정하라. 검증될 때까지 반복하라.**
작업을 검증 가능한 목표로 변환하라:
- "검증 추가" → "잘못된 입력에 대한 테스트를 쓰고, 통과시켜라"
- "버그 수정" → "버그를 재현하는 테스트를 쓰고, 통과시켜라"
- "X 리팩토링" → "리팩토링 전후로 테스트가 통과하는지 확인하라"
여러 단계로 이루어진 작업은 간단한 계획을 먼저 밝혀라:
1. [단계] → 검증: [확인 방법]
2. [단계] → 검증: [확인 방법]
3. [단계] → 검증: [확인 방법]
강한 성공 기준은 스스로 반복하며 진행하게 해준다. 약한 기준("작동하게 해줘")은
매 단계마다 개입을 요구한다.
---
이 지침이 효과가 있다는 신호: diff에 불필요한 변경이 줄어들고, 과한 복잡함으로 인한
재작성이 줄어들며, **실수한 뒤가 아니라 구현 전에** 확인 질문이 나온다.프로젝트별 설정 vs 전역 설정
처음에 헷갈렸던 부분입니다. CLAUDE.md는 두는 위치에 따라 적용 범위가 달라집니다.
| 위치 | 적용 범위 |
|---|---|
C:\claude\내프로젝트\CLAUDE.md |
그 프로젝트에서만 |
C:\Users\사용자명\.claude\CLAUDE.md |
모든 프로젝트 공통 |
공통 원칙은 전역에 두고, 프로젝트 고유 규칙만 각 폴더에 두는 방식이 편합니다. 저는 자동매매 프로젝트 폴더에 이런 줄을 따로 추가해뒀습니다.
## 이 프로젝트 규칙
- 실거래 주문을 보내는 코드는 수정 전 반드시 확인받을 것
- API 키는 절대 코드에 직접 쓰지 말고 환경변수로만
- 매매 로직을 바꿨으면 백테스트를 먼저 돌려서 결과를 보고할 것참고로 메모장으로 저장할 때는 파일 형식을 모든 파일로 바꿔야 합니다. 안 그러면 CLAUDE.md.txt가 되어서 인식되지 않습니다.
써보니 어땠나
가장 큰 변화는 바뀌는 줄이 짧아진 것입니다. 예전엔 한 번 요청에 파일 서너 개가 바뀌어서 전부 훑어야 했는데, 지금은 관련된 부분만 바뀌어서 확인이 빠릅니다.
두 번째는 질문을 먼저 한다는 것입니다. 예전엔 다 만들고 나서 "아 이게 아닌데" 하는 경우가 많았는데, 이제는 애매한 지점에서 먼저 물어봅니다. 처음엔 왔다갔다 하는 게 늘어난 것 같지만, 다시 만드는 횟수가 줄어서 결과적으로 훨씬 빠릅니다.
파이썬을 아예 모르는 상태에서 자동매매 프로그램을 만들기 시작한 입장에서, 이 파일 하나 넣은 게 지금까지 한 세팅 중 효율이 제일 좋았습니다. 클로드 코드를 쓰고 계신데 바뀐 줄이 매번 지저분하다면 한 번 만들어볼 만합니다.
클로드 코드를 이제 막 시작하셨다면 이 글들도 같이 보시면 됩니다.
'AI 코딩 > 클로드 코드' 카테고리의 다른 글
| KIS API로 자동매매하다 막힌 것들 — 초당 호출 제한·실시간 시세·주문 (0) | 2026.08.20 |
|---|---|
| 한국투자증권 KIS API를 고른 이유 — HTS를 켜지 않아도 되는 자동매매 (0) | 2026.08.20 |
| 코딩 몰라도 됩니다 — 클로드 코드 설치와 첫 실행 (터미널 없이) (0) | 2026.08.19 |
| 클로드 코드 승인창이 계속 뜰 때 — settings.json 권한 설정법 (0) | 2026.08.18 |
