프롬프트 밖에 벽을 세워라 — 하네스 엔지니어링

3편에서 역할을 나눴다면, 다음 질문은 이것입니다. 그 계약을 누가 강제로 지키게 하나? 프롬프트에 “.env 건드리지 마”라고 쓰는 것과, 커밋 훅·CI·샌드박스가 물리적으로 막아버리는 것은 다릅니다.

핵심 한 줄: 하네스 엔지니어링은 모델을 더 똑똑하게 만드는 일이 아니라, 모델 바깥에 도구·권한·검증·추적 벽을 세우는 일입니다.

이 글은 「코딩은 대화다」 4편입니다. 멀티에이전트 다음에 런타임 강제로 올라갑니다.

하네스란? (모델 vs 주변 장치)

OpenAI 에이전트 문서의 구분부터 가져옵니다 (Sandbox Agents):

모델은 “생각”을 하고, 하네스는 무엇을 할 수 있는지·무엇을 증명해야 하는지를 정합니다. 약한 하네스 안의 강한 모델은 여전히 사고칩니다.

왜 승인 클릭만으로는 부족한가

Anthropic은 Claude Code에서 매 턴 사람 승인에 의존했다가, 사용자가 대략 93% 승인하는 approval fatigue를 관측했다고 공개했습니다. 그래서 OS 샌드박스(워크스페이스 쓰기, 기본 네트워크 거부 등)로 할 수 있는 일 자체를 줄였고, 권한 프롬프트가 크게 줄었다고 설명합니다 (How we contain Claude).

교훈은 단순합니다. 확률적 감독(사람이 매번 읽기) 보다 결정적 경계(샌드박스·훅·CI) 가 스케일됩니다.

처음에는 “Allow”를 습관처럼 누르다가, 에이전트가 rm에 가까운 명령을 제안했을 때도 손가락이 먼저 움직인 적이 있습니다. 그다음부터는 위험한 셸은 훅으로 막고, 안전한 명령만 자동 승인하는 쪽으로 바꿨습니다.

하네스의 네 기둥

1) Tools — 무엇을 쥐어 줄까

• 읽기 전용 검색 vs 쓰기 vs 네트워크 vs 시크릿 스토어
• MCP/플러그인은 allowlist
• 3편의 Research 역할 = 도구를 읽기 위주로 잠그는 것과 같은 축

2) Sandbox — 어디서 돌릴까

• 워크스페이스 밖 쓰기 금지
• 네트워크 기본 거부 또는 허용 도메인만
• 임시 디렉터리 / 컨테이너 / 벤더 샌드박스 세션

3) Permissions — 언제 사람을 부를까

• 고위험만 인간 게이트 (배포, 시크릿, 스키마 파괴)
• 저위험은 자동화 (포맷, 테스트, lint)
• PapaCoder: 에이전트는 draft upsert만, Publish는 Admin

4) Eval — 어떻게 증명할까

• “테스트 돌렸다”는 말 vs CI exit code
• 품질 점수·accuracy 게이트 (PapaCoder editorial: ≥85, accuracyFail 블록)
• 실패를 다음 루프의 입력으로 (5편에서 깊게)

Anthropic 쪽 평가 논의에서도 모델과 하네스를 함께 본다는 관점이 반복됩니다. 프롬프트만 고치면 재발하는 실패는 대개 하네스 구멍입니다.

실습: 주말 프로젝트용 미니 하네스 체크리스트

레포 루트에 아래를 한 번에 깔아 보세요.

A. AGENTS.md — 정책 (여전히 필요)

# Harness policy (human-readable)

## Forbidden without explicit human approval
- Editing `.env*`, credentials, or CI secrets
- `git push --force`, production deploy
- Dropping database tables / destructive migrations

## Required before claiming done
- Run unit tests for touched packages
- No new network calls to unknown hosts

## Publish
- Agents may create drafts only; humans publish

B. Cursor Hooks — 결정적 차단 (모델이 무시 못 함)

Cursor는 .cursor/hooks.json으로 에이전트 루프 전후에 스크립트를 걸 수 있습니다. beforeShellExecution 등으로 셸을 관찰·차단·수정할 수 있고, 훅은 JSON stdio로 통신하는 별도 프로세스입니다 (Hooks).

예시 골격 (프로젝트 루트):

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      { "command": ".cursor/hooks/deny-dangerous-shell.sh" }
    ]
  }
}

#!/usr/bin/env bash
# .cursor/hooks/deny-dangerous-shell.sh — illustrative
# Read JSON from stdin; exit non-zero or return deny payload per Cursor hooks schema.
# Block patterns: force push, curl|bash, rm -rf /, production secrets paths.

(정확한 allow/deny JSON 필드는 현재 Hooks 문서의 스키마를 따르세요. 요지는 프롬프트가 아니라 프로세스가 막는다는 점입니다.)

C. CI — 말 대신 exit code

# .github/workflows/agent-gate.yml (sketch)
name: agent-gate
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm test --filter ./packages/core
      - run: pnpm lint

에이전트에게 “PR 열어”라고 해도, 게이트가 빨갛면 머지 권한이 없는 상태가 진짜 하네스입니다.

D. 시크릿 경계 — PapaCoder식

• 에이전트/Cursor 세션: INTERNAL_API_KEY로 draft API만
• DATABASE_URL은 에이전트에 주지 않음
• Publish = Admin 세션

이건 제품 헌법과 같은 하네스입니다. “에이전트가 착해서”가 아니라 키가 없어서 못 합니다.

Cursor / Claude Code에서 오늘

실패 모드

5편으로 넘어가는 신호

하네스가 “벽”이라면, 루프 엔지니어링은 그 벽 안에서 plan→act→observe를 몇 번·어떤 WIP로 돌릴지입니다. 재시도 정책, 품질 루프, 사람 에스컬레이션이 5편의 주제입니다.

다음 편 — 「코딩은 대화다」

1. 도구·요금
2. 바이브 → 배포
3. 멀티에이전트
4. 지금 글 — 하네스
5. 루프 엔지니어링
6. 그래프 엔지니어링
7. PapaCoder 실전 사례

FAQ

Q. 하네스 = 프레임워크 이름인가요?
A. 제품 이름이라기보다 패턴입니다. Cursor hooks, Claude sandbox, OpenAI sandbox agent, CI, 시크릿 분리 모두 하네스 조각입니다.

Q. AGENTS.md만으로 충분한가요?
A. 시작은 됩니다. 무시되면 훅·CI·샌드박스를 추가하세요.

Q. PapaCoder는 어디가 하네스인가요?
A. Internal API(초안만), 품질/정확도 게이트, Admin publish, 에이전트에 DB 미제공이 대표적입니다.

참고 출처

• OpenAI — Sandbox Agents
• Anthropic — How we contain Claude
• Cursor — Hooks
• PapaCoder editorial draft publish runbook

마무리

3편이 “누가 무엇을 하는가”라면, 4편은 누가 무엇을 못 하게 하는가입니다. 그 금지를 프롬프트가 아니라 하네스에 심을 때, 에이전트 팀은 비로소 제품 팀에 가까워집니다.

앞으로는 모델 업그레이드보다 실패를 eval로 고정하는 속도가 격차를 벌릴 가능성이 큽니다. 5편에서는 그 실패를 루프로 돌리는 법을 다룹니다.