나는 AI 에이전트를 실제 프로젝트에 붙여 쓰는 과정을 반복하면서, 프롬프트가 아니라 워크플로우를 설계해야 한다는 인사이트를 얻었다. (참고) 그래서 14개 에이전트, 6단계 사고 모델, /start → /done 워크플로우까지 만들어 실제 프로젝트에서 돌렸다. 분명 잘 돌아갔는데, 문제가 있었다.

"git add -A 쓰지 마"라고 써놨는데 썼다.
"rm -rf는 위험하니까 실행하지 마"라고 했는데 실행했다.

프롬프트에 굵은 글씨로 절대 하지 말라고 적어놔도, 에이전트는 가끔 그냥 한다. 이게 프롬프트 엔지니어링의 한계다. 아무리 정교하게 써도, 결국 “부탁”일 뿐이다. 그래서 나는 부탁하는 걸 그만뒀다. 대신 에이전트가 실행되는 환경 자체를 설계하기 시작했다. 프롬프트가 아니라 시스템으로 통제하는 거다.

나중에 보니 업계에서는 이를 ‘하네스 엔지니어링’이라고 부르고 있었다. 하네스는 모델 바깥에서 에이전트가 어떻게 실행되고, 어떤 도구를 쓰며, 어디서 멈춰야 하는지를 통제하는 구조를 뜻한다. OpenAI가 올해 2월에 이 개념을 소개했고, 소프트웨어 아키텍처와 리팩토링 분야의 권위자 마틴 파울러도 이 주제를 다뤘다. 이 글은 그 여정에 대한 기록이다.

규칙이 많으면 에이전트가 오히려 못 따른다

6단계 사고 모델은 인지적 도제 이론에서 출발했다. 대장간에서 장인이 견습생을 가르치는 과정에서 착안했다. 시연하고, 코칭하고, 보조를 줄여가며, 독립시키는 흐름을 에이전트에 적용해 본 것이다. 읽고, 반응하고, 분석하고, 재구조화하고, 구조화하고, 성찰하는 흐름이다. 이론적으로는 깔끔했다.

근데 실무에서 세 가지가 터졌다.

토큰 낭비: 버튼 색상 바꾸는 건데 “현재 구조를 분석합니다...” 이러고 있더라. 이전에 “100개 규칙보다 1개의 올바른 원칙이 더 강력하다”고 느꼈는데, 사고 모델도 마찬가지였다.
경계 모호: READ와 REACT의 차이가 뭔가. 나도 설명이 애매한데, 에이전트가 구분할 수 있을까. 모호한 단계를 두면 “어디에 속하는지 판단하느라” 토큰을 써버린다.
실패 루프 없음: 검증에서 lint가 터지면? 처음부터 6단계를 다시 밟아야 하나. 실패했을 때 어디로 돌아갈지가 정의되어 있지 않았다.

4단계로 줄였더니

GROUND → APPLY → VERIFY
  ↑                 ↓
  └─── ADAPT ←──────┘
       (실패 시만)

GROUND: 먼저 코드를 읽는다. 기억에서 추론하지 않는다. 이게 가장 중요하다.
APPLY: 관찰한 패턴대로 구현한다. 5가지 불변 제약이 있다. 읽기 우선, 패턴 준수, 정책 보존, 최소 변경, 스코프 준수.
VERIFY: lint/tsc/테스트를 돌린다. 사람 눈이 아니라 도구로 확인한다.
ADAPT: 여기가 핵심이다. 6단계 모델에는 없던 것이다. VERIFY에서 실패하면 “왜 실패했는지”를 분석하고 GROUND로 돌아간다. 같은 원인으로 2번 실패하면 접근법을 바꾸고, 3번 실패하면 사람에게 판단을 넘긴다.

4개 파일 수백 줄이 1개 파일 99줄이 됐다. 에이전트는 오히려 더 잘 따랐다. 이 경험이 이후 모든 설계의 기준이 됐다. 복잡해지면 줄여라. 줄였는데도 잘 된다면, 원래 그만큼만 필요했던 거다.

팀에서 쓰려니까 전부 다 문제였다

