shared-mental-model

name	shared-mental-model
description	에이전트 팀의 Shared Mental Model(공유 정신 모델)을 _workspace/SMM.md 파일로 구축·유지하는 스킬. 팀이 시작할 때, 팀원 간 산출물이 어긋날 때, 용어/인터페이스/목표를 합의해야 할 때 반드시 사용. 'SMM', '공유 정신 모델', '단일 진실 원천', '팀원 간 정합성', '인터페이스 합의' 요청 시 트리거. Team Big Five 조율 메커니즘 1.

Shared Mental Model — 팀의 단일 진실 원천

Team Big Five의 첫 번째 조율 메커니즘. 팀원들이 과제·역할·상호작용을 같은 방식으로 이해하게 만드는 공유 문서다. SMM이 없으면 팀원들은 같은 단어를 다르게 해석하고, 산출물 경계면이 어긋난다.

왜 필요한가

에이전트 팀의 최대 실패 원인은 "각자 똑똑하지만 서로 다른 가정으로 작업해서 합쳐지지 않음"이다. SMM은 이 가정들을 한 곳에 고정해 모든 팀원이 같은 그림을 본다. 명령이 아니라 공유된 이해이므로, 팀원은 SMM을 읽고 스스로 올바른 판단을 한다.

파일에 쓰는 것만으로는 공유가 아니다 — 작성된 SMM일 뿐이다. 공유는 킥오프 브리핑에서 각 팀원이 자기 책임 영역을 **재진술(read-back)**할 때 성립한다 (오케스트레이터 Phase 2 참조).

과제 유형별 적응 (Task-type adaptation)

SMM은 코드 과제만의 도구가 아니다. "경계면 계약"의 내용이 과제 유형에 따라 달라진다 — 메커니즘은 같고 채우는 항목이 다르다. 리더는 Phase 1에서 과제 유형을 먼저 판별하고 해당 행을 채운다.

과제 유형	경계면 = "계약"의 내용	핵심 SMM 섹션
코드/설계	I/O 스키마, API shape, 타입/시그니처, 데이터 형식	§4 인터페이스, §7 파일 소유권
리서치/분석	사실 원장(주장→출처), 용어 정의, 분석 단위·기간, 인용 양식	§4, §8 사실 원장, §2 용어집
보고서/문서	문서 개요(섹션 책임), 용어, 독자·목적, 인용/근거 규칙	§3 작업 맵, §6 스타일/보이스, §2
창작(소설/세계관)	캐릭터 보이스 시트, 세계관 사실(canon), 타임라인, POV·시제	§6 스타일/보이스, §8 사실/canon
마케팅/카피	포지셔닝·핵심 메시지, 브랜드 보이스, 금칙어, CTA 일관성	§6 스타일/보이스, §1

코드가 아닌 과제에서 §4는 스키마가 아니라 위 표의 해당 계약을 기술한다. §6·§8은 창작·리서치·문서·마케팅 과제에서 필수, 코드 과제에선 생략 가능.

SMM 파일 구조 (_workspace/SMM.md)

# Shared Mental Model

## 1. 공유 목표 + 완료 기준 (Goal + Definition of Done)
{측정 가능한 팀 목표 한 줄}
완료 기준 — 체크 가능한 수용 기준 목록 (rubric):
- [ ] {객관 게이트가 있으면: 예) `npm test` exit 0, `tsc --noEmit` clean, 빌드 통과}
- [ ] {주관 산출물이면: 예/아니오로 판정 가능한 수용 기준 3~6개}
      예) "모든 핵심 주장에 출처가 달렸는가", "주인공 보이스가 5개 장면에서 일관되는가"

## 2. 용어집 (Glossary)
| 용어 | 정의 | 정의한 팀원 |
|------|------|-----------|
{해석이 갈릴 수 있는 핵심 용어만 — 코드 타입명, 창작 신조어, 리서치 term-of-art}

## 3. 작업 맵 (Task Map)
| 작업 | 담당 | 결정권자 | 의존 | 산출물 경로 | 상태 |
{누가 무엇을 하고, 누가 그 영역의 계약을 확정할 권한이 있고(decision rights), 무엇에 의존하는지}

## 4. 인터페이스/계약 (Interfaces / Shared Conventions)
{팀원 A의 출력이 팀원 B의 입력이 되는 모든 경계면. 과제 유형별 적응 표 참조}
| 경계면 | 계약 (shape/규칙) | 버전 | 신뢰 등급 | 생산자 | 소비자 |
|--------|------------------|------|----------|--------|--------|
- 코드 과제: 계약은 prose가 아니라 실제 스키마 파일로 — TS interface / OpenAPI / JSON Schema
  를 `_workspace/contracts/`에 두고 여기서 경로로 참조. method·path·status·error shape·nullability 명시.
- 버전: 계약 변경 시 증가. 하위 산출물의 "검증됨"은 이 버전에 묶인다 (아래 무효화 규칙).
- 신뢰 등급: verify-once | verify-on-change | re-verify-each-round — 경계면의 *결과 영향*으로 결정.

## 5. 결정 로그 (Decisions)
| 날짜 | 결정 | 사유 | 영향받는 팀원 |
{타인에게 영향 주는 *팀 결정*. 충돌 해결은 삭제 대신 출처 병기로 기록}

