vibe coding은 그만—Claude Code로 진짜 Agentic Engineering을 하는 법

오늘 하루에만 별 329개—누적 59,382개를 돌파한 레포가 GitHub 트렌딩 1위를 차지했다. shanraisshan/claude-code-best-practice. "vibe coding에서 agentic engineering으로"라는 슬로건이 핵심을 찌른다. AI에게 막연히 시키는 단계를 넘어, 자율적·체계적으로 작동하는 엔지니어링 파이프라인을 만드는 법을 집대성한 실전 레포다.

이게 뭔가

Claude Code는 Anthropic의 터미널 기반 AI 코딩 에이전트다. 이 레포는 그것을 그냥 쓰는 것과 잘 쓰는 것의 차이를 메운다. 핵심 개념 세 가지:

• Agents(에이전트): 복잡한 작업을 자율 처리하는 하위 실행 단위
• Commands(명령): 반복 작업을 슬래시 명령(/review, /test)으로 자동화
• Skills(스킬): 특정 도메인 지식을 AI에게 주입하는 컨텍스트 파일

이 셋을 연결한 Orchestration Workflow가 레포의 심장이다. 파키스탄 개발자 Shan Raisshan이 직접 실무에 적용하며 축적한 내용이고, Disrupt.com·ClaudeKit 같은 스폰서가 붙을 만큼 커뮤니티 신뢰를 얻었다.

왜 지금 뜨는가

세 흐름이 정확히 맞물린 타이밍이다.

① Claude Code 실무 도입 급증: Anthropic이 Claude Code를 공식 GA하면서 '어떻게 잘 쓰나'에 대한 수요가 폭발했다. 공식 문서는 기능을 설명하지만, 실전 워크플로우는 커뮤니티가 채워야 한다.

② Context Engineering이 화두로 부상: 프롬프트 엔지니어링의 다음 단계로 '컨텍스트 엔지니어링'—AI가 읽을 정보를 설계하는 기술—이 주목받는 시점이다. 이 레포가 그 구현 방법을 정면으로 다룬다.

③ Boris Cherny 효과: Claude Code 핵심 개발자 Boris Cherny의 X 코멘트 세 개가 레포에 직접 인용·시각화돼 있다. 팀 내부 관점이 외부 커뮤니티 문서에 담긴 건 드문 일이다.

핵심 기능

개념	역할
Subagents	대형 태스크를 병렬 처리하는 하위 에이전트 위임
Custom Commands	슬래시 명령으로 반복 업무 원클릭 자동화
Skills	프로젝트별 규칙·도메인 지식을 AI에게 지속 주입
Orchestration Workflow	세 가지를 연결한 자율 실행 파이프라인

누구에게 쓸모 있나

• 이미 Claude Code를 쓰는 개발자: 막연히 쓰던 걸 체계화할 레퍼런스
• AI 도구를 팀에 도입하려는 엔지니어링 리드: 실전 워크플로우 청사진
• 프롬프트 엔지니어링의 한계를 느끼는 사람: 에이전틱 접근으로의 전환 로드맵
• 비개발자(PM·디자이너): 개념 문서가 평이하게 쓰여 있어 AI 도구 이해에 도움

시작하기

별도 패키지 설치 없이 레포를 참고 문서로 쓴다. Claude Code만 설치돼 있으면 된다.

# 레포 클론
git clone https://github.com/shanraisshan/claude-code-best-practice.git

# 추천 탐색 순서
# 1. best-practice/        → 핵심 원칙 파악
# 2. orchestration-workflow/orchestration-workflow.md → 전체 구조 이해
# 3. implementation/       → 실제 예시 적용

이후 ~/.claude/ 또는 프로젝트 .claude/ 폴더에 아래 예시들을 복사해 바로 적용할 수 있다.

사용 예시

① 커스텀 Command — 코드 리뷰 자동화

# .claude/commands/review.md
당신은 시니어 엔지니어입니다. 변경된 파일을 분석하고
버그 가능성 / 성능 문제 / 가독성 기준으로 리뷰하세요.
각 지적에 코드 라인을 인용하고 개선안을 함께 제시하세요.

/review 한 줄로 PR 수준 코드 리뷰가 자동 실행된다.

② Skill 파일 — 도메인 지식 영구 주입

# .claude/skills/api-conventions.md
이 프로젝트 API 규칙:
- 모든 엔드포인트: /api/v2/ 접두사
- 에러 응답 형식: { code, message, details }
- 인증: Bearer 토큰, 만료 1시간

새 API를 작성할 때마다 Claude가 이 컨텍스트를 자동 참조한다.

③ Subagent 오케스트레이션 — TDD 자동화

# .claude/agents/feature-builder.md
기능 명세를 받아 아래 순서로 독립 서브에이전트를 호출하세요:
1. 테스트 코드 작성 (TDD 원칙)
2. 구현 코드 작성
3. README·CHANGELOG 업데이트
각 단계 완료 후 결과를 다음 에이전트에 전달하세요.

기능 명세 한 줄로 TDD 전체 사이클이 자율 완성된다.

한계·주의

• Claude Code 전용: Anthropic 제품 외 GPT·Gemini 기반 워크플로우에는 직접 적용되지 않는다.
• 빠른 노후화 위험: Claude Code 자체 업데이트 속도가 빠르다. 레포 배지의 최종 업데이트 날짜(Jun 23, 2026)를 주기적으로 확인하라.
• 문서 레포, 라이브러리 아님: npm install 류의 자동화는 없다. 직접 읽고 복사·적용해야 한다.
• 실습 없인 반쪽: 레포 이름처럼 "practice makes perfect"—읽기만 해선 부족하다. 자신의 프로젝트에 붙여봐야 이해가 완성된다.