Claude Code로 좋은 결과 얻기

• 최근 몇 달 동안 다양한 LLM 프로그래밍 에이전트를 실험한 결과 Claude Code가 가장 만족스러운 도구였음
• Claude Code 덕분에 약 12개의 프로그램과 프로젝트를 단기간에 작성했으며, 평소라면 시간 문제로 시작하지 않았을 작업들도 가능해졌음
• 성공적인 활용을 위해서는 명확한 사양서 작성, 프로젝트 구조·빌드·린트 실행법이 담긴 문서 제공, AI 스스로의 코드 리뷰 요청, 그리고 개인화된 글로벌 에이전트 가이드 운용이 핵심
• AI가 작성한 코드는 종종 부정확하거나 비효율적일 수 있으므로, 모든 코드와 테스트 케이스를 반드시 직접 검토하고, 부족한 테스트는 직접 추가하거나 AI에 작성 요청 후 재검토함
• 부록으로 공개한 글로벌 에이전트 가이드에는 단계적 구현 계획, 테스트 주도 개발, 단순성·명확성·실용성 중심의 철학, 품질 기준, 문제 해결 프로세스 등 세부 개발 지침 포함

---

Claude Code 활용 경험 및 효과

• 최근 수개월 동안 다양한 LLM 프로그래밍 에이전트를 실험했고, 특히 Claude Code 사용 경험이 가장 우수했음
• 문제가 전혀 없는 것은 아니지만, 짧은 시간 내 12개 이상의 프로그램 및 프로젝트를 완성할 수 있었음
• Claude Code 없이 같은 기간에 이 모든 작업을 수행하는 것은 불가능에 가까웠을 것임
• 많은 작업은 시간 소요 문제로 시도조차 하지 않았을 프로젝트였음

Claude Code 활용 전략

• 명확한 사양서 작성
  • 프로젝트 시작 전 요구사항과 맥락을 명확히 문서화해 에이전트에게 제공
  • 이를 통해 코드 작성 방향과 범위를 분명히 함
• 프로젝트 구조 문서화
  • 빌드, 린트, 테스트 실행 방법을 포함한 문서를 마련
  • 에이전트가 코드베이스를 더 효과적으로 탐색하고 작업 가능
• 에이전트 코드 리뷰 요청
  • Claude Code에게 생성한 코드를 직접 리뷰하게 하여 예상치 못한 개선점이나 버그를 발견
• 개인 글로벌 가이드 활용
  • 문제 해결 접근, TDD 적용, 단순성·명확성 유지, 시도 횟수 제한(3회) 등 개인 규칙을 담은 ~/.claude/CLAUDE.md를 통해 일관된 개발 프로세스 유지

LLM 작성 코드 검증

• AI 생성 코드는 종종 논리적 오류, 성능 저하, 불완전한 테스트 등의 문제가 있음
• 작성자는 모든 코드를 수동으로 검토하고 동작을 확인
  • 누락된 테스트 케이스를 직접 추가
  • 또는 AI에 작성 요청 후 코드·테스트를 다시 검토
• 프로페셔널 환경에서는 PR에 자신의 이름이 들어가는 이상, 최종 품질 책임은 본인에게 있다고 강조

개인 “글로벌” 에이전트 가이드 주요 내용

해당 가이드는 ~/.claude/CLAUDE.md 파일로 관리함

• 철학과 핵심 원칙

  • 점진적 진행: 작은 단위로 변경, 항상 컴파일과 테스트 통과
  • 기존 코드 학습: 구현 전 코드 패턴 분석 및 계획 수립
  • 실용성 우선: 프로젝트 상황에 맞춘 유연한 접근
  • 명확성 우선: 읽기 쉽고 의도가 분명한 코드, 불필요한 트릭 회피

• 단순성 정의

  • 함수·클래스는 단일 책임
  • 조기 추상화 지양
  • 복잡성 줄이고 설명 필요 없는 코드 지향

• 작업 프로세스

  • 1. 기획 및 단계 설정:
    • 복잡한 작업은 3~5단계로 나눠 IMPLEMENTATION_PLAN.md에 기록
    • 단계별 목표, 성공 기준, 테스트 케이스, 진행 상태 명시
  • 2. 구현 흐름:
    • 이해 → 테스트 작성(빨강) → 최소 구현(초록) → 리팩토링 → 커밋
  • 3. 3회 시도 제한 후 재평가:
    • 실패 시 시도 내역과 오류, 원인 기록
    • 대안 탐색(2~3가지 접근)
    • 근본적인 설계·문제 분해 재검토
    • 다른 패턴·기능 시도