사고 모델을 단순화하니까 더 큰 문제가 보였다. Emotion 패턴, Next.js Pages Router 가정, Jotai 컨벤션이 규칙 파일에 하드코딩되어 있었다.나 혼자 쓸 때는 괜찮았다. 하지만 팀에서 쓰려면 이야기가 달라진다. A 프로젝트는 Zustand를 쓰고, B 프로젝트는 Redux를 쓰며, 새 프로젝트는 Tailwind를 쓴다. Jotai 컨벤션이 박혀 있는 설정을 줘봐야 의미가 없다.

하드코딩을 모듈로 쪼갰다

그래서 스택 컨벤션을 modules/ 디렉터리로 추출했다. React, Vue, Jotai, Zustand, Emotion, Tailwind를 각각 독립된 파일로 분리하고, 프리셋으로 조합하는 구조로 바꿨다.

{
  "modules": {
    "framework": "react-nextjs-app",
    "state": "zustand-tanstack",
    "styling": "tailwind",
    "testing": "vitest"
  }
}

현재 13개 모듈이 있다. 프레임워크 3종, 디자인 시스템 2종, 상태 관리 3종, 스타일링 3종, 테스팅 2종이다. 목록에 없는 라이브러리가 감지되면 옵션에 자동으로 추가되고, 직접 입력도 가능하다. 에이전트와 사고 모델은 동일하게 두고, 스택만 바꾸면 된다.

그런데 배포가 문제였다

모듈을 분리하니까 이번엔 “어떻게 전파하지?”가 문제였다. 처음에는 에이전트 설정을 별도 Git 레포로 관리했다. 팀원들에게 “이 레포 주소 줄 테니까 클로드한테 주고, 지금 프로젝트에 맞게 설정해달라고 하면 됩니다”라고 했다.

당연히 사람마다 설정이 달라졌다. 그리고 더 큰 문제는 동기화였다. 설정 레포에서 에이전트 규칙을 업데이트해도, 이미 각 프로젝트에 복사해 놓은 파일은 구버전 그대로였다. “설정 레포 최신 커밋 읽어서 지금 프로젝트에 반영해줘”를 매번 해야 했다. PR 트리거나 GitLab 훅으로 자동 동기화까지 고민했지만, 근본적인 해결은 아니었다.

플러그인이라는 해결책

그러던 중 Claude Code가 플러그인을 공식 지원하기 시작했다. claude plugin install로 한 번 설치하면 끝이다. session-init.sh라는 SessionStart 훅이 세션을 열 때마다 리모트 버전을 확인하고, 변경이 있으면 자동으로 pull해서 업데이트한다. 배포 문제가 한 방에 해결된 거다.

그래서 모든 걸 플러그인으로 전면 교체했다. 이게 code-forge, AI 대장간의 시작이다. 기존 프로젝트에서 /setup을 실행하면 package.json을 읽어 스택을 자동 감지하고, profile.json에 기록한 뒤 그에 맞는 CLAUDE.md를 생성한다. 새 프로젝트라면 프리셋을 선택해 처음부터 세팅해준다.

에이전트를 "컴파일"하다: 대장장이의 탄생

컨벤션을 모듈로 분리하면서 동시에 떠오른 생각이 있었다. “모듈로 분리할 수 있다면, 에이전트도 조합하고 컴파일할 수 있지 않을까?”당시 읽고 있던 클린 아키텍처와 동료와의 대화에서 아이디어를 얻었다. 에이전트를 STATE(이 에이전트가 아는 것)와 ACT(이 에이전트가 하는 것)로 나누는 거다.

기존에는 에이전트 하나에 모든 걸 다 써야 했다. 14개 에이전트에 “React를 안다”, “TypeScript를 안다” 같은 내용이 중복으로 들어가 있었다. 하나를 바꾸려면 14개를 다 바꿔야 한다. 이건 앞서 컨벤션이 하드코딩되어 있었던 문제와 똑같은 구조였다.

STATE/ACT로 분리하면 이렇게 조합할 수 있다.

code-reviewer = lang.typescript + framework.react + quality.review
implementor   = lang.typescript + framework.react + dev.implement

