▲

Claude Code가 왜 그렇게 좋은가

 (minusx.ai)
5P by GN⁺ 2일전 | ★ favorite | 댓글 2개
  • Claude Code는 사용성 측면에서 매우 뛰어난 AI 에이전트/워크플로우임
  • 건축적 단순성과 명확한 제어 루프 덕분에 디버깅과 유지관리가 수월한 경험 제공임
  • RAG 도입을 최소화하고 고도화된 프롬프트 및 문맥 파일을 적극 활용함으로써 LLM의 강점을 극대화함
  • 다양한 도구(툴) 와 명확한 가이드라인을 통해 작업 명확성·일관성을 유지함
  • 복잡성 대신 알기 쉬운 구조와 프롬프트 설계로, 자신만의 LLM 에이전트도 비슷하게 구현 가능한 장점 있음

개요

  • Claude Code(이하 CC) 는 현재 사용 가능한 AI 에이전트/코딩 워크플로우 가운데 가장 만족스러운 경험을 제공함
  • CC의 장점은 타겟에 맞는 코드 편집, 불필요한 방해 감소, 사용자의 제어권 유지를 통한 쾌적한 UX에 있음
  • Claude 4 모델과 특유의 Interleaved Thinking이 핵심 역할을 하지만, Cursor나 Github Copilot 등 동일한 모델 기반의 다른 도구보다도 더 적은 불편함을 제공함
  • 이 글은 CC의 구현 원리를 해부하고, 비슷한 경험을 제공하는 자체 LLM 에이전트를 구현하기 위한 실전 가이드를 제공함

Claude Code의 핵심 미덕: 단순함

  • 가장 큰 교훈은 "단순하게 유지할 것(Keep Things Simple, Dummy) "임
  • LLM 에이전트는 복잡한 구조(멀티 에이전트, 복잡한 RAG, 검증체계 등)를 도입하면 디버깅 및 개선이 극도로 어려워짐
  • CC는 단일 메인 루프, 단순한 툴셋, 한눈에 파악 가능한 구조를 채택하며, 모든 핵심 로직을 하나의 파일에 담아 불필요한 보일러플레이트와 복잡함을 배제함

왜 단순함이 중요한가

  • 멀티 에이전트 구조 대신 하나의 메인 스레드에서 대부분의 작업을 처리함
    • 히스토리 요약, UX를 위한 메시지 통합 등은 보조 형태로 적용
    • 복잡한 작업이 필요할 때는 자신을 복제하여 서브 에이전트로 분기(재귀적 분기 없음, 한 단계까지만 허용)
  • 할 일 목록(todo list) 을 적극 활용
    • 복잡한 문제는 서브에이전트에서 분할 처리하되, 결과를 메인 메시지 히스토리에 병합
    • 지나치게 추상적인 멀티 레이어 구조(다중 에이전트, 그래프 내비게이션)는 오히려 시스템 안정성·확장성 저하각 있음

경량화된 모델 적극 활용

  • claude-3-5-haiku 등 경량 LLM 모델을 대다수 요청에 사용
    • 대용량 파일 읽기, 웹페이지 파싱, git 히스토리 요약 등 많은 작업을 효율적으로 처리
    • 경량 모델 사용 시 비용이 최대 70~80%까지 절감됨
  • 모든 주요 기능 호출에 최적화된 모델 조합 활용을 추천

정교한 프롬프트 설계

  • CC의 시스템 프롬프트는 방대한 분량(약 2800 tokens) 과 다양한 섹션(톤&스타일, 작업관리, 도구 사용정책, OS/디렉토리 정보 등)으로 구성
    • claude.md 등 문맥 파일 전체를 항상 포함시켜 컨텍스트의 풍부함을 극대화
    • 시스템 프롬프트는 정책성 규칙, 예시, 유의점, 도구 사용 타이밍 등 매우 상세하게 안내

XML과 Markdown의 동시 활용

  • 프롬프트 내에 XML 태그와 Markdown 구조를 동시에 사용
    • <system-reminder>, <good-example>, <bad-example> 등으로 디테일하고 조건 분기가 가능한 정보 전달
    • markdown heading으로 명료하게 섹션 구분

컨텍스트 파일의 중요성

  • claude.md의 유무에 따라 CC 성능 차이가 극명하게 드러남
    • 코드베이스로부터 추론이 어려운 추가 규칙(폴더/라이브러리 제외, 선호 정책 등) 전달에 필수
    • MinusX도 minusx.md로 팀/사용자 선호도를 체계화하고 있음

