| name | tc-이미지매칭 |
| description | TC 시트의 K열(담당자)에 Confluence 페이지 이미지를 선택적으로 임베드. 본 TC-v2 파이프라인과 완전 분리된 on-demand 스킬. 트리거 "이미지 매칭해줘", "TC에 이미지 링크 추가", "비고에 Confluence 이미지 붙여줘", "/tc-이미지매칭". |
tc-이미지매칭 (on-demand)
트리거
- 슬래시:
/tc-이미지매칭
- 자연어: "이미지 매칭해줘", "TC에 이미지 링크 추가해줘", "비고에 Confluence 이미지 붙여줘"
입력 (사용자에게 묻기)
- 스프레드시트 ID + 탭 이름 (또는 URL)
- 범위: 전체 / 카테고리(대분류) / TC ID 범위 / 단건
- 기획서 위치: 시트 L6 셀 (TC 생성 시 자동 입력됨). 없으면 사용자에게 물어보기.
제외 룰 (이미지 매칭 안 함)
다음 조건 중 하나라도 해당되면 이미지 매칭 스킵:
| 조건 | 이유 |
|---|
| ① 대분류 = "기본기능" (또는 기본기능 섹션 내 상속 행) | 자명한 화면, 시각자료 불필요. |
| ② 행 번호 ≤ 10 | 양식/헤더/프로젝트 정보 패널 영역. 데이터 행 아님. |
OR 조건. 둘 중 하나만 맞아도 제외.
흐름
STEP 1: 사전 정보 수집
- 시트 메타데이터 읽기:
- 헤더(1행): TC ID / 대분류 / 중분류 / 소분류 / 검증단계 / 재현 스탭 / 플랫폼 / PC 결과 / 모바일 결과 / 비고(J열) / 담당자(K열)
- 비고(J)는 건드리지 않음. 이미지 링크는 K열(담당자) 사용.
- 시트 L6 = Confluence URL 확인
- 대상 TC 데이터 추출 (재현스탭, 검증포인트, K열 기존 값)
- 제외 룰 적용: 기본기능 OR 행 ≤ 10인 TC는 후보에서 제외
STEP 2: Confluence 분석 (image_manifest 생성)
confluence_get_attachments (Atlassian MCP, 토큰) → 첨부의 숫자 attID(id의 att 제거) + 파일명 추출. 미리보기 URL에 attID 필수이며, attID는 이 토큰 기반 호출로만 얻음 (getConfluencePage/confluence_raw.md엔 pageID·파일명만 있고 attID 없음)- 이미지 위치/섹션 컨텍스트:
confluence_get_page 또는 specs/{기능명}/confluence_raw.md(있으면 재사용)에서 섹션 헤딩 + nearby_text 추출 (매칭 판단용)
- specs/{기능명}/image_manifest.md 캐시 저장:
| imgId | pageId | attId | filename | section_path | nearby_text(±200자) |
STEP 3: TC ↔ 이미지 매칭 (LLM 판단)
채택 기준:
- ✅ UI 레이아웃/위치 다이어그램이 텍스트 설명 보완에 핵심
- ✅ 표/차트가 검증포인트에 직접 인용
- ✅ 비교 시각자료가 핵심 (예: 이족/사족 보행)
- ❌ 자명한 화면 (로그인, 메인 메뉴 등)
- ❌ 단순 동작 검증 (이동/점프 안정성)
- ❌ 부정/예외 케이스 중 단순 오류 시나리오
권장 부착 비율: TC 100건당 10~20%. 초과 시 우선순위 재평가.
STEP 4: HYPERLINK 임베드
URL 템플릿 (미리보기 — 클릭 시 페이지에서 이미지가 라이트박스로 열림):
https://YOUR_SITE.atlassian.net/wiki/spaces/{SPACE_KEY}/pages/{PAGE_ID}?preview=/{PAGE_ID}/{ATT_ID_NUMERIC}/{FILENAME}
- 사이트 도메인·
SPACE_KEY: 기획서(Confluence) URL에서 그대로 가져옴. ATT_ID_NUMERIC: confluence_get_attachments id("att123…")에서 att 제거
- ⚠️ 이 미리보기 형식만 "이미지가 보이는 화면"으로 이동 (2026-06-02 검증). 대안은 안 됨:
- 다운로드 URL(
/wiki/download/attachments/…) → 클릭 시 파일 다운로드 (페이지 이동 X)
- 섹션 앵커(
…#heading) → Confluence Cloud에서 점프 안 되고 페이지 최상단으로만 감
→ attID(토큰)가 필요. 단 토큰은 생성 시에만 필요하고 클릭은 SSO라 토큰 무관
대상 컬럼: K열 (담당자 헤더 위치이지만 대부분 비어있음)
셀 입력 패턴 (K열 기존 내용에 따라 분기):
| 케이스 | 처리 | 셀 값 |
|---|
| ① 빈 셀 | ✅ 즉시 삽입 | =HYPERLINK(url, "{라벨}") |
| ② 짧은 담당자 텍스트 (≤30자, 예: "기획", "서버") | ✅ 라벨 흡수 | =HYPERLINK(url, "{기존텍스트} / {라벨}") |
| ③ 긴 자유 텍스트 (>30자) | ⏸ 보류 | 셀 유지, 보고서에 "수동 처리 권장" 표기 |
| ④ 줄바꿈된 다중 라인 | ⏸ 보류 | 셀 유지, 보고서에 "구조 보존 필요" 표기 |
| ⑤ 기존 다른 HYPERLINK (다른 URL) | ⏸ 보류 | 셀 유지, 보고서에 "사용자 확인 필요" |
| ⑥ 이미 동일 URL HYPERLINK | ⚠️ 스킵 | 변경 없음, 보고서에 "중복 없음 확인" |
비고(J열)는 절대 건드리지 않음 — 기존 코멘트·버그 ID(예: "BUG-xxxx") 보존.
핵심 원칙: 데이터 손실 절대 X. ③④⑤ 케이스는 무조건 보류하고 사용자에게 결정 위임.
라벨 작성 규칙:
- 이모지 사용 금지 (TC 시트 일관성)
- 8~16자 한국어, 이미지 내용 요약
- section_path 또는 nearby_text 활용
- 예:
캐릭터 소켓 위치, 자동 생성 Z 계산, 사족 보행 비교
- 하이퍼링크는 파란색 밑줄로 자동 표시되므로 별도 마커 불필요
STEP 5: 결과 보고
## 이미지 매칭 결과
- 대상 TC: N건
- 부착 완료: M건 (X.X%)
- 빈 셀 삽입: a건
- 라벨 흡수 (짧은 텍스트): b건
- 미부착 (시각자료 불필요): K건
- 보류: L건
- 긴 자유 텍스트: TC-XXX, TC-YYY ...
- 다중 라인: TC-ZZZ ...
- 기존 다른 HYPERLINK: TC-AAA ...
- 변경 셀: K{row1}, K{row2}, ...
안전망
- 실패 격리: 매칭/임베드 실패 시 해당 TC만 스킵. 나머지는 정상 처리.
- 기존 J열 보존 (최우선): 30자 초과 / 다중 라인 / 다른 HYPERLINK는 보류, 사용자 결정 후 처리.
- 30자 임계값: 짧은 텍스트는 라벨로 흡수 (
"기존 / 라벨" 형태)
- 404 이미지: HYPERLINK는 그대로 두되, 보고서에 "링크 깨짐 의심: TC-XXX" 표기.
- 중복 검출: 동일 URL이면 스킵 (멱등성), 다른 URL이면 보류.
파일 산출물
| 위치 | 내용 |
|---|
specs/{기능명}/image_manifest.md | 첨부-섹션 매핑 캐시 (1시간 TTL) |
specs/{기능명}/image_match_log.md | 어떤 TC에 어느 이미지를 부착했는지 로그 |
비용·시간 (참고)
- 전체 100 TC: ~25K 토큰 / ~25초 / ~$0.10 (Sonnet)
- 카테고리 20 TC: ~8K / ~10초 / ~$0.03
- 단건: ~3K / ~5초 / ~$0.01
본 파이프라인 무영향 원칙
- tc-v2 파이프라인 (STEP 1~6 + 완료처리)에 절대 호출되지 않음
- 사용자가 명시적으로 트리거 시에만 실행
- 실패해도 TC 작성 결과에 영향 없음
