# 하네스: Ubisam 산출물

## 목표

프로젝트 산출물을 Ubisam 협업관리(칸반) 6단계 양식으로 구성·생성·재생산·검증한다.
산출물 트리는 `docs/[Ubisam산출물]/` 하위에 미러링한다(로컬 전용 — `.gitignore` 제외 대상).

## 트리거 — 어느 스킬을 쓰는가

입력이 무엇이냐로 갈린다.

| 입력 | 요청 예시 | 스킬 |
|---|---|---|
| **없음** (트리부터) | "산출물 구조 만들어줘", "트리 스캐폴딩" | `ubisam-deliverables` |
| **PTOP 소스코드** | "소스 기준으로 설계 산출물 최신화", "PLC 신호정의서 갱신" | `ptop-deliverables` |
| **기존 타사 문서** | "이 xlsx를 Ubisam 양식으로 바꿔줘", "타사 산출물 재생산" | `ubisam-deliverable-rebuild` |
| **조회만** | "상태 enum이 뭐였지", "6단계 슬롯 알려줘" | `ubisam-format-map` |

렌더링 전용 스킬: `.pptx` → `ubisam-ppt-make`, `.docx` → `ubisam-docx`(**사용자 전역 스킬 — 이 저장소에는 없음**),
화면 도식 이미지 → `ui_layout_image`.

## 재생산 하네스 팀 구성 (`ubisam-deliverable-rebuild`)

| 에이전트 | 담당 | 산출 (`docs/[Ubisam산출물]/_workspace/`) |
|---|---|---|
| `ubisam-analyst` | 원본 구조 해부·타설비 잔재 식별·6단계 슬롯 매핑 | `01_analyst_{문서}.md` |
| `ubisam-producer` | 매핑표대로 xlsx·pptx·md 재생산·출처 기입 | `02_producer_{문서}.md` + 산출물 파일 |
| `ubisam-qa` | 원본↔매핑표↔산출물 교차 대조·enum·잔재·출처 검증 | `03_qa_{문서}.md` |

**실행 모드:** 서브 에이전트 + **점진적 생성-검증 루프**.
producer가 문서 1건을 끝낼 때마다 qa가 즉시 검증한다 — 구조적 결함이 늦게 발견되면
이후 산출물 전부를 되돌려야 하기 때문이다.

기동은 `Agent`(`model: "opus"`), 소통은 `SendMessage`, 진행 공유는 `_progress.md` 파일.
이 환경에 `TeamCreate`/`TeamDelete`는 없다.

## 불변 규칙