RAG 최소화, LLM 서치 활용

  • CC는 RAG(Retrieval Augmented Generation) 대신, 실제 개발자처럼 ripgrep, jq, find 명령어 등 직접적인 코드 검색 기반 구조를 선호함
    • 이는 복잡한 RAG 구성에서 오는 숨겨진 실패 가능성(예: 유사도 함수, 재랭커, 청킹)에 대한 대안을 제공
    • LLM이 실제 코드 문맥을 직접 탐색·이해하는 구조로, 움직이는 부품 수 감소 및 RL 학습의 효율성까지 기대 가능

도구(tool) 설계 및 계층 구조

  • CC는 저수준(Bash, Read, Write), 중간수준(Edit, Grep, Glob), 고수준(Task, WebFetch 등) 도구를 모두 지원함
    • 사용 빈도·정확성 등을 고려해 필요한 도구를 개별적으로 분리
    • 툴의 설명, 예시, 사용 시점 등을 명확히 시스템 프롬프트에 고지함
  • 복잡한 작업은 Task나 고수준 툴을 통해 일관성 있게 관리

Explicit Todo 관리로 컨텍스트 유실 방지

  • 장기 실행 LLM 에이전트의 대표적 문제(문맥 유실, 방향 상실)를 해결하기 위해, CC는 직접 유지되는 Todo 리스트로 상태 관리
    • 멀티 에이전트 체계 대신, 모델이 자율적으로 Todo를 갱신하며 작업 방향성과 유연함 동시에 확보

에이전트의 톤, 스타일, 친화도 제어

  • 톤, 스타일, 적극성 등을 별도 섹션으로 관리
    • 불필요한 설명 자제, 이모지는 명시적으로 요청받을 때만 허용 등, 일관된 사용자 경험 설계
  • "매우 중요(IMPORTANT) ", "절대(NEVER) ", "항상(ALWAYS) " 등 강력한 수식어로 주의점 전달

판단 알고리듬·흐름 설계

  • LLM이 따라야 할 주요 알고리듬을 명확하게 서술 및 예시화
    • Do/Don't 리스트의 나열보다 플로우 차트, 단계별 체크리스트가 알고리듬 안정성 유지에 효과적임
    • 여러 지침·예시가 충돌할 가능성 고려, 역할 범위와 정책을 구조적으로 명시

디자인 패턴과 적용 실전 팁

  • 강력한 오피니언과 구조는 자체 에이전트 설계 시 바로 벤치마크로 삼을 만함
    • 머리가 복잡해지는 프레임워크 남용 대신, 단순하고 효과적인 구조 설계가 중요
  • 실제 MinusX에서도 다수 원리를 적용 중이며, 점차 확대될 계획임

결론

  • Claude Code의 가장 큰 교훈: “단순함이 최고의 힘”
  • 구조적 명확성, 의미 있는 프롬프트 설계, 경량 도구 조합이 강력한 LLM 에이전트를 가능하게 함
  • 자신만의 LLM 에이전트 개발 시, CC의 설계 철학과 가이드를 적극 참고할 가치가 높음
▲
kaydash 10시간전  [-]

너무조아 행보케 최고야 달달해 계속할랭