• 기술 표준

  • 구성(Composition) 우선, 의존성 주입 활용
  • 인터페이스 사용, 테스트 용이성 확보
  • 명시적 데이터 흐름
  • TDD 권장, 테스트 비활성화 금지

• 코드 품질 규칙

  • 모든 커밋은 컴파일 성공, 테스트 통과, 신규 기능 테스트 포함, 코드 스타일 준수
  • 커밋 전 포매터·린터 실행, 변경사항 셀프 리뷰, "왜"를 설명하는 커밋 메시지 작성

• 오류 처리

  • 빠른 실패와 구체적 메시지
  • 디버깅에 필요한 컨텍스트 제공
  • 적절한 레벨에서 예외 처리, 예외 은폐 금지

• 의사결정 기준

  • 1. 테스트 용이성
  • 2. 6개월 후에도 이해 가능한 가독성
  • 3. 프로젝트 패턴과의 일관성
  • 4. 단순함
  • 5. 변경 용이성

• 프로젝트 통합

  • 유사 기능 3개 이상 분석
  • 기존 패턴·라이브러리 재사용
  • 동일한 테스트 유틸리티 사용
  • 새 도구 도입 시 강력한 이유 필요

• 품질 게이트

  • 모든 테스트 통과
  • 프로젝트 규칙 준수
  • 린터 경고 없음
  • 커밋 메시지 명확
  • 구현이 계획과 일치
  • TODO에 이슈 번호 포함

• 테스트 지침

  • 구현이 아닌 동작 중심 테스트
  • 가능하면 테스트당 하나의 단언
  • 시나리오를 설명하는 명확한 이름
  • 기존 테스트 유틸리티 재사용
  • 테스트는 결정론적이어야 함

• 절대 금지

  • --no-verify로 훅 우회
  • 테스트 비활성화
  • 컴파일 안 되는 코드 커밋
  • 검증 없는 추측

• 반드시 수행

  • 점진적 커밋
  • 문서 지속 업데이트
  • 기존 구현에서 학습
  • 3회 실패 후 접근 재평가

Claude Code로 제작한 오픈소스 프로젝트

• HTML/XML 인식 리버스 프록시 (cdzombak/xrp)
• VS Code Solarized 테마(라이트/다크) (cdzombak/dzsolarized-vscode)
• Flickr 포토스트림 RSS 생성기 (cdzombak/flickr-rss)
• Lychee 사진 라이브러리 메타데이터 툴 (cdzombak/lychee-meta-tool)
• macOS 스크린락 상태 MQTT 보고 (cdzombak/macos-screenlock-mqtt)
• Lychee Bird Buddy 사진 제목 자동 설정 (cdzombak/lychee-birb-title)
• 로컬 LLM 기반 사진 자동 분류 (cdzombak/lychee-ai-organizer)
• macOS용 소프트웨어 일괄 설치 자동화 (cdzombak/mac-install)
• RSS 서비스 프로젝트 (cdzombak/rss.church)
• Flickr 사진 전체/선택적 내보내기 및 메타데이터 보존 (cdzombak/flickr-exporter)
• 정적 HTML 갤러리 생성기 (cdzombak/gallerygen)

[wedding]

좋은 결과가 나왔다는건, 누군가 이미 만든 코드를 잘 참조했다는 뜻일까요.

[aeolian21]

글쓴이가 한거 다들 이미 옛날에 다 하고 있으니 쓸데없는거 자랑하지 말고
LLM간에 비교했을때 왜 claude가 제일 나았다고 생각했는지 근거나 쓰는게 훨씬 의미 있는 글이 될듯
실제 생성된 코드 비교, 컴파일 에러 빈도, 맥락 파악의 안정성 등등
실제로 맥락 파악 능력이 가장 뛰어난건 gemini임(100만 토큰)

[zxcv123]

별 쓸모없는것들만 만들고 글만 장황하게 늘어놨네

[knunu]

누군가에겐 쓸모있을 수 있죠 ㅎㅎ

[GN⁺]

Hacker News 의견

