AI 에이전트(Agent)에게 복잡하고 긴 작업을 맡겼을 때, 도중에 오류가 나거나 맥락(Context)을 잃어버려 처음부터 다시 실행되는 경험을 해보신 적이 있으신가요? 이러한 미완료 실행(Unfinished Runs)은 시간 소비뿐만 아니라 불필요한 API 토큰 비용을 크게 증가시키는 주원인입니다.
Claude Code 및 Claude Opus 5.5 모델 환경에서 긴 워크플로를 중단 없이 안정적으로 끝까지 완수할 수 있도록 돕는 7단계 하네스 엔지니어링(Harness Engineering) 아키텍처를 소개합니다.
하네스 엔지니어링(Harness Engineering)이란?
하네스(Harness)는 AI 모델 주위에서 지침(Instructions), 도구(Tools), 권한(Permissions), 상태(State), 검증(Checks)을 총괄 조정해 주는 실행 프레임워크입니다.
작업을 시작하기 전, 결과물이 저장될 위치와 검증 기준을 프레임워크에 미리 정의함으로써 모델이 길을 잃지 않도록 통제합니다.
장기 작업 성공을 위한 7가지 핵심 레이어
Layer 1. 지속되는 작업 지침 설정 (CLAUDE.md)
작업 전체에 걸쳐 항상 유지되어야 하는 공통 규칙(출력 경로, 출처 요구사항, 글쓰기 컨벤션 등)을 워크스페이스 최상위 CLAUDE.md 파일에 정의합니다.
- 핵심 가이드: 일회성 마감일이나 변동 가능성이 있는 질문은 제외하고, 작업 전반에 적용되는 사실과 규칙만 포함합니다.
- 파일 예시 (
CLAUDE.md):
Project instructions:
- Use sources/ for reference material and drafts/ for working files.
- Keep approved files in published/.
- Record the source URL and the date it was checked.
- Save confirmed decisions and next actions in progress.md.Layer 2. 재사용 가능한 스킬(Skill) 정의
반복되는 작업 프로세스(읽기 ➔ 초안 작성 ➔ 검증 ➔ 결과 저장)를 스킬 단위로 모듈화합니다.
- 핵심 가이드:
.claude/skills/write-draft/SKILL.md경로에 구체적인 단계별 프로세스를 작성합니다. - 파일 예시:
---
name: write-draft
description: Draft an article from sources and verify its claims.
---
Requested topic: $ARGUMENTS
1. Read relevant files in sources/ and open primary links.
2. Write an outline and save to drafts/article.md.
3. Ask evidence-reviewer to check factual claims.
4. Save claim-checking table to drafts/checks.md.
5. Update progress.md with decisions and next action.Layer 3. 외부 소스 연결 (MCP, Model Context Protocol)
Notion, GitHub, 외부 데이터베이스 등 작업에 필요한 외부 자원을 안전하게 조회할 수 있도록 MCP 연동을 설정합니다.
- 실행 명령:
claude mcp add --transport http notion [https://mcp.notion.com/mcp](https://mcp.notion.com/mcp)- 핵심 가이드: 에이전트에 정확한 문서 링크와 추출할 영역을 명시하여 불필요한 전체 조회를 방지합니다.
Layer 4. 실행 레이어 권한 제어 (Permissions)
에이전트가 건드려서는 안 되는 중요한 데이터나 승인되지 않은 경로를 수정하지 못하도록 샌드박스 및 권한 규칙을 부여합니다.
- 설정 예시 (
.claude/settings.json):
{
"permissions": {
"deny": [
"Read(.env)",
"Read(.env.*)",
"Edit(published/**)"
]
}
}Layer 5. 증거 기반 검토자 에이전트 (Evidence Reviewer)
작성 에이전트와 검증 에이전트의 역할을 분리합니다. 서브에이전트(Subagent)를 두어 사실관계를 객관적으로 검증하도록 구성합니다.
- 설정 예시 (
.claude/agents/evidence-reviewer.md):
---
name: evidence-reviewer
description: Verify factual claims in drafts using primary sources.
tools: Read, Grep, Glob, WebSearch, WebFetch
effort: high
---
Read the draft and source material.
Return a table: claim, verdict (verified / incorrect / unresolved), source URL, required correction.Layer 6. 추론 노력(Reasoning Effort) 할당
주 작업과 검증 작업의 난이도에 맞게 AI 모델의 추론 수준을 지정합니다.
- 실행 명령:
claude --model claude-opus-5-5 --effort medium- 핵심 가이드: 모호한 주장을 검증해야 하는 서브에이전트에게는
effort: high를 부여하여 정확도를 높입니다.
Layer 7. 목표 및 완료 조건 정의 (/goal)
작업 완료를 입증할 저장 파일과 검증 조건을 명확히 전달합니다.
- 실행 예시:
/goal Use write-draft to prepare an article from sources/. Completion requires drafts/article.md and drafts/checks.md to exist, incorrect claims to be corrected, and output paths to appear. Stop after 12 turns if condition remains unmet.핵심 요약: 세션 간 연속성 유지 (progress.md)
장기 작업을 안전하게 수행하는 핵심은 “체크포인트”입니다. 한 세션이 끝나거나 중간에 중단되더라도 progress.md에 상태를 기록해 두면 다음 세션에서 곧바로 작업을 이어받을 수 있습니다.
# progress.md 구조 예시
Task: [현재 주제]
Outputs: [초안 및 검증 파일 경로]
Completed: [완료된 단계]
Decisions: [확정된 결정 사항]
Open issues: [미해결 검증 항목]
Next action: [다음에 수행할 구체적 행동 1가지]체크포인트 중심의 하네스 구조를 도입하여 에이전트의 예산 낭비를 막고 장기 프로젝트 완수율을 극대화해 보세요!
댓글 남기기