---
title: "GOVERNANCE.md"
description: "진단 결과를 바탕으로 제품의 구조적 약속을 GOVERNANCE.md로 문서화하는 가이드. 에이전트가 지켜야 할 경계와 불변식을 명시해 에이전틱 부채를 막는다."
canonical: "https://architecture.reopt.ai/ko/governance"
language: "ko"
alternate-markdown: "https://architecture.reopt.ai/governance.md"
site-index: "https://architecture.reopt.ai/llms.txt"
source: "reopt architecture"
---

# GOVERNANCE.md

> 진단 결과를 바탕으로 제품의 구조적 약속을 GOVERNANCE.md로 문서화하는 가이드. 에이전트가 지켜야 할 경계와 불변식을 명시해 에이전틱 부채를 막는다.

AGENTS.md가 AI의 행동 규칙을 정의하듯, GOVERNANCE.md는 제품의 구조적 약속을 정의한다. 진단(레이더) 결과를 바탕으로 아래 4개 영역을 작성하고, OCLS 루프를 돌 때마다 갱신한다.

## GOVERNANCE.md란

프로젝트 루트에 두는 한 장짜리 문서다. 누가 무엇을 소유하고, 어떤 조건에서 판단하며, 어떻게 협업하고, 무엇을 기준으로 개선하는지를 선언한다. 구조가 문서화되지 않으면 순환과 실행은 방향을 잃는다.

## Sections

Section order: 진단 스냅샷 → 소유 구조 → 판단 계약 → 협업 규칙 → 개선 기준. 누락 또는 순서 위반은 린터 룰에서 막힌다.

### 진단 스냅샷

Assessment Snapshot — /assessment 결과를 최상단에 요약한다

- 최종 진단 날짜와 선택한 프리셋을 기재한다.
- Top 3 우선 패턴과 점수를 나열한다. 어떤 패턴이 가장 시급한지 한눈에 드러난다.
- 핵심 긴장 관계 1-2개와 대응 가이드를 기재한다. 트레이드오프 의사결정의 근거가 된다.
- 추천 성숙도 단계를 요약한다. 지금 어디에 있고 다음은 무엇인지 짚는다.
- 전체 진단 리포트는 `docs/assessment-YYYY-MM-DD.md`로 보관하고 경로를 참조한다.

**템플릿 예시**

```markdown
## 진단 스냅샷

> 최종 진단: YYYY-MM-DD
> 프리셋: <프리셋 이름>
> 전체 리포트: docs/assessment-YYYY-MM-DD.md

### Top 3 우선 패턴
1. **<패턴명>** (<점수>/100)
2. **<패턴명>** (<점수>/100)
3. **<패턴명>** (<점수>/100)

### 핵심 긴장 관계
- <긴장 설명> — <대응 가이드>

### 추천 성숙도
**Stage N — <단계명>**
```

### 소유 구조 (OWN)

OWN — 누가(사람 또는 AI) 어떤 결과를 소유하는가

- 제품의 핵심 결과물과 각 결과물의 소유자를 나열한다.
- 소유자가 사람인지 AI인지 명시한다. 소유 주체에 따라 계약의 엄격도가 달라진다.
- AI 소유: 모든 판단 조건을 명시해야 하고 가드레일과 에스컬레이션이 필수다.
- 사람 소유: 맥락적 판단이 가능하지만 판단 기준을 문서화해야 팀이 공유한다.
- 소유자가 불명확한 영역(회색 지대)을 식별하고 배정한다.

**템플릿 예시**

```markdown
# 소유 구조

| 결과물 | 소유자 | 유형 | 거버넌스 수준 |
|--------|--------|------|-------------|
| 문의 분류 | Intake Agent | AI | 계약 기반 자동 실행, 오분류 시 사람 에스컬레이션 |
| 응답 품질 | Response Agent | AI | 가드레일 + 사후 QA 검토 |
| 환불 승인 (50만원 초과) | CS 매니저 | 사람 | 사전 승인 필수 |
| 비용 한도 준수 | Ops 팀 | 사람 | 일간 대시보드 모니터링 |
| 규제 준수 | Compliance Officer | 사람 | 외부 감사 대응 |
```

### 판단 계약 (CONTRACT)

CONTRACT — 어떤 조건에서 어떤 판단을 내리는가

- 각 실행 단위의 입력 조건, 출력 형식, 거절 조건을 선언한다.
- 자동 승인 / 사후 검토 / 사전 승인의 분류 기준을 정의한다.
- 실패 시 복구 경로와 폴백 동작을 명시한다.

**템플릿 예시**

