에이전트 플레이북은 언제 md에서 스크립트로 승격해야 할까 2026 — runbook과 harness 경계선

Posted on by

처음엔 다 문서로 시작한다.

이럴 땐 이렇게 해라

실패하면 저기 봐라

훅 붙일 땐 이 순서다

이 정도는 md만 있어도 굴러간다.

근데 어느 순간부터 문서가 일을 안 하고 사람이 문서를 대신 읽어주느라 일을 하게 된다.

그때부터 고민이 생긴다.

이거 아직 문서로 둬도 되나?

아니면 이제 스크립트로 올려야 하나?

아예 하네스로 빼야 하나?

이 질문을 대충 넘기면 운영팀은 문서를 계속 늘리고, 현실은 계속 사람 손으로 막는다.

그래서 이 글은 2026년 4월 7일 기준으로 에이전트 플레이북을 언제 markdown 문서로 두고, 언제 스크립트로 승격하고, 언제 harness까지 올려야 하는지 경계선을 정리한 글이다.

Quick Answer
사람이 읽고 상황에 따라 판단해야 하는 지식이면 md로 두는 게 맞다.
반대로 같은 조건에서 같은 반응이 반복되어야 하거나,
Claude Code lifecycle 특정 지점에서 자동 실행되어야 하거나,
실패 후 복구까지 필요해지면 스크립트나 harness로 승격해야 한다.
한 줄로 줄이면
설명이면 md, 결정이면 script, 복구까지면 harness다.

이 글이 필요한 사람

  • 운영 플레이북이 점점 길어지는데 실제론 잘 안 지켜지는 사람
  • Claude Code hooks, agents, scripts, harness가 자꾸 겹쳐 보이는 사람
  • md 문서만 잔뜩 늘고 실제 자동화는 부족한 팀
  • 반대로 스크립트만 늘다가 아무도 이유를 설명 못 하는 팀
  • 문서와 실행체의 경계선을 잡고 싶은 사람

지금 결론

  1. 반복되는 설명은 md로 시작하는 게 맞다.
  2. 같은 조건에서 같은 판단을 내려야 하면 script로 올린다.
  3. 세션을 넘어 상태가 남아야 하고, 실패 후 복구 루프가 필요하면 harness다.
  4. hooks는 “언제 반응할지”를 정하는 트리거고, script는 “무슨 일을 할지”를 정하는 실행체다.
  5. 문서를 스크립트로 승격하는 핵심 질문은 사람이 읽고 판단할 필요가 남아 있나다.

공식 문서가 말하는 것부터 보자

Claude Code 공식 Hooks 문서는 hooks를 Claude Code lifecycle 특정 지점에서 자동 실행되는 user-defined shell commands, HTTP endpoints, or prompts 라고 설명한다.

그리고 훅은

  • 세션 시작
  • 프롬프트 제출 전
  • 도구 실행 전후
  • 파일 변경
  • 작업 생성/완료

같은 이벤트에 걸 수 있다고 정리한다.

즉 hooks는 문서를 잘 읽었으면 알아서 하세요 가 아니라, 이 타이밍엔 이 반응이 자동으로 나가야 합니다 를 시스템에 박는 장치다.

또 공식 문서는 hooks를

  • 전역 설정
  • 프로젝트 .claude/settings.json
  • skill/agent frontmatter

같은 여러 위치에 둘 수 있다고 안내한다.

이 말은 곧 운영 로직이 문서 안에만 있지 않고, 실행 계층으로도 끌어내릴 수 있다는 뜻이다.

우리 쪽에서 말하는 harness는 더 무겁다

워크스페이스 가이드에서 harness는 단순 역할 문서가 아니라

  • health check
  • 자동 재시작
  • fallback
  • 상태 저장/복원

까지 포함하는 실행 계층으로 정의돼 있다.

이 차이가 중요하다.

script는 보통 한 번 실행해서 입력 받고 결과 내고 끝나는 쪽에 가깝다.

harness는 계속 살아 있으면서 실패를 다시 붙잡는 쪽에 가깝다.

그러니까 승격 사다리는 대충 이렇다.

