Claude Code로 reopt architecture 5단계 실행하기

진단→정의→순환→실행→평가 방법론을 Claude Code의 CLAUDE.md 자동 로드, slash command, sub-agent, skill에 매핑하여 실제 레포에 적용하는 실전 가이드.

개요 — 방법론에서 도구로

reopt architecture는 AI 제품을 다섯 단계(진단→정의→순환→실행→평가)로 돌려 구조를 만드는 방법론이다. 문제는 이 순환을 주간 회의록이나 PPT 같은 오프라인 산출물에만 의존하면, 실제 커밋·PR·에이전트 동작에 규율이 스며들지 않는다는 것이다. Claude Code는 이 방법론을 일상 개발 도구에 박아 넣는 통로가 된다.

Claude Code가 제공하는 네 가지 확장점 — CLAUDE.md 자동 로드, slash command, sub-agent, skill — 을 5단계와 매핑하면 거버넌스가 곧 실행 가능한 워크플로가 된다. 아래는 실제 레포에 1사이클을 돌리는 최소 가이드다.

전제 — 저장소 구조

먼저 저장소 루트에 다음 경로를 확보한다. 모두 버전 관리 대상이다.

<repo-root>/
├── CLAUDE.md                       # 세션 시작 시 자동 로드
├── GOVERNANCE.md                   # reopt architecture 4섹션
├── docs/
│   └── assessment-YYYY-MM-DD.md    # 진단 결과 타임스탬프 보관
└── .claude/
    ├── commands/
    │   ├── ocls-review.md          # 03 순환 slash command
    │   └── debt-audit.md           # 05 평가 slash command
    ├── agents/
    │   └── governance-reviewer.md  # sub-agent 정의
    └── skills/
        └── reopt-module-contract/
            └── SKILL.md            # 8패턴 중 하나의 skill

01 진단 — 현재 구조를 객관화한다

두 경로를 병행한다. 팀이 직접 슬라이더를 조작하는 UI 진단과, Claude가 코드베이스를 직접 스캔하는 자동 진단이다. 두 결과가 어긋나면 그 간극 자체가 다음 단계의 입력이 된다.

팀: 사이트 /assessment에서 기술·사업 16개 속성 슬라이더를 조작하고 결과 화면을 docs/에 캡처.
Claude Code: 레포를 16개 속성으로 평가하고 각 속성마다 코드 근거와 점수(1-10)를 인용하도록 요청. 결과를 docs/assessment-YYYY-MM-DD.md로 저장.

# 프롬프트 예시
이 레포를 reopt 16개 속성으로 평가해줘.
기술축: 보안, 신뢰성, 규제준수, 품질검증, 응답성능, 데이터의존도,
        확장규모, 비용민감도, AI자율도
사업축: 매출기여도, 사용자접점, 출시압박, 업무복잡도, 이해관계자,
        의사결정영향, 시장성숙도, 시장규모

각 속성마다:
- 점수(1-10)
- 근거가 되는 파일·라인 인용
- 예상 긴장관계(속도↔규제, 비용↔신뢰성 등)

최종 결과는 docs/assessment-<today>.md로 저장.

Claude가 Grep·Read로 스캔하며 속성별 점수·긴장관계·우선 패턴을 리포트한다. 이 리포트가 다음 단계인 GOVERNANCE.md의 소스가 된다.

02 정의 — GOVERNANCE.md를 작성하고 주입한다

진단 결과를 4섹션(OWN / CONTRACT / LAYER / SHARPEN)으로 선언한다. 사이트 /governance 페이지의 템플릿을 Claude에 전달하면 현재 레포 상태에 맞춰 초안을 생성한다.

그 전에 먼저 /assessment에서 진단 결과를 export한다. 두 버튼을 사용해 스냅샷과 전체 리포트를 얻는다.

'GOVERNANCE.md 요약 복사' — Top 3 우선 패턴, 핵심 긴장, 추천 성숙도를 담은 마크다운 블록이 클립보드에 복사된다. GOVERNANCE.md 최상단의 '진단 스냅샷' 섹션에 붙여넣는다.
'전체 진단 리포트 다운로드' — 16개 속성 점수, OCLS 단계 점수, 8개 패턴 우선순위, 긴장 관계 전체를 담은 파일이 생성된다. docs/assessment-YYYY-MM-DD.md로 저장해 다음 사이클의 진단 입력으로 삼는다.

