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>

팀 도입 체크리스트: 출구부터 정합니다

처음부터 완전한 Agent Harness 플랫폼을 만들 필요는 없습니다. 먼저 workflow의 출구를 정해야 합니다. 콘텐츠 운영의 출구는 “초안 작성”이 아니라 “공개 URL이 200을 반환하고, Analytics와 광고 태그가 남아 있으며, 모바일에서 코드 블록이 깨지지 않는 상태”입니다. 영업 자동화의 출구는 “메일 발송 완료”가 아니라 “후보 회사 목록, 샘플 페이지, 메일 초안이 검토 가능한 상태”입니다.

이렇게 출구를 정하면 use case별로 자동화 범위가 보입니다.

use case	먼저 자동화해도 되는 것	승인을 남길 것
콘텐츠 운영	주제 후보, 초안, 번역, 내부 링크, build	deploy, git push, 광고 스크립트 변경
SaaS 연동	읽기 전용 조회, CSV 정리, 문안 생성	메일 발송, 데이터 삭제, 과금 설정 변경
보안 수정	patch 작성, 테스트 실행, 영향 범위 메모	secret 접근, 운영 배포, 권한 완화

가장 흔한 pitfall은 읽기와 실행을 섞는 것입니다. Agent가 문서, issue, 로그를 읽는 것은 비교적 안전합니다. 하지만 같은 세션에 메일 발송, DB 변경, 배포 권한까지 주면 외부 문서의 악성 문장이 실제 명령처럼 작동할 risk가 생깁니다. OWASP의 Top 10 for LLM Applications는 Prompt Injection과 Excessive Agency를 중요한 위험으로 다루며, 코드 Agent 운영에서도 그대로 적용됩니다.

Claude Code를 쓰는 팀은 공식 security guide와 permissions guide를 먼저 확인하세요. Codex를 함께 쓰는 경우에는 OpenAI의 code generation guide도 기준점이 됩니다. 내부 교육 자료로는 Claude Code 보안 실패 사례와 위험한 prompt 패턴를 묶어 읽는 것이 좋습니다.

바로 적용할 템플릿과 체크리스트는 /products/에 정리해 두었습니다. 리포지토리 권한, CI, 배포 승인, 운영 룰까지 같이 설계해야 한다면 /training/에서 도입 상담을 받는 편이 빠릅니다.

리뷰에서는 여섯 가지만 확인합니다

Agent Harness 리뷰에서 모든 프롬프트를 문장 단위로 토론할 필요는 없습니다. 고정 질문 여섯 개가 더 효과적입니다. 첫째, Agent가 secret을 읽을 수 있는가. 둘째, 메일 발송, 삭제, deploy, 과금 변경 같은 외부 부작용이 있는가. 셋째, 실패했을 때 어떤 파일이 바뀌었는지 알 수 있는가. 넷째, 성공 조건이 command로 검증되는가. 다섯째, 모바일 표시나 다국어 누락처럼 자주 빠지는 검사도 포함되는가. 여섯째, 사람이 읽을 수 있는 실행 로그가 남는가.

이 review 방식은 보안 전문가가 아니어도 참여할 수 있다는 장점이 있습니다. 기획자는 승인해야 할 행동을 고르고, 엔지니어는 deny할 명령을 정하고, 운영자는 결과 확인 기준을 말할 수 있습니다. Harness의 목적은 절차를 무겁게 만드는 것이 아니라 risk를 보이게 만드는 것입니다.

답을 못 하는 use case는 곧바로 production에 연결하지 마세요. 먼저 계획, diff, 리포트 생성까지만 맡기고, 여러 번 안정적으로 통과한 뒤 낮은 위험의 command만 allow로 옮기는 편이 안전합니다.

정리

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

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

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