추천 승격 사다리

단계 언제 충분한가 한계가 오기 시작하는 신호
메모(md) 설명과 예시가 목적일 때 같은 질문이 계속 반복됨
체크리스트(md) 사람이 보고 판단할 때 판단 편차가 커짐
스니펫(script) 같은 명령을 매번 실행할 때 실패 복구가 없음
hooks + script 특정 이벤트마다 자동 반응할 때 장기 상태/복구가 필요함
harness 감시, 복구, 상태 지속이 필요할 때 이미 운영 시스템이 됨

이 표에서 핵심은 “더 멋져 보이니까 올린다”가 아니라 “사람 판단으로 버티기 어려워졌으니 올린다”다.

md에 남겨야 하는 것

1. 왜 이 규칙이 존재하는지

이건 코드가 못 담는다.

스크립트는 무엇을 할지, 어떻게 실패할지, 어떻게 막을지를 담을 수는 있어도

왜 이걸 선택했는지, 언제 예외를 허용하는지, 어디까지 자동화하면 안 되는지는 문서가 더 잘 담는다.

2. 예외와 맥락

이 경우엔 사람이 봐야 한다

이 조건이면 승인 루프를 거친다

이런 건 md가 더 잘한다.

3. 팀 합의 내용

누가 owner인지, 어디까지 권한이 있는지, 무엇을 금지하는지

이런 건 문서가 소스 오브 트루스다.

script로 올려야 하는 순간

1. 같은 판단을 세 번 이상 반복할 때

예를 들어

  • 커밋 전 특정 문자열 검사
  • 출력 길이 자르기
  • 파일 위치 규칙 검사
  • frontmatter 누락 점검

이런 건 사람이 체크리스트로 볼수록 실수 편차가 커진다.

세 번 넘게 반복되면 대체로 script로 올릴 가치가 생긴다.

2. 실패 기준이 명확할 때

맞다/아니다

막는다/통과시킨다

경고 띄운다/아무것도 안 한다

처럼 분기 조건이 단단하면 script로 빼는 게 좋다.

3. 이벤트 지점이 명확할 때

공식 hooks 문서처럼

  • PreToolUse
  • PostToolUse
  • FileChanged
  • SessionStart

같은 이벤트에 붙일 수 있으면 사람이 기억할 필요가 줄어든다.

이런 경우엔 문서보다 훅 + 스크립트가 더 낫다.

harness까지 올려야 하는 순간

1. 실패 후 다시 살아나야 할 때

스크립트는 실패를 알려준다.

하네스는 실패 후에도 다시 붙든다.

장기 작업, 백그라운드 루프, 감시형 자동화는 보통 여기서 갈린다.

2. 상태를 기억해야 할 때

세션을 끊었다가 다시 와도

  • 마지막 체크 시점
  • 누락된 작업
  • 다음 재시도 대상

같은 게 남아 있어야 하면 script보다 harness가 맞다.

3. 복구 루프가 필요한데 사람이 매번 붙기 싫을 때

이건 거의 확실하다.

사람이 계속 재시작 버튼을 눌러야 한다면 이미 문서 단계는 지났다.

제일 흔한 승격 실수

문서를 스크립트로 너무 빨리 올리는 것

이러면 팀이 아직 합의하지도 않은 규칙을 기계가 먼저 강제한다.

그 순간부터 도구가 똑똑해지는 게 아니라 사람이 짜증나기 시작한다.

스크립트로 올려야 하는 걸 문서에만 두는 것

반대로 이러면 문서는 두꺼워지고 실제 실행은 계속 사람 손에 남는다.

이 상태가 제일 나쁘다.

문서도 길고, 자동화도 약하고, 실수는 반복된다.

harness가 필요한데 shell snippet으로 버티는 것

이건 처음엔 가볍고 좋아 보인다.

근데 장기 실행, 실패 복구, 상태 지속이 들어오면 곧 shell script가 진흙탕 된다.

승격 판단표

