Claude Code 하니스 완벽 가이드: AI를 전담 직원으로 만드는 법

Claude Code 사용법을 찾고 있다면, 오늘 소개할 하니스(Harness)가 정말 게임을 바꿀 거예요. 하니스는 Claude Code에게 "우리 팀은 이렇게 일해"를 미리 알려주는 보조 도구로, 스킬·에이전트·커맨드 세 가지 요소로 구성돼 있어요. 이 세 가지를 갖추면 Claude Code는 범용 AI에서 우리 프로젝트 전담 AI 전문가로 변신해요.

 

하니스가 뭔가요? 새 직원 비유로 쉽게 이해하기

아무리 똑똑한 신입 직원이라도 첫날부터 우리 회사의 모든 방식을 알 수 없잖아요. 코드 리뷰는 어떻게 하는지, 브랜치 이름은 어떻게 짓는지, 배포 전에 꼭 확인해야 할 게 뭔지. 아무도 안 알려주면 물어보거나 알아서 눈치껏 하는 수밖에 없어요.

 

Claude Code도 정확히 똑같아요. 기본 상태에서는 굉장히 능력 있는 AI지만, 우리 프로젝트의 코딩 스타일이나 규칙은 모르는 상태예요. 매번 프롬프트에 "우리 팀은 이런 방식으로 써요"라고 설명하는 건 번거롭고, 조금만 어긋나면 결과물이 들쭉날쭉해져요.

 

하니스는 이 문제를 해결해줘요. 우리 팀의 일하는 방식을 문서로 미리 정리해두면, Claude Code가 그걸 읽고 처음부터 그 방식에 맞게 행동해요. 처음 설정이 약간 번거롭게 느껴질 수 있는데, 한 번 해두면 그 이후엔 같은 설명을 반복할 필요도 없고 매번 일관된 결과물이 나와서 장기적으로 시간이 훨씬 절약돼요.

스킬: 동네 의사를 전문의로 만드는 가이드북

일반 Claude Code가 동네 병원 의사라면, 스킬(Skill)을 붙이면 그 분야 전문의가 되는 거예요. 특정 기술이나 도구에 대한 전문 지식을 미리 담아둔 문서를 Claude Code의 도구 모음에 추가하는 방식이에요.

 

사용법은 매우 간단해요. 슬래시 커맨드 앞에 스킬 이름만 붙이면 돼요. 예를 들어 /fastapi-backend-guidelines 회원가입 기능 만들어줘 식으로 쓰면, Claude Code는 FastAPI 스킬에 정의된 코드 구조와 규칙을 바탕으로 답변해줘요.

 

하니스에 기본으로 포함된 스킬들은 꽤 다양해요. FastAPI 백엔드 가이드라인은 역할별로 깔끔하게 나눈 코드 구조를 자동으로 적용해줘요. 서랍장처럼 코드도 어디에 뭘 넣어야 하는지 명확하게 정리해줘요. Next.js 프론트엔드 가이드라인은 최신 방식에 맞는 빠른 구조로 화면을 만들어줘요.

 

그 외에도 흐름도와 관계도를 자동으로 그려주는 Mermaid 스킬, PDF 파일에서 글자를 추출하거나 페이지를 분리·합치는 작업을 도와주는 PDF 스킬, 코드로 PPT를 자동 생성하는 PPTX 스킬도 있어요. 웹 디자인 가이드라인 스킬은 색상 대비나 여백 같은 디자인 요소를 리뷰해주는 역할을 해요. 코딩을 잘 몰라도 이런 다양한 스킬들을 활용하면 결과물의 수준이 눈에 띄게 달라져요.

 

에이전트: 시키면 알아서 끝까지 해주는 보조 직원

스킬과 에이전트는 비슷해 보이지만 역할이 꽤 달라요. 스킬이 "이 분야 전문 지식으로 답해줘"라면, 에이전트(Agent)는 "이 문제 스스로 해결해줘"예요. 에이전트는 파일을 직접 열고 읽고, 문제를 파악하고, 수정하고, 확인까지 혼자 처리해요.

 

