[Claude Agent] Subagents·Commands·Skills 역할 구분

 

안녕하세요! 재아군의 관찰인생입니다. 오늘은 Claude Agent을 실무 개발자 관점에서 정리해보겠습니다.

 

Claude Agent은 단순히 새 도구를 하나 더 외우는 주제가 아닙니다. AI 코딩을 반복 가능한 개발 프로세스로 바꾸고, 결과물을 운영 코드에 넣기 전에 어떤 질문과 검증을 거쳐야 하는지 다루는 주제입니다.

 

이 글은 Claude Code 설정을 만들다가 명령어와 에이전트, 스킬의 경계가 헷갈리는 개발자를 위해 작성했습니다. claude-code-best-practice README를 기준으로 핵심 개념을 정리하되, 실제 프로젝트에 넣을 때 생기는 결정 지점과 주의점을 함께 다룹니다.

 

Claude BP Agent의 핵심은 AI에게 더 많은 일을 시키는 것이 아니라, 더 명확한 역할과 검증 기준 안에서 일하게 만드는 것입니다.

 

 

---

1. Claude BP Agent이 필요한 이유

 

Subagents, Commands, Skills를 언제 나누고 어떻게 조합해야 하는지 정리하는 기준이 중요한 이유는 AI 코딩의 병목이 이제 “코드를 만들 수 있느냐”에서 “믿고 합칠 수 있느냐”로 이동했기 때문입니다. 코드 생성 자체는 빨라졌지만, 설계 누락, 테스트 부족, 리뷰 사각지대, 배포 리스크는 여전히 사람이 관리해야 합니다.

 

현업에서는 작은 기능 하나에도 제품 의도, 기존 아키텍처, 보안 정책, 배포 타이밍이 얽혀 있습니다. Claude BP Agent을 도입하면 이런 관점을 대화 한 번에 섞어버리지 않고, 단계와 역할로 나누어 확인할 수 있습니다.

 

• 대상 독자: Claude Code 설정을 만들다가 명령어와 에이전트, 스킬의 경계가 헷갈리는 개발자
• 핵심 자료: claude-code-best-practice README
• 주요 목표: Subagents, Commands, Skills를 언제 나누고 어떻게 조합해야 하는지 정리하는 기준
• 최종 산출물: 계획, 구현, 테스트, 리뷰, 출시 체크리스트

 

 

2. Claude BP Agent 핵심 개념과 구조

 

Claude Code Best Practice을 볼 때 가장 먼저 해야 할 일은 기능 이름을 외우는 것이 아니라, 어떤 책임을 어디에 둘지 나누는 것입니다. AI가 모든 맥락을 한 번에 들고 있으면 빠르게 느껴지지만, 작업이 커질수록 중요한 제약을 잊거나 자기 결과를 스스로 합리화하기 쉽습니다.

 

그래서 Claude BP Agent에서는 역할, 명령, 검증 기준을 명시적으로 분리하는 접근이 중요합니다. 이 분리는 대형 조직의 프로세스를 흉내 내려는 것이 아니라, 혼자 일할 때도 제품 담당자, 구현자, 리뷰어, QA의 질문을 순서대로 통과시키기 위한 장치입니다.

 

레이어	내용	실무 효과
문제 정의	Subagents, Commands, Skills를 언제 나누고 어떻게 조합해야 하는지 정리하는 기준	성공 기준을 먼저 적어 AI의 과잉 구현을 줄입니다.
도구 구조	Claude Code Best Practice의 핵심 명령과 규칙	반복 가능한 절차를 만들어 결과 품질을 안정화합니다.
검증 방식	테스트, 리뷰, QA, 체크리스트	그럴듯한 답변과 실제 동작을 분리합니다.
운영 기준	팀 규칙, 권한, 유지보수	한 번 만든 지침이 오래된 부채가 되지 않게 합니다.

 

핵심 장점

 

• 역할별 책임을 분리할 수 있습니다
• 반복 워크플로우를 명령어로 고정할 수 있습니다
• 세부 전문성은 skill로 재사용할 수 있습니다
• 오케스트레이터가 command-agent-skill을 연결합니다

 

