RobotAutomationDevelopment-Dept/LGES-OC5-PtoP-Welder
12
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
LGES-OC5-PtoP-Welder/.claude/skills/ubisam-deliverable-rebuild/SKILL.md
NohDoyeon241104 45d991a25c UPDATE
2026-08-06 11:29:00 +09:00

14 KiB
Raw Blame History

name description
ubisam-deliverable-rebuild 타사 양식으로 받은 기존 산출물(Doc/산출물문서의 xlsx·pptx·docx)을 Ubisam 협업관리 양식으로 분석·재배치·재생산·검증하는 3에이전트 오케스트레이터. "이 문서 Ubisam 양식으로 바꿔줘", "타사 산출물 재생산", "협업관리 양식으로 재배치", "산출물 채움", "이 xlsx를 Ubisam 단계로 매핑", 그리고 **재생산에 대한** 후속 표현("산출물 재실행", "재생산 다시", "이 문서만 다시", "재생산 결과 보완", "이전 재생산 기반으로") 시 이 스킬을 쓴다. 구분 — 빈 트리를 새로 까는 스캐폴딩은 `ubisam-deliverables`, PTOP 소스코드를 읽어 설계 MD를 뽑는 것은 `ptop-deliverables`, 양식 enum 조회만이면 `ubisam-format-map`, **PTOP 아키텍처·구현·빌드 분석**은 `orchestrate-ptop-harness`다. 맨손 "업데이트"·"다시 실행"만으로는 이 스킬을 고르지 않는다 — 대상 문서를 먼저 확인한다.

ubisam-deliverable-rebuild — 타사 양식 → Ubisam 양식 재생산 오케스트레이터

