Harness & 프로덕션

Agent Harness란?

개념

Agent Harness = Claude 모델 주변의 실행 환경 + 도구 + 컨텍스트 관리 체계

Harness(하네스)는 원래 "마구"(말에 채우는 장비)라는 뜻입니다. AI 에이전트 맥락에서는 모델을 감싸고 제어하는 실행 환경 전체를 가리킵니다. 실무에서 "harness를 잘 설계해야 한다"고 하면, 모델 자체가 아니라 도구 구성, 컨텍스트 관리, 오류 복구 체계를 잘 만들어야 한다는 뜻입니다.

Claude Code 자체가 하나의 완성된 Agent Harness입니다. 우리가 터미널에서 claude를 실행할 때, 그 뒤에서 동작하는 것들이 바로 Harness의 구성 요소입니다.

Harness 구성 요소

왜 중요한가?

터미널에서 claude를 실행해 10분 대화하는 건 쉽습니다. 하지만 다음과 같은 상황에서는 Harness 설계가 필수입니다:

• 장시간 작업: 8개 브랜드 데이터를 순차적으로 분석하는 3시간짜리 작업
• 자동 복구: 네트워크 오류나 API 장애 시 이전 상태로 되돌리기
• 컨텍스트 관리: 대화가 길어지면 초기 지시사항을 잊는 문제 해결
• 보안 제어: 프로덕션 DB에 DELETE 쿼리를 실행하지 못하게 차단

Harness 설계 원칙

Anthropic 엔지니어링 블로그에서 공개한 장시간 에이전트 앱 설계 원칙을 이그니스 실무에 맞게 정리합니다.

1. 컨텍스트 관리

Claude Code의 컨텍스트 윈도우는 유한합니다 (현재 최대 1M 토큰). 대화가 길어지면 초기 지시사항을 잊거나 성능이 떨어집니다.

# 대화가 길어지면 요약해서 컨텍스트 확보
/compact

# 특정 포커스로 압축 (무엇을 기억할지 지정)
/compact 브랜드별 매출 분석 결과와 남은 작업에 집중

# 핵심 규칙은 CLAUDE.md에 넣어 매 세션마다 자동 로드
# .claude/CLAUDE.md 또는 프로젝트 루트의 CLAUDE.md

실무 팁:

• 작업 시작 전 CLAUDE.md에 이번 작업의 목표와 제약 조건을 명시
• 50턴 이상 대화가 진행되면 /compact로 요약
• 핵심 규칙은 CLAUDE.md에, 일시적인 지시는 대화로 전달
• SessionStart 훅으로 /compact 후 컨텍스트를 자동 재주입하는 패턴도 가능

2. Plan-Work-Review 사이클

장시간 작업을 "계획 - 실행 - 검토"의 반복 루프로 구조화합니다.

[Plan] 작업 목표와 단계를 정리
  |
[Work] 한 단계씩 실행
  |
[Review] 결과 검증, 에러 확인
  |
다음 단계로 -> [Plan] 으로 돌아가기

이그니스 실무 예시:

카페24 8개 브랜드 월간 보고서를 생성해줘.

진행 방식:
1. [Plan] 브랜드 목록과 데이터 파일 확인
2. [Work] 브랜드별로 하나씩 분석
3. [Review] 각 브랜드 분석 결과 검증 (수치 오류, 누락 확인)
4. 8개 브랜드 완료 후 통합 요약 생성

각 브랜드 분석 완료 시 중간 결과를 저장해줘.

3. 체크포인트: Git 커밋으로 안전망 확보

작업의 중간 단계마다 Git 커밋을 남기면, 문제가 생겼을 때 안전하게 되돌릴 수 있습니다.

# 작업 단계별 자동 커밋 요청
"한끼통살 분석 완료. 이 상태를 커밋해줘.
메시지: checkpoint - 한끼통살 분석 완료"

# 문제 발생 시 롤백
"마지막 체크포인트로 되돌아가줘"

자동화 시에는 Harness 레벨에서 단계 완료 시 자동으로 커밋하도록 설계합니다:

# 비대화형 모드에서 작업 실행 후 자동 커밋
claude -p "한끼통살 데이터 분석해줘" && git add . && git commit -m "checkpoint: 한끼통살 분석"