## 6. 스타일/보이스 (Style & Voice)  ※ 산문·창작·마케팅 과제 필수, 코드 생략
{합의된 톤·문체·POV·시제·서식·인용 양식. 코드의 인터페이스 계약에 해당하는 산문 계약}
| 규칙 | 내용 | 강도 |
|------|------|------|
{강도: [hard]=위반 시 차단 / [soft]=탐색 허용, 권고만. 예: canon 사실=[hard], 보이스 실험=[soft]}

## 7. 파일 소유권 (File Ownership)  ※ 코드 과제 필수
| 파일/디렉터리 | 단독 소유자 | 공유 위험 |
{contributor별 쓰기 경계. >1명이 같은 파일을 만지면 공유 위험 표기 → 직렬화 또는 단독 소유자 지정}

## 8. 사실 원장 / Canon (Facts & Canon)  ※ 리서치·창작 과제 필수
| 사실/주장 | 출처 | 신뢰도 | 강도 | 정의한 팀원 |
{단일 진실 원천. 두 팀원이 모순된 수치·플롯 사실을 주장하지 못하게. 충돌은 출처 병기}

## 9. 리스크/대응 (Risks & Contingencies)
| 위험 가정 | 틀리면 영향 | 사전 대응(fallback) |
{틀리면 재계획을 강제하는 상위 1~2개 가정 + 대비책. monitor가 이를 명시적으로 감시}

## 10. 미해결 질문 / 이견 (Open Questions & Dissent)
{아직 합의 안 된 사항 + 팀원이 제기한 불확실성·이견(FLAG-UNCERTAIN / DISSENT).
 해결되면 결정 로그로 이동. 리더가 적응 체크포인트마다 triage — 방치 금지}

섹션은 과제에 맞게 취사. 코드 과제는 1·3·4·5·7·9·10, 창작 과제는 1·2·3·5·6·8·9·10 중심.

운영 규칙

시점	행동
팀 시작	리더가 SMM을 초기화 — 과제 유형 판별 후 목표·완료기준(rubric)·작업 맵·결정권·알려진 계약·리스크를 채운다
킥오프 브리핑	각 팀원이 자기 책임 슬라이스를 read-back ACK → SMM이 공유됨을 보장
작업 단위 시작 전	모든 팀원이 SMM을 Read하여 자기 계약·의존·신뢰 등급을 확인
타인에게 영향 주는 결정 시	결정한 팀원이 SMM(계약/결정 로그)을 즉시 갱신 + 영향받는 팀원에게 폐쇄 루프로 통보
계약 버전 변경 시	버전 증가 → 그 계약에 의존하던 하위 산출물의 "검증됨"은 무효화, 재검증 대상으로 표기
불확실/이견 발생 시	팀원이 §10에 FLAG-UNCERTAIN/DISSENT 등재 — 추측으로 덮지 않는다
적응(계획 변경) 시	리더가 SMM을 먼저 갱신한 뒤 팀에 브로드캐스트 — SMM이 항상 현재 계획을 반영
충돌 발견 시	삭제하지 않고 결정 로그/사실 원장에 출처 병기, 리더가 중재

신뢰 등급과 검증 무효화 (Calibrated Trust)

• 신뢰는 이진(재작업 금지/허용)이 아니라 계약별 등급이다. 등급은 그 경계면이 틀렸을 때의 비용으로 정한다 — 부담 큰/되돌리기 어려운 경계면은 re-verify, 가벼운 건 verify-once.
• 검증은 계약 버전에 묶인다. 의존 계약이 갱신되면 하위 "검증됨"은 자동 무효 → 재검증. 코드에서 계약 변경이 하위 전부를 무효화하는 현실과 일치.
• 검증 후 반복해서 OK인 경계면은 등급을 낮출 수 있다(획득된 신뢰). 이것이 신뢰 보정 루프다.

왜 이렇게 하는가 (원리)

• 단일 진실 원천 하나만 — 진실이 여러 곳에 흩어지면 곧 어긋난다. SMM 한 파일만 권위를 가진다.
• 결정은 영향받는 사람에게 통보 — 갱신만 하고 알리지 않으면 폐쇄 루프(메커니즘 2)가 끊긴다. SMM 갱신과 통보는 한 쌍이다.
• 계약을 코드/규칙 수준으로 — prose "shape"는 nullable·enum·error shape를 못 잡는다. 가능하면 실제 스키마/규칙으로.
• 용어집을 가볍게 유지 — 모든 단어가 아니라 해석이 갈릴 단어만. 과적합 금지.
• 하드 vs 소프트 구분 — 사실·canon·계약은 [hard]로 지키되, 보이스·플롯 탐색은 [soft]로 풀어 창의를 죽이지 않는다.

안티패턴

• 산출물 본문에 가정을 묻어두고 SMM에 안 올림 → 다른 팀원이 못 봄
• SMM을 읽지 않고 기억에 의존 → 갱신된 인터페이스를 놓침
• 리더만 SMM을 갱신 → 결정의 출처가 흐려짐. 결정한 팀원이 갱신한다
• 출처 없는 사실 주장을 사실 원장에 등재 → 신뢰가 무근거 주장을 세탁. 무출처는 §10으로
• 코드 과제에서 계약을 prose로만 기술 → 경계면 버그의 근원. 스키마 파일로