Opus 5.5를 사용하여 긴 작업을 끝까지 완료하도록 만드는 '하네스 설정(Harness Setting)'에 대한 글을 모아봤습니다.
※필수 배경지식도 설명되어 있으니 읽어보시길 바랍니다.
필수 배경지식
-
Claude Code:
Anthropic사의 AI 에이전트입니다. 터미널에서 작동하며 파일의 읽기/쓰기나 명령어 실행 등을 스스로 수행합니다.
사용하는 대부분의 사용자들은 Claude를 사용하지만, 실제로 활용해야 하는 것은 Claude Code입니다.
-
Opus 5.5:
Claude의 상위 모델입니다.
-
하네스(Harness):
AI 모델을 둘러싸는 전체적인 구조를 의미합니다. 지시사항, 도구(Tool), 권한, 작업 상태, 검증 절차 등을 한데 모아 관리하는 시스템입니다. 본래 의미는 '마구(馬具)'입니다.
-
컨텍스트(Context):
AI가 한 번에 파악할 수 있는 작업 메모리 공간입니다.
대화가 길어지면 요약(Compression)되면서 세부 정보가 누락될 수 있습니다.
-
서브 에이전트(Sub Agent):
메인 AI가 업무를 위임하는 별도의 AI입니다.
자신만의 컨텍스트를 가집니다.
-
MCP:
Notion과 같은 서비스와 AI를 연결하는 공통 규격입니다.
이 글의 핵심 의미
긴 작업이 도중에 무너지는 원인은 모델 자체의 지능만 부족해서가 아닙니다.
부족한 것은 '무엇이 남아있어야 완료인지', '누가 어떻게 검증할지', '내일 어디서부터 계속할지'를 작업 전에 시스템적으로 결정해 두는 것입니다.
커버 이미지가 이를 한 장에 표현하고 있습니다.
왼쪽의 '입력'(자료, 지시서, 1차 정보, 합격 기준)을 제공합니다.
아래 흐름에 따라 7개의 레이어를 거칩니다.
마지막에는 오른쪽의 '검증', '상태', '산출물' 세 가지가 반드시 남게 됩니다.
이러한 시스템을 한 번 구축해 두면, 다음부터는 주제와 합격 기준만 바꿔주면 같은 절차를 재사용할 수 있습니다.
이것이 바로 '재활용 가능하다(Reusable)'라는 의미입니다.
준비
작업 폴더에 다음 세 개의 폴더를 만듭니다.
- sources/: 참고 자료
- drafts/: 초안
- published/: 승인된 파일
글에서는 글쓰기를 예시로 들고 있지만, 이 사고방식은 다른 작업에도 적용할 수 있습니다.
제1층: CLAUDE.md에는 '매번 사용하는 사실'만 기록하기
작업 폴더 바로 아래에 CLAUDE.md를 만들고 다음 내용을 붙여넣습니다. Claude Code는 시작 시 이 파일을 자동으로 읽어들입니다. ※원문은 영어이지만, 한국어로 작성해도 작동합니다.
프로젝트 지시사항
참고 자료는 sources/를 사용하고, 작업 중인 파일은 drafts/를 사용한다.
승인된 파일은 published/에 둔다.
한국어로 작성하며, 한 단락은 1~2문장으로 한다.
기술적 주장은 공식의 1차 정보를 사용한다.
출처 URL과 확인한 날짜를 기록한다.
취득한 자료는 주어진 작업의 근거로만 사용한다.
확정된 결정 사항과 다음 액션은 progress.md에 저장한다.
작업이 끝나면, 출력 파일 경로와 검증 결과를 보고한다.
마감일 같은 일시적인 정보는 여기에 적지 않고 작업 자체에 기록합니다.
무엇이 아직 유효한 정보인지 AI가 다음 실행 시 구분하기 쉬워집니다.
@경로 를 사용하여 다른 파일을 읽어오는 방법도 있지만, 읽어온 내용 역시 시작 시 모두 읽힙니다.
이는 정리 목적으로 감수하고, 가끔만 사용하는 절차는 제2층의 스킬에 두는 것이 좋습니다.
내용은 /memory 에서 확인할 수 있습니다.
제2층: 반복하는 절차를 '스킬'로 저장하기
.claude/skills/write-draft/SKILL.md를 만들고 다음 내용을 붙여넣습니다. --- 로 둘러싸인 부분은 설정란이므로, 항목명은 영어 그대로 유지합니다.
name: write-draft
description: 자료에서 기사 초안을 만들고 사실관계를 검증한다.
요청된 주제: $ARGUMENTS
- sources/의 관련 파일을 읽어 1차 정보 링크를 연다.
- 구성안을 만들고, 초안을 drafts/article.md에 저장한다.
- evidence-reviewer에게 사실 주장을 자료와 대조시킨다.
- 오류를 수정하고, 미해결 주장에는 표시를 한다.
- 대조 결과표를 drafts/checks.md에 저장한다.
- progress.md에 결정 사항, 미해결 과제, 다음 액션을 작성한다.
- 두 개의 출력 경로와 검증 결과를 보고한다.
사용할 때는 '/write-draft 생성형 AI의 최신 동향'처럼 입력합니다.
뒤에 적은 글자가 $ARGUMENTS에 들어가기 때문에, 주제가 바뀌어도 같은 절차로 동일한 출력을 얻을 수 있습니다.
핵심은 각 단계에 '눈에 보이는 결과'를 남기는 것이다.
단순히 '정확성을 확인한다'고만 적는다면, 누가 무엇을 어떻게 확인할지 결정되지 않는다.
확인 담당자, 출처 조건, 보고 형식까지 명시해야 한다.
공개 승인은 초안 작성과 분리하여 관리해야 한다.
이 스킬은 검토용 파일을 준비하는 단계에서 멈추고, 실제 공개를 위해서는 별도의 작업과 허가가 필요하다.
제3층: MCP로 외부 자료에 접근하기
자료가 Notion에 있는 경우, 터미널에서 다음을 실행한다.
이어서 Claude Code를 열고, /mcp로 인증 및 연결 상태를 확인한다.
긴 작업에 사용하기 전에, 내용이 확실한 페이지 하나를 가져와서 제대로 읽을 수 있는지 시험해 본다.
가져오기에 실패했을 때는 페이지 ID와 실패 이유를 기록한다.
같은 작업을 반복하기 전에는 반드시 인증이나 접근 권한을 확인해야 한다.
외부 서비스의 내용을 수정하는 작업에는 권한을 설정하고, 사용하지 않는 서버는 /mcp에서 비활성화해 둔다.
제4층: 실행 단계에서 허용할 범위를 제한하기
.claude/settings.json에 다음 내용을 추가한다. 이미 설정이 있는 경우, 그 안에 통합시킨다.
{
"permissions": {
"deny": [
"Read(.env)",
"Read(.env.*)",
"Edit(published/**)"
]
}
}
이 설정을 통해 비밀번호 등이 들어가는 .env 파일의 읽기 및 published/ 내부 파일의 편집을 금지할 수 있다.
테스트 방법: published/에 더미 파일을 만들고 Claude에게 편집을 요청해 본다.
거부된다면 설정이 작동하고 있다는 의미이다.
실제로 적용된 규칙은 /permissions에서 확인할 수 있다.
단, 이 제한은 Claude Code의 파일 조작 도구에만 유효하다.
Python이나 Node 스크립트를 통과시키면 파일에 접근할 수 있으므로, 이를 막으려면 OS의 샌드박스(sandbox) 기능이 필요하다.
인수나 작업 상태에 따라 판단을 변경하고 싶을 때는, 도구 실행 직전에 작동하는 'PreToolUse 훅'을 사용한다. 외부로 쓰기가 타임아웃된 경우, 사실은 쓰기가 완료되었을 가능성이 있으므로, 다시 시도하기 전에 쓰기 대상을 확인해야 한다.
제5층: 검증 담당자에게 '근거'를 제시하게 하기
.claude/agents/evidence-reviewer.md 파일을 만들고 다음 내용을 붙여넣는다.
전달받은 초안과 자료를 읽는다.
사실 주장을 실제로 열어본 일차 정보와 대조한다.
'주장・판정・출처 URL・필요한 수정'의 표로 반환한다.
판정은 verified(확인됨), incorrect(오류), unresolved(미해결) 세 가지를 사용한다.
미해결 주장에는 어떤 근거가 부족한지 명시한다.
이 검증 담당자는 읽기 및 검색 도구만 가지고 있다. 초안을 수정하는 것은 메인 AI의 역할이다.
등록되었는지 여부는 /agents에서 확인한다.
여기서 중요한 점은, AI가 대화로 '확인했습니다'라고 보고한 내용을 믿지 않는 것이다.
실제로 저장된 파일을 열어 주장과 출처의 대응을 자신의 눈으로 직접 확인해야 한다.
제6층: 작업별 추론 깊이(effort) 할당하기
작업 폴더에서 다음 명령어를 실행한다.
claude --model claude-opus-5-5 --effort medium
시작 후, 화면 상단에 Opus 5.5와 지정한 effort가 표시되면 성공이다.
기사에 실린 공식 문서 목록에 따르면, 각 레벨의 사용처는 다음과 같다.
-
low:
아이디어 구상이나 이름 변경 등, 한 번씩 결과를 보는 가벼운 작업에 적합하다.
-
medium:
Opus 5.5의 기본값이다. 범위가 명확한 일상적인 개발 작업에 적합하다.
-
high:
기존 코드의 버그 수정처럼, 검증이 중요하고 예상치 못한 케이스가 발생하기 쉬운 작업에 적합하다.
-
xhigh:
토큰을 많이 사용하더라도 더 깊게 생각하게 만들고 싶을 때 사용한다.
-
max:
보안 취약점 찾기 같은 어려운 문제에 적합합니다.
너무 많이 생각하면 효과가 정체되기 쉬우므로, 광범위하게 사용하기 전에 시도해 보는 것이 좋습니다.
-
ultracode:
레벨이 아니라 Claude Code 자체의 설정에서 작업별 동적인 워크플로우를 구성합니다.
이 글에서는 메인 작업을 medium으로, 검증 담당을 high로 설정했습니다.
프롬프트에 '깊이 생각하라'고 적어도 설정된 effort는 변하지 않습니다.
실제 운영 전에,
/context (로드된 지시사항),
/agents (검증 담당자),
/permissions (권한)를 확인하고 부족한 부분을 수정해 둡니다.
제7층: /goal로 완료 조건을 결정하기
sources/에 자료를 넣은 후, Claude Code에 다음 내용을 붙여넣습니다.
/goal write-draft 를 사용하여 sources/에서 기사를 준비합니다. 완료 조건은 drafts/article.md와 drafts/checks.md가 존재하고, 잘못된 주장이 수정되었으며, 미해결 주장에 명확한 표시가 되어 있고, 출력 경로와 검증 결과가 대화에 표시되는 것입니다.
12턴이 지나도 조건을 충족하지 못하면 멈추고, 방해가 되는 원인을 보고합니다.
/goal은 대화에 표시된 증거를 바탕으로 턴마다 완료 여부를 판정합니다.
따라서 AI가 결과를 대화로 출력하는 것이 전제되어야 합니다.
'12턴' 부분은 AI가 판단하는 것이므로 엄격한 상한선이 아닙니다.
시간이나 비용을 정확하게 제한하고 싶다면, 실행 메커니즘 측에서 구속해야 합니다.
목표를 취소하려면 /goal clear를 사용합니다.
/rewind를 사용하면 Claude Code가 기록한 파일 편집은 되돌릴 수 있습니다.
다만, 쉘(shell)에서 진행된 변경이나 서브 에이전트에 의한 많은 편집은 돌아가지 않습니다.
오랫동안 보존해야 할 이력은 Git으로 관리하는 것이 확실합니다.
전체 과정을 한 번에 실행하기
sources/task.md에 작업 지시서를 작성합니다.
테마: [구체적인 테마]
독자: [누구를 위한 설명인지]
산출물: 실용적인 절차와 공식 출처를 포함한 기사
합격 기준: 필요한 항목을 모두 다루고 있다. 사실이 검증되었다.
미해결 주장에 표시가 되어 있다.
초안과 검증표가 저장되어 있다.
제약: [글자 수, 문체, 다루지 않을 주제]
제6층의 명령어로 시작하고, 제7층의 /goal을 실행합니다. drafts/article.md, drafts/checks.md, progress.md 세 가지가 생성되면 성공입니다.
스킬이 나타나지 않으면 파일 위치와 --- 설정 부분을 재검토합니다.
검증 담당자가 나타나지 않으면 name과 description을 검토한 후 /agents를 확인합니다.
다음 날, 이어서 재개할 수 있도록 하기
적절히 끊어지는 지점에서 progress.md를 다음 형식으로 업데이트합니다.
태스크: [현재 테마]
산출물: [초안과 검증표의 경로]
완료: [끝난 단계와 체크]
결정 사항: [확정된 선택과 그 근거]
미해결: [부족한 근거나 장애]
다음 액션: [다음에 할 구체적인 한 수]
새로운 세션을 열면 다음 내용을 붙여넣습니다.
progress.md를 읽고 기록된 초안과 검증표를 확인합니다.
기록된 다음 액션부터 이어서 진행하고, 진척 메모를 업데이트합니다.
AI가 처음부터 다시 시작하는 경우, 메모에 빠뜨린 결정 사항이나 파일 경로를 추가합니다.
작업 폴더 직하단의 CLAUDE.md는 대화 요약 후에도 다시 읽힙니다.
효과는 자신의 환경에서 측정하기
사용량은 /usage로, 컨텍스트 내용은 /context로 확인할 수 있습니다.
검증 담당자의 분이나 재시도한 노력도 합산합니다.
AI의 출력을 확인하는 시간과 직접 수정한 양도 기록합니다.
크게 수정할 필요가 있었던 출력은 그 실행 전체의 가치를 떨어뜨리기 때문입니다.
설정을 바꿀 때는, 태스크와 합격 기준을 동일하게 유지한 채 한 곳만 바꿔 비교해 봅니다.
Anthropic 초기 테스터 보고서에서 읽어낼 수 있는 '토큰 60% 절감'은 그 실험에서의 숫자일 뿐입니다.
자신이 얼마나 절약할 수 있는지는 스스로 측정하고 확인해야 합니다.
요약
Harness란, AI에게 '산출물', '검증의 증거', '재개용 기록'을 반드시 남기게 하는 시스템입니다.
설정하는 파일은 CLAUDE.md, 스킬, settings.json, 검증 담당자 4가지에 필요에 따라 외부 연결(MCP)만 추가하면 됩니다.
한 번 작동시키면, 주제와 자료를 바꾸어 같은 스킬을 재활용합니다.
만약 동일한 수정 사항이 반복적으로 나온다면, 이는 절차상의 누락이므로 스킬에 한 줄을 추가합니다.
이를 반복하며 발전시켜 나가는 것이 본 글에서 권장하는 진행 방식입니다.
#ClaudeCode #Opus55 #AI에이전트 #하네스엔지니어링 #생성AI #업무효율화 #AI활용
끝나지 않은 Opus 5.5 실행이 예산을 소모하게 두지 마세요.
다음 장기 작업을 시작하기 전에 하네스를 설정하세요.
진행 상황을 저장하고, 결과를 검증하며, 워크플로우를 재사용하세요.
전체 7계층 설정은 아래를 참고하세요 ↓ https://t.co/rz78goHxfw