4. 자동 복구

장시간 작업 중 실패는 불가피합니다. Harness는 실패를 감지하고 복구하는 메커니즘을 제공합니다.

CLAUDE.md에 복구 규칙을 미리 정의해두면 Claude가 자동으로 따릅니다:

# 복구 규칙
- 파일 쓰기 실패 시: 3회 재시도 후 에러 보고
- 분석 결과가 비어 있으면: 원본 데이터 형식 재확인
- 예상 밖의 칼럼명이면: 매핑 테이블 참조 (.claude/column-map.json)

Hooks 심화

Hooks는 Claude Code의 도구 실행 전후에 자동으로 실행되는 셸 스크립트입니다. 기본편에서 기초를 다뤘다면, 여기서는 전체 Hook 종류와 고급 패턴을 다룹니다.

Hook 전체 종류

Hook 설정 구조

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/validate-command.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"Claude Code\"'"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '오늘 날짜: '$(date +%Y-%m-%d)"
          }
        ]
      }
    ]
  }
}

Hook 환경 변수

Hook 스크립트에서 사용할 수 있는 환경 변수:

Hook 출력 처리

이그니스 실전: 위험 명령 차단 Hook

#!/bin/bash
# .claude/hooks/validate-command.sh
# PreToolUse Hook: 위험한 명령어 차단

INPUT="$CLAUDE_TOOL_INPUT"

# DROP/DELETE/TRUNCATE가 포함된 SQL 차단
if echo "$INPUT" | grep -iE "(DROP|DELETE|TRUNCATE)\s+(TABLE|FROM|DATABASE)" > /dev/null; then
  echo "BLOCK" # stdout으로 BLOCK 출력
  echo "데이터 삭제 명령이 감지되었습니다. DBA 승인이 필요합니다." >&2
  exit 0
fi

# rm -rf / 같은 위험한 시스템 명령 차단
if echo "$INPUT" | grep -E "rm\s+-rf\s+/" > /dev/null; then
  echo "BLOCK"
  echo "위험한 삭제 명령입니다." >&2
  exit 0
fi

# 프로덕션 환경 접근 차단
if echo "$INPUT" | grep -iE "production|prod\.egnis" > /dev/null; then
  echo "BLOCK"
  echo "프로덕션 환경 접근이 차단되었습니다. 스테이징을 사용하세요." >&2
  exit 0
fi

exit 0

자동 포맷팅 Hook

#!/bin/bash
# .claude/hooks/auto-format.sh
# PostToolUse Hook: 파일 저장 후 자동 포맷팅

FILE="$CLAUDE_FILE_PATH"

# 확장자별 포맷터 실행
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE" 2>/dev/null
    ;;
  *.py)
    python -m black "$FILE" 2>/dev/null
    ;;
  *.json)
    python -m json.tool "$FILE" > "$FILE.tmp" && mv "$FILE.tmp" "$FILE" 2>/dev/null
    ;;
esac

exit 0

프로덕션 운영 가이드

비대화형 모드

CI/CD 파이프라인이나 스크립트에서 Claude Code를 자동으로 실행할 수 있습니다:

# 단일 명령 실행 후 종료 (-p = print mode, 비대화형)
claude -p "테스트를 실행하고 결과를 알려줘"

# 파이프로 입력 전달
cat error.log | claude -p "이 에러 분석해줘"

# git diff를 입력으로 보안 리뷰
git diff main --name-only | claude -p "변경된 파일 보안 리뷰해줘"

# 결과를 파일로 저장
claude -p "이번 달 매출 데이터를 분석해줘" > report.md

# JSON 출력 모드
claude -p "package.json 의존성 분석" --output-format json

GitHub Actions 연동

PR이 올라올 때 Claude Code가 자동으로 코드 리뷰를 수행하는 예시:

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          claude -p "다음 코드 변경사항을 리뷰해줘.
          보안, 성능, 코드 품질 관점에서 검토하고
          심각도(Critical/Warning/Info)별로 분류해줘:

          $DIFF" > review.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: review
            });

예약 작업

# 5분마다 배포 상태 체크
/loop 5m 배포 상태를 확인하고 에러가 있으면 알려줘

# 매일 오전 9시 데이터 분석 (클라우드 예약)
/schedule "매일 오전 9시에 카페24 신규 주문을 분석하고 이상치를 보고해줘"

