reopt-module-contract

---
name: reopt-module-contract
description: When adding or replacing a module, tool, or function. API boundary design, external-system integration, defining an inter-agent interface. When you touch code whose input/output schema and refusal conditions are unclear.
---

# 모듈 계약 (Module Contract)

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

## 핵심 규칙

- 모든 모듈에 명시적 계약을 부여한다: 입력 스키마, 출력 스키마, 필요한 권한, 거절 조건, 실패 응답의 형태.
- 계약은 코드와 문서 양쪽에 살아 있어야 하고 위반은 런타임에서 감지 가능해야 한다.
- 모듈을 교체할 때는 계약 호환성을 먼저 검증한다.
- 사람을 위한 인터페이스에 투자하듯 ACI(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**: 계약 없는 배포 도구는 "개발에선 되는데 운영엔 권한이 없다" 같은 환경별 실패를 반복한다. 필요한 권한, 롤백 조건, 타임아웃을 계약에 선언하면 환경 간 일관성이 보장된다.

## 호출 예시

```
"Response Agent의 generate() 함수에 모듈 계약을 적용해줘.
지금은 계약 없이 문자열만 반환한다. 거절 조건(PII, 법률 자문)과 실패 모드
(confidence < 0.7)를 계약에 포함해줘."
```

## 관련 패턴

- 책임 분할 — 분리된 각 책임은 계약이 필요하다
- 평가와 가드레일 — 계약 위반의 런타임 검증