이 조합 시스템을 Smith(대장장이)라고 이름 붙였다. 대장장이가 재료(STATE)와 기법(ACT)을 조합해 도구를 만들듯, Smith는 지식과 행동을 조합해 에이전트를 만든다. 만들어진 에이전트는 Anvil(작업대) 위에서 사용자와 함께 코드를 단조한다.

처음에는 런타임 해석 방식이었다. 매 세션마다 규칙 파일을 주입하고, spawn할 때마다 STATE 체인을 재귀적으로 재계산했다. 28개 파일을 이중으로 관리해야 했고, 권한(permissionMode)이 심링크에서 동작하지 않는 버그까지 발생했다.

그때 떠오른 생각이 단순했다.

TypeScript를 매번 런타임에 해석하는 사람은 없다. tsc로 .js를 만들어 놓고 쓰는 거지.

에이전트도 빌드타임에 컴파일하면 되는 거였다. /smith-build로 STATE+ACT 체인을 미리 계산해 정적 .md 파일로 만들어 두는 방식이다.

런타임 인프라를 전부 삭제했다. “복잡성을 제거”한 게 아니라, “복잡성을 빌드타임으로 옮긴” 것이다.

단일 진입점

“로그인 페이지 만들어줘”라고 하면 만들어준다. 그런데 문제는 매번 다르게 만든다는 거다. 어떤 때는 코드 분석부터 하고, 어떤 때는 바로 파일을 생성하고, 어떤 때는 테스트를 쓰고, 어떤 때는 안 쓴다. 워크플로우를 스킬로 만들어 놓으면 어떤 입력이 들어와도 같은 순서로 진행된다.

/start feature-login.md

MD 파일 하나면 된다. 이걸 주면 /start가 분석 → 디자인 확인 → 구현 → 테스트 → 린트 → 커밋 → PR까지 수행한다. 중간에 사용자가 확인하는 건 딱 두 번이다. “구현할까요?”, “커밋할까요?”

입력 형태도 가리지 않는다. MD 파일이든 Figma URL이든 이미지 캡처든, 같은 진입점으로 들어와 같은 워크플로우를 탄다. 여기까지가 프롬프트 레벨의 이야기다. 규칙을 만들고, 모듈로 나누고, 에이전트를 컴파일하고, 워크플로우를 정의했다. 그런데 이 모든 것이 “부탁”이라는 본질적 한계를 넘지는 못했다.

하네스 엔지니어링: 진짜 문제는 여기였다

여기서부터가 이번 글의 핵심이다. 워크플로우를 아무리 잘 만들어도, 프롬프트를 아무리 정교하게 써도, 에이전트가 “그냥 무시”하는 경우가 생긴다. 프롬프트는 결국 자연어다. 자연어로 된 지시는 강제력이 없다. 프롬프트가 쓸모없다는 게 아니다. 프롬프트만으로는 부족하다는 것이다.

그래서 하네스 엔지니어링으로 전환했다. 하네스(harness)는 원래 말에 씌우는 마구(馬具)라는 뜻이다. AI 에이전트의 출력을 원하는 방향으로 강제하는 전체 시스템 설계 기법이다. 프롬프트를 잘 쓰는 게 아니라, 에이전트가 실행되는 환경 자체를 설계하는 것이다.

핵심 주장은 하나다.

“프롬프트 엔지니어링만으로는 AI 출력을 강제할 수 없다. hooks라는 시스템 레벨 이벤트 핸들러로 무조건 실행되도록 강제해야 한다.”

Claude Code의 hooks는 에이전트의 생명주기(세션 시작, 도구 실행 전/후, 응답 완료 등)에 셸 스크립트나 LLM 판단을 끼워 넣을 수 있는 메커니즘이다. 에이전트가 Bash를 실행하려 할 때 guard.sh가 먼저 실행되어 위험한 명령을 차단하고, 파일 수정 후에는 lint-fix.sh가 자동으로 포맷을 맞추는 식이다.

하네스 3층 구조

code-forge의 하네스는 3층으로 구성된다.

