# Claude Code가 왜 그렇게 좋은가

> Clean Markdown view of GeekNews topic #22696. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=22696](https://news.hada.io/topic?id=22696)
- GeekNews Markdown: [https://news.hada.io/topic/22696.md](https://news.hada.io/topic/22696.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2025-08-24T14:33:49+09:00
- Updated: 2025-08-24T14:33:49+09:00
- Original source: [minusx.ai](https://minusx.ai/blog/decoding-claude-code/)
- Points: 8
- Comments: 2

## Summary

**Claude Code**는 **단순성과 명확성**을 중심에 두어 **AI 에이전트** 및 **코딩 워크플로우** 설계의 새로운 기준을 제시합니다. 복잡한 **멀티 에이전트**나 **RAG** 구현 대신, **명확한 제어 루프**와 **경량 LLM 모델**, 체계화된 **프롬프트·문맥 파일**을 적극 활용해 디버깅과 유지관리를 크게 용이하게 했습니다. **직접 검색 기반의 코드 탐색**, 명확한 **도구 계층**, **Explcit Todo 리스트** 등으로 작업의 일관성과 확장성을 높이며, 불필요한 복잡성 없이 자신만의 **LLM 에이전트**도 쉽게 구현할 수 있도록 설계된 점이 특징입니다. **구조적 단순함**과 **정교한 프롬프트** 조합이 효율적인 **AI 개발 환경** 구현에 중요한 실전 인사이트를 제공합니다.

## Topic Body

- **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의 설계 철학과 가이드를 적극 참고할 가치가 높음

## Comments



### Comment 42923

- Author: kaydash
- Created: 2025-08-25T18:01:48+09:00
- Points: 1

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

### Comment 42840

- Author: neo
- Created: 2025-08-24T14:33:50+09:00
- Points: 1

###### [Hacker News 의견](https://news.ycombinator.com/item?id=44998295) 
- KISS 같은 단순함이 언제나 이김이라는 믿음임, 그리고 이 글을 잘 정리해줘서 유익했다는 소감임

- Claude Code가 오픈소스가 아니라 아쉽지만, 내부 동작을 더 잘 파악할 수 있는 도구들이 있다는 소개임, 만약 진짜로 어떻게 작동하는지 관심 있다면 Claude Trace를 추천함  
  [https://github.com/badlogic/lemmy/tree/main/apps/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace)  
  이 도구는 세션에서 사용된 모든 도구와 프롬프트를 보여주는 JSON 파일과 보기 쉽게 포맷된 HTML 파일을 만들어 줌
  - 오픈소스 대안을 찾는다면 OpenHands CLI를 체크해 보라는 제안임  
    [https://github.com/All-Hands-AI/OpenHands?tab=readme-ov-file](https://github.com/All-Hands-AI/OpenHands?tab=readme-ov-file)
  - [https://github.com/anthropics/claude-code](https://github.com/anthropics/claude-code)  
    시스템 프롬프트도 확인할 수 있음  
    모델이 기본적으로 작업을 여러 단계로 쪼개서 인내심 있게 해결하도록 학습되어 있음, 실패 케이스에도 어느 정도 강건함

- 요즘 멀티에이전트 시스템이 각광받는 시기에 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](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일 전에 만료된 상태임, 사이트가 유효하지 않으니 조심하라는 안내임