- **enum 고정** — 상태 4종·유형 9종은 `ubisam-format-map`이 단일 기준. 임의 변형 시 칸반 조건부서식이 깨진다.
- **출처 명시** — 채운 값마다 `— 출처: 파일:심볼`. qa가 이걸로 검증한다.
- **추측 금지** — 진실원이 없으면 `(제안)` 또는 `미정 — 확인 필요`.
- **추론 표기** — 확인 전 서술은 문장 앞에 `[추론]` (`rules.md` #15·#16). 아래 축으로 구분하며
  `[추론]`은 나머지를 **대체하지 않는다**(필요하면 병기):

  | 상황 | 표기 |
  |---|---|
  | 원본·소스로 확인함 | `— 출처: 파일:심볼` (표기어 없음) |
  | 확인했으나 값이 없음·측정 못 함 | `미측정` · `불명확 — 확인 필요` · `미검증` · `미확인` |
  | 확인 전 서술 · 검증 불가 | 문장 앞 `[추론]` (구 `(추정)` 을 대체) |
  | 진실원 자체가 없음 | `(제안)` · `미정 — 확인 필요` |
- **비침습** — `docs/[Ubisam산출물]/` 밖은 읽기만. 소스·`CLAUDE.md`·루트 규칙 파일 수정 금지.
- **MD 200줄 상한** (`rules.md` #4) — 초과 시 분할 + 상대경로 링크.
- **UTF-8** — 스크립트 실행은 `PYTHONUTF8=1 py <script>`.

## 구성 요소

**Agents:** `.claude/agents/ubisam-analyst.md`, `ubisam-producer.md`, `ubisam-qa.md`
**Skills:** `.claude/skills/ubisam-deliverable-rebuild/`, `ubisam-deliverables/`,
`ptop-deliverables/`, `ubisam-format-map/`, `ubisam-ppt-make/`, `ui_layout_image/`

## 변경 이력

| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 2026-08-03 | 하네스 문서 신규 작성 | docs/harness-ubisam.md | Ubisam 산출물 스킬 5개가 CLAUDE.md에 포인터 없이 존재했음 |
| 2026-08-03 | 팀원 에이전트 3개 신규 생성 | agents/ubisam-{analyst,producer,qa}.md | 오케스트레이터가 참조하는 에이전트 정의가 어디에도 없었음(dead link) |
| 2026-08-03 | `ubisam-deliverable` → `ubisam-deliverable-rebuild` 리네임 | skills/ | 복수형 `ubisam-deliverables`와 한 글자 차이로 트리거 혼동 |
| 2026-08-03 | 형제 스킬 경계표를 3개 스킬 description에 추가 | ptop-deliverables, ubisam-deliverables, ubisam-deliverable-rebuild | 산출물 관련 스킬 3개의 트리거 경계가 겹쳤음 |
| 2026-08-03 | 작업공간을 `docs/[Ubisam산출물]/_workspace/`로 고정 | agents/ubisam-* 3개 | 베어 `_workspace/`가 PTOP 하네스의 루트 작업공간과 문자열 충돌 |
| 2026-08-03 | 타 프로젝트(LGIT_구미_FMM) 고정값 삭제, `_meta/project.yaml`을 유일 진실원으로 | ubisam-format-map | 잔재 소탕이 목적인 하네스가 스스로 타설비 값을 주입하고 qa가 정답으로 대조하고 있었음 |
| 2026-08-03 | 진입 가드 추가 — 대상 미지정·에이전트 미등록 시 중단 | ubisam-deliverable-rebuild, ptop-deliverables | "산출물 업데이트해줘" 발화가 3개 스킬 중 무엇이든 잡을 수 있어 오발동 위험 |
| 2026-08-03 | 슬롯 전용 xlsx 스크립트 부재 시 `xlsxfill` 기반 신규 작성 허용 | ubisam-producer | 02.설계 외 슬롯은 생성 수단이 없는데 수작업은 금지라 데드엔드였음 |
| 2026-08-03 | analyst 실패 시 중단 규칙 명문화 (producer/qa 실패와 구분) | ubisam-deliverable-rebuild | "결과 없이 진행" ↔ "매핑표 없으면 시작 안 함"이 상충 |
| 2026-08-03 | `build_02설계_xlsx.py` 4개 저장 지점에 `os.makedirs` 추가 | references/build_02설계_xlsx.py | 슬롯 폴더 부재 시 `FileNotFoundError`로 4종 전부 실패 (실행 재현·수정 후 4/4 성공 확인). 형제 pptx 스크립트에는 이미 있었음 |
| 2026-08-03 | rebuild 경로에서는 `build_02설계_xlsx.py`를 쓰지 않도록 명시 | ubisam-producer | 그 스크립트는 PTOP 소스 데이터가 하드코딩된 무인자 스크립트라 매핑표를 반영할 입구가 없음 → 창작 금지 규칙에 스스로 걸림 |
| 2026-08-03 | `00-harness.md` 계약 2건 정정 (멱등 정의·ref 복제 방식) | references/00-harness.md | "먼저 읽으라"고 지정된 계약이 "덮어쓰지 않는다"·"원본 템플릿 복제"로 하위 절차와 정면 충돌 |
| 2026-08-03 | 실행 명령 3곳 정규화, `제어시퀀스_인터락_정의서.md` 파일명 통일, 표 헤더 경로 정정 | SKILL·09-pptx-integration·harness-ubisam | `PYTHONUTF8` 별도 줄·맨 파일명 실행·파일명 불일치로 조용한 실패 |
| 2026-08-03 | `rules.md` #6(문서 갱신 확인)·#10(중간 진행 보고) 바인딩, stale을 파일에도 기록 | 두 오케스트레이터 | 규칙이 하네스 어디에도 참조되지 않았고, stale이 채팅에만 남아 폴더만 여는 사람은 구분 불가 |
| 2026-08-03 | `background_color` spec 키 기술 삭제 | ubisam-ppt-make ×2, 09-pptx-integration | `build_deck.py`가 파싱하지 않는 키 — 넣어도 조용히 무시됨 |
| 2026-08-03 | frontmatter description을 `>-` 블록 스칼라로 전환 | ubisam-ppt-make | 평문 스칼라 안의 `#4A8DCB`가 **YAML 주석으로 파싱돼 description이 "blue"에서 절단** — 트리거 문장이 통째로 소실돼 있었음 |
| 2026-08-03 | `layout_selection.md` 배경색 3곳 `BG_SOFT`→`WHITE` | ubisam-ppt-make/reference | `build_deck.py:55-73`은 `WHITE`. 최신 커밋으로 추가된 파일이 코드·형제 문서와 정반대 |
| 2026-08-03 | `matplotlib`·`soffice`·`fitz` 가용성 가드 추가 | ui_layout_image, ubisam-ppt-make | 셋 다 이 환경에 미설치. 렌더링 핵심이 첫 import에서 죽는데 폴백 부재 |
| 2026-08-03 | `YEL` 미정의 식별자 제거, `L_alarm`에 표 높이 상한 추가 | build_deck.py | 20행 알람표가 `0.5×21=10.5"`로 슬라이드(7.5")를 넘어감 — 수정 후 7.000" 확인 |
| 2026-08-03 | pptx 빌더의 조직·담당자·`Ajin` 단정 제거 → `_meta/project.yaml` 주입 | build_02설계_pptx.py | 하네스가 §5에서 금지한 "타 프로젝트 값 하드코딩"을 자기 산출물이 위반. 22슬라이드 재렌더로 잔존 0건 확인 |
| 2026-08-03 | 브래킷 경로 인용 의무·POSIX 절대경로 함정 명시 | 00-harness.md | `docs/[Ubisam산출물]/`의 대괄호는 bash 문자클래스라 조용히 오해석됨 |
| 2026-08-03 | `rules.md` #15·#16 바인딩 + 표기 축 판정표 | ubisam-analyst·producer·qa, rebuild, harness-ubisam | 신규 조항이 하네스에 인용 0건 — 미시행 상태였음. analyst의 `[추론]`을 producer가 사실로 승격시키는 경로를 qa 검증항목 11로 차단 |
| 2026-08-03 | Phase 2에 producer·qa **기동 문장**(`Agent(subagent_type:…)`)과 절대경로 전달 지시 추가 | ubisam-deliverable-rebuild | Phase 1은 analyst를 명시 기동하는데 Phase 2는 "producer가 재생산한다"는 서술뿐이라 **누가 띄우는지가 없었다.** qa에 원본·매핑표·산출물 3경로를 주는 지시도 부재 |
| 2026-08-03 | qa에 "검색 0건은 결함 없음이 아니다" 규칙 추가 | ubisam-qa.md | 브래킷 경로가 패턴에서 문자클래스로 먹혀 **에러 없이 0건**이 나오는데, qa가 이를 통과로 판정할 경로 |
| 2026-08-04 | **19R.** Phase 1·2 전달 항목에 실행 모드 4종 추가, 3인에 모드 수신 규칙 이식 | rebuild/SKILL.md, ubisam-analyst·producer·qa | 모드 판별이 승인 목록 산정에만 쓰이고 이동·재사용 결정에 도달하지 못했음 (`이어서` 소비처 0건) |
| 2026-08-04 | 표기 축 2행을 `rules.md` 판정표와 동기(3종 → **4종**, `미측정` 편입) | harness-ubisam.md | 하네스에서 34회 쓰이는 토큰이 자기 판정표에 없었음 |
| 2026-08-04 | `SendMessage` `summary` 필수 명시, 200줄 문구에 `rules.md #4` 앵커 부착 | ubisam 3인 | 스키마상 필수 인자 누락. #4 는 앵커가 없어 자가 점검 명령에 안 잡혔음 |
| 2026-08-04 | 데이터 전달·에러 표를 `references/protocol.md` 로 분리 | rebuild/SKILL.md | 204줄로 `rules.md` #4 자기 위반 |
| 2026-08-04 | ppt spec 예시의 타 프로젝트 조직·담당자 → 플레이스홀더, 데모 데이터 복사 금지 경고 | ubisam-ppt-make/SKILL.md | 스킬이 금지한 "타 프로젝트 값 하드코딩"을 자기 예시가 유발 |
| 2026-08-04 | `README.md` 디자인 지시를 §7 부재에 맞게 재작성, 유형 뱃지 11→**9**, `TODAY` 출처 정정 | ubisam-deliverables/SKILL.md, design-system.md, 05-form-schemas.md | 존재하지 않는 템플릿 지시 · enum 9종과 뱃지 수 불일치 · `xlsxfill.py` 에 없는 상수를 그 파일 절에 기재 |
| 2026-08-04 | **20R.** producer·qa 기동에 `run_in_background: true` (21R에 재기술 문장까지 보강) | rebuild/SKILL.md | `to:"main"` 은 백그라운드 서브에이전트 전용 — 전경 기동 시 오케스트레이터 회신이 막힌다 |
| 2026-08-04 | 조건부서식 상수 소재 정정 — `xlsxfill.py` 에 **없다**(관련 API 0건) | 00-harness.md | 계약 문서가 `ubisam-producer.md` 와 정반대를 적었고 계약이 먼저 읽힌다 |
| 2026-08-04 | `build_deck.py`·`showcase.json` 타 프로젝트 실명 20건 → 플레이스홀더 | ubisam-ppt-make/ | 스킬이 금지한 "타 프로젝트 값 하드코딩"을 자기 데모·예시가 유발 |
| 2026-08-04 | **21R.** `xlsxfill.py` 타 프로젝트명 제거 + 실행 지시 전체 경로화 | references/xlsxfill.py | 형제 3곳은 정규화됐는데 이 파일만 맨 파일명 실행을 지시 |
| 2026-08-04 | 200줄 문구 `rules.md #4` 앵커 부착(스킬·에이전트 5건 + 22R에 이 문서 본문 1건), README 디자인 지시 §7 부재 반영 | ubisam-deliverables/ 외 | 앵커가 없어 자가 점검 명령에 안 잡혔고, 없는 템플릿 적용을 명령했다 |
| 2026-08-04 | **22R.** analyst 기동에 `run_in_background: true` — 3인 전원 적용 완료 | rebuild/SKILL.md | 20R qa·21R 재기술문에 이어 마지막 누락. 단일 문서일 때 `to:"main"` 회신이 막혔다 |
| 2026-08-04 | **23R(최종, 미채점).** `ubisam-analyst` 의 `_workspace_prev/` 이동을 **전면 금지**로 정정 | ubisam-analyst.md | 오케스트레이터는 "팀원은 안 한다"인데 analyst 는 "`전면`이면 옮긴다"로 정반대 — 이중 이동 시 산출물 유실 |
| 2026-08-04 | 본문 200줄 문구에 `rules.md #4` 앵커 부착, `protocol.md` 베어 `_workspace/` → 전체 경로 | harness-ubisam.md, references/protocol.md | 21R 지적 2R 연속 미이행. PTOP 하네스의 루트 `_workspace/` 와 혼동 |