안녕하세요, miruky입니다.
지난 3월에 '하네스 엔지니어링(Harness Engineering)'이 무엇인지에 대한 글을 작성했습니다.
다만 그때는 주로 용어와 개념 소개가 중심이었기 때문에, 실제로 자신의 리포지토리에 무엇을 배치해야 하는지에 대한 실물 예시는 다루지 못했습니다. 이번에는 예시 리포지토리 하나를 만들고, Claude Code와 Codex를 실제로 구동하면서 하네스에 포함할 내용과 그 육성 방법을 정리해 보겠습니다.
- AI 구동 개발은 현재 어디까지 왔을까?
- 하네스 엔지니어링란 무엇인가?
- 예시 리포지토리를 만들었습니다
- 작동하기 전에 전달해야 할 것들
- 작동한 후에는 기계에 검증받습니다
- 막아야 할 세 가지 계층의 실수
- 길고 넓게 구동할 때
- 측정 가능하도록 준비합니다
- 하네스를 육성합시다
- 구조화된 하네스 위에서 개발은 이렇게 진행됩니다
- 시작한다면, 이 것 하나부터
2025년 2월, 안드레이 칼파시(Andrey Karpaczy)가 'vibe coding'이라는 용어를 게시했습니다. 차이점 확인 없이 받아들이고, 오류가 발생하면 그대로 붙여넣어 수정하는 방식이며, 본인은 주말에 사용하는 일회성 프로젝트용이라고 설명했습니다.
1년 정도가 지난 후, 아디 오스마니(Adi Osmanhi)와 사이먼 윌리슨(Simon Wilson)은 업무상 책임을 지고 에이전트(Agent)를 사용하는 개발을 'agentic engineering'이라 부르며, vibe coding과는 구별되는 글들을 계속해서 발표했습니다.
한국어에서 AI 구동 개발이라는 용어는 폭넓게 사용되지만, 이 글에서는 에이전트에게 구현을 맡기고 사람은 요청과 확인을 담당하는 개발 방식을 의미합니다.
코딩 에이전트는 모델(Model)을 반복적으로 호출하는 프로그램으로 작동합니다. Claude Code의 문서에 따르면 이러한 반복 과정은 '컨텍스트 수집', '행동', '결과 확인' 세 가지로 설명됩니다.
회의실 예약 CLI에 booking list --date를 추가하라는 요청이 있다고 가정해 봅시다. 에이전트는 코드와 테스트를 열고, 수정하여 테스트를 구동합니다. 한 항목에서 실패하면, 실패한 테스트를 열어 수정하고 다시 구동하는 과정까지가 2회차입니다.
모델 자체가 하는 일은 단순히 글자를 받아 글자를 반환하는 것뿐입니다. 파일을 여는 행위, 명령을 실행하는 것, 어디서 끝낼지 결정하는 등의 부분은 모두 모델 외부(outside the model)에 존재합니다.
아무것도 준비되지 않은 리포지토리에서 현재의 모델을 그대로 구동하면 어떻게 될까요? 예시 리포지토리에 기능을 추가하라는 요청 몇 가지를 준비하여, Claude Opus 5.5 (이하 Opus)에게 반복적으로 해결하게 해보았습니다. 총 15번입니다.
기능은 매번 올바르게 작동했습니다. 채점 항목을 모두 충족하지 못한 경우는 2번이었고, 두 경우 모두 한국어 요청에 영어로 완료 보고를 한 경우였습니다.
비교를 위해, 작은 모델인 Claude Haiku 5.5 (이하 Haiku)에게도 같은 요청을 해결하게 했습니다. 이 모델은 모든 항목을 충족한 것이 6번이었으며, 정제 과정을 거치지 않고 완료 보고를 하거나, 요청과 관련 없는 .env 파일을 연 경우도 있었습니다.
실패했던 항목들은 보고 언어, 끝내기 전에 실행해야 하는 것들, 열어서는 안 되는 파일 등 모두 코드만으로는 결정할 수 있는 것이 아니었습니다. 이 리포지토리만의 규칙은 모델이 똑똑해져도 누군가가 알려주어야 합니다.
1장에서 언급된 '모델 외부에 존재하는 것'을 하네스(Harness)라고 부릅니다. 원래는 마구(馬具)를 뜻하는 말로, 힘 있는 것을 사람이 원하는 방향으로 작동하게 만드는 장치를 의미합니다 (강아지 산책 시 착용하는 것도 하네스가 맞습니다).
가장 넓은 정의는 LangChain의 블로그에 있습니다.
"If you're not the model, you're the harness."
(모델이 아니라면, 모두 하네스이다)
다만 그 범위는 사용하는 사람에 따라 다릅니다. Claude Code나 Codex라는 제품 자체를 지칭하는 사람도 있고, 자신의 리포지토리에 추가할 부분만을 지칭하는 사람도 있습니다.
루프(Loop)나 도구(Tool), 컨텍스트 압축은 제품 자체에 처음부터 내장되어 있습니다. 이 글에서 구조화하려는 것은 그 외부에 스스로 추가하는 부분입니다.
가장 먼저 등장한 것은 미첼 하시모토(Mitchell Hashimoto)의 'My AI Adoption Journey'였습니다. 에이전트가 실수할 때마다, 같은 실수를 두 번 다시 하지 않도록 개입하는 작업. 이 작업을 '하네스 엔지니어링'이라고 부릅니다.
그 6일 후에, OpenAI가 '하네스 엔지니어링'이라는 글을 공개했습니다. 소규모 팀이 사람의 손으로 코드를 작성하지 않고 약 100만 줄 분량의 제품을 만들었다는 기록입니다.
개인적으로 저는 이 2026년 2월이 상당한 변곡점이었다고 생각합니다. 하시모토의 글과 같은 날 Claude Opus 4.6이 등장했기 때문입니다. AI에게 일을 맡겨도 괜찮다고 느낀 첫 모델이었던 기억이 있습니다.
4월에는 빌기타 베켈러(Birgitta Becker)가 사용자 관점에서 본 하네스(Harness)의 개념을 정리했습니다. 누가 이 용어를 처음 사용했는지에 대해서는 자료마다 차이가 있어 단정하지 않겠습니다.
프롬프트 엔지니어링(Prompt Engineering)은 단일 요청문의 작성 방법을 다룹니다. 컨텍스트 엔지니어링(Context Engineering)에서는 모델에 전달되는 정보 전체가 대상이 됩니다. 여기에 검사, 권한, 실행 환경까지 포함한 명칭이 하네스 엔지니어링(Harness Engineering)입니다.
'XX 엔지니어링'이 너무 많다는 이야기는 이전 글에 정리했습니다.
하네스에 배치하는 요소들은 베켈러의 두 가지 축으로 나누어 보면 파악할 수 있습니다.
한 축은 언제 작동하는가입니다. 에이전트(Agent)가 움직이기 전에 전달하는 것을 가이드(Guide)라 하고, 움직인 후에 확인하는 것을 센서(Sensor)라고 부릅니다. 다른 한 축은 누가 판단하느냐에 따른 것으로, 린터(Linter)나 테스트처럼 동일한 입력에 동일한 결과를 반환하는 것이 계산적(Computational)이고, 모델이 문장으로 판단하는 것이 추론적(Inferential)입니다.
가이드만으로는 지켜졌는지 확인할 수 없고, 센서만으로는 에이전트가 같은 실패를 매번 반복합니다. 두 가지 모두를 배치하고, 센서에서 발견한 실패를 가이드로 되돌립니다.
터미널에서의 작업을 수행하게 하는 Terminal-Bench라는 벤치마크의 순위표를 동일한 Claude Opus 4.6으로 한정하여 비교했습니다. 가장 낮은 Claude Code와 가장 높은 Meta-Harness 사이에는 18포인트가 넘는 차이가 있었습니다.
하지만 하네스에는 비용이 듭니다. Martin Fowler의 사이트에 실린 Nareish Jain의 "Are Harnesses Worth the Cost?"에 따르면, 상위 모델들은 하네스가 없어도 매번 성공했지만, 추가하자 비용만 약 7배가 되었습니다. 작은 규모의 모델은 성공률이 10회 중 3회에서 매번으로 증가하고 있습니다.
예시 레포지토리는 여기입니다.
주제는 회의실을 예약하는 Python CLI입니다. 코드는 domain, service, storage, cli 네 계층으로 구성되어 있으며, 테스트와 ruff, mypy가 포함되어 있습니다. 여기에 Claude Code와 Codex 양쪽 모두에서 동일한 규칙으로 작업할 수 있도록 에이전트용 요소를 추가했습니다.
도구가 달라도 준비된 요소들은 매우 유사합니다.
| 배치하는 요소 | Claude Code | Codex | Cursor | GitHub Copilot |
|---|
| 지시 파일 | CLAUDE.md | AGENTS.md | AGENTS.md, .cursor/rules/ | AGENTS.md, .github/copilot-instructions.md |
| 위치별 규칙 | .claude/rules/의 paths | | | |
폴더별 AGENTS.md | | | | |
규칙의 globs | | | | |
.github/instructions/의 applyTo | | | | |
| 스킬 | .claude/skills/ | .agents/skills/ | .agents/skills/ | .agents/skills/, .github/skills/ |
| 서브 에이전트 | .claude/agents/ | .codex/agents/ | .cursor/agents/ | .github/agents/ |
| 훅(Hook) | .claude/settings.json | .codex/hooks.json | .cursor/hooks.json | .github/hooks/ |
| 권한 및 승인 | permissions와 권한 모드 | approval_policy | Run Modes | --allow-tool, --deny-tool |
| 샌드박스 | sandbox | sandbox_mode | sandbox.json | /sandbox |
| 비대화형 실행 | claude -p | codex exec | agent -p | copilot -p |
Claude Code 2.1.321과 Codex CLI 0.166.0 열은 예시로 직접 작동시켜 확인한 내용입니다. Cursor와 GitHub Copilot의 열은 공식 문서에 기재된 내용입니다. 공통으로 사용할 수 있는 부분은 .agents/에 두고, 각 도구별 설정에서 이곳을 호출하고 있습니다.
가장 먼저 배치하는 것은 지시 파일(Instruction File)입니다. 제가 처음 배정되었을 때, 저는 Git 명령어와 브랜치 개념조차 알지 못했습니다. 에이전트는 세션마다 그 상태에서 출발합니다. 마치 인계 메모를 매일 아침 다시 건네주는 것과 같습니다.
예시의 AGENTS.md는 40줄이며, 제목(헤딩)은 5개가 있습니다. 그중 3개가 다음과 같습니다.
## 작업을 끝내기 전에
`make check`를 실행합니다. 포맷팅, 린트(Lint), 타입, 레이어 방향, 테스트 등을 한 번에 확인하며, CI(지속적 통합)도 같은 것을 실행합니다.
## 규칙
...
제가 작성한 내용은 코드를 열어봐도 알 수 없는 것들만입니다. 폴더 구성이나 사용 중인 라이브러리는 에이전트가 스스로 조사할 수 있기 때문에 생략했습니다.
AGENTS.md는 Codex, Cursor, GitHub Copilot 등이 공통으로 사용하는 지시 파일입니다. Claude Code가 여는 것은 CLAUDE.md이므로, 1행에 @AGENTS.md라고 작성하여 가져오고, 그 아래에 Claude Code만의 보충 설명을 추가했습니다. 무엇이 가져와졌는지는 /memory에서 확인할 수 있습니다.
지시를 추가했는데도 지켜지지 않을 때는, 먼저 이 화면에 해당 파일이 올라와 있는지 확인합니다.
지시 파일을 길게 만들면 대가도 있습니다. AGENTS.md의 효과를 측정한 취리히 공과대학교(ETH Zurich) 등의 논문에서는, 개발자가 작성한 파일을 배치하더라도 과제의 성공률에 통계적인 차이는 나타나지 않았으며, 비용은 최대 20% 정도 증가했습니다. 에이전트는 지시에 잘 따르기 때문에, 적혀 있는 모든 것을 하려고 하면서 조사하는 양과 테스트 횟수가 늘어나는 것입니다.
저 역시 AI 구동 개발을 시작했을 무렵에는, 스킬(Skill)에 넣어야 할 절차까지 CLAUDE.md에 적어 놓았습니다. 줄 수가 엄청나게 늘어나서, 규칙이 지켜지지 않는 상황이 계속되었던 것을 기억합니다.
유명한 OSS에서도 줄 수에는 상당히 폭이 있습니다. 대략적인 기준은 Claude Code의 문서가 200줄 미만, OpenAI 기사가 약 100줄입니다. 예시에서는 상한선을 정하고, 초과하면 CI(지속적 통합)가 실패하도록 설정했습니다.
테스트 작성 방식처럼, 특정 폴더를 건드릴 때만 필요한 규칙은, AGENTS.md에 쓰면 관련 없는 작업에서도 컨텍스트를 사용합니다. Claude Code에서는 .claude/rules/에 두고, 맨 앞에 paths를 지정합니다.
# .claude/rules/tests.md의 맨 앞에 작성하는 부분. 해당되는 파일을 열었을 때만 표시됨
paths:
- "tests/**/*.py"
구동 시점에 올라오는 것은 CLAUDE.md와 AGENTS.md뿐이며, 규칙은 해당 파일을 열 때 추가됩니다. Cursor의 globs나 GitHub Copilot의 applyTo도 같은 방식입니다.
절차를 거치는 작업에는 스킬(Skill)을 사용합니다. 이름과 설명만 처음에 컨텍스트에 올라오고, 사용하기로 결정했을 때 본문이 열리는 매뉴얼입니다.
# .agents/skills/add-cli-command/SKILL.md의 맨 앞에 작성하는 부분
name: add-cli-command
description: booking의 CLI에 서브 커맨드나 옵션을 추가할 때의 절차. "명령어를 추가해", "옵션을 추가해", "CLI로 ~가 가능하게 해"와 같은 요청을 받으면 사용합니다.
스킬이 사용될지 여부는 description으로 결정되므로, 어떤 단어로 요청받았을 때 사용할 수 있는지까지 작성해 둡니다. 위치는 Codex도 참조하는 .agents/skills/로 하고, Claude Code에는 .claude/skills에서 링크를 걸었습니다. 사람이 입력했을 때만 작동시키고 싶은 스킬에는 disable-model-invocation: true를 붙입니다.
비슷한 스킬을 너무 많이 늘리는 것도 문제입니다. 제 컴퓨터에서는 디자인용 스킬이 어느새 늘어나서, 어떤 것이 사용되었는지 알 수 없었던 적이 있습니다.
대화나 머릿속에만 존재하는 설계 판단은, 에이전트에게는 존재하지 않는 것과 같습니다. 예시에서는 docs/decisions/
판단을 건별로 파일 하나에 남기고 있습니다. 결정과 함께 이유를 전달하는 것은 다른 상황에도 적용해 보도록 하기 위함입니다.
Claude Code에는 에이전트가 스스로 작성하는 자동 메모리 기능도 있습니다. 대화에서 받은 수정 사항이나 선호도를 로컬 머신에 남겨 다음 세션에서 사용할 수 있습니다. 팀원들과 공유되지 않기 때문에, 모두가 지켜주길 바라는 학습 내용은 지시 파일이나 검사(check)로 옮깁니다.
요청 문구가 한 줄이면, 에이전트가 부족한 부분을 스스로 결정해 버리는 경우가 있습니다. 결정했으면 하는 것은 구현 전에 사양(specification)으로 작성합니다. 이를 '사양 주도 개발(仕様駆動開発)'이라고 부르는 진행 방식입니다.
사양은 docs/specs/
에 기능별로 파일 하나에 두었습니다. 예약(booking)을 CSV로 출력하는 기능의 사양 일부입니다.
## 행동 양식 (ふるまい)
- `booking export --format csv` 로, 예약을 표준 출력으로 CSV 형식으로 출력한다.
- 예약이 한 건도 없을 때는, 헤더 행 1줄만 출력한다.
...
완료 조건을 확인할 수 있는 문장으로 작성해 두면, 요청은 이 조건을 충족하면 끝이라는 약속이 됩니다. 이 파일만 넘겨서 Opus에게 구현하게 했습니다.
보고서에서는 조건 하나하나에 테스트 이름이 대응하고 있었습니다. 게다가, --format
을 생략했을 때의 동작 등 사양이 결정되지 않은 점 2가지를 언급하며, 손대지 않고 되물어오고 있습니다.
이것만 통과하면 끝이라고 말할 수 있는 하나의 커맨드에서 만듭니다. 예시에서는 make check
에 정리했습니다.
# 정형화, 린트(lint), 타입, 레이어 방향, 테스트를 한 번에 확인합니다
make check
사람도, 에이전트도, CI도 같은 하나의 명령어를 사용합니다. 확인 방법이 여러 개 있으면, 에이전트는 그중 일부를 생략할 수 있습니다. 출력은 그대로 컨텍스트로 들어가기 때문에, 통과했을 때는 짧게, 실패했을 때만 자세히 나오도록 했습니다.
에이전트가 받는 오류 메시지에 수정 방법까지 적어주면, 그것이 바로 다음 지시가 됩니다. domain
안에서 datetime.now()
를 호출하면, 예시의 tools/check_layers.py
는 다음과 같이 반환합니다.
src/booking/domain/deadline.py:13: [clock] domain에서 datetime.now()를 호출하고 있습니다
수정 방법: 현재 시각은 인수로 받아주세요.
이유는 docs/decisions/0002-inject-clock.md에 있습니다.
출력에는 위치, 위반 내용, 수정 방법, 이유의 저장 위치가 포함되어 있습니다. 사람이 사용하는 린터라면 위반 이름만으로 충분하지만, 에이전트에게는 이 정도까지 전달합니다. OpenAI 기사와 Beckeler 기사가 각각 별도로 소개했던 작성 방식입니다.
AGENTS.md
에 적은 것은 모델에게 부탁하는 것입니다. 대부분 지켜지지만, 지켜지지 않은 경우도 기록으로 남습니다. 반드시 실행하고 싶은 것은 훅(hook)에 넣습니다. 도구를 사용하기 전이나 후에, 응답을 끝내기 전 등 정해진 시점에 하네스(harness)가 실행하는 명령어입니다.
{
"hooks": {
"Stop": [
...
Stop은 에이전트가 응답을 끝내려고 하는 시점입니다. 스크립트가 make check
를 실행하고 실패하면 종료 코드 2로 끝나게 됩니다. 그러면 표준 오류 내용이 에이전트에게 돌아오고, 작업이 계속됩니다.
예약 단위를 15분에서 10분으로 변경시키고, 테스트는 고치지 말라고 부탁해 보겠습니다.
끝나려고 할 때마다 3번 연속으로 멈추었고, 네 번째는 멈추지 않고 '사람의 확인이 필요합니다'라고 표시되었습니다. 고쳐지지 않은 채 계속 돌지 않도록, 횟수를 정해두었습니다.
예시에서 사용한 이벤트는 4가지입니다.
| 이벤트 | 동작 시점 |
|---|
SessionStart | 세션 시작 시 |
PreToolUse | 도구 실행 전 |
PostToolUse | 도구 실행 후 |
Stop | 응답 종료 전 |
Claude Code의 훅 이벤트는 문서 목차를 세어보면 33가지가 있습니다. 3월에 Hooks 기사를 작성했을 때는 21가지였는데, 반년여 만에 상당히 늘었습니다.
Codex에도 같은 형태의 훅이 있으며, 입력 JSON도 거의 공통적입니다. 스크립트는 .agents/hooks/
두 설정 모두에서 같은 것을 호출하도록 변경했습니다.
테스트가 모두 통과하더라도, 규칙이 바뀌었을 때 실패할 것이라고는 보장할 수 없습니다. 에이전트가 작성하는 테스트는 구현을 그대로 따라 하는 것에 그칠 수 있습니다. 예약 규칙을 한 번에 하나씩 의도적으로 수정하여 테스트가 떨어지는지 확인하는 tools/check_tests_bite.py를 만들었습니다. 이는 뮤테이션 테스트(Mutation Test)를 축소한 것입니다.
수정한 6개 지점 중 절반은 모든 테스트가 통과했습니다. 최대 시간을 4시간에서 3시간으로 변경해도 어떤 테스트도 실패하지 않았습니다. 정확한 값을 확인하는 테스트가 없었던 것입니다. 놓친 부분은 제7장에서 에이전트에게 보충하도록 하겠습니다.
테스트와 린터(Linter)로는 확인할 수 없는 것은, 다른 컨텍스트에서 작동하는 서브 에이전트(Sub-agent)를 통해 재검토받습니다. 구현한 본인에게 의존하면 자신이 작성한 것에는 관대해지기 마련입니다.
# .claude/agents/reviewer.md 파일의 맨 앞에 적을 부분. 사용할 툴과 모델을 여기서 결정합니다
name: reviewer
description: 변경 사항을 다른 컨텍스트에서 검토하는 리뷰 역할. 구현이 완료되어 make check가 통과한 후, 커밋 전에 사용합니다.
...
서브 에이전트는 차분(diff)과 문서만 가지고 조사하기 시작하며, 결과 요약만을 부모에게 반환합니다. booking stats를 추가해달라고 요청했을 때 다음과 같이 돌아왔습니다.
24초 만에 응답했으며, 판정은 '현 상태로 좋다'였습니다. 모델은 메인보다 작은 Sonnet을 사용하도록 하고, 검토는 커밋 전에 1회로 정했습니다. 지적과 수정을 여러 번 왕복시키면 시간과 비용만 늘어납니다.
직접 사용하는 후크(hook)는 설정을 변경하면 제거할 수 있으므로, 누구의 장비에서도 아닌 곳에서도 다시 make check를 통과시킬 수 있습니다.
jobs:
check:
runs-on: ubuntu-latest
...
check_harness.py는 하네스 자체에 대한 검사입니다. 지시 파일의 줄 수, 언급된 경로가 실제로 존재하는지, 후크 스크립트가 실행 가능한지를 확인합니다. 사실 이 CI(Continuous Integration)는 첫 푸시에서 실패했습니다.
setup-uv@v10이라는 태그가 존재하지 않았기 때문입니다. 워크플로우는 에이전트에게 작성하게 한 것이라 번호를 정확히 기억하고 있지 못했습니다. 에이전트가 작성한 버전 번호는 실제로 존재하는지 확인한 후에 사용하는 것이 좋다고 생각합니다.
제4장의 사양은 리포지토리에만 두면 개발자 외의 눈에 띄기 어렵습니다. Confluence와 같은 사내 문서 저장소에 사본을 내리는 것으로 했습니다. 작성 및 대조 경로는 CI 스크립트와 MCP(Multi-Context Platform) 두 가지입니다. 현장에서는 Confluence API와 MCP를 모방한 서버를 상대하여 작동시키고 있습니다.
기본은 CI 스크립트입니다. 사양이 변경된 푸시가 있을 때마다 tools/docs_sync.py가 API로 작성하고, 풀 리퀘스트(Pull Request)에서는 일치 여부를 확인합니다.
CSV 기능의 풀 리퀘스트에는 실제로 지적 사항을 넣었습니다.
에이전트는 사양을 먼저 수정한 후, 구현과 테스트를 합쳐서 같은 풀 리퀘스트에 커밋합니다. 다시 푸시하면 동일한 워크플로우가 작동하므로, 지적으로 수정한 부분도 사본에 반영됩니다.
대조는 2단계입니다. 첫째, 페이지 끝에 작성된 sha256을 로컬과 비교하고, 둘째, 가져온 페이지의 전체 내용을 로컬 Markdown에서 만든 본문과 비교합니다. 전체 내용까지 비교하면 Confluence 화면에서 누군가 직접 수정한 경우도 발견할 수 있습니다.
'도쿄 시간'을 'UTC'로 변경한 페이지를 대조가 찾아냈습니다. 이 경로는 모델을 거치지 않기 때문에, 전체 내용을 비교해도 토큰이 소모되지 않습니다.
사내 네트워크나 인증상의 이유로 CI에서 API가 도달할 수 없는 환경도 있습니다. 그 경우의 대체재가 MCP입니다. 에이전트를 외부 서비스에 연결하는 공통 규격이며, Atlassian은 Confluence용 서버를 공개하고 있습니다. 연결 대상은 리포지토리 루트의 .mcp.json에 적습니다.
{
"mcpServers": {
"atlassian": { "type": "http", "url": "https://mcp.atlassian.com/v2/mcp" }
...
}
MCP에서는 에이전트가 도구를 호출하여 페이지를 작성합니다. 호출할지 여부는 모델이 결정하므로, 5-3의 종료 전 후크에 작성되지 않은 사양이 없는지 확인하는 절차를 추가했습니다. 작성이 완료된 후에는 해당 페이지를 가져와 CI와 동일한 검증을 거칩니다. 통과하지 못하면 작성된 것으로 간주하지 않습니다.
MCP에서 주의해야 할 것은 토큰입니다. 페이지 전체를 가져오면 그 글자가 모두 컨텍스트에 들어갑니다. /sync-specs 스킬에는 작은 것부터 가져오는 절차를 작성했습니다.
변경된 파일은 로컬에 보관한 sha256과 비교하면 알 수 있으므로, 통신도 토큰도 사용하지 않습니다. 작성되지 않은 페이지는 버전 번호만 가져오고, 마지막으로 작성된 시점 그대로라면 일치로 간주합니다. 번호가 진행된 페이지에 대해서만 이전 및 이후의 차이(diff)를 가져오고, 전체 내용을 가져오는 것은 작성된 페이지에 한정됩니다.
누군가가 화면에서 1페이지를 수정한 상태로 확인을 요청했습니다. 전체 내용을 가져온 페이지는 없었고, 차이점은 1줄이었습니다. 그렇다면 비용에는 어느 정도의 차이가 날까요?
5개 페이지를 확인하는 데 드는 비용은 전체 내용을 가져오는 방식보다 버전 번호만 사용하는 방식이 3할 이상 저렴했습니다. 페이지가 작아서 이 차이지만, 페이지가 길고 수가 많아질수록 전체 내용을 가져오는 방식만 무거워집니다.
Claude Code에서는 에이전트가 수행한 작업을 permissions와 대조합니다. 확인 없이 실행하는 allow, 사람에게 확인을 요청하는 ask, 실행하지 않는 deny의 세 가지입니다.
{
"permissions": {
"allow": ["Bash(make *)", "Bash(uv run *)", "Bash(git commit *)"],
...
}
여러 규칙에 해당할 때는 deny, ask, allow 순서로 우선순위가 결정됩니다. ask 동작은 의존성 추가를 요청하며 확인했습니다. AGENTS.md에는 의존성을 늘리기 전에 이유를 덧붙여 상담해야 한다고 적혀 있습니다.
에이전트는 uv add를 실행하지 않고, 표준 라이브러리로 충분한 방안과 함께 되물어왔습니다. 여기까지는 지시 파일의 작동입니다. "추가해 주세요"라고 진행하자, 이번에는 설정에 대한 ask가 확인을 요청합니다.
질문을 받는 횟수에도 적정량이 있습니다. Anthropic이 공개한 데이터에 따르면, Claude Code 사용자가 승인하는 비율은 권한 확인의 93%였습니다. 대부분 그냥 승인만 하게 되면, 결국 내용을 확인하지 않고 누르게 됩니다. ask에 포함할 내용은 질문받았을 때 정말 생각해야 하는 것들로 충분합니다.
권한 규칙이 판정에 사용하는 것은 도구의 이름과 인자이기 때문에, 같은 것을 다른 방식으로 실행해도 통과해 버립니다. 이 구멍은 OS 기능으로 범위를 정하는 샌드박스(sandbox)로 막습니다.
{
"sandbox": {
"enabled": true,
...
}
Bash에서 실행하는 명령어가 쓸 수 있는 위치와 통신할 수 있는 경로는 이 범위로 제한됩니다. cat .env는 후크가 막기 때문에, 후크 검증에 해당하지 않는 방식으로 요청해 보았습니다.
python3 -c "print(open('.env').read()))"은 후크를 통과했고, OS가 막았습니다. 내용은 표시되지 않은 채입니다. Codex에서는 .codex/config.toml로 같은 것을 결정합니다.
# 쓸 수 있는 것은 작업 폴더 안으로만. 외부로 나가는 동작은, 그때마다 사람에게 확인 요청
sandbox_mode = "workspace-write"
approval_policy = "on-request"
/status를 통해 현재의 권한과 승인 상태를 확인할 수 있습니다. Agents.md 줄에는 개인용과 리포지토리의 AGENTS.md가 모두 올라와 있었습니다.
세 번째 계층은 5장에서도 사용했던 후크입니다. PreToolUse 후크는 명령어가 실행되기 전에 내용을 확인하고, 막을 때는 이유를 반환할 수 있습니다.
RULES: list[tuple[str, str]] = [
# push는 사람이 수행한다. 에이전트는 커밋한 곳에서 멈춘다
(r"\bgit\s+push\b",
...
]
첫 번째는 에이전트가 AGENTS.md의 규칙을 언급하며 거절했습니다. "규칙은 알고 있으니"라고 덧붙여 요청하자 실행하려고 했고, 후크가 막았습니다. 지시 파일의 규칙은 대화 속에서 사람이 덮어쓸 수 있지만, 후크는 대화에서 무엇을 말하든 동일하게 작동합니다. 같은 스크립트로 Codex도 멈췄습니다.
이 세 가지는 중첩하여 사용됩니다. 후크(Hook)는 이유를 반환할 수 있지만, 작성 방식을 바꾸면 우회될 수 있습니다. 권한 규칙은 도구의 이름과 인수로 제한하며, 그곳을 벗어난 프로세스는 샌드박스(Sandbox)가 제한합니다.
외부에서 오는 지시도 차단 대상입니다. 에이전트가 열어둔 웹페이지나 이슈에 '비밀을 외부에 전송하라'고 적혀 있다면, 이를 따르곤 합니다. 비밀 데이터에 접근하고 신뢰할 수 없는 문서를 가져와 외부로 전송하는 것도 가능합니다. 이러한 조건들이 중첩되면 위험하다고 Simon Wilson은 지적했습니다. 예시에서는 .env 파일을 열지 못하게 하고 통신 대상을 제한하고 있습니다.
에이전트가 한 번에 처리할 수 있는 용량의 틀(Context Window)은 Claude Code의 /context 명령어로 세부 내역을 확인할 수 있습니다.
예시를 실행한 직후에는 틀의 약 3% 정도만 사용하고 있었습니다. 지시 파일은 작고, 도구 정의나 스킬 설명 부분이 훨씬 크다는 것을 알 수 있습니다. 스킬 항목이 많은 이유는 저 개인용으로 만든 스킬도 포함되었기 때문입니다 (상당히 많이 넣었습니다).
틀이 크더라도 포함하는 내용은 제한합니다. 불필요한 정보가 늘어날수록 모델은 필요한 정보를 찾기 어려워지므로, 작업이 바뀌면 /clear로 대화를 비우고 긴 조사는 서브 에이전트(Sub-agent)에게 맡깁니다.
긴 대화의 후반부에서 처음에 전달했던 규칙이 빠지는 경우가 저도 자주 있었습니다. 그럴 때는 '대화 기록을 따라가라'고 명시적으로 요청하고 있습니다.
여러 파일에 걸친 변경 사항은 작성하기 전에 계획을 세우도록 합니다. Claude Code의 계획 모드(Plan Mode)를 사용하면 에이전트는 파일을 조사하고 계획을 수립하는 단계에서 멈춥니다. 매주 반복 예약 추가 요청에 사용했습니다.
에이전트는 코드를 조사한 후, 요청서에 적혀 있지 않은 사양을 물어왔습니다.
몇 시간이 걸리는 작업에서는 도중에 대화가 압축되거나 세션이 끊길 수 있습니다. 다음 내용을 저장할 위치는 docs/plans/입니다.