REOPT
ARCHITECTURE
AI 에이전트 아키텍처: 설계 패턴과 거버넌스
AI 에이전트 아키텍처는 에이전트가 내릴 수 있는 판단, 호출할 도구, 접근할 컨텍스트, 실행을 중단하거나 복구할 조건을 정한다. reopt architecture는 동작하는 에이전트를 책임 있게 운영할 수 있는 시스템으로 발전시키려는 팀을 위한 실무 참조서다.
도구 권한, 사람의 승인, 평가 기준, 비용 한도를 갖춘 AI 에이전트를 설계한다. 8개 아키텍처 패턴, GOVERNANCE.md 템플릿, 구현 사례를 함께 제공한다.
막아야 할 실패에서 시작한다
워크플로 하나와 가장 큰 손실을 일으킬 실패를 고른다. 해당 패턴으로 아래 산출물을 만들고, 에이전트의 권한을 넓히기 전에 경계를 검증한다.
에이전트가 승인 없이 데이터를 변경한다
행동의 제안과 실행을 분리한다. 승인 대상을 정확한 작업과 인자에 연결하고, 실행 시점에 권한을 다시 검증한다.
산출물: 승인 기록과 변경되거나 만료된 요청을 거절하는 테스트.
사람의 승인 설계하기재시도와 도구 호출이 예산을 넘는다
실행마다 예산과 중단 조건을 정한다. 도구 내부의 모델 호출과 재시도도 같은 비용 경계에 포함한다.
산출물: 실행 예산과 소진 시 실행이 멈추는지 확인하는 테스트.
에이전트 비용 제한하기실패한 실행을 아무도 설명하지 못한다
사용자 요청, 에이전트 버전, 도구 호출, 승인, 결과를 하나의 추적 ID로 연결한다. 기록에서 가릴 데이터도 정한다.
산출물: 비밀정보를 노출하지 않고 실패한 행동을 재구성하는 실행 기록.
판단을 추적 가능하게 만들기
설계 예제: 환불을 제안하는 고객 지원 에이전트
운영 성과를 측정한 사례가 아닌 설계 예제다. 에이전트는 접근 권한이 있는 주문을 읽고 환불을 제안한다. 결제 작업은 별도 실행기가 담당하며, 결과의 책임은 고객 지원 책임자에게 둔다.
| 경계 | 구현 결정 | 검증할 실패 |
|---|---|---|
| 권한 | 에이전트에는 read_order와 propose_refund를 제공한다. execute_refund는 서버 권한 검사 뒤에서 실행한다. | 프롬프트나 도구 인자가 결제 작업을 직접 호출하려 한다. |
| 승인 | 제안에 주문, 금액, 통화, 요청자, 승인자, 만료 시각을 저장하고 실행 전에 다시 검사한다. | 승인 후 금액이 바뀌거나, 승인이 만료되거나, 다른 테넌트의 주문이 전달된다. |
| 복구 | 승인된 작업에 멱등 키를 사용한다. 결제 결과가 불확실하면 재시도 전에 처리 상태를 대조한다. | 결제사가 환불을 접수했지만 응답이 타임아웃된다. |
| 평가 | 쓰기 권한을 부여하기 전에 거절, 만료, 테넌트 불일치, 중복 요청을 검증하고 실행 기록을 남긴다. | 모델의 그럴듯한 응답은 리뷰를 통과하지만 실제 행동은 규칙을 위반한다. |
이 결정을 GOVERNANCE.md에 쓰고 도구 핸들러와 테스트에서 강제한다. 정책 문서나 프롬프트 지시만으로 결제 작업의 경계를 강제할 수는 없다.
5단계 방법론
진단
현재 상태를 객관화한다
기술·사업 17개 속성으로 제품의 요구사항과 구조적 리스크를 스캔한다. 팀이 같은 결과를 보면서 우선순위를 합의하는 것이 첫 단계다.
Product Assessment정의
구조적 약속을 문서화한다
진단 결과를 GOVERNANCE.md로 고정한다. 소유 구조, 판단 계약, 협업 규칙, 개선 기준 — 네 가지를 선언하면 순환과 실행의 방향이 잡힌다.
GOVERNANCE.md 가이드순환
OCLS 4단계로 구조를 보정한다
- OWN소유결과의 소유자를 정한다 — 사람인지 AI인지에 따라 거버넌스가 달라진다
- CONTRACT계약판단 조건과 경계를 선언한다 — AI 소유일수록 계약이 엄격해야 한다
- LAYER계층제품 구조를 계층화하고 확장한다
- SHARPEN보정운영 결과로 구조를 개선한다
실행
패턴으로 설계 결정을 내린다
상황마다 맞는 패턴을 골라 설계 결정을 내린다. 책임 분할, 모듈 계약, 컨텍스트 라우팅 — 8개 패턴이 던지는 판단 질문에 팀이 답할 때, GOVERNANCE.md의 선언이 실제 설계로 옮겨진다.
패턴 카탈로그평가
결과를 측정하고 반복한다
실행 결과를 에이전틱 부채 관점에서 평가한다. GOVERNANCE.md를 갱신하고, 다시 진단(1단계)으로 돌아간다. 이 순환이 반복될수록 구조가 선명해진다.
다시 진단하기구현 기록과 현장 경험
방법론의 배경이 된 코드 예시, 설계 결정, 한계를 확인한다. 저자가 보고한 경험이며 다른 시스템에서도 같은 결과가 난다는 근거는 아니다.
Reopt Agentic Governance 구현기: 진단에서 시스템까지
8개 AI 에이전트를 운영하는 프로덕션 SaaS에서 reopt architecture 원칙으로 거버넌스 공백을 진단하고, 범용 감사 로깅, 영속적 승인 기록, MCP 추적·속도 제한, 에이전트 제약, Admin 대시보드까지 구현한 과정.
프로젝트끼리 비교하며 설계를 배우는 법
개발 원칙이 다른 프로젝트를 함께 운영하고, 문제를 먼저 해결한 프로젝트를 기준으로 현재 설계를 리뷰한다. 차이에서 개선 가설을 찾아 검증하고 기록하는 교차 설계 리뷰 절차를 정리한다.
Claude Code로 reopt architecture 5단계 실행하기
진단→정의→순환→실행→평가 방법론을 Claude Code의 CLAUDE.md 자동 로드, slash command, sub-agent, skill에 매핑하여 실제 레포에 적용하는 실전 가이드.
시스템에 필요한 부분부터 적용한다
결정적인 워크플로에는 모듈 계약, 책임자, 실패 테스트만 필요할 수 있다. 열린 판단이 필요한 작업에 에이전트 위임을 도입하고, 권한 경계를 넘는 행동에 승인을 추가한다. 이 참조서는 특정 에이전트 프레임워크에 종속되지 않으며 규정 준수 인증을 제공하지 않는다.