reopt-module-contract

---
name: reopt-module-contract
description: 새 모듈·도구·함수를 추가하거나 교체할 때. API 경계 설계, 외부 시스템 통합, 에이전트 간 인터페이스 정의. 입출력 스키마와 거절 조건이 불명확한 코드를 만졌을 때.
---

# 모듈 계약 (Module Contract)

OCLS 단계: **CONTRACT** · 실행 단위의 조건, 권한, 실패 경로를 계약으로 선언한다.

## 핵심 규칙

- 모든 모듈에 명시적 계약을 부여한다: 입력 스키마, 출력 스키마, 필요 권한, 거절 조건, 실패 시 반환 형태.
- 계약은 코드와 문서 양쪽에 존재하며, 위반은 런타임에서 감지 가능해야 한다.
- 모듈 교체 시 계약 호환성을 먼저 검증한다.
- 사람 인터페이스에 투자하듯 에이전트 인터페이스(Agent-Computer Interface)에도 투자한다 — Poka-yoke 원칙(잘못 사용하기 어렵게 설계).

## 판단 질문

**이 모듈은 어떤 조건에서 거절하거나 실패해야 하는가?**

## 적용 체크

1. 입력/출력 스키마가 명시되어 있는가?
2. 거절해야 하는 입력은 무엇인가?
3. 실패 시 반환 형태는? 호출자는 이를 어떻게 감지하나?
4. 필요 권한 범위는 어디까지인가?

## 코드 예시

```typescript
// ✅ 명시적 계약을 가진 모듈
interface GenerateReplyContract {
  input: {
    category: string;
    context: string;
    tone: "formal" | "casual";
    maxTokens: number;
  };
  output:
    | { ok: true; response: string; confidence: number; sources: string[] }
    | { ok: false; reason: "rejected" | "failed"; code: string };
  authority: { read: ["knowledge-base"]; write: [] };
  rejects: [
    "category === 'legal-advice'",
    "context.length > 10000",
    "PII detected in context",
  ];
}

async function generateReply(
  input: GenerateReplyContract["input"],
): Promise<GenerateReplyContract["output"]> {
  if (input.category === "legal-advice") {
    return { ok: false, reason: "rejected", code: "LEGAL_ADVICE" };
  }
  // ... 실행
}
```

## 안티패턴

**고객 상담**: 계약 없이 운영하면 "LLM을 바꿨더니 응답 형식이 달라져 QA Agent 파싱 실패", "새 모듈이 법률 자문에도 답해 컴플라이언스 이슈" 같은 문제가 발생한다.

**DevOps**: 계약 없는 배포 도구는 "dev 환경에서는 동작하는데 prod에서는 권한 부족"처럼 환경별 실패가 반복된다. 필요 권한·롤백 조건·타임아웃을 계약에 명시하면 환경 간 일관성이 보장된다.

## 호출 예시

```
"Response Agent의 generate() 함수에 Module Contract를 적용해줘.
현재 계약 없이 string을 반환한다.
거절 조건(PII 포함, 법률 자문)과 실패 모드(신뢰도 < 0.7)를 계약에 포함해."
```

## 관련 패턴

- Responsibility Partitioning — 분할된 책임 경계마다 계약 필요
- Evaluation and Guardrails — 계약 위반의 런타임 검증