• 오늘 Claude와 코딩 에이전트로 처음 제대로 성공 경험을 해봄, 이전에는 Cursor를 써봤지만 이제 Claude와 다른 것도 함께 시도 중임, 기사에서 언급된 대로 명확한 사양을 작성하는 것이 핵심임, 2시간 동안 12단계 문서를 직접 작성해 구현 방식을 정리하고 백그라운드 정보도 포함시켰음, Claude는 그 절차를 따라 차례대로 코드를 생성했음, 내 생각에는 아마 6~10시간 정도를 절약한 셈임, 이제 내가 검토하고, 테스트해서 점진적으로 조정하고 기능을 추가할 계획임, 이 성공의 기반은 Claude가 해야 할 모든 단계를 내가 직접 명확하게 썼기 때문임, 즉 내가 전체 흐름을 설계하고 Claude는 지시에만 따르는 구조임, 이 과정을 통해 중급 이상 개발자는 당분간 AI에 대체되지 않을 거라는 확신이 생김, 하지만 Claude가 명세를 쭉 읽고 정리된 문서화된 코드를 뽑아내는 장면을 보는 건 정말 신기한 경험임, 내가 직접 코딩하지 않아도 되는 점이 대단함

  • 나는 이렇게까지 준비하지 않고도 Claude로 좋은 결과를 얻음, 거의 내가 직접 코드를 쓸 때처럼 한 번에 한 단계씩 Claude에게 요청함, 매번 변경된 부분을 바로 적용하고 커밋한 뒤 diff를 검토함, 만약 Claude가 이상한 결과를 만들면 바로 수정 요청함, 그리고 적용하고 싶은 기존 코드나 함수 레퍼런스를 직접 알려줌, 이 방식으로 훨씬 적은 타이핑과 시간으로 훌륭한 결과를 얻을 수 있음

  • Naur의 “Programming as Theory Building”을 읽어보기를 추천함, 문제를 어떻게 이론적으로 이해하고 직접 모델링해야 하는지 배운 경험임, 그렇지 않으면 LLM이 (잘못된) 자체 이론을 만들어낼 수 있음
    “Programming as Theory Building” - Naur 읽기

  • 기사에서처럼 명확한 사양이 정말 중요함, 나는 Claude로 프로그래밍 언어를 만드는 중인데, 이 점을 직접 체감함, 프로그래밍에는 정말 많은 사소한 선택의 연속이 있음, 명확하게 가이드하지 않으면 LLM이 대부분 추측으로 대처하는데 종종 틀린 선택을 함, 이런 작은 실수들이 복합적으로 쌓여 잘못된 결과로 이어질 수 있음

  • 혹시 이런 사양 문서의 예시를 직접 공유할 수 있다면 정말 좋겠음, 개발을 독학하며 Claude Code를 실험하는 입장에서 실제 어떤 정보와 깊이가 도움이 되는지 파악하는 데 큰 도움이 될 것 같음

  • 사실 꽤 많은 중급, 시니어 개발자들도 제대로 된 사양서를 작성하지 못함, 말하고자 하는 의도에는 공감함

