AI 코딩 에이전트 하네스, 어떻게 설계할 것인가

AI 코딩 에이전트를 실무에 붙이고 나면 금방 이런 질문에 부딪힌다.

AGENTS.md에 얼마나 많이 써야 하지? 너무 적으면 에이전트가 실수하고, 너무 많으면 느려지고 엉뚱한 짓을 한다.

정답은 없다. 하지만 판단 기준은 만들 수 있다.

먼저 짚어야 할 것: AGENTS.md는 무엇을 하는 파일인가

AGENTS.md는 많은 코딩 에이전트가 작업을 시작할 때 우선 참고하는 프로젝트 지침 파일에 가깝다. 여기 들어간 내용은 대체로 모든 작업에 반복적으로 소비되는 컨텍스트가 된다.

여기서 두 가지 상반된 압력이 생긴다.

• 많이 쓸수록: 에이전트가 프로젝트를 더 잘 이해하고 실수를 덜 한다
• 적게 쓸수록: 지금 작업에 집중하고 판단이 선명해진다

어느 쪽이 맞냐는 프로젝트 상황에 따라 다르다.

언제 AGENTS.md를 두껍게 써도 되는가

이런 상황이라면 풍부한 컨텍스트가 더 낫다.

프로젝트 고유의 암묵적 규칙이 많을 때. 디렉토리 구조, 네이밍 컨벤션, 특정 패턴을 피해야 하는 히스토리적 이유 같은 것들은 코드만 봐서는 알 수 없다. 이런 내용은 에이전트가 매번 알아야 한다.

에이전트를 가끔 쓸 때. SKILL.md를 잘게 나누는 구조는 셋업과 유지보수 비용이 든다. 자주 안 쓰는 환경에서는 그 비용이 효과를 넘어버린다.

혼자 또는 소규모 팀일 때. 구조를 정교하게 설계할 시간보다 그냥 써서 결과를 내는 게 더 중요한 상황이 있다.

이런 경우 AGENTS.md는 이 정도면 충분하다.

# AGENTS.md

- 패키지 매니저: pnpm
- 테스트: pnpm test 실행 후 완료 보고
- apps/web이 메인 앱, packages/ui가 컴포넌트 라이브러리
- .env 파일 절대 수정 금지
- 새 의존성 추가 전 반드시 승인 받기
- 디자인 시스템 변경은 docs/design-system.md 먼저 확인

짧고 실용적이다. 규칙이 많지 않고 작업 유형도 단순하다면 이 정도로 잘 돌아간다.

언제 인덱스 구조가 효과적인가

반대로 이런 상황이라면 얇은 AGENTS.md와 분리된 SKILL.md 구조가 빛을 발한다.

작업 유형이 명확하게 나뉠 때. 코드 리뷰, 버그 수정, 신규 기능, 리팩토링처럼 작업마다 판단 기준이 다르다면, 공통 규칙과 작업별 절차를 분리하는 게 에이전트에게도 사람에게도 깔끔하다.

여러 명이 함께 에이전트를 쓸 때. 팀 단위로 같은 워크플로우를 공유하고 독립적으로 개선할 수 있다.

에이전트를 자주, 반복적으로 쓸 때. 초기 설계 비용을 감당할 만큼 반복 효과가 생긴다.

이 경우 AGENTS.md는 공통 규칙과 라우팅 테이블만 들고 있고:

# AGENTS.md

## 항상 따를 것

- 작은 단위로 변경하고, 코드 수정 전 의도를 먼저 설명할 것
- 완료 전 검증 명령 실행할 것
- 새 의존성 추가나 인증/배포 설정 변경은 승인 후 진행

## 작업별 워크플로우

| 작업 유형 | 참고 파일 |
|---|---|
| 버그 수정 | skills/bugfix/SKILL.md |
| 코드 리뷰 | skills/code-review/SKILL.md |
| UI 컴포넌트 | skills/design-system-component/SKILL.md |
| 신규 기능 | skills/feature-dev/SKILL.md |

실제 절차는 각 SKILL.md가 들고 있다. Anthropic이 Agent Skills 설계 원칙으로 설명하는 점진적 공개(Progressive Disclosure)가 바로 이 구조다. 처음부터 모든 정보를 쏟아붓는 대신, 지금 작업에 필요한 파일만 그때 읽는 방식이다.

# skills/bugfix/SKILL.md

1. 재현 조건 확인 후 실패하는 테스트 먼저 작성
2. 최소한의 변경으로 수정
3. 관련 엣지케이스 확인
4. pnpm test 실행 후 완료 보고

# skills/code-review/SKILL.md

1. 변경된 파일을 보고 의도한 동작 파악
2. 테스트가 동작 변경을 커버하는지 확인
3. 엣지케이스와 위험한 가정 확인

## 출력 형식

### 판정: APPROVED / REVISE

### 블로킹 이슈 / 논블로킹 메모

여기서 말하는 인덱스 구조는 거창한 것이 아니다. AGENTS.md 안에 모든 절차를 직접 적는 대신, 어떤 작업에서 어떤 문서나 스킬을 봐야 하는지만 안내하는 방식이다.

