12 KiB
12 KiB
하네스: 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/ 와 혼동 |