하네스 엔지니어링 입문 — Claude Code를 내 방식대로 길들이기

이 글은 Claude Code 실전 활용기 후속편입니다.

하네스 엔지니어링이란?

하네스 엔지니어링(Harness Engineering)은 AI 코딩 에이전트의 동작을 설정 파일, 규칙, 훅, 커스텀 에이전트 등으로 체계적으로 제어하는 기법이다.

단순히 프롬프트를 잘 쓰는 것(프롬프트 엔지니어링)을 넘어서, AI가 일관되게 원하는 방식으로 동작하도록 환경 자체를 설계하는 접근이다.

프롬프트 엔지니어링 vs 하네스 엔지니어링

항목	프롬프트 엔지니어링	하네스 엔지니어링
적용 범위	단일 대화	모든 세션에 영구 적용
방식	매번 지시사항 입력	설정 파일로 사전 정의
일관성	매번 달라질 수 있음	항상 동일한 규칙 적용
자동화	수동	훅으로 자동 실행 가능
확장성	제한적	에이전트, 스킬로 무한 확장

비유하자면, 프롬프트 엔지니어링이 매번 구두로 지시하는 것이라면, 하네스 엔지니어링은 업무 매뉴얼을 만들어두는 것이다.

하네스의 구성 요소

Claude Code의 하네스는 크게 5가지 계층으로 구성된다.

┌─────────────────────────────┐
│         Skills              │  ← 재사용 가능한 작업 템플릿
├─────────────────────────────┤
│         Agents              │  ← 특화된 서브 에이전트
├─────────────────────────────┤
│         Hooks               │  ← 자동 실행 트리거
├─────────────────────────────┤
│      Settings / Rules       │  ← 전역 설정과 규칙
├─────────────────────────────┤
│        CLAUDE.md            │  ← 프로젝트별 컨텍스트
└─────────────────────────────┘

아래에서 하나씩 살펴보자.

1. CLAUDE.md — 프로젝트의 두뇌

CLAUDE.md는 프로젝트 루트에 두는 파일로, Claude Code가 매 세션 시작 시 자동으로 읽는다. 프로젝트의 컨텍스트, 컨벤션, 빌드 방법 등을 담는다.

  
# CLAUDE.md

## 프로젝트 개요
Next.js 14 + TypeScript + Prisma + PostgreSQL 기반 Todo 앱

## 기술 스택
- Frontend: React 18, TailwindCSS
- Backend: Next.js API Routes
- DB: PostgreSQL + Prisma ORM
- 패키지 매니저: pnpm

## 코딩 컨벤션
- 함수형 컴포넌트만 사용
- TypeScript strict 모드
- 변수명: camelCase
- 컴포넌트명: PascalCase

## 주요 명령어
- `pnpm dev` : 개발 서버
- `pnpm build` : 프로덕션 빌드
- `pnpm test` : 테스트 실행
- `pnpm db:migrate` : DB 마이그레이션

## 디렉토리 구조
- `src/app/` : 페이지 및 라우트
- `src/components/` : 공통 컴포넌트
- `src/lib/` : 유틸리티, DB 클라이언트
- `prisma/` : 스키마 및 마이그레이션

CLAUDE.md가 중요한 이유

매번 “이 프로젝트는 Next.js고, pnpm을 쓰고…“라고 설명할 필요가 없다. 파일 하나로 Claude Code가 프로젝트를 즉시 이해한다.

적용 범위

위치	적용 범위
프로젝트 루트 `CLAUDE.md`	해당 프로젝트에서만
`~/.claude/CLAUDE.md`	모든 프로젝트에 전역 적용

2. Settings & Rules — 행동 규칙 정의

~/.claude/settings.json으로 Claude Code의 전역 설정을 관리하고, ~/.claude/rules/ 디렉토리에 주제별 규칙 파일을 둔다.

settings.json 예시

  
{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(pnpm build)",
      "Bash(pnpm test)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "pnpm prettier --write \"$FILE_PATH\""
      }
    ]
  }
}

Rules 디렉토리 구조

~/.claude/rules/
├── common/           # 언어 무관 공통 규칙
│   ├── coding-style.md
│   ├── testing.md
│   ├── security.md
│   └── git-workflow.md
├── typescript/       # TypeScript 전용
├── python/           # Python 전용
└── web/              # 웹 프론트엔드 전용

규칙 파일 예시 — security.md:

  
# 보안 규칙

커밋 전 반드시 확인:
- [ ] 하드코딩된 시크릿 없음 (API 키, 비밀번호, 토큰)
- [ ] 모든 사용자 입력 검증됨
- [ ] SQL 인젝션 방지 (파라미터화된 쿼리)
- [ ] XSS 방지 (HTML 이스케이프)

이렇게 규칙을 정의해두면, Claude Code가 모든 세션에서 일관된 코딩 표준을 따른다.

3. Hooks — 자동 실행 트리거

Hooks는 Claude Code의 특정 이벤트에 자동으로 쉘 명령을 실행하는 기능이다.

Hook 타입

타입	실행 시점	활용 예시
`PreToolUse`	도구 실행 전	파일 크기 제한, 위험한 명령 차단
`PostToolUse`	도구 실행 후	자동 포맷팅, 린트 검사
`Stop`	세션 종료 시	최종 빌드 검증

실전 예시: 자동 포맷팅 + 린트

  
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "pnpm prettier --write \"$FILE_PATH\"",
        "description": "파일 수정 후 자동 포맷팅"
      },
      {
        "matcher": "Write|Edit",
        "command": "pnpm eslint --fix \"$FILE_PATH\"",
        "description": "파일 수정 후 린트 자동 수정"
      }
    ],
    "Stop": [
      {
        "command": "pnpm build",
        "description": "세션 종료 시 빌드 검증"
      }
    ]
  }
}

