Claude Code Best Practice 저장소를 활용한 에이전트 엔지니어링 가이드

Claude Code Best Practice 저장소 활용법

이 저장소는 단순히 코드를 작성하는 방법을 넘어, LLM(거대 언어 모델)을 활용한 '에이전트 엔지니어링'의 개념과 실제 적용법을 학습하는 교육 과정처럼 접근해야 합니다.

1. 저장소를 코스처럼 학습하기

이 저장소는 당장 실행할 워크플로우나 기술 습득보다는, LLM 에이전트 개발의 기초 원리를 이해하기 위한 레퍼런스 자료로 활용하세요. 내용을 충분히 숙지한 후 실제 코드를 실행하며 익히는 것이 좋습니다.

2. Claude를 챗봇이 아닌 에이전트로 이해하기

Claude를 단순한 챗봇으로 사용하지 마세요. 저장소에서 소개하는 '에이전트(agents)', '명령어(commands)', '스킬(skills)', '훅(hooks)'과 같은 핵심 개념을 익히고, 이를 조합하여 자신만의 개발 워크플로우를 구축하는 방법을 배우는 데 집중하세요.

3. 전체 워크플로우 실행 예시: /weather-orchestrator

orchestration-workflow/orchestration-workflow.md 경로의 /weather-orchestrator 명령어를 실행하여 명령어부터 에이전트, 스킬까지 이어지는 전체 흐름을 직접 확인해 보세요. 이 예시는 기획부터 개발 완료까지, 어떤 개발 워크플로우에도 적용할 수 있는 템플릿 역할을 합니다.

4. 커스텀 훅 사운드 활용

개발 중에 들리는 커스텀 훅 사운드에 주목하세요. 이러한 훅의 구현은 별도의 Claude Code Hooks 저장소에 있으며, '에이전트 팀(Agent Teams)'과 같은 다른 패턴의 구현은 본 저장소의 implementation/ 디렉토리에서 찾을 수 있습니다.

5. 고급 주제 및 구현 학습

[🔥 Hot](#-hot) 섹션에서 소개하는 고급 주제와 그 구현 방식을 학습하세요. 예를 들어, 'Ralph Wiggum self-evolving loop'는 완전한 작동 리포지토리이므로, 해당 패턴을 처음부터 끝까지 보려면 복제(clone)하여 직접 실행해 볼 수 있습니다.

6. 나만의 프로젝트에 Claude 적용하기

자신의 프로젝트에 CLAUDE.md 파일을 만들고 Claude를 해당 파일에 지시하여 코드 수정 제안을 받으세요. 특히 CLAUDE.md 파일의 구조를 어떻게 개선할 수 있는지에 대한 팁은 Claude 팀이나 커뮤니티에서 제공된 실제 사례를 기반으로 합니다.

활용 사례

상황 1: 복잡한 LLM 워크플로우의 전체 흐름 이해

• 누가: 신규 LLM 프로젝트를 시작하는 백엔드 개발자
• 무엇을 하려다 막혔나: 여러 LLM 에이전트와 스킬이 복잡하게 얽힌 워크플로우를 어떻게 구성하고 실행해야 할지 감이 잡히지 않음.
• 어떤 단계: 저장소의 3번 단계인 /weather-orchestrator 실행. 이 명령어를 통해 명령어(command), 에이전트(agent), 스킬(skill)이 어떻게 연결되는지 실질적인 작동 방식을 확인.
• 결과: /weather-orchestrator와 같은 구조를 템플릿 삼아, 자신의 프로젝트에 맞는 LLM 워크플로우를 기획하고 개발하는 데 필요한 전체적인 그림을 이해하게 됨.

상황 2: 기존 프로젝트에 LLM 기반 코드 개선 적용

• 누가: 레거시 코드를 개선하려는 프론트엔드 개발자
• 무엇을 하려다 막혔나: 기존 코드베이스에 LLM을 적용하여 개선점을 찾고 싶은데, 어디서부터 시작해야 할지 막막함. 특히 CLAUDE.md 파일의 역할을 어떻게 활용해야 할지 모름.
• 어떤 단계: 저장소의 6번 단계 활용. 자신의 프로젝트 루트 디렉토리에 CLAUDE.md 파일을 생성하고, 이 저장소의 '팁과 요령' 섹션을 Claude에게 지시하며 코드 구조 개선 제안 요청.
• 결과: Claude가 CLAUDE.md 파일의 내용을 바탕으로 코드 리팩토링, 주석 추가, 네이밍 컨벤션 개선 등 구체적인 코드 수정 제안을 제공하여, LLM을 활용한 점진적인 코드 품질 향상 방법을 익힘.

출처: https://github.com/shanraisshan/claude-code-best-practice