예를 들어 코드 리뷰 체크리스트 전체를 AGENTS.md에 넣기보다, “코드 리뷰는 skills/code-review/SKILL.md를 따른다”고 적는 식이다. 디자인 시스템 컴포넌트 작성 규칙도 마찬가지다. 모든 작성 규칙을 한 파일에 몰아넣기보다, docs/design-system.md와 skills/design-system-component/SKILL.md를 보도록 연결하는 편이 낫다.

결국 인덱스형 AGENTS.md의 역할은 실행 절차를 모두 설명하는 것이 아니라, 에이전트가 지금 작업에 맞는 지침으로 빠르게 이동하게 만드는 것이다.

Hooks는 구조 문제가 아니라 신뢰 문제다

AGENTS.md를 얼마나 쓰느냐와 별개로, hooks는 다른 층위의 이야기다.

지침은 에이전트에게 “이렇게 해줘”라고 부탁하는 것이고, hooks는 “이건 절대 안 돼”를 시스템이 직접 잡는 것이다. Claude Code, OpenAI Codex 같은 도구들이 hooks를 지원하는 이유도 여기에 있다. 에이전트 실행 중 특정 시점(PreToolUse, PostToolUse, Stop 등)에 셸 명령을 끼워넣어 자동으로 검사하고 차단하는 방식이다.

다만 hooks도 공짜가 아니다. 셋업 비용, 유지보수, 팀원 온보딩까지 감안해야 한다. hooks를 쓸 가치가 있는 경우는 꽤 구체적이다.

• .env, 인증 키, 배포 설정처럼 실수했을 때 되돌리기 어려운 파일을 건드리는 패턴이 생겼을 때
• 테스트나 린트를 건너뛰고 완료 보고를 하는 일이 반복될 때
• 여러 사람이 쓰는 환경에서 일관성을 사람이 아닌 시스템이 보장해야 할 때

이 조건에 해당하지 않는다면 AGENTS.md에 주의사항을 적는 것으로 충분한 경우도 많다.

민감 파일 수정 차단 (PreToolUse)

파일을 수정하거나 Bash를 실행하기 직전에 검사한다. AGENTS.md에 “건드리지 마라”고 적어두는 것보다 훨씬 강한 통제다.

아래 예시는 Claude Code의 .claude/settings.json 스타일에 맞춘 간단한 의사 코드다. 실제 구현에서는 hook이 전달하는 tool input JSON을 파싱해 대상 파일이나 실행 명령을 추출해야 한다.

# .claude/hooks/protect_sensitive_files.py
# 예시용 의사 코드입니다. 실제 hook input JSON에서 대상 파일을 추출해야 합니다.
import sys
from fnmatch import fnmatch

PROTECTED = [".env", "*.pem", "terraform.tfstate"]

target_file = get_target_file_from_tool_input()

if any(fnmatch(target_file, pattern) for pattern in PROTECTED):
    print("민감 파일 수정 차단됨")
    sys.exit(1)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/protect_sensitive_files.py"
          }
        ]
      }
    ]
  }
}

완료 전 검증 강제 (Stop)

수정된 파일이 있는데 테스트를 실행한 기록이 없으면 완료 보고를 막고 루프로 되돌려보낸다.

# .claude/hooks/require_verification.py
# 예시용 의사 코드입니다. 실제 구현에서는 git diff와 hook 실행 기록 등을 기준으로 판정해야 합니다.
import sys

if modified_files_exist() and not verification_was_run():
    print("검증 명령을 먼저 실행하세요: pnpm test")
    sys.exit(1)

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/require_verification.py"
          }
        ]
      }
    ]
  }
}

한 가지 주의할 점은 hooks를 완전한 보안 경계로 보면 안 된다는 것이다. 프롬프트 지침보다는 강하지만, 샌드박스나 권한 정책 자체를 대체하지는 않는다. hooks는 권한 설정, 승인 정책과 함께 하네스의 한 계층으로 보는 편이 맞다.

정리하면

하네스 설계에 정답은 없다. 지금 프로젝트가 어느 단계인지, 에이전트를 얼마나 자주 쓰는지, 팀이 몇 명인지에 따라 최적 구조가 달라진다. 처음부터 완벽한 구조를 만들려 하기보다, 불편한 지점이 생길 때 하나씩 추가하는 게 현실적으로 더 잘 작동한다.

참고 자료

• AGENTS.md — 에이전트를 위한 README처럼 프로젝트 지침을 제공하는 파일 포맷 소개
• Anthropic Agent Skills — 필요한 정보를 단계적으로 로드하는 Progressive Disclosure 개념 설명
• Claude Code Hooks Guide — PreToolUse, PostToolUse, Stop 등 에이전트 실행 시점에 hooks를 거는 방식 설명
• OpenAI Codex Hooks — 에이전트 생명주기 중 deterministic script를 실행하는 hooks 프레임워크 설명

• #Agent Skills
• #AGENTS.md
• #AI 에이전트
• #Claude Code
• #Codex
• #Hooks
• #개발 생산성
• #코딩 에이전트
• #하네스 엔지니어링