Layer 1이 핵심이다. Claude든 Codex든 Cursor든, 어떤 모델이 코드를 작성하더라도 같은 시스템 레벨 가드레일이 적용된다. 프롬프트는 무시할 수 있어도 hooks는 무시할 수 없기 때문이다.

비유하자면 이렇다.

Layer 1(hooks): 건물의 소방 스프링클러. 누가 불을 질러도 자동으로 동작한다.
Layer 2(프롬프트): 건물 내 “금연” 표지판. 대부분은 따르지만 강제력은 없다.
Layer 3(에이전트): 각 방의 출입 카드. 권한이 없으면 들어갈 수 없다.

exit 0 스텁 5개에서 실동작 11개까지

솔직히 말하면, 처음에 hooks는 껍데기에 불과했다.

# guard.sh (Before)
#!/bin/bash
exit 0

4줄짜리 스텁 5개였다. “나중에 채우자”고 해놓고 몇 달을 그냥 뒀다. 하네스를 설계한다고 했지만, 실제로는 프롬프트 레벨에만 의존하고 있었던 것이다.

리팩터링을 하면서 기존 5개를 채우고, 6개를 더 만들었다.

guard.sh는 52줄이다. Claude Code 훅은 에이전트가 도구를 실행하기 직전에 JSON 형태로 입력을 넘긴다. 처음에는 단순 문자열 매칭으로 처리했지만, 리팩터링하면서 JSON을 파싱해 명령어를 정확히 추출하도록 바꿨다.

# guard.sh (After) — JSON 파싱 + 9개 위험 패턴 차단
COMMAND=$(echo "$HOOK_INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))")

# 차단 패턴 예시
if echo "$COMMAND" | grep -qE "git add \.|git add -A"; then
  echo "BLOCKED: git add . / -A 금지. 파일을 명시적으로 지정하세요."
  exit 2
fi

Prompt 핸들러: regex로 못 잡는 걸 LLM이 잡는다

여기서 흥미로운 게 하나 있다. 정규표현식으로 위험 명령을 차단하는 건 결국 “내가 생각한 패턴”만 막는다는 뜻이다. rm -rf /는 막는데 find / -delete는? git push --force는 막는데, 한국어로 “강제 푸시해줘”라고 하면?

Claude Code 훅에는 command 타입 말고, prompt 타입이 있다. 훅 자체를 LLM 호출로 처리하는 방식이다.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [
        { "type": "command", "command": "guard.sh" },
        { "type": "prompt", "prompt": "이 Bash 명령이 되돌리기 어려운 파괴적 작업인지 판단해라. 그렇다면 차단해라." }
      ]}
    ]
  }
}

command 훅은 속도가 빠르고 확실하다. 알려진 패턴은 즉시 차단한다. prompt 훅(haiku 기반)은 느리지만 의미를 이해한다. 두 개를 레이어로 쌓았다. regex가 놓치는 부분을 LLM이 잡는다.

새로운 이벤트 타입들: SubagentStop, PreCompact

SubagentStop은 서브 에이전트가 작업을 마쳤을 때 발생하는 이벤트다. 여기에 tsc를 걸었다.

왜 Stop이 아니라 SubagentStop인가. /start 워크플로우는 implementor, assayer 같은 서브 에이전트를 순차적으로 spawn한다. Stop은 세션 전체가 끝날 때 발생하는데, 그 시점에 tsc를 돌리면 이미 다음 단계가 진행 중일 수 있다. 각 에이전트가 끝날 때마다 타입 체크를 돌려야 오류를 즉시 잡을 수 있었다.

PreCompact는 컨텍스트 압축 직전에 발생한다. 긴 세션에서 Claude가 컨텍스트를 압축하면 작업 중간 상태가 날아가는 경우가 있었다. 여기에 pre-compact.sh를 달아 현재 브랜치, 미커밋 파일, 스테이지 상태를 스냅샷으로 주입한다. 압축 후에도 복귀 지점이 남는다.

lint-fix.sh도 채웠다. 파일 수정 후 exit 0으로 그냥 넘기던 것을, ESLint --fix + Prettier --write를 자동으로 실행하고 오류가 남으면 경고를 출력하도록 바꿨다.