질문 예 아니오
사람이 읽고 상황 판단해야 하나 md 유지 다음 질문
조건이 명확하고 반복되나 script 후보 md 유지
특정 lifecycle 이벤트에 붙일 수 있나 hooks + script 수동 실행 script
실패 후 자동 재시도가 필요한가 harness 후보 script 유지
상태 복원이 필요한가 harness script 또는 md

실제로 이렇게 보면 덜 헷갈린다

md로 남길 만한 것

  • 도입 가이드
  • 금지선 설명
  • 예외 상황
  • 정책 이유
  • 운영 철학

script로 올릴 만한 것

  • 링크 깨짐 검사
  • 출력 길이 제한
  • frontmatter 검증
  • 특정 파일 생성 규칙
  • 비용 로그 점검

harness로 올릴 만한 것

  • 주기 감시
  • 자동 재시작
  • 상태 파일 기반 이어달리기
  • 실패 누적 보고
  • 장기 백그라운드 운영

1인 운영 기준 최소 조합

혼자 굴리는 경우엔 처음부터 하네스 풀세트 깔 필요는 없다.

보통 이 조합이면 충분하다.

  1. AGENTS.md나 운영 허브 md
  2. 자주 쓰는 script 2~3개
  3. 꼭 필요한 hook 1~2개

그리고 아래 질문에 예가 생길 때만 harness를 붙이면 된다.

  • 매일 같은 시간에 반복된다
  • 실패 복구가 귀찮다
  • 상태를 이어서 봐야 한다

언제는 아예 안 붙여도 되나

증상 굳이 스크립트 안 붙여도 되는 이유
아직 팀 합의가 불안정함 문서가 먼저다
예외가 많고 맥락 판단이 큼 사람이 더 정확하다
한 달에 한 번 볼까 말까 함 자동화 비용이 더 크다
실패해도 큰 사고가 아님 md 체크리스트면 충분하다

자동화는 늘 멋져 보이지만 안 붙이는 것도 운영 실력이다.

실수 TOP

1. 멋있어 보여서 hooks부터 붙이는 것

문서 합의가 약하면 훅은 자동화가 아니라 자동 혼선이다.

2. runbook이 길어진다고 무조건 harness로 가는 것

길다고 다 harness 후보는 아니다.

재시작, 상태, 복구, 감시가 있어야 진짜 harness다.

3. script가 커졌는데 책임자는 없는 것

문서에서 owner를 안 박아두면 실행체는 금방 유령이 된다.

4. 정책 이유를 코드에만 숨기는 것

그러면 팀은 왜 막혔는지 이해 못 한다.

5. script와 hook과 harness를 같은 걸로 보는 것

trigger, execution, recovery는 역할이 다르다.

5분 셀프 체크

아래 질문에 예가 많을수록 md에서 script 또는 harness로 올릴 시점이다.

  • 같은 실수 예방 문구를 매일 반복하나
  • 같은 체크를 매번 손으로 하고 있나
  • 실패 시점이 명확한가
  • lifecycle 이벤트에 붙이면 편한가
  • 실패 후 복구까지 필요하나

셋 이상 예면 문서만으로 버티는 쪽이 더 비싸질 수 있다.

FAQ

Q1. playbook은 무조건 md로 남겨야 하나?

아니다.

정책과 이유는 md에 남기고, 반복 판단은 script로 올리는 혼합 구성이 제일 현실적이다.

Q2. hooks를 쓰면 script가 필요 없나?

아니다.

hooks는 언제 반응할지 정하는 트리거고, 실제 검사나 처리 로직은 script에 두는 편이 관리가 쉽다.

Q3. harness는 언제부터 과하지 않나?

실패 후 자동 재시작, 상태 저장, 복구 루프가 필요해질 때부터는 과한 게 아니라 맞는 구조다.

Q4. 팀이 작아도 분리해야 하나?

작을수록 더 그렇다.

작은 팀은 사람 한 명이 빠지면 문서와 실행체 경계가 더 빨리 무너진다.

Q5. 제일 먼저 스크립트화할 만한 건 뭐가 좋나?

반복 실수 방지 체크, 출력 길이 검사, frontmatter 검증, 비용 로그 경고처럼 판단 규칙이 단순한 것부터 올리는 게 좋다.

다음에 읽을 글

Sources