192 lines
14 KiB
Markdown
192 lines
14 KiB
Markdown
---
|
|
name: ubisam-deliverable-rebuild
|
|
description: >-
|
|
타사 양식으로 받은 기존 산출물(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` §경로 인용 의무.
|
|
|
|
|
|
0. **진입 가드 2건. 둘 다 통과해야 Phase 1로 간다.**
|
|
- **대상 미지정** — 사용자 발화에 어떤 문서를 재생산할지 없으면(예: "산출물 업데이트해줘")
|
|
**아무 파일도 만들지 말고 되묻는다.** `Doc/산출물문서/`에 후보가 여럿이므로 임의로 고르면
|
|
원하지 않은 문서에 3에이전트 풀런이 돌아간다.
|
|
- **에이전트 미등록** — `ubisam-analyst`/`ubisam-producer`/`ubisam-qa`가 `Agent` 도구의
|
|
subagent_type 목록에 없으면 시작하지 말고 "프로젝트 에이전트 미등록 — 세션 재시작 필요"를
|
|
보고하고 중단한다. `.claude/agents/`에 파일을 방금 추가했다면 세션 재시작 전까지 호출되지 않는다.
|
|
|
|
1. 대상 문서와 작업 디렉토리를 정한다. 기본 작업공간 `docs/[Ubisam산출물]/_workspace/`.
|
|
|
|
2. **실행 모드 판별** (승인 목록을 확정하기 위해 먼저 한다):
|
|
`docs/[Ubisam산출물]/_workspace/` 의 **산출물(`01_analyst_*`·`02_producer_*`·`03_qa_*`) 존재 여부**로
|
|
판별한다 — 폴더 존재만 보면 로그·메모만 있어도 오판정한다(PTOP 하네스와 동일 규칙).
|
|
- 하나도 없음 → **초기 실행** (Phase 1부터. 폴더가 있어도 초기 실행이다)
|
|
- 일부만 있음 + 전체 재생산 요청 → **이어서 실행.** 있는 것 재사용, 없는 것만 생성, 이동 없음
|
|
- 부분 수정 요청("OO만 다시") → **부분 재실행** (해당 에이전트만 재호출)
|
|
- **새 입력 문서** 또는 "처음부터 다시" 명시 → **`전면`** (기존을 `_workspace_prev/`로 이동)
|
|
|
|
네 모드의 이름은 **`초기` / `이어서` / `부분` / `전면`** 이며, Phase 1·2에서 팀원에게 이 문자열
|
|
그대로 전달한다. `_workspace_prev/` 이동은 **오케스트레이터만** 하고 팀원은 하지 않는다 —
|
|
팀원은 모드를 "기존 산출물을 재사용할지" 판단에만 쓴다.
|
|
|
|
3. **스캐폴딩 필요 여부 판정.** `docs/[Ubisam산출물]/`가 없으면 `ubisam-deliverables` 스캐폴딩이
|
|
선행되어야 한다. 그 스킬이 만들 폴더·파일 목록도 아래 승인 대상에 **합산**한다.
|
|
|
|
4. **승인 게이트.** 아래 **넷**을 **한 번에** 제시하고 승인받는다 (`rules.md` #2) —
|
|
① 스캐폴딩분 ② 모드별 이동·덮어쓰기분(`_workspace_prev/` 이동 포함) ③ 재생산분
|
|
④ **작업공간 관리 파일**(`_workspace/` 생성, `_progress.md`, `01_analyst_*`·`02_producer_*`·`03_qa_*` 중간 로그).
|
|
④를 빼면 `ubisam-producer.md`의 "승인 범위 밖 금지"와 충돌해 작업 로그조차 못 쓴다.
|
|
모드 판별·스캐폴딩 판정을 승인보다 먼저 하는 이유는, 그러지 않으면 승인 목록이
|
|
실제 변경 범위와 어긋나기 때문이다.
|
|
|
|
5. **스캐폴딩 실행** (3에서 필요하다고 판정된 경우에만). `ubisam-deliverables` 스킬의 A단계를
|
|
호출한다 — 대상이 이미 명시됐으므로 그 스킬의 진입 가드는 통과한다.
|
|
그 스킬의 **진입 가드 승인과 A단계 0번 승인 모두** 위 4에서 통합으로 받았으므로 생략한다
|
|
(승인을 두 번 걸지 않는다).
|
|
완료를 확인한 뒤 다음 단계로 간다. 이 단계를 건너뛰면 producer가
|
|
`docs/[Ubisam산출물]/{NN.단계}/`·`_meta/build_scripts/`에 쓰려는 순간 부모 폴더가 없어 실패한다.
|
|
|
|
6. `docs/[Ubisam산출물]/_workspace/_progress.md`를 만든다. **행 단위는 `{에이전트}:{문서}` 다** —
|
|
문서가 3건이면 analyst·producer·qa 각 3행씩 **9행**이다(Phase 2가 문서 1건당 producer 1기동이므로).
|
|
문서별로 따로 세야 "같은 결함 2회" 상한이 문서 단위로 작동한다. 문서가 1건이면 3행이다.
|
|
재시도 카운트(`시도 N/2`)의 **진실원이 이 파일**이다 — `TaskCreate`/`TaskUpdate`는 서브에이전트
|
|
컨텍스트에 없을 수 있어 도구에만 의존하면 횟수가 대화 맥락에만 남는다. 도구가 가용하면 병행 등록해도 된다.
|
|
7. `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](references/protocol.md)
|
|
|
|
**에러 핵심 3가지:**
|
|
- 실패 = ①에러 종료 ②산출 파일 미생성 ③빈 파일·헤더만. **지연은 실패가 아니다.**
|
|
- 재시도는 같은 `Agent` 재호출이며 `SendMessage` 독촉이 아니다. 횟수는 `_progress.md`의 `시도` 칸이 진실원.
|
|
- **analyst 2회 실패는 중단**(매핑표 부재 = 기준 부재). producer/qa 실패는 해당 문서만 건너뛰고 누락 명시.
|
|
|
|
## 테스트 시나리오
|
|
|
|
정상 흐름 1건(타사 xlsx 시트 10개 → 6단계 슬롯 매핑) + 에러 흐름 1건(원본 쓰기 잠김 → 부분 성공 보고)
|
|
→ [references/test-scenarios.md](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)
|