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