도입 전 알아야 할 한계

 

• 모든 것을 agent로 만들면 호출 비용과 복잡도가 늘어납니다
• 명령어가 길어지면 문서와 다를 바 없어집니다
• skill 설명이 모호하면 자동 활성화가 불안정합니다

 

---

3. Claude BP Agent 명령어와 작업 흐름

 

좋은 워크플로우는 “멋진 프롬프트”보다 “반복 가능한 순서”에 가깝습니다. 특히 Claude Code나 다른 코딩 에이전트를 쓸 때는 명령어 하나가 무엇을 입력으로 받고, 무엇을 출력으로 내야 하는지 정해두는 편이 훨씬 안정적입니다.

 

아래 표는 Claude Code Best Practice을 실제 프로젝트에 넣을 때 자주 쓰게 되는 흐름입니다. 팀마다 이름은 바뀔 수 있지만, 조사, 계획, 실행, 리뷰, 출시라는 구조는 대부분의 코드 변경에 적용됩니다.

 

명령/개념	역할	추천 사용 시점
.claude/agents	먼저 사용자가 부를 command를 정의합니다	초기 설계 단계
.claude/commands	command 안에서 필요한 agent 역할을 분리합니다	초기 설계 단계
.claude/skills	반복 지식은 skill로 빼서 재사용합니다	검증과 운영 단계
orchestrator pattern	출력 형식과 완료 기준을 각 파일에 고정합니다	검증과 운영 단계

 

.claude/
  agents/
    reviewer.md
    qa-lead.md
  commands/
    ship.md
    plan.md
  skills/
    test-driven-development/
      SKILL.md

 

이 예시는 그대로 복사하기보다 팀의 실제 명령어와 테스트 환경에 맞게 줄이는 것이 좋습니다. 중요한 것은 Claude BP Agent을 호출했을 때 항상 같은 종류의 산출물이 나오도록 만드는 것입니다.

 

 

4. 실무 적용 시나리오

 

Claude BP Agent을 처음 적용할 때 가장 좋은 대상은 “작지만 검증이 필요한 작업”입니다. 예를 들어 결제 문구 수정, 인증 오류 처리, 관리자 화면 필터 추가처럼 범위는 작지만 회귀가 나면 곤란한 기능이 좋습니다.

 

이때 AI에게 바로 구현을 맡기지 말고, 먼저 현재 코드와 요구사항을 읽게 한 뒤 계획을 만들게 합니다. 그 다음 테스트나 체크리스트를 먼저 합의하고, 구현은 그 범위 안에서만 진행하게 만드는 것이 핵심입니다.

 

1. 먼저 사용자가 부를 command를 정의합니다
2. command 안에서 필요한 agent 역할을 분리합니다
3. 반복 지식은 skill로 빼서 재사용합니다
4. 출력 형식과 완료 기준을 각 파일에 고정합니다
5. 한 달에 한 번 사용 빈도를 보고 정리합니다

 

실무 체크리스트

 

• 작업 시작 전에 완료 기준을 한 문장으로 적습니다.
• 수정할 파일과 건드리지 않을 파일을 구분합니다.
• 테스트 명령과 수동 확인 경로를 미리 정합니다.
• 리뷰는 구현자와 다른 관점으로 요청합니다.
• 출시 전 롤백 기준과 모니터링 지표를 남깁니다.

 

---

5. 비교 분석: 언제 Claude BP Agent을 선택할까

 

모든 프로젝트에 같은 도구가 맞지는 않습니다. 중요한 것은 지금 팀의 병목이 속도인지, 품질인지, 지식 공유인지 구분하는 것입니다. Claude BP Agent은 특히 AI 코딩 결과를 검증 가능한 프로세스로 묶고 싶은 상황에서 가치가 큽니다.

 

선택지	강점	주의점
Command	사용자가 직접 호출하는 절차	반복 작업, 오케스트레이션
Agent	독립 역할과 관점	리뷰어, QA, 보안 담당
Skill	특정 기법과 지침	TDD, 디버깅, 문서화

 

