하네스 엔지니어링 실전: 에이전트 환경 설계하기

4과에서 에이전트를 배웠고, 3과에서 Claude Code를 설치했습니다. 이제 그것들을 연결해 진짜 작업 환경을 만들어봅시다. 하네스는 크게 세 가지로 나뉩니다. 1. 지침(Instructions) — CLAUDE.md: AI에게 '어떻게 행동해야 하는지'를 알려주는 파일입니다. 내 역할, 업무 맥락, 금지 사항, 자주 쓰는 용어, 출력 형식 등을 한 번 정리해두면 매번 설명할 필요가 없습니다. 2. 도구(Tools) — MCP 서버: AI가 외부 세계와 연결되는 플러그인입니다. Gmail, 캘린더, 파일시스템, 데이터베이스에 실제로 접근해 행동할 수 있게 합니다. 3. 스킬(Skills) — 슬래시 커맨드: 자주 반복하는 업무를 패키지화한 것입니다. '/연차계산', '/계약서검토', '/주간보고서'처럼 이름을 부르는 것만으로 복잡한 작업이 실행됩니다.

CLAUDE.md는 AI에게 보내는 '업무 매뉴얼'입니다. 처음 만날 때 건네는 명함이자, 함께 일하는 동안 지켜야 할 약속이기도 합니다. 좋은 CLAUDE.md의 4가지 요소: 정체성: 이 프로젝트에서 AI가 맡는 역할. '너는 노무법인의 법률 문서 초안 작성 보조다'처럼 명확하게. 맥락: 자주 쓰는 배경 정보. 회사명, 업종, 자주 등장하는 용어 정의, 고객 유형 등. 행동 규칙: AI가 해야 할 것과 하지 말아야 할 것. '판례 번호는 반드시 검색으로 확인하라', '최종 판단을 단정적으로 내리지 말라'처럼. 출력 형식: 결과물의 형태. '보고서는 결론 먼저, 그 다음 근거', '표가 필요하면 마크다운 표 형식으로'.

# CLAUDE.md 예시 — 인사팀 업무 보조

## 역할
너는 인사팀 업무를 보조하는 AI다.

## 맥락
- 회사명: (주)한동 / 직원 수: 약 50명
- 근로기준법, 4대보험 기반 업무
- 자주 쓰는 약어: 연차=연차휴가, 4대=4대보험

## 행동 규칙
- 법령 조문은 반드시 번호까지 명시
- 임금 계산은 산식을 함께 보여줄 것
- 추측성 내용은 '~로 보입니다'로 표현

## 출력 형식
- 긴 분석: 결론 → 근거 → 주의사항 순서
- 표 필요 시 마크다운 표 사용

같은 작업을 매번 긴 프롬프트로 요청하는 것은 비효율적입니다. 스킬(슬래시 커맨드)을 만들면 한 단어로 복잡한 작업을 실행할 수 있습니다. Claude Code에서 스킬 만드는 방법: 1. 프로젝트 폴더 안에 `.claude/commands/` 폴더 생성 2. 원하는 이름으로 `.md` 파일 생성 (예: `weekly-report.md`) 3. 파일 안에 해당 작업의 지시문 작성 4. Claude Code에서 `/weekly-report`로 실행 팁: 스킬 파일 안에서 `$ARGUMENTS`를 쓰면 실행 시 추가 정보를 전달할 수 있습니다. '/연차계산 홍길동 2024-03-01'처럼 이름과 날짜를 함께 전달하는 식입니다. 이미 잘 만들어진 스킬들은 GitHub에서 오픈소스로 공유되고 있습니다. 검색어: 'Claude Code skills github'