AI 에이전트가 만드는 일을 둘로 나눠서 봅니다. 기계가 정답을 채점할 수 있는 것과, 사람의 판단이 필요한 것. 앞의 것은 검증을 자동화하고 강제하고, 뒤의 것은 들어가기 전에 탐색 범위를 좁힙니다. 이 구분 하나가 워크플로 설계의 첫 질문입니다.
겪고 계신 문제가 이것들일 겁니다
에이전트로 개발하면서 자주 나오는 증상이 있습니다.
원하는 결과에 끝내 도달하지 못하고 어딘가 늘 구멍이 있습니다. 워크플로의 주도권을
잃어서 내 프로젝트가 어디로 가는지 블랙박스가 됩니다. 같은 문제가 계속 반복되고
매번 고치면서 스트레스를 받습니다. 에이전트가 자기 결과물의 문제를 못 잡아서 피드백
사이클에 매번 제가 끼어들어야 합니다. CLAUDE.md에 적어둔 걸 지키지 않습니다.
저는 이 문제들의 원인을 하나로 봅니다. 가드레일이 없기 때문입니다.
먼저 두 가지로 나눕니다
에이전트에게 시키는 일을 두 갈래로 나눠서 봅니다. 나누는 이유는 어느 쪽이냐에 따라 설계 방법이 아예 다르기 때문입니다.
결정적인 작업은 테스트가 통과하는지, 컴파일이 되는지, 타입이 맞는지, 빌드가 되는지 같은 것입니다. 정답이 하나라 기계가 채점할 수 있습니다.
비결정적인 작업은 아키텍처를 어떻게 가져갈지, 비즈니스 로직을 어떻게 설계할지, 어떤 기술 스택을 쓸지 같은 것입니다. 정답이 정해져 있지 않고 판단이 필요합니다.
| 무엇 | 어떻게 | |
|---|---|---|
| 결정적 | 테스트 · 타입 · 린트 · 빌드 | 검증을 자동화하고 강제한다 |
| 비결정적 | 구조 · 저장 방식 · 우선순위 | 들어가기 전에 탐색 범위를 좁힌다 |
결정적인 쪽에서 중요한 단어는 강제입니다. 에이전트가 다 됐다고 스스로 끝을 선언하게 두지 마세요. 끝났는지 아닌지는 우리가 세팅한 검증을 통과했느냐로 판단하게 해야 합니다.
확률에 맡기고 있는 것들
여기서 많이들 하는 실수를 하나 짚겠습니다.
CLAUDE.md에 지침을 잔뜩 넣어두셨을 겁니다. 그런데 에이전트가 그걸 매번 빠짐없이
지키던가요. 아닐 겁니다. 잘 지키는 것 같다가도 한 번씩 안 지킵니다. 컨텍스트가 차서
압축이 한 번 일어나면 현저하게 무시하기 시작하고요.
정말 반드시 지켜야 하는 규칙이라면 확률적인 지시에서 결정적인 구조로 옮겨야 합니다. 그 규칙을 안 지키면 작업을 못 끝내거나, 커밋이 안 되거나, PR을 못 합치게 만드는 방식으로요.
린트 규칙으로 강제할 수 있는 건 CLAUDE.md에 안 씁니다. 검증 과정에서 에이전트가
스스로 피드백 루프를 돌게 하면 됩니다. 조금 더 복잡한 것도 마찬가지예요. 아키텍처
의존성 경계나 공개 API 계약 같은 것도 스냅샷 테스트, 스키마 검증, 타입 수준의
계약으로 묶어두면, 무엇을 바꾸면 안 된다고 문서에 강조할 필요가 없어집니다.
확률적으로 다뤄야 한다고 생각했던 것들 중에 결정적으로 끌어올 수 있는 게 생각보다 많습니다.
에이전트가 스스로 돌게 합니다
에이전트에게 사용자 프로필을 수정하는 API를 하나 추가해달라고 했다고 합시다.
세팅이 없으면 코드를 쭉 짜고 추가했습니다 하고 끝납니다. 그러면 제가 서버를 띄워 호출해보고, 타입 에러가 나면 복사해서 다시 던져주고, 테스트가 깨지면 또 알려줘야 합니다.
이렇게 하지 않으려면 에이전트가 작업을 완료했다고 말하려면 검증까지 끝나야 그렇게 말할 수 있게 루프를 설계해야 합니다.
방법은 여러 가지입니다. 쉽게는 CLAUDE.md에 쓸 수도 있고요. 그런데 앞에서 말했듯이
확률적으로 도는 걸 결정적인 구조로 들여오는 편이 낫습니다. 클로드 코드 설정의 훅으로
이 루프를 강제하는 식으로요.
핵심은 하나입니다. 에이전트가 스스로 루프를 돌고 자기 결과물의 문제를 스스로 잡아내게 만드는 것. 그러지 않으면 우리는 영원히 결과물을 하나하나 확인해줘야 합니다.
같은 문제를 두 번 겪지 않는 구조
제일 스트레스받는 문제가 있습니다. 같은 버그가 계속 반복되고 매번 똑같은 걸 고치라고 말하는 것.
결론부터 말하면 반복되는 문제는 확률이 아니라 구조로 막아야 합니다.
같은 문제가 반복되면 생각을 전환할 시점입니다. 어떻게 하면 두 번 다시 이 문제가 반복될 수 없게 만들 수 있을까. 그 답은 앞에서 말한 것들로 이루어집니다. 테스트로 고정하거나, 커밋을 막거나, 타입으로 불가능하게 만들거나.
같은 문제를 두 번 겪지 않는 시스템을 만드는 것. 에이전트로 개발하는 내내 계속 고민해야 할 영역입니다.
정리
에이전트가 하는 일을 결정적인 것과 비결정적인 것으로 나눕니다. 결정적인 건 검증을 자동화하고 강제합니다. 비결정적인 건 들어가기 전에 탐색 범위를 좁힙니다.
확률적으로 다루던 것 중에 결정적으로 끌어올 수 있는 게 많습니다. 그렇게 만든 검증을 가지고 에이전트가 스스로 피드백 루프를 돌게 합니다. 한 번 겪은 문제는 다시 못 터지게 구조에 박아둡니다.
도구가 먼저가 아닙니다. 무엇을 결정적으로 강제하고 무엇의 확률 범위를 좁힐지, 그 구분으로 접근하는 것이 먼저입니다.
내 CLAUDE.md 를 결정적/비결정적으로 나눠서 점검해줘. 1. 지금 CLAUDE.md 에 적힌 규칙을 두 갈래로 분류해줘. - 기계가 채점할 수 있는 것 (테스트·린트·타입·빌드로 막을 수 있는 것) - 사람의 판단이 필요한 것 2. 첫 번째 갈래에 있는 것들은 무엇으로 옮기면 되는지 알려줘. 린트 규칙, 테스트, 커밋 훅 중에 어디가 맞는지. 3. 옮기고 나서 CLAUDE.md 에서 지워도 되는 줄을 짚어줘. 바로 고치지 말고 목록만 보여줘.