보안 체크리스트

프로덕션에서 Claude Code를 운영할 때 반드시 확인해야 할 항목:

에이전트 분업 설계 가이드

Harness의 핵심은 하나의 큰 작업을 여러 전문 에이전트로 나누는 것입니다. 사람 조직처럼 역할을 분리하면 품질과 효율이 올라갑니다.

분업 설계 원칙

실전: 이그니스 에이전트 팀 설계

[사용자]
   │
   ▼
[리드 에이전트] ──── 전체 작업을 조율
   │
   ├── [data-analyst] ──── 카페24 데이터 분석
   │      tools: Read, Bash, Grep
   │      입력: 카페24 주문 엑셀
   │      출력: 분석 결과 JSON + 요약 마크다운
   │
   ├── [report-writer] ──── 보고서 생성
   │      tools: Read, Write
   │      입력: 분석 결과 JSON
   │      출력: 경영진 보고서 (docx/md)
   │
   └── [qa-checker] ──── 결과물 검증
          tools: Read, Grep, Bash
          입력: 보고서 파일
          출력: 검수 결과 (오류/개선점)

에이전트 정의 파일

---
name: data-analyst
description: 카페24 주문 데이터를 분석하고 인사이트를 추출합니다
tools: Read, Bash, Grep, Glob
model: sonnet
memory: project
---
# 데이터 분석 에이전트

## 역할
카페24에서 내보낸 주문 데이터를 분석합니다.

## 작업 순서
1. input 폴더에서 엑셀/CSV 파일을 찾는다
2. 칼럼 구조를 파악하고, 불필요한 칼럼을 식별한다
3. SKU별 주문수, 매출, 평균단가를 계산한다
4. 전월 대비 증감률을 계산한다
5. 이상치(평균 대비 3배 이상)를 플래그한다
6. 결과를 output/analysis.json + output/summary.md로 저장한다

## 출력 형식
- analysis.json: 전체 분석 데이터 (구조화)
- summary.md: 핵심 인사이트 5줄 이내

---
name: report-writer
description: 분석 결과를 경영진 보고서로 변환합니다
tools: Read, Write
model: sonnet
---
# 보고서 작성 에이전트

## 역할
data-analyst의 분석 결과를 경영진용 보고서로 변환합니다.

## 작업 순서
1. output/analysis.json과 output/summary.md를 읽는다
2. 경영진 보고서 구조로 재구성한다:
   - 핵심 지표 요약 (4개 KPI)
   - SKU 성과 Top 10 / Bottom 5
   - 전월 대비 변화 하이라이트
   - 권장 액션 3가지
3. output/report.md로 저장한다

## 톤
- 데이터 기반, 간결하게
- 경영진이 1분 내에 파악 가능한 분량

---
name: qa-checker
description: 생성된 보고서와 분석 결과를 검증합니다
tools: Read, Grep, Bash
model: haiku
---
# QA 검증 에이전트

## 역할
보고서의 정확성과 완성도를 검증합니다.

## 검증 항목
1. 숫자 정합성: analysis.json의 합계와 report.md의 수치 일치 여부
2. 누락 항목: 필수 섹션(KPI, Top 10, 권장 액션)이 모두 있는지
3. 형식: 날짜 형식, 금액 단위(₩), 천 단위 콤마 확인
4. 오탈자: 브랜드명, SKU명 오타 검출

실행 방법

1. data-analyst 에이전트로 input 폴더의 3월 데이터를 분석해줘
2. 분석이 끝나면 report-writer로 보고서 만들어줘
3. 보고서가 나오면 qa-checker로 검증해줘

에이전트 팀을 만들어줘:
- data-analyst: 3월 데이터 분석
- report-writer: 분석 완료 후 보고서 작성
- qa-checker: 보고서 완료 후 검증

data-analyst가 끝나면 report-writer가 시작하고,
report-writer가 끝나면 qa-checker가 검증해줘.

# 분석
claude -p "data-analyst 에이전트로 input/ 폴더 분석해줘"

# 보고서
claude -p "report-writer 에이전트로 output/analysis.json 기반 보고서 만들어줘"

# 검증
claude -p "qa-checker 에이전트로 output/report.md 검증해줘"

