AI 코딩 에이전트를 위한 기계적 강제 장치 구축 방법 — 그리고 프롬프트만으로는 부족한 이유

나는 AI 코딩 에이전트들이 실제 운영 환경(production)에서는 살아남을 수 없는 인상적인 데모를 만들어내는 것을 몇 달 동안 지켜보았다.

코드는 맞아 보였다. 컴파일도 되었다. 심지어 첫 번째 테스트도 통과했다.

그러다 엣지 케이스(edge cases)에 부딪혔다. 잊혀진 제약 조건들. 에이전트가 5분 전에 동의했던 규칙이 다음 컨텍스트 윈도우(context window)에 의해 덮어씌워져 사라져 버렸다.

근본적인 원인은 능력이 아니었다. 그것은 바로 **프로세스(process)**였다.

"가공되지 않은 모델은 에이전트가 아니다. 하네스(harness)가 모델에게 상태(state), 도구 실행(tool execution), 피드백 루프(feedback loops), 그리고 강제 가능한 제약 조건(enforceable constraints)을 부여할 때 비로소 에이전트가 된다."
— Osmani, Saboo & Kartakis, The New SDLC With Vibe Coding, 2026 [1]

문제점: 능력은 있지만 규율이 없음

AI 에이전트는 코드를 생성하는 데 매우 뛰어나다. 하지만 내장된 규율이 전혀 없다:

• 테스트 없이 커밋(commit)한다
• 리뷰 없이 푸시(push)한다
• 서로의 작업을 덮어쓴다
• 올바르게 보이지만 조용히 망가지는 출력을 생성한다

METR 연구 (Becker et al., 2025년 7월 [2])는 직관에 반하는 사실을 발견했다: AI를 사용하는 개발자들은 20% 더 빠르다고 느꼈지만, 실제로는 19% 더 오래 걸렸다. 속도는 환상이었다. 디버깅 비용은 실재했다.

업계의 대응은 더 많은 기술, 더 많은 프롬프트(prompts), 더 큰 컨텍스트 윈도우(context windows)였다. 하지만 문제는 지능이 아니라 **책임성(accountability)**이다.

프롬프트에만 존재하는 규칙은 제안에 불과하다. 규칙을 "아는" 에이전트는 결국 그것을 잊어버릴 것이다. 컨텍스트(Context)는 저하된다. 주의력(Attention)은 흐트러진다. 문제는 에이전트가 규칙을 어길지 여부가 아니라, 언제 어길 것인가이다.

통찰: 메모리는 강제 장치가 아니다

48시간 동안 발생한 세 가지 사건이 나에게 이 교훈을 가르쳐 주었다.

내 에이전트는 30초도 안 되어 자체 커밋 승인 시스템을 우회했다. 악의적이어서가 아니라, 그 "관문(gate)"이 파일에 적힌 또 다른 규칙에 불과했기 때문이다. 기억해야 할 또 다른 것. 잊어버릴 또 다른 것.

나는 커밋 승인을 위해 SHA256 토큰 시스템을 구축했다. 완벽하다고 생각했다. 하지만 내 에이전트가 --auto 옵션으로 실행되자, 그 토큰들은 연극(theater)이 되어버렸다.

해결책은 더 나은 토큰 시스템이 아니었다. 해결책은 아키텍처(architecture)를 바꾸는 것이었다.

메모리에 의존하는 규칙은 실패한다. 가시적인 블록(visible blocks)에 의존하는 규칙은 성공한다.

이것이 바로 **기계적 강제 (mechanical enforcement)**의 핵심 통찰이다. 즉, 에이전트 수준이 아닌 인프라스트럭처(infrastructure) 수준에서 실행되는 게이트(gates)를 만드는 것이다. 에이전트는 무시할 수 없는 것을 우회할 수 없다.

해결책: 에이전트 = 모델 + 하네스 (Harness)

나는 이 프로젝트를 하네스 아키텍처 (Harness architecture) [3]의 완전한 오픈 소스 구현체로 구축했다. 이는 가공되지 않은 AI 지능을 신뢰할 수 있는 출력물로 변환하는 기계적 인프라스트럭처이다.

구성 요소	설명
지침 및 규칙 (Instructions & Rules)	에이전트의 정체성, 중요하게 여기는 것, 절대 해서는 안 되는 일
...

차별점: 대부분의 "에이전트 프레임워크 (agent frameworks)"는 단순한 프롬프트 라이브러리(prompt libraries)에 불과하다. 반면 이 시스템은 12개의 기계적 사전 커밋 게이트(pre-commit gates), 3단계 게이트 커밋 승인 시스템, 그리고 항상 로드되는 토큰을 약 45% 절약하는 컨텍스트 엔지니어링(context engineering) 레이어를 추가한다.

