Claude Code/Codex 안전 Agent Harness 설계: 권한, 검증, 롤백

강한 에이전트에는 더 강한 발판이 필요합니다

Claude Code나 Codex를 처음 사용할 때는 프롬프트만 잘 쓰면 된다고 생각하기 쉽습니다. 작은 수정에는 맞는 말입니다. 하지만 배포, SaaS API, 파일 수정, 글 발행, 메일 발송까지 맡기기 시작하면 문제는 프롬프트가 아니라 운영 구조가 됩니다.

이 글에서는 그 구조를 Agent Harness라고 부릅니다. Agent Harness는 AI 에이전트를 안전하게 움직이기 위한 외부 장치입니다. 권한 정책, 실행 계획, 검증 스크립트, 실행 로그, 복구 절차가 여기에 포함됩니다.

개념을 먼저 보고 싶다면 하네스 엔지니어링 가이드를 참고하세요. 실패 사례는 Claude Code 보안 실패 사례와 이어집니다.

User request
  |
  v
Agent
  |
  v
[1] Policy layer       허용, 승인 필요, 금지 작업을 나눕니다
[2] Plan layer         어떤 순서로 작업할지 정합니다
[3] Verification layer 성공을 명령으로 확인합니다
[4] Recovery layer     실패했을 때 되돌리는 방법을 정합니다
  |
  v
Files / shell / SaaS APIs / deploy

Claude Code의 공식 문서는 settings, permissions, hooks, MCP를 나누어 설명합니다. 시작점으로 Claude Code settings, Hooks reference, MCP를 확인할 수 있습니다.

예시: 글 발행 Harness

“오늘 글 하나 발행해줘”는 하나의 작업처럼 보이지만 실제로는 여러 단계입니다.

1. 최근 7일 분석 데이터를 읽습니다
2. 성과가 좋은 주제 주변에서 새 주제를 고릅니다
3. 기존 글과 중복되는지 확인합니다
4. 원문을 작성합니다
5. 모든 언어 버전을 만듭니다
6. frontmatter, slug, 내부 링크를 확인합니다
7. 사이트를 빌드합니다
8. 공개 URL이 200인지 확인합니다
9. commit과 push를 수행합니다

이 과정을 기억에만 의존하면 에이전트는 본문 작성처럼 눈에 보이는 부분만 끝내고, 번역이나 배포 확인을 빠뜨릴 수 있습니다. Plan layer는 지루하지만 중요한 단계를 빠뜨리지 않게 합니다.

SaaS 연동에서는 읽기, 생성, 전송을 분리합니다

예를 들어 에이전트가 회사 정보를 찾고 샘플 페이지와 영업 메일을 만든다고 합시다.

작업	자동화	이유
공개 웹 페이지 읽기	가능	영향이 작습니다
로컬 CSV 저장	가능	나중에 검토할 수 있습니다
샘플 페이지 생성	가능	공개 전 확인할 수 있습니다
메일 초안 생성	가능	아직 전송하지 않습니다
메일 전송	승인 필요	외부 사람에게 영향을 줍니다

Agent Harness의 핵심은 이 경계를 설계하는 것입니다. 읽기와 초안 생성은 자동화해도 되지만, 배포와 전송은 승인 단계에 둡니다.

Policy layer: allow, ask, deny

최소 정책 파일은 다음처럼 시작할 수 있습니다.

{
  "allowCommands": [
    "npm run build",
    "npm run test",
    "node scripts/content-trend-report.mjs"
  ],
  "askCommands": [
    "git push",
    "wrangler pages deploy",
    "node scripts/outreach-send-mails.mjs --send"
  ],
  "denyCommands": [
    "rm -rf",
    "git reset --hard",
    "curl * | sh",
    "npm publish"
  ],
  "protectedPaths": [
    ".env",
    ".env.local",
    "claudecode-lab-sheets-f54fc47c68f0.json"
  ]
}

Claude Code에서는 프로젝트 설정으로 비슷한 경계를 둘 수 있습니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test *)",
      "Bash(node scripts/content-trend-report.mjs *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(wrangler pages deploy *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git reset --hard *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./claudecode-lab-sheets-f54fc47c68f0.json)"
    ]
  }
}

“비밀정보를 조심해”라고 쓰는 것보다, 실제 파일과 명령을 규칙으로 막는 편이 훨씬 안전합니다.

Verification layer: 성공을 코드로 확인합니다

빌드가 통과했다고 끝이 아닙니다. 공개 URL, AdSense 태그, Analytics 태그, 모바일 코드 블록까지 확인해야 합니다.

const url = process.argv[2];
const response = await fetch(url, { redirect: "follow" });

if (!response.ok) {
  throw new Error(`Page returned ${response.status}: ${url}`);
}

const html = await response.text();
const checks = [
  ["title", /<title>.+<\/title>/i],
  ["description", /<meta name="description"/i],
  ["adsense", /ca-pub-2125588229998303/i],
  ["analytics", /G-3YR0LE68MJ/i]
];

for (const [name, pattern] of checks) {
  if (!pattern.test(html)) throw new Error(`Missing ${name}`);
}

console.log(`OK: ${url}`);

레이아웃 위험이 있으면 Playwright로 모바일 폭에서 pre, code, table이 넘치지 않는지도 확인합니다.

Recovery layer: 무엇을 바꿨는지 남깁니다

실패 자체보다 위험한 것은 실패 후 무엇이 바뀌었는지 모르는 상태입니다.

{
  "runId": "2026-05-19-article-001",
  "topic": "agent harness security",
  "changedFiles": [
    "site/src/content/blog/claude-code-codex-agent-harness-security.mdx"
  ],
  "commands": [
    "node scripts/content-trend-report.mjs --days 7",
    "npm run build"
  ],
  "status": "deployed"
}

복구는 넓은 reset보다 좁은 diff와 revert가 안전합니다.

git status --short
git diff -- site/src/content/blog/target-article.mdx
git revert <bad-commit>

정리

AI 에이전트의 품질은 프롬프트만으로 결정되지 않습니다. 실무에서는 모델 바깥의 발판이 품질을 결정합니다.

• Policy: 무엇을 허용하고 막을지
• Plan: 어떤 순서로 실행할지
• Verification: 성공을 어떻게 증명할지
• Recovery: 실패했을 때 어떻게 되돌릴지

Claude Code든 Codex든, 이 네 계층을 준비하면 에이전트에게 맡길 수 있는 범위가 넓어집니다. 중요한 것은 AI를 무제한 실행자로 만드는 것이 아니라, 안전하게 일할 수 있는 통로를 만드는 것입니다.