Claude Code를 활용한 AI 프로그래밍 효율화 전략과 한계

몇 년 전에 만든 jQuery + Django 프로젝트를 SvelteKit으로 갈아엎는다고 생각해 보세요.

HTML 구조는 div 지옥에서 벗어나야 하고, Bootstrap은 최소한의 Tailwind로 대체해야 하고, 템플릿에 뒤엉킨 조건 분기들은 깔끔한 Svelte 컴포넌트로 쪼개야 합니다.

직접 손으로 하면 한 라우트 옮기는 데 1~2시간은 금방입니다. 그래서 "이거야말로 AI 코딩의 완벽한 사용처 아닌가?" 싶은데, 막상 써 보면 내가 직접 짠 코드 퀄리티의 90%에도 못 미치는 느낌이 들죠.

이 글에서는 실제 개발자들이 Hacker News에서 주고받은 경험을 바탕으로, Claude Code와 같은 AI를 프로그래밍에 제대로 활용하는 방법과 그 한계까지 정리해 봅니다. 특히 CLAUDE.md, 플랜 모드, 피드백 루프, 컨텍스트 관리, Opus 4.5 모델 활용법에 초점을 맞춰 설명합니다.

프로젝트마다 꼭 두는 CLAUDE.md, 어떻게 써야 제대로 먹힐까

Claude Code에는 특별한 파일이 하나 있습니다. 바로 프로젝트 루트에 두는 CLAUDE.md입니다.

이 파일은 "팀에 새로 합류한 개발자에게 주는 요약 문서"와 비슷한 역할을 합니다. 프로젝트의 코드 스타일, 금지 사항, 선호 패턴, 테스트/포매터 규칙 등을 적어 두면, Claude는 매 세션 시작 때 이 파일을 자동으로 읽고 참고하려고 합니다.

여기서 중요한 포인트는 두 가지입니다.

첫째, "Claude가 자꾸 반복해서 틀리는 것들"을 이 파일에 옮겨 적는 것입니다. 예를 들어 "주석은 수정하지 말 것", "테스트를 반드시 실행할 것", "React 컴포넌트는 20줄 이상이면 반드시 분리할 것" 같은 것들을 간단명료하게 적어 두면, 이후 대화에서 같은 설명을 반복할 필요가 줄어듭니다.

둘째, 너무 길게 쓰지 않는 것입니다. Claude Code 팀은 대략 1,000 토큰(대략 700~800단어) 이내를 권장합니다. 규칙이 많아지면, 핵심이 흐려지고, 실제로 모델이 중요하게 보지 않게 됩니다. 그래서 많은 팀은 CLAUDE.md에서 각 언어나 서브시스템에 대한 세부 스타일은 별도 XXX_STYLE.md 파일로 분리하고, 핵심 원칙만 짧게 정리합니다.

실제 유저들 이야기처럼, CLAUDE.md의 내용이 항상 완벽하게 지켜지는 것은 아닙니다. 모델은 결정론적인 프로그램이 아니라 "다음 단어를 확률적으로 예측하는 시스템"이라, 지시가 문맥 속에서 희미해질 때가 분명히 있습니다. 그래서 CLAUDE.md를 "절대 규칙"이라기보다 "잘 설계된 온보딩 문서 + 반복 방지 장치" 정도로 받아들이는 편이 현실적입니다.

플랜 모드: "먼저 설계, 나중에 구현"이 진짜 2~3배 빨라지는 이유

Claude Code가 다른 코딩 도구와 확실히 다른 지점 중 하나가 플랜 모드(Plan Mode)입니다. 에디터에서 Shift + Tab 두 번을 눌러 켜는 모드죠.

플랜 모드는 "바로 코드를 짜지 않고, 먼저 계획부터 세우도록 강제하는 모드"입니다. 복잡한 리팩터링이나 신규 기능을 할 때, AI에게 곧바로 "이거 다 구현해 줘"라고 던지면 대개 어딘가 망가진 상태로 돌아옵니다. 반면 플랜 모드를 쓰면, 다음과 같은 흐름으로 작업하게 됩니다.

우선 Claude가 전체 작업을 여러 단계의 계획으로 쪼갭니다. 사람은 이 계획을 읽어 보면서 "이 단계는 필요 없다", "여기는 Svelte 컴포넌트로 나누자", "이 부분은 기존 Django 템플릿 로직과 동일해야 한다"처럼 피드백을 줍니다. 몇 번의 왕복 대화로 계획이 마음에 들면, 그제서야 각 단계를 실제 코드로 옮기게 하는 방식입니다.

이 접근의 장점은 명확합니다.

• AI가 잘못 이해한 부분을 코드가 아니라 계획 단계에서 잡아낼 수 있다

• 큰 기능을 자연스럽게 작은 작업 단위로 나눌 수 있다

• 계획 문서가 파일로 저장되기 때문에 이후에 참조하거나 수정하기 쉽다