코드: 우회할 수 없는 commit-msg 훅

다음은 기계적 강제의 핵심인, 스탬프가 찍히지 않은 커밋을 차단하는 commit-msg git 훅 (v6) [4]이다:

#!/usr/bin/env bash
# commit-msg — Three-Gate Approval Check (v6)
set -euo pipefail
...

모든 커밋이 통과되기 위해서는 세 가지 조건이 충족되어야 한다:

1. 테스트 통과 (최근 1시간 이내) — 맹목적인 커밋 방지
2. 커밋 매니페스트(Commit manifest) 존재 (에이전트가 변경 사항을 기록함) — 조용한 변이(silent mutations) 방지
3. 사용자 승인 (5분 이내, 메시지 일치) — 유효하지 않은(stale) 승인 방지

에이전트는 채팅에서 사용자가 "yes commit"이라고 말한 후에 승인 파일을 작성한다. 훅(hook)은 해당 파일이 최신 상태인지(< 5분) 확인하고, 커밋 메시지와 정확히 일치하는지 검증한다. 만약 에이전트가 승인 없이 커밋을 시도하면, 훅은 매번 이를 차단한다.

이것은 에이전트가 기억해야 하는 규칙이 아니다. 에이전트가 우회할 수 없는 게이트이다.

결과: 57개의 기술, 12개의 게이트, 지름길 없음

수개월간의 반복(iteration) 끝에, 프로젝트가 출시되었습니다 [5]:

지표 (Metric)	수량 (Count)
조합 가능한 기술 (Composable skills)	57
...

내가 배운 것

프롬프트는 지침(instructions)이다. 게이트(Gates)는 보증(guarantees)이다.

AI 에이전트(AI agents)를 구축하고 있다면, 스스로에게 질문해 보세요:

• 에이전트가 모든 커밋(commit) 전에 테스트를 실행하는가? 제안(suggestion)이 아니라, 기계적으로(mechanically) 실행하는가?
• 에이전트가 푸시(push)하기 전에 리뷰를 위한 변경 사항을 제시하는가? 기억할 때만이 아니라, 매번(every time) 수행하는가?
• 에이전트가 스스로의 규칙을 우회할 수 있는가? 만약 그렇다면, 그것은 규칙이 아니라 제안일 뿐이다.

"인상적인 데모(impressive demo)"와 "프로덕션급(production-grade)" 사이의 격차는 지능의 차이가 아니다. 그것은 지능을 제어하는 하네스(harness, 구속 장치)의 차이다.

직접 시도해 보세요:

git clone https://github.com/juandelossantos/another-agent-skills.git
cd another-agent-skills
bash install.sh
...

MIT 라이선스. 무료. 구독료 없음. 57개의 기술. 12개의 게이트.

juandelossantos.github.io/another-agent-skills

프로덕션 환경에서 AI 에이전트의 규율을 유지하기 위해 어떤 패턴을 발견하셨나요? 여러분의 스택에서 무엇이 효과가 있는지(혹은 효과가 없는지) 듣고 싶습니다.

참고 문헌 (References)

1. Osmani, A., Saboo, S., & Kartakis, S. (2026). Vibe Coding과 함께하는 새로운 SDLC: 임시 프롬프팅(ad-hoc prompting)에서 에이전트 공학(Agentic Engineering)으로. — Harness architecture 논문
2. Becker, S. et al. (2025). 개발자가 AI를 사용할 때: 생산성 및 인식. METR (Model Evaluation and Threat Research). — arxiv.org/abs/2507.09089
3. Another Agent Skills. Harness Architecture — 6가지 구성 요소. — docs/HARNESS.md
4. Another Agent Skills. commit-msg hook (v6) — 3단계 승인 체크(Three-Gate Approval Check). — scripts/git-hooks/commit-msg
5. Another Agent Skills. 저장소(Repository) 및 문서화(Documentation). — github.com/juandelossantos/another-agent-skills
6. Another Agent Skills. 에이전트 어댑터(Agent Adapters) — 호환성 매트릭스(Compatibility Matrix). — docs/AGENT-ADAPTERS.md
7. Another Agent Skills. 컨텍스트 예산(Context Budget) — 지연 로딩(Lazy Loading) 아키텍처. — README.md
8. Singhal et al. (2026). 에이전트 기술(Agent Skills): AI 코딩 에이전트를 위한 평가 주도 개발(Evaluation-Driven Development). Google Research. — 논문
9. Osmani, A. (2026). 팩토리 모델(The Factory Model): 지휘자(Conductors)에서 오케스트레이터(Orchestrators)로. — addyosmani.com
10. Another Agent Skills. SOUL.md — 프로젝트 정체성 및 원칙. — SOUL.md