```markdown
# 판단 계약

## 분류 기준
- 자동 승인: 비용 < 10만원, 기존 정책 범위 내
- 사후 검토: 비용 10만~50만원, 신규 케이스
- 사전 승인: 비용 > 50만원, 법적 책임, 고객 약속

## 거절 조건
- PII 포함 응답 → 차단
- 경쟁사 비교 발언 → 에스컬레이션
```

### 협업 규칙 (LAYER)

LAYER — 주체 간 정보 전달과 승인 흐름

- 주체 간 정보 전달 시 포함/제외할 컨텍스트 범위를 정의한다.
- 협업 순서와 의존 관계를 명시한다.
- 병렬 실행 가능한 영역과 순차 의존 영역을 구분한다.

**템플릿 예시**

```markdown
# 협업 규칙

## 정보 전달 범위
- 분류 → 응답: 카테고리, 감정 분석, 이전 대응 이력
- 응답 → QA: 응답 초안, 참조한 정책, 판단 근거
- QA → 운영: 품질 점수, 위반 항목, 개선 제안

## 의존 관계
- 분류 완료 → 응답 시작 (순차)
- 응답 + 비용 계산 (병렬)
- QA는 모든 응답에 비동기 실행
```

### 개선 기준 (SHARPEN)

SHARPEN — 무엇을 측정하고 언제 구조를 보정하는가

- 핵심 품질 지표와 목표치를 정의한다.
- 비용 추적 단위와 예산 한도를 설정한다.
- 구조 보정을 촉발하는 시그널(리뷰 주기, 임계값)을 명시한다.

**템플릿 예시**

```markdown
# 개선 기준

## 핵심 지표
| 지표 | 목표 | 리뷰 주기 |
|------|------|----------|
| 응답 정확도 | > 95% | 주간 |
| 토큰 비용/건 | < 500원 | 일간 |
| 에스컬레이션율 | < 5% | 주간 |

## 보정 시그널
- 정확도 < 90% 3일 연속 → 소유 구조 재검토
- 비용 예산 80% 도달 → 모델 배정 재조정
- 신규 거절 패턴 10건 이상 → 계약 갱신
```

## 린터 룰

각 룰은 governance-reviewer 스킬이 PR diff에서 검출한다. error는 머지 전 해소가 원칙, warning은 리뷰 코멘트로 남긴다.

| 룰 | 강도 | 검사 대상 |
| --- | --- | --- |
| `missing-section` | error | §01–§05 중 하나 이상이 비어 있음 |
| `section-order` | error | OWN → CONTRACT → LAYER → SHARPEN 순서 위반 |
| `authority-sprawl` | warning | OWN 섹션에 권한 범위가 선언되지 않음 |
| `contract-gap` | error | CONTRACT 섹션에 input·output·reject_when 누락 |
| `observability-gap` | warning | LAYER 섹션에 trace·log 명세 누락 |
| `validation-gap` | error | SHARPEN 섹션에 metric·임계값·리뷰 주기 누락 |
| `broken-ref` | error | frontmatter의 참조가 본문에서 정의되지 않음 |

→ [룰을 직접 돌려보기](https://architecture.reopt.ai/ko/governance/lint.md)

## 머신 가독 frontmatter

사람용 마크다운과 동등한 YAML 표현. 본문은 사람을, frontmatter는 린터·코딩 에이전트를 향한다. 두 표현이 어긋나면 broken-ref가 발생한다.

## 근거 — 왜 OCLS인가

네 개 원칙이 OCLS 4페이즈로 구현된다. 페이즈 순서는 원칙 순서를 그대로 잇는다.

- **기능이 아니라 책임 단위로 설계한다** — 에이전트는 함수 호출기가 아니라 결과를 끝까지 책임지고 설명하는 주체다.
- **모듈은 호출 가능한 도구가 아니라 계약을 지키는 실행 단위다** — 모듈에 계약이 있어야 평가, 교체, 권한 제어, 테스트가 가능해진다.
- **확장은 분류하고 구조화해 거버넌스할 때 가능하다** — 에이전트가 늘어날수록 카테고리·계층·경계로 구조화해야 거버넌스가 유지되고 확장도 이어진다.
- **아키텍처는 운영 중 진화하는 시스템이다** — 실패 로그와 평가 결과를 보고 책임 경계와 정책을 계속 조정한다.

## 관련 패턴

각 거버넌스 약속을 어떤 구현 패턴으로 만들 수 있는지. 패턴명을 누르면 카탈로그 항목으로 이동한다.

## 완성된 예시

고객 상담 AI 제품을 기준으로 작성한 GOVERNANCE.md 전체 예시. 프로젝트 루트에 이 파일을 두고 OCLS 루프를 돌 때마다 갱신한다.

---

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