Claude Code 에이전트 활용에는 세 가지가 기본으로 들어 있어요. 먼저 플래너 에이전트는 새 기능을 개발하기 전에 단계별 계획을 세워줘요. 어떤 파일을 어떤 순서로 건드려야 하는지, 각 기능이 어떻게 연결되는지, 도중에 어떤 위험이 있을 수 있는지까지 명확하게 정리해줘요. 처음에는 이게 필요한가 싶을 수 있지만, 실제로 써보면 계획 없이 바로 코딩하다 생기는 문제를 꽤 많이 막아줘요.

 

플랜 리뷰어 에이전트는 그 계획의 빈틈을 자세히 찾아줘요. 보안 문제나 미래에 생길 수 있는 위험 요소를 검토해서 플래너가 놓친 부분을 짚어내요. 두 에이전트를 함께 쓰면 계획 단계에서 발생할 수 있는 실수를 크게 줄일 수 있어요.

 

웹 리서치 스페셜리스트 에이전트는 개발하다가 막혔을 때 정말 유용해요. 개발자 커뮤니티, Q&A 사이트, 공식 이슈 게시판을 동시에 검색해서 결과를 한 곳에 정리해줘요. 여러 탭 열어가며 찾던 시간을 많이 아낄 수 있어요. 에이전트는 작업 내용이 서로 섞이지 않고 독립적으로 관리되기 때문에, 여러 에이전트를 동시에 실행해도 결과물이 엉키지 않아요.

커맨드: 복잡한 작업을 슬래시 하나로

커맨드(Command)는 자주 반복하는 복잡한 작업을 슬래시 명령어 하나로 실행하는 매크로예요. 예를 들어 코드 리뷰를 할 때마다 "보안 취약점 체크하고, 코드 스타일을 확인하고, 개선 제안까지 해줘"라고 매번 쓰는 건 번거로워요. 이걸 /code-review 하나로 묶어두면 한 번에 처리돼요.

 

커맨드의 강점은 스킬과 에이전트를 조합해서 실행할 수도 있다는 점이에요. 배포 전 체크리스트처럼 여러 단계로 구성된 작업을 커맨드 하나에 담아두면, 매번 빠뜨리는 단계 없이 일관되게 처리할 수 있어요. Claude Code 사용법에서 이 부분이 특히 반복적인 업무가 많은 팀에 큰 도움이 돼요. 복잡한 워크플로우도 슬래시 하나로 시작된다고 생각하면 꽤 편리해요.

 

우리 팀 맞춤으로 커스터마이징하기

하니스는 기본값으로 써도 충분히 유용하지만, 우리 팀 규칙을 추가하면 훨씬 강력해져요. 스킬 파일은 일반 텍스트 문서라서 편집이 쉬워요. Anthropic 공식 문서 기준으로 SKILL.md 파일은 500줄 이하를 권장하는데, 그 안에 우리 팀이 지키는 네이밍 규칙이나 금지 패턴 같은 내용을 넣을 수 있어요.

 

에이전트도 마찬가지예요. .claude/agents/ 폴더에 파일 하나만 추가하면 새 에이전트를 만들 수 있어요. 우리 회사 방식으로 코드를 리뷰해주는 에이전트, 우리 서비스 특성에 맞는 디버그 에이전트처럼 목적에 딱 맞는 AI 전담 직원을 직접 만드는 거예요.

 

처음 설정이 약간 번거롭게 느껴질 수 있어요. 하지만 Claude Code를 범용 AI가 아닌 우리 프로젝트 전담 전문가로 쓰고 싶다면, Claude Code 하니스 설정에 한 번 투자하는 게 맞아요. 스킬·에이전트·커맨드, 이 세 가지를 내 팀 방식으로 갖추고 나면 Claude Code가 쓰는 경험이 완전히 달라질 거거든요.