# 프롬프트 예시
docs/assessment-2026-04-17.md와 사이트 /governance 템플릿을 바탕으로
GOVERNANCE.md를 작성해줘. 4섹션:

1. 소유 구조 (OWN) — 결과물별 소유자(사람/AI) 표
2. 판단 계약 (CONTRACT) — 각 주체의 입출력·거절·실패 경로
3. 협업 규칙 (LAYER) — 정보 전달 범위, 의존·병렬 관계
4. 개선 기준 (SHARPEN) — 지표·임계값·리뷰 주기

핵심은 이 파일이 Claude Code 세션의 매 호출마다 참조되도록 묶어두는 것이다. CLAUDE.md에 파일 참조를 추가하면 프로젝트의 모든 Claude Code 대화가 자동으로 거버넌스를 로드한다.

# CLAUDE.md (프로젝트 루트)

이 레포의 구조적 계약은 @GOVERNANCE.md에 선언되어 있다.
모든 코드 제안은 해당 문서의 OWN / CONTRACT / LAYER / SHARPEN
섹션을 준수해야 한다. 승인 분류, 거절 조건, 비용 한도를
우회하는 변경을 생성하지 않는다.

@GOVERNANCE.md

CLAUDE.md의 @파일참조는 세션 시작 시 해당 파일을 자동 로드한다.

03 순환 — OCLS 체크리스트를 slash command로

OCLS 4단계 검증을 하나의 명령어로 캡슐화한다. .claude/commands/ocls-review.md에 검증 프롬프트를 두면 세션에서 /ocls-review만 입력해도 체크리스트가 돌아간다.

---
description: "현재 변경사항을 OCLS 4단계로 검증"
---

방금 변경된 파일(git status)을 OCLS 관점으로 검토해라.

**OWN**: 새 결과물이 있다면 소유자(사람/AI)가 GOVERNANCE.md
소유 구조에 등록되어 있는가?

**CONTRACT**: 새 모듈·도구·에이전트의 입출력, 거절 조건,
실패 모드가 계약에 명시되어 있는가?

**LAYER**: 협업 규칙이 깨지지 않았는가? 컨텍스트 전달 범위가
필요 최소한인가?

**SHARPEN**: 측정 지점(로그·메트릭)이 추가되었는가?
운영 데이터가 SHARPEN 루프로 흐르는가?

위반 항목을 체크리스트로 나열하고 각각에 대한 패치 제안을 줘라.

.claude/commands/ocls-review.md — /ocls-review 호출 시 실행되는 프롬프트

정규 PR 검증용으로는 sub-agent를 별도 정의한다. 범용 세션은 main agent가, 거버넌스 검증은 특화 sub-agent가 담당하도록 책임을 분할한다 — Responsibility Partitioning 패턴 그대로다.

---
name: governance-reviewer
description: "PR이나 브랜치의 변경사항을 reopt architecture 관점으로 리뷰. PR 리뷰 시 자동 또는 수동 호출."
tools: [Read, Grep, Glob, Bash]
---

당신은 reopt architecture의 OCLS 4단계와 8패턴에 정통한
거버넌스 리뷰어다. @GOVERNANCE.md의 선언을 참조 기준으로 삼아
다음 네 가지 시그널을 확인한다.

- 권한 확산(Authority Sprawl)
- 계약 공백(Contract Gap)
- 관측 부재(Observability Gap)
- 검증 부족(Validation Gap)

발견한 부채는 에이전틱 부채 4종으로 분류하고 OCLS 단계별
조치를 제안해라.

.claude/agents/governance-reviewer.md — sub-agent 프론트매터 + 지침

04 실행 — 패턴을 skill로 등록하고 호출한다

8패턴을 skill로 등록하면 Claude가 상황 트리거에 맞춰 해당 패턴 가이드를 자동으로 로드한다. 패턴별 skill 파일은 사이트의 patterns 컨텐츠(context·problem·forces·solution·antiPattern)를 그대로 프롬프트화한다.

---
name: reopt-module-contract
description: "모듈·도구·함수의 입출력·권한·거절 조건·실패 모드를 계약으로 선언하는 패턴. 새 도구 등록, API 경계 설계, 외부 시스템 통합 시 트리거."
---