에이전트 수 결정 기준

고급 패턴

Worktree 격리

에이전트가 별도 Git worktree에서 작업하면 메인 브랜치를 안전하게 보호할 수 있습니다.

# 에이전트 전용 worktree 생성
git worktree add ../agent-workspace -b agent/feature-landing

# 해당 worktree에서 Claude Code 실행
cd ../agent-workspace && claude -p "랜딩 페이지를 구현해줘"

# 검토 후 메인 브랜치에 머지
cd ../main-project && git merge agent/feature-landing

# 작업 완료 후 worktree 정리
git worktree remove ../agent-workspace

---
name: feature-builder
description: 기능을 별도 워크트리에서 안전하게 구현합니다
tools: Read, Write, Edit, Bash, Glob, Grep
isolation: worktree
---

컨텍스트 엔지니어링

장시간 작업에서 컨텍스트를 효과적으로 관리하는 패턴:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude/context-briefing.md"
          }
        ]
      }
    ]
  }
}

# CLAUDE.md
## 프로젝트 컨텍스트
- 이 프로젝트는 이그니스의 8개 브랜드 관리 시스템입니다
- 프로젝트 히스토리는 .claude/agent-memory/ 를 참조하세요
- 알려진 이슈는 .claude/known-issues.md 를 참조하세요

/compact 현재까지의 분석 결과와 남은 브랜드 목록에 집중

# compact 후 즉시 다음 지시
이제 랩노쉬 데이터를 분석해줘.
이전 분석 결과는 output/한끼통살/ 폴더에 있어.

멀티에이전트 오케스트레이션

다음 순서로 진행해줘:
1. cafe24-analyst로 3월 데이터 분석
2. 분석 결과를 brand-reporter에게 전달해서 보고서 생성
3. 생성된 보고서를 code-reviewer로 마크다운 품질 검토

다음 3가지를 동시에 조사해줘 (각각 서브에이전트 사용):
- API 문서에서 rate limit 정책 확인
- 기존 코드에서 에러 핸들링 패턴 분석
- 테스트 커버리지 현황 파악

에이전트 팀으로 다음 3개 기능을 동시에 개발해줘.
각 팀원은 별도 worktree에서 작업하고, 완료 후 PR을 생성해줘.

- 팀원 A: /features/auth 모듈 리팩토링
- 팀원 B: /features/dashboard 신규 위젯 추가
- 팀원 C: /features/export CSV 내보내기 기능

이그니스 실전 통합 시나리오

지금까지 배운 개념을 하나의 시나리오로 통합합니다.

시나리오: 월간 브랜드 성과 보고 자동화

매월 1일, 8개 브랜드의 전월 성과를 자동으로 분석하고 보고서를 생성하는 파이프라인입니다.

[GitHub Actions - 매월 1일 09:00 KST 실행]
  |
  |-- 1단계: cafe24-analyst (서브에이전트)
  |     +-- 카페24 데이터 다운로드 및 1차 분석
  |     +-- 브랜드별 summary.json 생성
  |
  |-- 2단계: brand-reporter (서브에이전트)
  |     +-- summary.json 기반 브랜드별 보고서 생성
  |     +-- 전월 대비 변동 분석
  |
  +-- 3단계: 메인 에이전트
        +-- 8개 브랜드 보고서 통합
        +-- 경영진용 요약본 (1페이지) 생성
        +-- GitHub PR로 결과물 공유

name: Monthly Brand Report
on:
  schedule:
    - cron: '0 0 1 * *'  # 매월 1일 09:00 KST (UTC 00:00)

jobs:
  generate-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate Monthly Report
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "월간 브랜드 성과 보고서를 생성해줘.

          1단계: data/ 폴더의 카페24 데이터를 cafe24-analyst로 분석
          2단계: 분석 결과를 brand-reporter로 전달해 보고서 생성
          3단계: 8개 브랜드 통합 요약 생성
          4단계: reports/ 폴더에 저장

          각 단계 완료 시 체크포인트 커밋."

정리: 단계별 도입 가이드

1~2단계는 오늘 당장 시작할 수 있습니다. 기본편에서 기초를 익힌 뒤, 이 장의 패턴을 하나씩 적용해보세요.

참고 자료