Stop hook의 quality-gate.sh는 응답이 완료될 때마다 eslint --quiet와 tsc --noEmit를 실행한다. 에이전트가 아무리 “잘 됐다”고 해도 린터가 최종 확인하는 구조다.

이런 식으로 5개 스텁에서 11개 실동작으로 늘었고, 총 441줄이 됐다.

AGENTS.md: 멀티모델 컨벤션

hooks로 시스템 레벨을 잡았다면, AGENTS.md는 멀티모델 컨벤션을 담당한다. Claude Code만 쓰던 프로젝트에 Codex CLI를 투입하면 어떨까. 기존에는 CLAUDE.md를 읽지 못해서, 컨벤션을 모르는 상태로 코드를 작성했다. 그러면 린터가 터지거나 스타일이 달라지기도 했다.

AGENTS.md는 AAIF(Agentic AI Foundation) 표준에 맞춘 파일이다. OpenAI와 Anthropic이 2025년 12월 Linux Foundation에 공동 기증한 에이전트 설정 표준으로, Codex CLI와 Cursor가 네이티브로 읽는다.

CLAUDE.md (Claude 전용)
  └── @AGENTS.md 임포트

AGENTS.md (공용, AAIF 표준)
  └── Codex CLI ← 네이티브로 읽음
  └── Cursor   ← 네이티브로 읽음

/setup이 2개 파일을 동시에 생성한다. AGENTS.md에는 스택, 명령어, 컨벤션, 금지 규칙이 들어가고, CLAUDE.md는 이를 임포트한 뒤 Claude 전용 설정을 추가한다.

결과적으로 클로드를 쓰든, 코덱스를 쓰든, 커서를 쓰든 같은 하네스를 따르면 같은 아웃풋이 나온다.프롬프트 레벨(AGENTS.md)에서 안내하고, 시스템 레벨(hooks)에서 강제하는 구조다.

하나의 모델만 쓰면 맹점이 생긴다

하네스 엔지니어링과 함께 2026년의 핫 키워드가 하나 더 있다. 멀티모델이다. 혼자 만든 시스템에는 맹점이 생긴다. 같은 Claude 모델끼리는 비슷한 편향을 공유하기 때문이다. 나는 이걸 실제로 느꼈다. code-forge를 만들면서 가장 많이 쓰는 기능이 Agent Teams로 계획을 세울 때 Codex(GPT)에게 함께 검증을 맡기는 부분이었다.

Claude가 짠 구현 계획을 Codex에게 보여주면, 다른 시각에서 허점을 찾아낸다. 그것도 부족하다 싶으면 Critic 에이전트를 세워 심판을 보게 한다. 루프를 돌며 3라운드 토론을 붙이기도 한다. 경험적으로 확실했다. 하나의 모델이 혼자 결정할 때보다, 비판적 의견이 들어갔을 때 더 좋은 결과가 나온다.

그래서 멀티모델 지원이 필수라고 판단했다. Codex도 이 프로젝트의 사고 모델을 적용받고, 같은 하네스 안에서 돌아간다면 더 좋은 결과로 이어질 수 있지 않을까. 그게 앞서 말한 AGENTS.md가 나온 이유다. Claude만 읽는 CLAUDE.md가 아니라, 어떤 모델이든 읽을 수 있는 공용 표준이 필요했다.

실제 토론 사례

구조 검증 토론: Codex에게 프로젝트를 보여줬더니 CONDITIONAL REJECT가 왔다. “참조 파일 2개가 중복이고, @참조 매트릭스가 과도하다.” Critic(Claude Opus)이 반론했다. “무조건 줄이는 게 답이 아니다.” 이 토론으로 중복은 정리하되, 역할별 참조는 유지하는 균형을 찾았다.
v3.0 방향성 토론: Builder(실용) vs Visionary(비전) vs Critic(비판)의 3라운드였다. Critic의 한마디가 방향을 잡았다. “새로 만들 것은 최소한으로. 있는 것을 채우고 다듬는다.”

이 말이 hooks 실구현으로 이어졌다. “새로 만들 것”(새 기능)보다 “있는 것을 채우는 것”(스텁을 실동작으로)이 우선이었기 때문이다.