• ~/.claude/CLAUDE.md를 만들어서 규칙을 넣는 건 사실상 효과가 크게 없을 것 같음, Claude는 사람이 아니라 각 코드 라인별로 신중하게 추론하지 않음, 주관적이고 모호한 지침들이 코드를 실제로 바꾸게 만들지는 않음, 그리고 'context rot'이라는 문제도 있음
  (context rot 관련 설명: LLM이 긴 대화나 작업 중 맥락을 잃거나 왜곡하는 현상임, 참고링크: https://news.ycombinator.com/item?id=44564248)
  현실적으로 단일 파일 내에 온갖 규칙을 다 집어넣고 AI가 알아서 지키길 기대하는 건 불가능함, 그렇게 하려면 각 규칙마다 sub-agent를 만들어서 AI가 아닌 일반적인 파이프라인으로 분리해야 함, 하지만 이렇게 되면 비용이 기하급수적으로 상승함

  • 비용 문제라면, 워크플로우가 안정화된 후에는 저렴한 LLM을 활용할 수 있음 (운영비는 비싸지만), 파인 튜닝, 프롬프트 최적화, 특화된 distillation 기법 등으로 비용 절감이 가능함, 이 분야는 이미 많은 연구가 이루어지고 있음

  • CLAUDE.md에는 어떤 내용을 포함하면 좋은지 궁금함

• 페이지 하단에 나온 샘플 프로젝트들을 보면, 하나의 특정한 목적에 최적화된 소프트웨어가 대부분임, 앞으로 오픈소스 프로젝트들도 이런 식으로 한 사람의 필요를 충족하는 굉장히 특화된 형태로 진화할 것 같음, 이런 소프트웨어(유틸리티)는 LLM이 한 번에 생성하는 소모성 코드가 되어 갈 거란 생각임

• Claude Code에 대한 내 접근 방식이 계속 바뀌고 있음, 회사 대형 웹 앱에 Claude Code로 실제 의미 있는 기능을 바로 기여하는 데에는 아직 성공하지 못함, 사양이 어느 정도 도움은 되는데 결국은 괴상한 방향으로 흐름이 틀어지고 잘못된 선택이 반복되는 루프로 빠지게 됨, 이게 Claude의 한계일 수도 있고 내 사양서가 아직 충분히 정확하지 않아서일 수도 있음, 실험을 많이 해봤지만 '도전적이거나 도메인 전문지식이 많이 필요한 것'에서는 실패가 많아서 더 이상 시도하지 않음, 대신 친구의 추천으로 정신적 부담이 거의 없는 백로그 작업에 Claude를 활용하기 시작함, 예를 들어 별로 애착 없는 Playwright 테스트를 새 워크스페이스에 만드는 일을 Claude에게 시켜 봤음, 아주 성공적이었음, 사용자 경험을 사람에게 설명하듯 Claude에 말해주고 dev 서버 경로를 지정해주었음, Playwright MCP를 활용해 어떤 feature를 어떻게 써야 하는지 알아내고, 실행 과정을 문서화하고, 테스트를 작성하고, 에러를 디버깅하도록 지시했음, 그리고 프로젝트 내 UI코드를 뒤져 data-testid 셀렉터를 추가하는 작업도 포함시켰음, 전체 프로세스를 master task.md에 정리해두고, 각 feature별로 개별 task markdown도 만들게 지시했음, 이 방식이 매우 효과적이었음, 특히 2명의 브라우저 유저가 비직관적으로 상호작용하는 복잡한 feature에도 활용했는데, 100% 정확하진 않아도 복잡할수록 조금 더 컨텍스트 보정과 코드 수정이 필요했을 뿐, 전체적으로 며칠씩 걸릴 귀찮은 작업을 단번에 해결함

• CLAUDE.md는 최대한 100줄 미만의 미니멀한 파일로 유지하는 것이 제일 좋았음,

  • 프로젝트의 본질적인 맥락과 목적 요약
  • 타입, 인터페이스, 헬퍼를 알 수 있는 최소한의 프로젝트 구조 설명
  • package.json을 반복 파싱할 필요 없는 주요 커맨드만 포함 구현/테스트 흐름 중 경험상 Claude가 테스트를 한 번에 미리 모두 작성하려고 하거나, 임포트 실패 시에만 전부 구현하는 경우가 있었음(TDD 방식이 제대로 아님), 그래서 TDD-Guard라는 훅을 만들어서 한 번에 하나의 테스트만 통과, 테스트가 올바른 이유로 실패, 테스트를 통과시키는 최소 코드를 구현하도록 강제했음, 코드 품질은 husky, lint-staged, commitlint 등을 자동화해서 아주 좋은 결과를 얻었음, 이렇게 하면 더 중요한 정보를 위해 context를 확보할 수 있음, Claude Code가 막히면 결국엔 개발자가 직접 개입하는 게 제일 좋은 방법이라는 데 동의함, 다만 너무 일반적인 가이드에 머물면 아쉬움,
  • 자동화 접근에 관심 있다면:
    • tdd-guard와 예제 설정
    • husky
    • commitlint
    • lint-staged

• 한 달 넘게 매일 Claude Code와 작업하는 중임, Cursor, Q 등 써봤지만 Claude Code가 훨씬 뛰어남, 기사에서 언급된 팁들이 내가 깨달은 점이랑 많이 겹침,
  몇 가지 추가 생각을 공유하자면:

  • 웹 콘솔에서 Claude와 아이디어 세션부터 시작함, 프로젝트의 목표를 설명하고, 도메인 모델링과 마일스톤을 큰 틀로 구상함, 소규모 프로젝트면 몇 시간 만에 왕복 토론으로 정리함, 여기서 CLAUDE.md 첫 버전이 나옴

  • 실제 프로젝트를 시작할 때 Claude가 내 글로벌 CLAUDE.md와 프로젝트 CLAUDE.md를 모두 읽고 출발함, 세션마다 그런 방식임

  • 진행 중에도 Claude Code가 프로젝트 CLAUDE.md를 계속 업데이트하게 지시함, 계획을 따라가며 진행 상황을 표시하고, 세션 말미에 프로젝트 요약, 동작 방식, 코드 네비게이션 방법 등을 써넣게 함, 일종의 장기 기억 역할임, 효과가 좋았음

  • 아무리 가이드라인이 좋아도 Claude가 먼저 앞서나가려는 성향이 있음, 그래서 직접 참여하는 작업은 꼭 작은 인크리먼트로 단계별로 집중하도록 함, 그냥 일회성이나 프로토타입일 땐 알아서 맘껏 구현하게 둠

    • $20 구독제가 Cursor와 비교해 가성비가 괜찮은지 궁금함, 매일 사용해야 그만한 가치가 있는지 알고 싶음

• 프로젝트 레벨 CLAUDE.md는 너무 길지 않고 간결하게 유지하는 것이 좋음, 그리고 더 세부적인 내용은 하위 폴더로 이동시키기 바람, 최상위는 일종의 맵 역할로 사용, 기능 하나를 기획할 때마다 Claude가 적절히 폴더를 들여다보고 필요한 컨텍스트를 참조하면서 단계별 구현 계획을 세움, 각 단계 끝날 때마다 Claude에게 새로운 컨텍스트로 구현 계획을 업데이트하게 지시함, 이렇게 하면 컨텍스트가 다음 단계로 자연스럽게 전달되고, 윈도우도 초기화해서 새로운 마음으로 다음 단계에 돌입할 수 있음

• Claude Code로 factorio류의 ASCII 게임을 만들고 있음, 초반에는 거의 감시 없이 코드를 짜게 했고 주요 기능(저장/로드, 옵션, 디버그, 맵 생성, 건설, 벨트, 제작, QoL 등) 대부분을 단번에 구현함, 그런데 디테일을 고치려니 예를 들어 이동을 바꾸면 벨트가 깨지는 식으로 다른 게 계속 망가짐, 그래서 Playwright 자동화 추가를 시켰지만 테스트가 질이 떨어지고 sleep 호출이 난무함, 코드를 자세히 들여다보니 React 프론트엔드와 useEffect를 쓰는 구조로 되어 있었고, 제대로 된 게임 엔진의 구조로 되어 있지 않았음, hook 규칙을 잘 지키지 못하고 타이밍 이해도 약했음, 그래서 이번엔 tick 기반 게임 엔진을 도입해 처음부터 다시 만들기 시작했고, 코드 리뷰도 추가함, 진행 속도는 더 느려졌지만 훨씬 더 탄탄하게 개발 중임, 좋은 데모가 완성되면 Show HN으로 공개할 계획임

  • 초반 기초 뼈대가 잡히기 전까지는 사람의 직접 기여가 정말 소중함, 리팩터링이 한번 지나가고 나서는 그 뒤로 조금 맘을 놓을 수 있음

• 나처럼 Claude의 업무용과 개인용 구독을 모두 쓰는 사람이 있다면, "alias claude-personal="CLAUDE_CONFIG_DIR=~/.claude-personal claude"" 이런 방식으로 계정 전환을 간단히 할 수 있음
  여러 Claude 계정을 효율적으로 쓰는 방법 블로그

• 모두가 '사전에 명확한 사양서를 써서 context를 주는 게 핵심'이라고 하지만, 내 경험상 이게 항상 통하는 건 아님, 실제 전문가와 같이 앉아 Opus 4 & Sonnet 4로 CC 세션을 해봤는데, 상대가 정말 명확한 spec을 준비했지만 내 방식(기능이 떠오르는 대로, CLAUDE.md 없이 바로바로 각각의 context로 요청)보다 별로 나은 결과가 없었음, 명세 기반 workflow는 중요한 걸 계속 잊어버리거나, 컨텍스트 문서에 없는 걸 임의로 만들어내거나(심지어 금지된 것도), 반면 나는 예를 들어 “invoice용 crud 페이지 추가해줘, 먼저 코드베이스 분석부터 해봐” 식으로 즉각적으로 지시하는 게 더 나았음, 이는 내 경험적(아네크도트)일 뿐이지만 실제로 Claude로 100개 넘는 프로젝트를 진행해본 결과, Claude가 오버스텝을 막기 위한 별도 hook 외에는 특정 방식이 더 낫다고 확신할 수 없음, 다양한 사람들이 'spec 기반이 낫다'고 해도 실제로 보여달라 하면 오히려 지나치게 많은 시간을 명백히 틀린 부분을 계속 고치는 데에 소모하는 경우가 많았음, 심지어 CLAUDE.md에 '이런 건 절대 하지 마'라고 적어도 계속 그걸 하는 경향이 있었음