개인 프로젝트라면 전체 체계를 다 가져오기보다 하나의 명령, 하나의 리뷰 규칙, 하나의 테스트 습관부터 시작하는 편이 낫습니다. 팀 프로젝트라면 공통 규칙을 문서화하고, 사용 빈도가 낮은 규칙은 과감히 제거해야 합니다.

 

 

6. Claude BP Agent 베스트 프랙티스

 

베스트 프랙티스의 출발점은 복잡한 자동화가 아니라 작은 반복 성공입니다. AI 코딩 도구는 지시를 잘 따라도, 지시 자체가 낡거나 모호하면 매우 빠르게 잘못된 방향으로 달릴 수 있습니다.

 

원칙	실행 방법	실패 신호
작게 시작	가장 자주 반복하는 작업 하나만 워크플로우로 만듭니다	명령어가 많지만 실제로 쓰는 것은 거의 없습니다
검증 먼저	테스트, 리뷰, QA 기준을 구현 전에 정합니다	완료 후에야 확인할 항목을 떠올립니다
권한 최소화	쓰기 권한과 외부 도구 접근을 필요한 범위로 제한합니다	AI가 예상 밖 파일이나 설정을 바꿉니다
문서 갱신	규칙이 바뀌면 CLAUDE.md나 팀 문서를 함께 고칩니다	AI가 오래된 관례를 계속 따릅니다
사람 검토	중요 변경은 사람이 diff와 배포 조건을 확인합니다	리뷰가 요약 칭찬으로 끝납니다

 

피해야 할 도입 방식

 

• 한 번에 모든 명령어와 스킬을 설치해 팀에 강제합니다.
• 공식 문서와 커뮤니티 팁을 구분하지 않고 운영 표준으로 씁니다.
• 테스트가 없는 상태에서 AI에게 대규모 리팩터링을 맡깁니다.
• 리뷰 결과를 반영한 뒤 재검증하지 않습니다.
• 컨텍스트가 오래된 상태인데 계속 같은 세션에서 밀어붙입니다.

 

7. 운영 기준과 확장 전략

 

Claude BP Agent을 운영 단계로 가져가려면 “좋아 보이는 자동화”보다 “문제가 생겼을 때 설명 가능한 구조”가 중요합니다. 누가 어떤 명령을 호출했고, 어떤 파일을 바꿨고, 어떤 테스트를 통과했는지 추적 가능해야 합니다.

 

초기에는 개인 생산성 도구처럼 시작해도 괜찮습니다. 다만 팀 표준으로 확장하려면 사용 로그, 실패 사례, 리뷰 품질, 배포 사고 감소 같은 지표를 함께 봐야 합니다. 이 지표가 없으면 도구가 늘어났는지, 개발 품질이 좋아졌는지 구분하기 어렵습니다.

 

운영 점검 질문
- 이 워크플로우는 어떤 실패를 줄였는가?
- AI가 바꿀 수 없는 파일과 명령은 무엇인가?
- 리뷰에서 실제 결함이 발견되는가?
- 새 팀원이 30분 안에 따라 할 수 있는가?
- 한 달 뒤에도 유지할 만큼 자주 쓰이는가?

 

 

---

마무리

 

Claude BP Agent은 AI 코딩을 더 화려하게 만드는 장식이 아니라, 결과를 더 차분하게 검증하기 위한 작업 방식입니다. Subagents, Commands, Skills를 언제 나누고 어떻게 조합해야 하는지 정리하는 기준을 제대로 활용하면 “AI가 코드를 써줬다”에서 “AI가 팀 규칙 안에서 검증 가능한 변경을 만들었다”로 수준이 올라갑니다.

 

정리하면 첫째, 작은 작업 하나에만 적용해 흐름을 익히고, 둘째, 테스트와 리뷰를 구현 전에 정의하고, 셋째, 오래된 지침을 계속 정리해야 합니다. 그렇게 운영할 때 Claude BP Agent은 재아군 블로그 독자들이 실제 프로젝트에서 바로 실험해볼 만한 강력한 개발 습관이 됩니다.