---
title: "reopt-module-contract — 모듈 계약"
description: "모듈을 추가하거나 변경할 때 사용하는 Claude Code 스킬. 코드 예제와 함께 입출력 계약, 거절 조건, 실패 처리를 검토한다."
canonical: "https://architecture.reopt.ai/ko/skills/reopt-module-contract"
language: "ko"
alternate-markdown: "https://architecture.reopt.ai/skills/reopt-module-contract.md"
site-index: "https://architecture.reopt.ai/llms.txt"
source: "reopt architecture"
---

# reopt-module-contract — 모듈 계약

> 모듈을 추가하거나 변경할 때 사용하는 Claude Code 스킬. 코드 예제와 함께 입출력 계약, 거절 조건, 실패 처리를 검토한다.

- **Category:** Pattern Skills
- **설치:** `.claude/skills/` ← `skills/patterns/reopt-module-contract/SKILL.md`
- **Source:** `skills/patterns/reopt-module-contract/SKILL.md`

이 레포의 파일을 당신의 프로젝트에 복사하면 Claude Code 세션에서 바로 활성화된다.

## SKILL.md

# 모듈 계약 (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)를 계약에 포함해줘."
```

## 관련 패턴

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

## 연결된 패턴

- [Module Contract — 모듈 계약](https://architecture.reopt.ai/ko/patterns/module-contract.md)

---

_이 문서는 https://architecture.reopt.ai/ko/skills/reopt-module-contract 의 마크다운 표현이다. 전체 색인: https://architecture.reopt.ai/llms.txt HTML 원본: https://architecture.reopt.ai/ko/skills/reopt-module-contract · English: https://architecture.reopt.ai/skills/reopt-module-contract.md_