Module Contract 패턴 요약:
- 모든 모듈에 입력 스키마, 출력 스키마, 필요 권한, 거절 조건,
  실패 시 반환 형태를 명시한다.
- 계약은 코드와 문서 양쪽에 존재해야 한다.
- 계약 위반은 런타임에서 감지 가능해야 한다.
- 계약 없이 모듈을 교체하거나 새 모듈을 추가하지 않는다.

적용 체크:
1. 이 모듈의 입력 스키마는?
2. 어떤 입력을 거절해야 하는가?
3. 실패 시 반환 형태는? 호출자는 이를 어떻게 감지하나?
4. 필요 권한 범위는 어디까지인가?

.claude/skills/reopt-module-contract/SKILL.md

팀의 일상 프롬프트는 개념 설명이 아닌 판단 질문 형태로 써야 한다. Claude가 skill을 로드하면 해당 패턴의 forces와 antiPattern까지 맥락에 올라온다.

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

# 나쁜 예
"이 함수 정리해줘"

05 평가 — 에이전틱 부채 감사와 갱신

스프린트 종료 시점에 에이전틱 부채 4종(권한 확산·계약 공백·관측 부재·검증 부족)으로 부채 리포트를 생성한다. 이 결과는 GOVERNANCE.md를 갱신하고 다음 진단 사이클로 넘어가는 입력이 된다.

---
description: "최근 스프린트의 에이전틱 부채 감사"
---

지난 2주간의 커밋(git log --since=2.weeks)과 운영 지표를 바탕으로
에이전틱 부채를 감사해라.

1. **권한 확산**: 에이전트·도구 권한 범위가 암묵적으로 확장된 사례
2. **계약 공백**: 추가되었지만 계약이 없는 모듈·에이전트
3. **관측 부재**: 로그·트레이스가 누락된 결정 경로
4. **검증 부족**: 평가 기준이 없는 출력 경로

각 부채에 대해:
- 발생 지점(파일:라인)
- OCLS 단계(OWN/CONTRACT/LAYER/SHARPEN)
- GOVERNANCE.md 갱신 제안
- 우선순위(High/Medium/Low)

출력은 docs/debt-<today>.md로 저장해라.

.claude/commands/debt-audit.md

생성된 부채 리포트를 다음 주 진단(01)의 입력으로 사용한다. 이렇게 하면 방법론의 5단계가 문서상 순환이 아니라 실제 파일 타임스탬프가 순환하는 구조로 동작한다.

1사이클 체크리스트

팀이 reopt architecture 1사이클을 완주하는 최소 체크리스트. 2주 스프린트 기준이다.

Day 1 — /assessment에서 팀 진단, Claude에 16개 속성 평가 요청, docs/assessment-YYYY-MM-DD.md 저장.
Day 1 — 진단 결과를 바탕으로 GOVERNANCE.md 생성, CLAUDE.md에 @GOVERNANCE.md 참조 추가.
Day 2-10 — 일상 개발 시 /ocls-review를 PR마다 호출. sub-agent governance-reviewer로 정규 검증.
Day 2-10 — 새 모듈·에이전트 추가 시 reopt-* skill을 명시적으로 호출하거나 판단 질문 프롬프트로 트리거.
Day 10 — /debt-audit로 2주간 부채 리포트 생성.
Day 10 — 부채 리포트로 GOVERNANCE.md 갱신. 다음 사이클 Day 1로 복귀.

결론 — 방법론이 살아 있게 하는 조건

reopt architecture의 핵심 주장은 구조가 곧 거버넌스라는 것이다. 이 주장이 현실이 되려면 거버넌스가 회의록이나 위키가 아니라 개발자가 매일 쓰는 도구 안에 있어야 한다. CLAUDE.md의 @참조 한 줄이 모든 세션에 GOVERNANCE.md를 로드하고, slash command 두 개(/ocls-review, /debt-audit)가 순환과 평가를 일상화하며, sub-agent와 skill이 책임과 패턴을 구현 시점에 주입한다.

방법론의 5단계 각각이 Claude Code의 기능 하나와 묶일 때, 문서는 활자로 남지 않고 실행되는 구조가 된다. 속도는 AI가 보장한다. 구조는 이 루프가 보장한다.

태그

claude-codeworkflowOCLSgovernancemethodology