다만 최근에는 "한 세션 안에서 여러 번 플랜 모드를 쓰면, 예전 계획을 계속 끌고 와서 헷갈린다"는 불편함도 보고되고 있습니다. 이럴 때는 의식적으로 "새 플랜을 시작하자"고 명시적으로 지시하거나, 아예 새 채팅 세션에서 다시 플랜 모드를 여는 식으로 사용하면 혼란을 줄일 수 있습니다.

컨텍스트 붕괴와 긴 대화의 함정: "대화는 짧게, 작업은 잘게"

Claude나 다른 LLM을 오래 쓰다 보면 모두 비슷한 현상을 겪습니다. 처음엔 CLAUDE.md도 잘 지키고, 프로젝트 규칙도 잘 따르던 모델이, 어느 순간부터는 테스트도 안 돌리고, 스타일 가이드도 무시하는 것처럼 느껴지죠.

이때 많은 사람이 "모델이 CLAUDE.md를 안 읽는다"고 느끼지만, 실제로는 조금 다릅니다. 모델은 여전히 시스템적으로 그 파일을 읽고 있지만, 컨텍스트 창 내부에서 오래전에 주어진 정보는 점점 영향력이 약해지는 현상이 있습니다. 이걸 흔히 "컨텍스트 로트(context rot)"라고 부릅니다.

그래서 경험 많은 사용자일수록 대화를 길게 이어가지 않습니다. 한 세션에는 하나의 작업만, 혹은 하나의 질문만 다루고, 다음 작업이 생기면 새 세션을 여는 식으로 사용합니다.

긴 프로젝트를 할 때는 다음과 같은 패턴이 효과적입니다.

하나, 처음에 Claude에게 전체 계획이나 체크리스트를 적게 해서, PLAN.md 같은 파일로 저장합니다.

둘, 실제 구현은 각 단계별로 새 채팅을 열어 진행하며, 필요한 파일과 해당 단계만 컨텍스트에 넣습니다.

셋, 작업이 끝날 때마다 계획 문서를 업데이트하고, 다음 단계로 넘어갈 때는 다시 새 채팅에서 그 일부만 가져와 진행합니다.

이런 방식은 귀찮아 보이지만, 실제로는 긴 컨텍스트에서 모델이 멍해지는 시간을 크게 줄여 줍니다. 특히 SvelteKit로 마이그레이션처럼 "동일한 패턴을 여러 라우트에 반복 적용하는 작업"에서는 매 라우트마다 새 세션을 열고, 필요한 파일만 주는 편이 훨씬 안정적입니다.

"AI에게 자기 검사를 시켜라": 테스트·브라우저·로그를 활용한 피드백 루프

AI 코딩에서 성능을 극적으로 올려 주는 요소는 좋은 피드백 루프입니다. 단순히 "코드 짜 줘" → "에러 났는데?" → "다시 고쳐줘" 수준에서 머물면, 모델이 어림짐작으로 고치다가 또 깨뜨리는 악순환이 반복됩니다.

Claude Code 팀이 권장하는 접근은 이렇습니다.

가능하면 코드가 제대로 동작하는지 확인할 수 있는 수단을 모델에게 같이 줍니다. 예를 들어 프론트엔드라면 Puppeteer나 Playwright 같은 MCP 서버로 브라우저를 띄워, 실제 페이지를 열어 보고 체크하게 만들 수 있습니다. 백엔드나 라이브러리라면 테스트 스위트나 샘플 입력/출력을 제공해, "테스트를 돌려 결과를 보고, 실패 원인을 분석하고 고치게" 할 수 있습니다.

또 하나 유용한 패턴은, 모델에게 스스로 로그를 심게 하는 것입니다. 오묘하게 실패하는 복잡한 버그가 있을 때, "디버깅을 위해 필요한 정보들을 로그로 남기는 코드를 추가해 달라"고 시킨 다음, 실행 로그를 통째로 넘겨 분석하게 하면, 사람이 두 시간 고민할 문제를 몇 분 만에 좁혀줄 때가 많습니다.

조금 더 어려운 문제에서는 "먼저 이상적인 구조를 가짜 코드(pseudocode)로 설계하게" 한 뒤, 현재 구현과의 차이점을 비교해 보게 하는 방식도 효과적입니다. 이런 패턴은 특히 레거시 코드 리팩터링, 프레임워크 마이그레이션, 상태 관리 정리 등에 잘 먹힙니다.

핵심은 단 하나입니다. AI가 해 놓은 일을 검증할 수단을 같이 제공해 주면, 그때부터는 진짜로 2~3배 빠른 도우미가 된다는 점입니다.

어떤 모델을 쓸까: Sonnet vs Opus 4.5, 그리고 비용 감각

Hacker News 스레드에서도 여러 번 언급되었듯, Opus 4.5는 Sonnet 4.5에 비해 확실한 "단계 차이"가 있다는 평가가 많습니다. 코드 품질, 지시 사항 준수, 플랜 생성 능력, 장기 맥락 파악 등에서 한 세대 위라는 느낌입니다.