AI와의 토론도 사람과의 토론과 같은 구조를 따른다: 입장이 다른 참여자가 있어야 하고, 비판자가 있어야 하며, 최종 판단은 사람이 해야 한다.

이 멀티모델 협업도 결국 하네스의 한 층이다. 모델마다 다른 시각을 갖되, 같은 규칙 안에서 움직이게 만들어야 한다.

대장간 체계

대장간 메타포는 처음부터 의도한 것이 아니었다. 사고 모델을 설계할 때 떠올렸던 인지적 도제 이론을 시스템 전체로 확장하다 보니, 각 구성 요소에도 자연스럽게 이름이 붙었다.

Forge (대장간)     = code-forge 전체
Smith (대장장이)   = 에이전트 빌드 시스템 — 재료(STATE)와 기법(ACT)을 조합해서 도구(에이전트)를 단조
Blueprint (설계도) = 사고모델, 규칙 — 모든 작업의 기준이 되는 도면
Assayer (감정사)   = 테스트 생성/검증 — 결과물의 품질을 판별
Bellows (풀무)     = 사용량 로깅 + 통계 — 불의 온도를 감지하듯 사용 패턴을 관찰하여 개선 방향을 제시
Whetstone (숫돌)   = 코딩 연습 — 개발자의 실력을 갈고닦는 도구

컨셉이 먼저는 아니었다. “이 기능은 대장간의 어디에 해당하지?”라고 물으면 불필요한 기능이 걸러졌다. 네이밍이 설계 도구가 된 셈이었다.

코딩 근육은 따로 단련해야 한다

AI가 코드를 잘 짜주는 건 좋은데, 문득 불안해졌다. Copilot을 켜놓고 Tab만 누르다 보면 직접 코드를 치는 감각이 무뎌지기 마련이다.

Whetstone(숫돌)은 이 문제에 대한 답이다. 4단계 힌트 시스템으로, 처음에는 힌트를 많이 주고 점진적으로 줄이면서 독립 해결까지 끌어올린다. 이것도 하네스의 일종이다. 힌트라는 보조 장치를 점진적으로 제거하면서 개발자의 독립적인 문제 해결력을 키우는 구조다. 지금은 별도 플러그인으로 분리해 발전시키고 있다.

대장간이 완성되기까지

돌아보면 가장 큰 효과를 준 건 두 가지였다.

하나는 단순화다. 6단계 → 4단계. 수백 줄 → 99줄. 런타임 해석 → 빌드타임 컴파일.
다른 하나는 실동작이다. 껍데기를 실제 동작으로 채우는 것이다. exit 0 스텁을 9개 패턴을 차단하는 가드레일로 바꾸고, 문서에만 있던 Stop hook을 quality-gate.sh로 구현했다.

이 두 가지가 합쳐져 하네스 엔지니어링이 됐다. 단순하게 설계하고, 단순하게 채운다.

아직 만들고 있다

대장간은 한 번 지으면 끝이 아니다. 새로운 재료가 들어오면 도구도 바뀌고, 공정도 바뀐다. 나는 결국 나를 닮은 대장간을 만들고 싶었던 것 같다. 새로운 서비스를 만들 때도, 기존 서비스를 분석하고 유지보수할 때도, 어떤 재료가 들어와도 같은 품질의 결과물이 나오는 곳. 분석하고, 단조하고, 검증하고, 다듬는 모든 동작이 하나의 공정 안에서 돌아가는 곳이 필요했다.

글의 초반에도 말했듯이 프롬프트로 부탁하는 건 한계가 있다. 대장간의 답은 단순하다. 부탁하지 않는다. 환경이 강제한다. 화로에 불은 넣었다. 아직 꺼질 생각은 없다. 풀무도 더 키우고, 보안 스캔도 붙이고, 숫돌도 계속 갈아야 한다. 더 좋은 재료가 있다면 대장간 문은 항상 열려 있다.

<참고>

code-forge GitHub

<원문>

프롬프트 엔지니어링은 끝났다 — 하네스 엔지니어링으로 AI 에이전트를 길들인 이야기