입력이 이미 존재하는 문서일 때 쓰는 하네스다. 그 문서를 해부해 Ubisam 6단계 슬롯으로 재배치하고 Ubisam 양식으로 다시 찍어낸 뒤 검증한다.

  • 실행 모드: 서브 에이전트 + 점진적 생성-검증 루프
  • 팀원: ubisam-analyst → ubisam-producer ↔ ubisam-qa (모두 model: "opus")
  • 공유 스킬: ubisam-format-map (enum·스키마·슬롯 — 모든 팀원이 먼저 읽음)
  • 작업공간: docs/[Ubisam산출물]/_workspace/, 최종 산출물은 6단계 폴더 또는 사용자 지정 경로 (사용자 지정 경로를 쓴 경우 00_rebuild_summary.md에 실제 배치 경로표를 남기고, qa는 검증항목 #1(슬롯 누락)을 그 표 기준으로 판정한다)

형제 스킬과의 경계

상황 쓸 스킬
산출물 트리가 아예 없음 → 폴더·_meta·일감 카드 스캐폴딩 ubisam-deliverables
기존 타사 문서를 Ubisam 양식으로 재생산 이 스킬
PTOP 소스코드를 읽어 설계 산출물 MD 생성 ptop-deliverables
enum·슬롯 값만 조회 ubisam-format-map

도구 사용 규칙

이 환경에는 TeamCreate/TeamDelete 도구가 없다. 팀은 아래 방식으로 구성한다.

  • 팀원 기동: Agent 도구 — subagent_type에 에이전트 이름, model: "opus", 병렬 구간은 run_in_background: true
  • 팀원 간 소통: SendMessage (to에 에이전트 이름 지정)
  • 진행 공유: docs/[Ubisam산출물]/_workspace/_progress.md 파일(진실원). 태스크 도구는 가용 시 보조
  • 산출물 전달: 파일 (docs/[Ubisam산출물]/_workspace/)

Phase 0: 컨텍스트 확인

경로 인용 주의. docs/[Ubisam산출물]/의 대괄호는 Glob/Grep 패턴에서 문자클래스로 해석돼 에러 없이 0건을 낸다(실측). 존재 확인은 Bash에서 따옴표로 감싸거나, Grep/Glob의 path 인자(리터럴)로 하거나, 패턴을 docs/\[Ubisam산출물\]/…로 이스케이프한다. 상세 → ubisam-deliverables/references/00-harness.md §경로 인용 의무.

  1. 진입 가드 2건. 둘 다 통과해야 Phase 1로 간다.

    • 대상 미지정 — 사용자 발화에 어떤 문서를 재생산할지 없으면(예: "산출물 업데이트해줘") 아무 파일도 만들지 말고 되묻는다. Doc/산출물문서/에 후보가 여럿이므로 임의로 고르면 원하지 않은 문서에 3에이전트 풀런이 돌아간다.
    • 에이전트 미등록 — ubisam-analyst/ubisam-producer/ubisam-qa가 Agent 도구의 subagent_type 목록에 없으면 시작하지 말고 "프로젝트 에이전트 미등록 — 세션 재시작 필요"를 보고하고 중단한다. .claude/agents/에 파일을 방금 추가했다면 세션 재시작 전까지 호출되지 않는다.

  2. 대상 문서와 작업 디렉토리를 정한다. 기본 작업공간 docs/[Ubisam산출물]/_workspace/.

  3. 실행 모드 판별 (승인 목록을 확정하기 위해 먼저 한다): docs/[Ubisam산출물]/_workspace/ 의 산출물(01_analyst_*·02_producer_*·03_qa_*) 존재 여부로 판별한다 — 폴더 존재만 보면 로그·메모만 있어도 오판정한다(PTOP 하네스와 동일 규칙).

    • 하나도 없음 → 초기 실행 (Phase 1부터. 폴더가 있어도 초기 실행이다)
    • 일부만 있음 + 전체 재생산 요청 → 이어서 실행. 있는 것 재사용, 없는 것만 생성, 이동 없음
    • 부분 수정 요청("OO만 다시") → 부분 재실행 (해당 에이전트만 재호출)
    • 새 입력 문서 또는 "처음부터 다시" 명시 → 전면 (기존을 _workspace_prev/로 이동)

    네 모드의 이름은 초기 / 이어서 / 부분 / 전면 이며, Phase 1·2에서 팀원에게 이 문자열 그대로 전달한다. _workspace_prev/ 이동은 오케스트레이터만 하고 팀원은 하지 않는다 — 팀원은 모드를 "기존 산출물을 재사용할지" 판단에만 쓴다.

  4. 스캐폴딩 필요 여부 판정. docs/[Ubisam산출물]/가 없으면 ubisam-deliverables 스캐폴딩이 선행되어야 한다. 그 스킬이 만들 폴더·파일 목록도 아래 승인 대상에 합산한다.

  5. 승인 게이트. 아래 넷을 한 번에 제시하고 승인받는다 (rules.md #2) — ① 스캐폴딩분 ② 모드별 이동·덮어쓰기분(_workspace_prev/ 이동 포함) ③ 재생산분 ④ 작업공간 관리 파일(_workspace/ 생성, _progress.md, 01_analyst_*·02_producer_*·03_qa_* 중간 로그). ④를 빼면 ubisam-producer.md의 "승인 범위 밖 금지"와 충돌해 작업 로그조차 못 쓴다. 모드 판별·스캐폴딩 판정을 승인보다 먼저 하는 이유는, 그러지 않으면 승인 목록이 실제 변경 범위와 어긋나기 때문이다.

  6. 스캐폴딩 실행 (3에서 필요하다고 판정된 경우에만). ubisam-deliverables 스킬의 A단계를 호출한다 — 대상이 이미 명시됐으므로 그 스킬의 진입 가드는 통과한다. 그 스킬의 진입 가드 승인과 A단계 0번 승인 모두 위 4에서 통합으로 받았으므로 생략한다 (승인을 두 번 걸지 않는다). 완료를 확인한 뒤 다음 단계로 간다. 이 단계를 건너뛰면 producer가 docs/[Ubisam산출물]/{NN.단계}/·_meta/build_scripts/에 쓰려는 순간 부모 폴더가 없어 실패한다.

  7. docs/[Ubisam산출물]/_workspace/_progress.md를 만든다. 행 단위는 {에이전트}:{문서} 다 — 문서가 3건이면 analyst·producer·qa 각 3행씩 9행이다(Phase 2가 문서 1건당 producer 1기동이므로). 문서별로 따로 세야 "같은 결함 2회" 상한이 문서 단위로 작동한다. 문서가 1건이면 3행이다. 재시도 카운트(시도 N/2)의 진실원이 이 파일이다 — TaskCreate/TaskUpdate는 서브에이전트 컨텍스트에 없을 수 있어 도구에만 의존하면 횟수가 대화 맥락에만 남는다. 도구가 가용하면 병행 등록해도 된다.

  8. ubisam-format-map 스킬을 로드해 양식 기준을 확보한다.

Phase 1(analyst)부터 시작한다. analyst를 건너뛰고 producer로 가면 매핑표가 없어 즉시 멈춘다.

Phase 1: 분석 (analyst)

Agent(subagent_type: "ubisam-analyst", model: "opus", run_in_background: true) 로 기동. 문서가 1건이어도 run_in_background 를 뺀다는 뜻이 아니다 — to: "main" 회신이 막힌다. (아래 "문서가 여러 개면 병렬 기동"은 개수에 관한 말이지 이 플래그의 조건이 아니다.) 대상 문서별로 구조 해부 · 타설비 잔재 식별 · 6단계 슬롯 매핑을 요청한다.

  • 산출: docs/[Ubisam산출물]/_workspace/01_analyst_{문서}.md
  • 산출 경로와 진행 원장 _progress.md 경로를 모두 저장소 루트 기준 절대경로로 변환해서 전달한다 — 서브에이전트의 셸 작업 디렉토리는 호출마다 초기화되므로 상대경로를 그대로 주면 파일이 엉뚱한 곳에 떨어지고, 실패 판정 ②(파일 미생성)가 오판한다. _workspace/가 없으면 먼저 만든다.
  • 실행 모드(초기/이어서/부분/전면) 를 문자열 그대로 전달한다. 빼면 analyst가 기존 01_analyst_*를 재사용할지 판단할 근거가 없어 모드 판별이 승인 목록 산정에만 쓰이고 죽는다.
  • 문서가 여러 개면 문서별로 병렬 기동(run_in_background: true)한다. 서로 의존이 없기 때문이다.

Phase 2: 재생산 ↔ 검증 (producer ↔ qa, 점진적)

Agent(subagent_type: "ubisam-producer", model: "opus", run_in_background: true) 로 기동한다. qa 도 같은 형태로 기동한다. run_in_background 를 빼면 SendMessage 의 to: "main" 회신이 막힌다 — 그 값은 백그라운드 서브에이전트 전용이고, 세 에이전트 모두 오케스트레이터에 main 으로 보고한다. 기동은 오케스트레이터 전담이다 — analyst·producer·qa는 서로를 띄우지 않는다. Phase 1과 동일하게 매핑표·산출·_progress.md 경로를 전부 저장소 루트 기준 절대경로로, 그리고 실행 모드(초기/이어서/부분/전면) 를 문자열 그대로 전달한다 (서브에이전트의 셸 작업 디렉토리는 호출마다 초기화된다).

문서가 여러 개면 문서 1건당 producer를 하나씩 기동한다. 한 번에 다 맡기면 "1건 끝날 때마다 qa"라는 아래 루프의 관측점이 사라져 점진 검증이 성립하지 않는다(전부 끝난 뒤 한꺼번에 검증하게 된다).

producer는 매핑표대로 산출물을 재생산한다 — xlsx = xlsxfill.py 기반 신규 스크립트(_meta/build_scripts/. 번들 build_02설계_xlsx.py는 데이터가 하드코딩돼 있어 이 하네스에서 쓰지 않는다), pptx = ubisam-ppt-make, docx = ubisam-docx, md = 디자인 템플릿.

문서 1건이 끝날 때마다 Agent(subagent_type: "ubisam-qa", model: "opus", run_in_background: true) 를 기동해 검증한다(run_in_background 는 위 규칙과 동일 — 빼면 to: "main" 회신이 막힌다). 전체 완성 후 일괄 검증하지 않는 이유는, 구조적 결함이 늦게 발견되면 이후 산출물 전부를 되돌려야 하기 때문이다. qa에는 원본·매핑표·산출물 3개 경로를 모두 절대경로로 준다 — 하나라도 빠지면 교차 대조가 성립하지 않는다.

  • Critical/Major → producer가 수정 후 재검증. 같은 결함은 최대 2회까지만 재작업을 요청하고, 3회째에는 "미해결"로 확정해 사용자 판단 항목으로 올린다(무한 루프 방지).
  • Minor → 로그에 기록만 하고 진행

Phase 3: 종합·보고

docs/[Ubisam산출물]/_workspace/00_rebuild_summary.md를 작성한다 — 필수 섹션: 산출물 목록(경로) · 산출물별 stale 표기 · qa 판정 · 누락/미검증 항목과 사유 · 출처. 이 파일이 "보고서에 누락을 명시"의 종착지다.

그 내용을 사용자에게도 요약 보고한다. 보고 시 rules.md #11~13 출력 형식을 따른다 — 수정 대상 줄은 초록 화살표(→), 단어 단위는 주황, 미변경은 기본색. 보고 끝에 docs/harness-ubisam.md를 갱신할 부분이 있는지 묻는다(rules.md #6). 문서 수가 많아 10분을 넘기므로 Phase 전환마다 진행 상황을 한 줄로 보고한다(rules.md #10). 중간 산출물(docs/[Ubisam산출물]/_workspace/)은 지우지 않고 보존한다 — 사후 감사 추적에 쓴다.

데이터 전달 · 에러 핸들링

전달 = 파일(_workspace/) + SendMessage(to+summary+message) + _progress.md(진행 원장). 상세 표 2종 → references/protocol.md

에러 핵심 3가지:

  • 실패 = ①에러 종료 ②산출 파일 미생성 ③빈 파일·헤더만. 지연은 실패가 아니다.
  • 재시도는 같은 Agent 재호출이며 SendMessage 독촉이 아니다. 횟수는 _progress.md의 시도 칸이 진실원.
  • analyst 2회 실패는 중단(매핑표 부재 = 기준 부재). producer/qa 실패는 해당 문서만 건너뛰고 누락 명시.

테스트 시나리오

정상 흐름 1건(타사 xlsx 시트 10개 → 6단계 슬롯 매핑) + 에러 흐름 1건(원본 쓰기 잠김 → 부분 성공 보고) → references/test-scenarios.md

후속 작업

  • "OO만 다시" → 해당 에이전트만 재호출하고 이전 docs/[Ubisam산출물]/_workspace/ 산출물 기반으로 변경분만 갱신
  • 각 에이전트 정의의 재호출 지침 섹션이 이전 산출물 처리 방식을 규정한다
  • 연쇄 무효화 확인. 01_analyst_*가 갱신되면 그에 의존한 02_producer_*·산출물·03_qa_*는 단순 "재사용"이 아니라 정합성 미확인이다. 함께 재실행할지 사용자에게 묻고, 거절하면 이전 실행 결과 재사용 — 매핑표 갱신으로 정합성 미확인(YYYY-MM-DD)으로 표기한다.
  • stale 표기 의무. 산출물별로 "이번 실행에서 갱신됨(YYYY-MM-DD)" / "이전 실행 결과 재사용(YYYY-MM-DD)"을 ① 채팅 보고 ② _workspace/00_rebuild_summary.md ③ 산출물 파일 자체 — .md는 첫 줄, xlsx는 첫 시트 배너 아래 셀, pptx는 history 슬라이드 최신 행에 같은 문구를 남긴다 — 세 곳에 남긴다 (PTOP 하네스와 동일 규칙). 파일만 열어보는 사람이 최신 여부를 알 수 있어야 한다.

성공 기준

  • 대상 문서의 모든 시트/슬라이드가 매핑표에 등장 (누락 0)
  • 01_analyst_* → 02_producer_* → 03_qa_*가 전부 존재하거나, 없으면 사유가 요약에 명시됨
  • qa 판정이 통과/조건부 통과/실패 중 하나로 기록됨
  • 타설비 잔재가 전수 검색으로 확인됨
  • 창작(매핑표에 없는 내용) 0건
  • 매핑표의 [추론] 항목이 산출물에서 사실로 승격되지 않음 (rules.md #15·#16, qa 검증항목 11)
  • 00_rebuild_summary.md가 존재하고 누락·미검증 항목이 적혀 있음
  • 한글이 깨지지 않음 (UTF-8)