물론 문제는 비용입니다. Opus 계열은 Sonnet보다 비싸고, 지연 시간도 긴 편입니다. 다만 Anthropic은 최근 단가를 꽤 내렸고, 일부 사용자는 "더 똑똑한 모델을 써서 오히려 전체 토큰 사용량이 줄어든다"고도 말합니다. 한 번에 제대로 이해하고 해결하니, 뻘짓 토큰이 줄어드는 식입니다.

개인 개발자라면 선택지가 몇 가지 있습니다.

클라우드 툴에서 무료/저가로 제공하는 Opus 4.5 할당량을 활용하거나, 일상적인 자동완성과 간단한 리팩터링은 가벼운 모델(Sonnet, 기타 IDE 내 모델)로 처리하고, 플랜 작성, 대규모 리팩터링, 프레임워크 마이그레이션 같은 고난도 작업에만 Opus 4.5를 쓰는 혼합 전략을 택하는 식입니다.

포인트는 "항상 제일 비싼 모델만 쓰자"가 아니라, 작업 난이도와 중요도에 맞춰 모델을 선택하는 전략을 세우는 데 있습니다.

AI가 만능은 아니다: 지침 무시, 보안 실수, 그리고 책임의 문제

현실적인 얘기도 필요합니다.

스레드에는 "CLAUDE.md에 분명히 쓰여 있는데도 테스트를 안 돌린다", "주석은 절대 건드리지 말라 했는데 또 고친다", "심지어 비밀 키를 프론트 코드에 박아 넣으려고 한다" 같은 경험담도 여럿 등장합니다.

이건 Claude만의 문제가 아니라, 모든 LLM이 가진 구조적인 한계와 관련이 있습니다. 모델은 규칙을 "논리적으로 이해하고 지키는 존재"가 아니라, 문맥에서 그럴듯한 다음 토큰을 뽑는 통계적 시스템입니다. CLAUDE.md의 지시가 최근 대화 흐름과 충돌하거나, 훈련 데이터에서 자주 봤던 패턴과 맞지 않으면, 사람이 보기엔 "말을 안 듣는 것처럼 보이는" 결과가 나옵니다.

그래서 실제로는 이런 태도가 필요합니다.

AI가 작성한 코드는 반드시 사람이 리뷰한다. 보안 관련 코드(인증, 결제, 비밀키, 데이터 삭제 등)는 특히 꼼꼼히 본다. 테스트/포매터/린터 실행을 "AI가 알아서 하겠지"라고 믿지 말고, CI나 pre-commit 훅으로 강제한다.

AI를 쓰면 생산성이 크게 오를 수 있지만, 책임의 무게는 여전히 개발자 본인에게 있다는 사실은 변하지 않습니다. "코드를 이해하지 않은 채 통으로 믿고 배포하는 것"은 단기적으로는 빨라 보일 수 있어도, 장기적으로는 유지보수 지옥을 예약하는 행동입니다.

오래 가는 워크플로우: 계획은 문서에, 작업은 세션별로, 규칙은 짧게

이제 다시 처음 이야기로 돌아와 봅니다. 오래된 jQuery + Django 프로젝트를 SvelteKit으로 옮기면서, 한 라우트당 1~2시간씩 들이고 있다면, AI는 정말 좋은 가속기가 될 수 있습니다. 다만 "한 번에 완벽한 Svelte 코드로 갈아주세요"라는 식의 마법 주문은 거의 통하지 않습니다.

더 현실적인 전략은 다음 흐름에 가깝습니다.

먼저 Claude에게 마이그레이션 전체 계획을 세우게 하고, 그 계획을 MIGRATION_PLAN.md 같은 파일로 저장합니다. 각 라우트나 화면 단위로 새 채팅 세션을 열어, 필요한 Django 템플릿과 스타일, 목표 Svelte 구조를 보여 주며 플랜 모드로 세부 계획을 다시 세웁니다. CLAUDE.md에는 Svelte 코드 스타일, Tailwind 사용 원칙, 컴포넌트 분리 기준 정도만 짧고 명확하게 적어 둡니다. 코드가 생성되면, 테스트와 Storybook, 브라우저 확인을 한 번씩 돌려 보고, 문제를 발견하면 그 결과를 다시 Claude에게 넘겨 "원인 분석 + 수정"을 맡깁니다.

이 정도만 지켜도, "손으로 다 하던 시절" 대비 체감 속도가 2배 이상 빨라지는 경우가 많습니다.

AI 프로그래밍에서 중요한 건 어떤 모델을 쓰느냐보다, 어떤 방식으로 함께 일하느냐입니다. 규칙은 문서에, 계획은 플랜 모드와 마크다운에, 작업은 짧은 세션으로 쪼개고, 검증은 테스트와 도구에 맡기는 구조를 만들면, Claude든 다른 AI든 훨씬 믿을 만한 동료가 되어 줍니다.

그리고 마지막으로 한 가지만 기억하면 좋겠습니다. "AI가 코드를 대신 써 줄 수는 있지만, 설계를 대신 책임져 주지는 않는다"는 것 말입니다.

출처 및 참고 : Ask HN: How can I get better at using AI for programming? | Hacker News