이렇게 설정하면 Claude Code가 파일을 수정할 때마다 자동으로 포맷팅과 린트가 실행된다. 코드 품질이 매번 보장된다.

800줄 이상 파일 작성 차단

  
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const c=i.tool_input?.content||'';const lines=c.split('\\n').length;if(lines>800){console.error('BLOCKED: '+lines+' lines');process.exit(2)}})\"",
        "description": "800줄 초과 파일 작성 차단"
      }
    ]
  }
}

파일이 비대해지는 것을 구조적으로 방지할 수 있다.

4. Agents — 전문 서브 에이전트

Agents는 특정 역할에 특화된 서브 에이전트다. Claude Code가 복잡한 작업을 처리할 때, 해당 분야의 전문가를 불러오는 것과 같다.

주요 에이전트

에이전트	역할	사용 시점
`planner`	구현 계획 수립	복잡한 기능 개발 전
`code-reviewer`	코드 리뷰	코드 작성 후
`security-reviewer`	보안 취약점 분석	커밋 전
`tdd-guide`	테스트 주도 개발	새 기능, 버그 수정
`build-error-resolver`	빌드 에러 해결	빌드 실패 시
`architect`	시스템 설계	아키텍처 결정 시

에이전트 정의 예시

~/.claude/agents/ 디렉토리에 마크다운 파일로 정의한다:

  
---
name: code-reviewer
description: 코드 품질, 보안, 성능을 리뷰하는 에이전트
tools: [Read, Grep, Glob, Bash]
---

## 리뷰 체크리스트
- 함수 50줄 이하
- 파일 800줄 이하
- 에러 처리 누락 없음
- 하드코딩된 시크릿 없음
- 테스트 커버리지 80% 이상

병렬 에이전트 실행

독립적인 작업은 에이전트를 병렬로 실행해서 속도를 높일 수 있다.

동시에 3개 에이전트 실행:
├── Agent 1: 인증 모듈 보안 분석
├── Agent 2: 캐시 시스템 성능 리뷰
└── Agent 3: 유틸리티 타입 체크

5. Skills — 재사용 가능한 워크플로우

Skills는 자주 반복하는 작업을 슬래시 명령어로 즉시 실행할 수 있게 만든 템플릿이다.

스킬 예시

명령어	동작
`/commit`	변경사항 분석 후 커밋 메시지 생성 및 커밋
`/code-review`	현재 변경사항 코드 리뷰
`/plan`	구현 계획 수립
`/verify`	빌드, 테스트, 린트 검증 루프
`/tdd`	TDD 워크플로우 실행

커스텀 스킬 만들기

~/.claude/skills/ 디렉토리에 마크다운 파일로 정의한다:

  
---
name: deploy-check
description: 배포 전 최종 점검
user_invocable: true
---

1. pnpm build 실행하여 빌드 확인
2. pnpm test 실행하여 테스트 통과 확인
3. git status로 커밋되지 않은 변경사항 확인
4. 결과 요약 보고

이후 /deploy-check로 언제든 실행할 수 있다.

Everything Claude Code (ECC)

Everything Claude Code는 Anthropic 커뮤니티에서 관리하는 하네스 엔지니어링 오픈소스 프로젝트다. 위에서 설명한 rules, hooks, agents, skills를 체계적으로 정리한 종합 패키지다.

ECC가 제공하는 것

ECC/
├── rules/            # 언어별 코딩 규칙
│   ├── common/       # 공통 (보안, 테스트, 코딩 스타일)
│   ├── typescript/
│   ├── python/
│   ├── golang/
│   └── web/
├── agents/           # 전문 서브 에이전트
├── skills/           # 슬래시 명령어 스킬
└── install.sh        # 원클릭 설치 스크립트

설치

# 공통 + 원하는 언어 규칙 설치
./install.sh typescript
./install.sh python

# 복수 언어 동시 설치
./install.sh typescript python web

ECC를 쓰면 뭐가 달라지나?

Before (기본 Claude Code)	After (ECC 적용)
매번 코딩 규칙 설명	자동으로 규칙 준수
포맷팅 직접 실행	파일 수정 시 자동 포맷
보안 체크 누락 가능	커밋 전 자동 보안 검사
코드 리뷰 수동 요청	코드 작성 후 자동 리뷰
빌드 실패 후 수동 디버깅	전문 에이전트가 자동 분석

시작하기: 최소 하네스 구성

처음부터 모든 걸 설정할 필요는 없다. 아래 3단계만으로도 충분한 효과를 볼 수 있다.

Step 1: CLAUDE.md 작성

프로젝트 루트에 프로젝트 개요, 기술 스택, 주요 명령어를 적는다.

Step 2: 자동 포맷팅 Hook 설정

~/.claude/settings.json에 PostToolUse 훅을 추가한다.

Step 3: 규칙 파일 추가

~/.claude/rules/ 에 가장 중요한 규칙(보안, 코딩 스타일)부터 하나씩 추가한다.

이 정도만 해도 Claude Code의 일관성과 코드 품질이 눈에 띄게 올라간다.

마무리

하네스 엔지니어링은 AI 코딩 도구를 진짜 팀원처럼 만드는 방법이다. 한번 설정해두면 모든 세션에서 효과가 지속된다.

다음 포스팅에서는 실제로 나만의 Claude Code 하네스를 처음부터 구축하는 과정을 단계별로 다뤄볼 예정이다.

시리즈 목차

Claude Code 실전 활용기 ✅
하네스 엔지니어링 입문 ✅ (현재 글)
나만의 Claude Code 하네스 구축하기 (예정)
ECC 프로젝트 분석 (예정)