✨핵심 원칙 수많은 조언을 관통하는 원칙은 결국 네 가지로 수렴한다. 1. 계획 먼저, → AI에게 무엇을 만들지 명확히 알려준다 2. 작게 쪼개고, → AI가 집중할 수 있는 크기로 만든다 3. 피드백 루프를 만들고, → AI가 스스로 수정할 수 있게 한다 4. 컨텍스트를 자주 초기화하라. → AI의 기억을 깨끗하게 유지한다 이 네 가지는 독립된 팁이 아니라 하나의 워크플로우를 구성하는 단계다.
네 가지 원칙이 작동하는 이유: 첫째, 계획 먼저 세우면 AI의 추측을 차단하고 명확한 목표를 제공하여 2~3배 개선된다. 둘째, 작게 쪼개면 컨텍스트 윈도우 한계를 극복하고 핵심 밀도를 유지하여 성공률이 급상승한다. 셋째, 피드백 루프를 설정하면 AI가 스스로 수렴할 수 있는 검증 기준이 생겨 반복 개선이 가능하다. 넷째, 컨텍스트 초기화를 통해 Recency bias를 극복하고 초기 지시의 영향력을 유지하면 일관성이 보장된다.
1. AI 코딩의 본질: "똑똑한 요리 보조 로봇"
AI 코딩을 '똑똑한 요리 보조 로봇'에 비유할 수 있다.
주방에 모든 레시피를 아는 로봇 셰프가 있다고 상상해 보자. 하지만 이 로봇은 다음과 같은 특이점이 있다.
모호한 지시에 약하다: "맛있는 요리해 줘"라고 하면 엉뚱한 결과물을 내놓는다.
구체적 지시에 강하다: "토마토 3개를 1cm 크기로 깍둑썰기해서 중불에 5분 볶아줘"라고 하면 완벽하게 수행한다.
멀티태스킹의 한계: 여러 단계를 한 번에 시키면 중간 과정을 누락한다.
지속적 피드백 필수: 중간에 맛을 보며 교정하지 않으면 틀린 방향으로 계속 간다.
많은 사람이 AI를 "마법의 지팡이"로 오해하지만, AI는 개발자의 머릿속에 있는 목표와 제약 사항을 스스로 읽을 수 없다. 결국 핵심은 '어떻게 지시하고 관리하느냐'에 달려 있다.
2. 우리가 놓치고 있는 5가지
Q1. 왜 "계획 먼저" 세워야 하는가?
AI는 명확한 지시가 없으면 추측을 시작한다. 계획이 없다는 것은 AI에게 "마음대로 추측해도 좋다"고 허락하는 것과 같다. Claude Code 개발자 Boris Cherny에 따르면, Plan 모드를 통해 계획을 먼저 세우면 어려운 작업에서 2~3배 더 나은 결과를 얻을 수 있다.
Claude Code에서는 Shift+Tab을 두 번 누르면 Plan 모드로 진입한다. 이 모드에서 AI는 코드를 읽기만 하고 수정하지 않으며, 구현 계획을 제시하고 승인을 요청한다. 계획이 만족스러울 때만 실행 단계로 넘어간다.
이 원칙은 Claude Code에만 해당하는 것이 아니다. 어떤 도구를 쓰든 핵심은 동일하다. 먼저 해결 계획을 문서로 만들고, 모호한 부분을 모두 드러나게 한 다음, 계획 자체가 충분히 명확해졌을 때만 코드 생성을 시작하는 것이다. 결과 품질은 프롬프트의 문장력이 아니라 계획 문서의 명확도에 좌우된다.
실제로 커뮤니티에서 높은 평가를 받는 워크플로우 도구들은 이 원칙을 구조적으로 강제한다. GitHub에 공개된 “superpowers” 플러그인은 brainstorming → design document → implementation plan → execution이라는 단계를 순서대로 밟지 않으면 코드 생성 자체가 시작되지 않도록 설계되어 있다.
Q2. "컨텍스트 윈도우"의 함정은 무엇인가?
대화가 길어질수록 AI가 똑똑해진다고 생각하면 오산이다. AI가 참고할 수 있는 정보 범위는 제한적이다.
대화가 길어지면 오래된 정보가 희미해지는 '컨텍스트 부패(Context Rot)'가 발생한다.
컨텍스트 윈도우 : AI가 한 번에 “기억하고 참고할 수 있는” 정보의 범위
실전에서 효과가 검증된 패턴은 다음과 같다. 먼저 사람이 한 번 최고 품질로 구현한다.
그 결과물을 기준 예제로 제공한 뒤, 동일한 패턴의 나머지 작업을 AI에 맡긴다.
이 방식은 AI가 가장 잘하는 영역, 즉 패턴 반복에 정확히 부합한다.
한 HN 사용자는 자신의 원칙을 이렇게 요약했다.
“500~750단어 정도가 이상적이다. Less is more다.”
프롬프트가 너무 짧으면 정보 부족으로 AI가 추측하게 되고, 너무 길면 핵심이 묻힌다. 적절한 밀도의 짧은 지시가 최선이다.
Q3. 왜 작업을 작은 단위로 쪼개야 하는가?
"전체 리팩터링해 줘"라는 요청은 실패할 확률이 높다.
반면 "이 파일의 이 함수를 인터페이스에 맞게 변환해 줘"와 같은 구체적 요청은 성공한다.
레고 성을 쌓듯, 한 벽씩 완성해 나가야 전체 구조가 견고해진다.
Q4. 피드백 루프가 왜 필요한가?
AI는 스스로 성공과 실패를 판단하지 못한다.
"잘 만들어줘"가 아니라 "이 테스트를 통과하게 만들어줘"와 같은 명확한 기준을 제시해야 AI가 반복하며 스스로 개선할 수 있다.
구체적으로는 테스트 통과, 빌드 성공, 린터 에러 0개 같은 자동 검증 가능한 목표를 제시하는 것이다.
Anthropic의 공식 가이드인 "Prompting the Agent Loop"에서도 이를 핵심 원칙으로 권장한다.
프롬프트에 "yarn test가 통과할 때까지 반복하라"처럼 루프 조건을 명시적으로 포함하면,
AI 에이전트가 도구를 반복 실행하며 문제를 해결하는 흐름이 만들어진다.
Boris Cherny는 검증 방법을 AI에게 제공하는 것이 중요하다고 강조했다. 예를 들어 Svelte 프로젝트에서는 Puppeteer MCP 서버를 연결해서 AI가 브라우저에서 직접 결과를 확인하게 할 수 있다. 로그 파일을 남기게 하거나, 디버거/트레이서를 배치 모드로 실행하게 하는 것도 같은 맥락이다.
기존 동작을 검증하는 테스트가 이미 있다면 리팩터링의 난이도는 크게 낮아진다. 테스트가 없다면 AI에게 먼저 테스트를 작성하게 한 후, 그 테스트를 통과하는 방향으로 리팩터링을 진행하는 TDD 스타일 접근도 효과적이다.
테스트 주도 개발(TDD, Test-Driven Development) 소프트웨어 개발 시, 실제 코드를 작성하기 전에 실패하는 테스트 케이스를 먼저 만들고, 이를 통과하는 최소한의 코드를 작성한 뒤 리팩토링하는 과정을 반복하는 방식
Q5. AI가 만든 코드를 바로 써도 될까?
CodeRabbit 데이터에 따르면, AI 생성 PR은 인간 대비 2배 이상의 이슈(26개 vs 12.3개)를 포함한다.
AI 코드는 아직까지는 "대부분 작동하지만 가끔 심각하게 잘못된다"는 사실을 명심해야 한다.
3. LLM의 구조적 특성과 대응 전략
이 원칙들은 LLM 특성에서 기인한다.
1. 최신성 편향(Recency Bias): 최근 대화에 더 집중하고 초기 지시를 잊는다. 따라서 컨텍스트를 자주 초기화해야 한다.
ㄴ 한 세션에서는 하나의 작업만 처리한다. 방향이 바뀌면 새 세션에서 다시 시작한다. 장기 프로젝트의 경우 `plan.md` 같은 문서에 현재 상태를 기록하고, 새 세션에서 이 문서를 다시 주입한다. ㄴ 결과가 마음에 들지 않을 때도 마찬가지다. 같은 세션에서 코드 수정 요청을 반복하면 품질이 빠르게 무너진다. 대신 계획 문서를 수정한 뒤 새 세션에서 처음부터 다시 실행하는 것이 낫다.
ㄴ 한 사용자는 "계획(PLAN)과 진행 상황(TO-DO)을 별도 문서로 분리하라"고 조언했는데, 같은 문서에 두면 AI가 코드를 수정할 때마다 계획 자체를 변경하는 문제가 발생하기 때문이다.
2. 물리적 한계: 정보량이 많아지면 밀도가 희석된다. 작업을 쪼개고 핵심 정보만 제공해야 한다.
3. 패턴 인식 강점: 추상적 언어보다 예시를 좋아한다. Before/After 예제를 주는 것이 가장 효과적이다.
4. 실전 워크플로우: 레거시 마이그레이션 예시
❌ 틀린 접근: "이 프로젝트를 마이크로서비스로 리팩터링해 줘."
✅ 올바른 접근: 1. 계획 단계 (새 세션): "구조 설계와 마이그레이션 순서를 담은 `plan.md`를 작성해 줘. 코드는 짜지 마." 2. 기준 구현 (새 세션 + plan.md): "계획에 따라 첫 번째 서비스를 구현해 줘. 테스트 통과가 필수야." 3. 패턴 반복: "첫 서비스의 패턴을 참고해서 다음 서비스를 구현해 줘."
1단계: 계획 세우기 (새 세션)
이 프로젝트를 마이크로서비스로 변환하는 상세한 계획을 세워줘.
다음을 포함해야 한다:
- 서비스 분리 기준
- 각 서비스의 책임
- API 경계
- 마이그레이션 순서
코드는 만들지 말고 plan.md 문서만 만들어줘.
→ AI가 plan.md를 생성한다 → 사람이 검토하고 승인한다
2단계: 첫 서비스를 직접 구현 (새 세션, plan.md 첨부)
plan.md를 참고해서 User Service를 구현해줘. 테스트가 모두 통과해야 한다.
→ AI가 구현한다 → 사람이 코드 리뷰하고 이해한다 → 이것이 "기준 예제"가 된다
3단계: 패턴 반복 (각 서비스마다 새 세션, plan.md + User Service 예제 첨부)
plan.md와 User Service의 패턴을 따라서 Order Service를 구현해줘. yarn test가 통과할 때까지 반복하라.
5. 규칙 문서(`CLAUDE.md`) 작성법: "Less is More"
규칙 문서는 1,000 토큰 이하로 유지하는 것이 좋다.
추상적인 원칙 대신 검증 가능한 구체적 규칙을 적는다.
* Bad : "가독성을 고려하세요", "보안에 신경 쓰세요"
# 코딩 가이드라인
- 좋은 코드를 작성하세요
- 가독성을 우선시하세요
- 성능을 고려하세요
- 보안을 신경쓰세요
(... 100줄 계속)
* Good : "모든 함수에 명시적 return 사용", "Float64 사용 금지", "함수는 50줄 이하 유지"
# 코딩 스타일
- 모든 함수에 명시적 return 사용
- Float32만 사용, Float64 금지
- 에러는 Result<T, E> 타입으로 반환
- 전역 변수 사용 금지
# Do
- 테스트 먼저 작성
- 함수는 50줄 이하로 유지
# Don't
- console.log 커밋 금지
- any 타입 사용 금지
Claude Code의 CLAUDE.md, Cursor의 rules 파일 등 규칙 문서의 크기에 대해 Boris Cherny가 직접 밝힌 기준은 "1,000 토큰 이하"다. Anthropic 팀 자체의 CLAUDE.md도 약 500 토큰 수준이라고 한다.
규칙 문서가 비대해지면 오히려 역효과가 난다. 자주 틀리는 것만 최소한으로 기록하고, 나머지는 코드와 자동 검사로 강제하는 것이 낫다. 한 사용자의 실제 CLAUDE.md 예시가 이 원칙을 잘 보여준다. 24줄, 코딩 스타일 6줄과 Do/Don’t 5줄이 전부다. 그는 Julia라는 니치 언어에서도 이것만으로 AI가 팀 스타일을 잘 따른다고 보고했다.
규칙 문서가 계속 커진다면 접근을 바꿔야 한다.Claude Code의 slash commands나 skills 기능으로 반복적 워크플로우를 분리하거나, CLAUDE.md를 여러 파일로 분할하여 디렉터리별로 lazy loading하는 방법이 있다. CLAUDE.md에서 @를 파일명 앞에 붙이면 해당 파일을 강제로 컨텍스트에 포함시킬 수 있다는 것도 유용한 팁이다.
6. 요약 및 행동 지침
AI 코딩 생산성을 2~3배 높이는 핵심은 간단하다.
설계와 검증은 사람이, 반복과 변환은 AI가 담당하는 분업을 명확히 하는 것이다.
✅ 오늘 바로 적용할 체크리스트: * 코드 요청 전 `plan.md`부터 작성하기 * 한 세션에서는 하나의 작업만 수행하기 * 테스트/빌드 통과 조건을 프롬프트에 명시하기 * 대화가 3~4번 이어지면 과감히 새 세션 시작하기 * CLAUDE.md를 점검하고 1,000 토큰이 넘으면 다이어트 * 추상적 지시("좋은 코드") → 구체적 규칙("Float32만")으로 전환한다 * Before/After 예제를 제공한다 * AI 생성 코드를 이해한 후 사용한다
"이 함수를 최적화해줘"
AI: [코드 생성]
"아니야, 다시 해봐"
AI: [더 나쁜 코드 생성]
"이건 더 느려졌잖아!"
AI: [횡설수설]
질문: 무엇이 잘못되었고, 어떻게 고쳐야 하는가? 1. 같은 세션에서 반복 수정 → 컨텍스트 부패 발생 2. "최적화"라는 모호한 지시 → AI가 추측 3. 검증 기준 없음 → AI가 수렴할 수 없음
올바른 접근: 1. 새 세션을 시작한다 2. 구체적으로 계획한다: "이 함수의 성능을 벤치마크하고, 병목을 찾아서, O(n²) 부분을 O(n log n)으로 개선하는 계획을 세워줘" 3. 피드백 루프를 설정한다: "bench_test.js가 기준선 대비 50% 성능 향상을 보일 때까지 반복"
시나리오 2: UI 리팩터링이 계속 실패한다 상황: "이 React 컴포넌트를 리팩터링해줘"라고 했더니, 기능은 작동하지만 레이아웃이 미묘하게 깨져 있다. 이것을 지적하면 또 다른 부분이 깨진다.
질문: 왜 이런 일이 발생하고, 어떻게 해결해야 하는가? * UI 리팩터링은 시각적 결과를 검증하기 어려운 작업이다.
* 테스트는 통과하지만 "미적으로 올바른가"는 AI가 판단할 수 없다.
올바른 접근 — 2단계 분할: 1단계 (AI): "이 컴포넌트를 함수형으로 변환해줘. 스타일과 레이아웃은 변경하지 마. 스냅샷 테스트가 통과해야 한다."
2단계 (사람): AI가 만든 함수형 컴포넌트를 기반으로 사람이 직접 UI 품질 리팩터링을 수행한다
시나리오 3: 프롬프트가 너무 길어지고 있다 상황: 프로젝트를 진행하면서 CLAUDE.md에 규칙을 계속 추가했더니 어느새 3,000단어가 되었다. 그런데 AI가 규칙을 잘 따르지 않는 것 같다.
질문: 무엇이 문제이고, 어떻게 개선해야 하는가? * 규칙 문서가 비대해지면 오히려 역효과가 난다. 핵심이 희석되고, 컨텍스트 윈도우를 낭비한다.
1) 최소화: 자주 틀리는 것만 남기고 나머지는 삭제한다 (목표: 1,000 토큰 이하) 2) 자동화로 강제: ESLint, Prettier, pre-commit hooks로 기계적 규칙은 코드로 강제한다. 3) 분할 로딩: 전역 CLAUDE.md에는 핵심 원칙만, 디렉터리별 CLAUDE.md에는 해당 모듈의 특수 규칙을 배치한다. 4) Slash commands/Skills: 반복 워크플로우는 별도 명령으로 분리한다
AI 코딩 도구는 마법이 아니다. 같은 모델을 써도 워크플로우에 따라 결과가 극적으로 달라진다. 이 글에서 다룬 원칙들은 특정 도구에 종속된 것이 아니라, 현재 LLM의 구조적 특성에서 도출된 것이다. 컨텍스트 윈도우의 한계, attention 메커니즘의 recency bias, 패턴 반복에 대한 강점, 모호한 지시에 대한 약점은 모든 모델에 공통적이다.
결국 가장 큰 생산성 향상은 모델의 선택이 아니라 사용법의 개선에서 온다. 계획을 먼저 세우고, 작게 쪼개고, 피드백 루프를 만들고, 자주 초기화하라. 그리고 AI가 생성한 코드를 반드시 이해하라. 이 원칙을 지킨다면, 어떤 모델을 쓰든 실질적인 생산성 향상을 경험할 수 있을 것이다.
AI 코딩 도구는 패턴 반복의 천재지만, 우리 머릿속을 읽을 수 없다. 계획을 먼저 문서로 만들고, 작은 단위로 쪼개서 하나씩 요청한다. 테스트나 빌드 성공 같은 명확한 기준을 제공하면 AI가 스스로 수정한다. 그리고 대화가 길어지면 새 세션을 시작한다. 이 네 가지만 지키면 생산성이 2~3배 올라간다.