답변달기
▲
GN⁺ 2일전  [-]
Hacker News 의견

  • KISS 같은 단순함이 언제나 이김이라는 믿음임, 그리고 이 글을 잘 정리해줘서 유익했다는 소감임

  • Claude Code가 오픈소스가 아니라 아쉽지만, 내부 동작을 더 잘 파악할 수 있는 도구들이 있다는 소개임, 만약 진짜로 어떻게 작동하는지 관심 있다면 Claude Trace를 추천함
    https://github.com/badlogic/lemmy/tree/main/apps/claude-trace
    이 도구는 세션에서 사용된 모든 도구와 프롬프트를 보여주는 JSON 파일과 보기 쉽게 포맷된 HTML 파일을 만들어 줌

  • 요즘 멀티에이전트 시스템이 각광받는 시기에 LLM 중심 조직이 어떻게 접근하는지 알 수 있어서 유익했다는 의견임, 본인도 여러 디자인 관점을 일상에서 실험 중이라 동질감을 느낌
    주요 인사이트로는
    (1) 프롬프트가 길어도 좋고, 툴의 목적이나 도움 방식 등 기본 설명을 꼭 포함해야 함
    (2) 툴 호출은 매우 기초적인 부분이라 맥락을 더 반영해야 함(언제 사용할지, 언제 쓰지 않을지 등)
    (3) 시스템의 상태를 메시지로써 관리하는 건 괜찮음, fancy한 방법(데이터프레임 저장, 변수 파싱 등)도 생각해봤지만, 컨텍스트 윈도우가 길어진다면 메시지만으로도 충분하다고 여김

    • 프롬프트가 길면 좋긴 한데, 모델이 그걸 잘 처리하도록 최적화되어 있을 때만 해당됨, 본인이 Claude Code에서 다른 모델로 바꿔봤는데, 장문 프롬프트와 툴 사용 둘 다 광고만큼 잘되는 로컬 모델이 거의 없었다는 경험임
      OpenAI, Google Gemini 등의 모델도 시도해보았으나 Anthropic 모델만큼 잘 되지 않고 속도도 느리다고 느낌, 프롬프트가 길어질수록 툴을 까먹거나 잘못된 포맷으로 결과를 내놓는 현상을 겪음
    • (블로그 글 작성자) 기본 기능만 잘 활용해도 거의 99%의 상황에서 좋은 성능을 뽑을 수 있다는 의견임, 루프를 단순하게 유지하고 명확한 툴을 제공하는 것이 중요함, 기능이 겹쳐도 괜찮음
      명확성과 단순함이 최우선임

  • Google Gemini(특히 Pro 버전)가 Claude에 비해 어떤지 궁금하다는 질문임, Google의 많은 제품을 좋아하지만 자주 제품을 중단시키거나, 기업 통제(Chrome 등)에 대해 투박하게 나오는 점이나 검열 이슈가 걱정임

    • Gemini는 전체 저장소의 머지 파일을 통째로 투입해서 대화할 수 있을 때 특히 탁월함, 코드베이스 전체를 이해하는 수준이 놀라울 정도임, 아키텍처 설계에도 큰 도움을 줌, Claude는 이런 점에서 많이 부족함
      본인만의 전략으로는 Gemini로 프로젝트 요약 및 고수준 설계 플랜을 만든 뒤, gpt5로 개선과 상세 워크플로우 설계(예: XML 문서)까지 시키고 이를 다시 Claude에 넘김, 이것만으로도 Claude의 우왕좌왕 현상을 거의 피할 수 있음
    • Gemini Pro가 코딩에서 나쁘지는 않은데, 경험상 Claude가 터미널 관련 작업(CLI 등)에서 훨씬 나음, 대부분의 CLI들도 Claude를 많이 씀
      https://www.tbench.ai/leaderboard
    • 웹 UI(채팅)는 Gemini 2.5 Pro를 꽤 좋아함, 커맨드라인 도구에서는 Gemini code는 쓸모없고 Claude code는 대부분 느림
    • Gemini가 여러 함수 호출을 따라가야 하는 힘든 문제 디버깅에 더 뛰어남, Claude는 매번 예측 가능하고 지시를 잘 따름, 투두 리스트 관리를 특히 잘함
    • 예전엔 꽤 마음에 들었는데 최근에는 좀 더 멍청해진 느낌이 듦(혹시 나만 그런지 궁금함)

  • 본인은 기본 모델 자체가 실제 코딩 업무에 강해서 사용자들이 좋은 평가를 내린다고 생각함(일반 벤치마크용 문제와 다름), GitHub Copilot을 사용해보면 Claude가 OpenAI, Google 모델보다 월등히 뛰어남, 그 차이가 너무 커서 다른 모델들은 실질적으로 무쓸모하게 느껴지는 수준임

    • Anthropic은 강화 학습 중에 내부적으로 모델과 프롬프트를 최적화할 수 있어서, 글에서 얘기한 “기존 방식을 그대로 활용하라”는 조언이 Anthropic 모델에 더 적합하다고 생각함, 구독 모델 덕분에 루프 효율화에 강한 인센티브가 있음
    • 단지 기본 모델만의 차이로 설명할 수 없음, vs code에서 opus와 cline을 같이 사용할 때랑 Claude code를 쓸 때 생산성 차이를 구체적으로 수치로 설명하긴 어렵지만, CC를 쓸 때 더 많은 일을 해냄
    • 많은 칭찬을 보고 기대하며 Claude Code를 한 달 사용해봤는데 오히려 실망만 커졌음, Cursor 사이드바보다 낮은 경험을 제공했고, 본인이 뭘 잘못 쓰는 건가 싶음, 두 다른 코드베이스에서 계속 어이없는 코드 실수를 많이 내어서 아쉬웠음

  • 지금 Claude Code로 Security Onion에서 Elastic 관련 문제 디버깅을 시도하고 있는데, 몇 분 지나면 난해한 JS 코드가 쏟아지고 “Error: kill EPERM”라는 에러가 뜸
    로그를 보면 Node.js 프로세스를 죽여서 Claude 자체도 죽는 게 아닐까 싶음, 혹은 문제를 못 풀어서 Claude가 스스로 종료하는 느낌임
    어쨌든 프로세스가 유지되면 좀 더 도와줬으면 좋겠음

    • Claude와 localstack 중 일부는 서로 잘 맞지 않음, Rust에서는 의외로 꽤 잘함
      앞으로 LLM이 가장 잘 아는 언어/플랫폼/아키텍처가 점점 대세가 될 거라는 생각임, 예를 들어 nodejs를 LLM이 10배 더 잘 다루면 처음부터 엘릭서나 Go 대신 nodejs를 쓰는 게 합리적이라는 관점임, 주니어 개발자도 LLM 도움으로 미들급/시니어급처럼 활용 가능함
    • 수퍼유저 권한으로 프로세스를 실행하려고 sudo 쓸 때 타임아웃 돼서 저런 에러가 뜨는 경우임
    • 설치를 업그레이드하거나 기존 설치 파일을 지우고 다시 설치하면 문제 해결되는 경우도 있음, 본인은 이렇게 고침
    • 다른 LLM으로 넘어가면서 무슨 일이 일어났는지 확인한 경험 있음(공식 조언은 아님)
    • 본인은 Elasticsearch와 LLM 조합에서 좋은 결과를 얻어본 적이 없음, 대부분의 결과가 근거 없는 ‘환각’들이었음, 인터넷에 제대로 된 예시가 많지 않기 때문이라고 생각함

  • 본인은 스타트업의 첫 MVP 전체를 Claude Code로 만들었고 이제 유료 고객까지 유치함, 물론 SEV(서비스 중단) 사고가 일어나면 한순간에 무너질 수 있다는 근본적 불안이 있지만, 보안 취약점 수정, 테스트 주도 개발, 장기 로드맵에 따른 소프트웨어 아키텍처 설계를 위해 계속 Claude를 적극적으로 활용 중임
    이런 스토리가 앞으로 점점 흔해지길 바람

    • 제품이 궁금하니 링크를 공유해줄 수 있냐는 요청임, 실사용자 사례가 궁금함
    • “보안 취약점 수정”이라는 게 처음부터 Claude가 코드 작성하고 취약점도 만든 것이 아니냐는 농담 섞인 질문임
    • 테스트 주도 개발, 소프트웨어 설계와 같은 부분에서 구체적으로 어떻게 도움을 받았는지 예시를 설명해 달라는 요청임
    • 본인은 Claude Code에게 매달 은행 계좌로 돈을 송금하라고 시켰더니 실제로 해준다는 농담임
    • 구체적으로 무슨 걸 Claude Code로 만들었는지 공개해줬으면 좋겠다는 피드백임

  • “Keep things simple”이란 주장이 맞다면, 오히려 다소 복잡한 구성처럼 느껴지기도 한다는 의견임
    본인은 늘 원프롬프트씩 필요한 걸 묻는 단순한 방식으로 충분히 많은 작업을 해오고 있음
    논의된 복잡한 구조들이 정말 정교하게 만든 프롬프트 대비 어떤 추가적 가치를 주는지 확신하지 못하겠음
    예를 들어 "새로 배우는 언어에서 while 루프 만드는 법"처럼 한 문장 프롬프트가 오히려 효율적일 수 있지 않냐는 생각임
    컨트롤 플로우가 오히려 불명확하게 느껴짐, LLM은 appendix(도구나 시스템 프롬프트) 부분을 제대로 쓰는지도 의문임, 요청이 너무 복잡하면 일부가 무시되거나 토큰 낭비 아닐까 생각함
    조각별로 개별 프롬프트를 던지는 식으로 프로그래밍하는 게 본인에겐 훨씬 자연스러움
    다른 방식을 쓴 사례나 프롬프트들을 한 번 보고 싶음
    실제로 LLM을 활용해 전체적인 프로그램을 사람들은 어떻게 만드는 건지 궁금함, 프롬프트별로 쪼개서 만드는 사례를 찾아 보고 싶음

    • 본인도 똑같이 쓰고 있어서, 다른 사람들의 답변이 궁금하다는 의견임

  • 참고로, 글 마지막에 minusx.com 링크가 있는데 보안 인증서가 553일 전에 만료된 상태임, 사이트가 유효하지 않으니 조심하라는 안내임

답변달기