tc

name	tc-이미지매칭
description	TC 시트의 K열(담당자)에 Confluence 페이지 이미지를 선택적으로 임베드. 본 TC-v2 파이프라인과 완전 분리된 on-demand 스킬. 트리거 "이미지 매칭해줘", "TC에 이미지 링크 추가", "비고에 Confluence 이미지 붙여줘", "/tc-이미지매칭".

tc-이미지매칭 (on-demand)

트리거

• 슬래시: /tc-이미지매칭
• 자연어: "이미지 매칭해줘", "TC에 이미지 링크 추가해줘", "비고에 Confluence 이미지 붙여줘"

입력 (사용자에게 묻기)

1. 스프레드시트 ID + 탭 이름 (또는 URL)
2. 범위: 전체 / 카테고리(대분류) / TC ID 범위 / 단건
3. 기획서 위치: 시트 L6 셀 (TC 생성 시 자동 입력됨). 없으면 사용자에게 물어보기.

제외 룰 (이미지 매칭 안 함)

다음 조건 중 하나라도 해당되면 이미지 매칭 스킵:

조건	이유
① 대분류 = "기본기능" (또는 기본기능 섹션 내 상속 행)	자명한 화면, 시각자료 불필요.
② 행 번호 ≤ 10	양식/헤더/프로젝트 정보 패널 영역. 데이터 행 아님.

OR 조건. 둘 중 하나만 맞아도 제외.

흐름

STEP 1: 사전 정보 수집

1. 시트 메타데이터 읽기:
   • 헤더(1행): TC ID / 대분류 / 중분류 / 소분류 / 검증단계 / 재현 스탭 / 플랫폼 / PC 결과 / 모바일 결과 / 비고(J열) / 담당자(K열)
   • 비고(J)는 건드리지 않음. 이미지 링크는 K열(담당자) 사용.
   • 시트 L6 = Confluence URL 확인
2. 대상 TC 데이터 추출 (재현스탭, 검증포인트, K열 기존 값)
3. 제외 룰 적용: 기본기능 OR 행 ≤ 10인 TC는 후보에서 제외

STEP 2: Confluence 분석 (image_manifest 생성)

1. confluence_get_attachments (Atlassian MCP, 토큰) → 첨부의 숫자 attID(id의 att 제거) + 파일명 추출. 미리보기 URL에 attID 필수이며, attID는 이 토큰 기반 호출로만 얻음 (getConfluencePage/confluence_raw.md엔 pageID·파일명만 있고 attID 없음)
2. 이미지 위치/섹션 컨텍스트: confluence_get_page 또는 specs/{기능명}/confluence_raw.md(있으면 재사용)에서 섹션 헤딩 + nearby_text 추출 (매칭 판단용)
3. 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}, ...

안전망

1. 실패 격리: 매칭/임베드 실패 시 해당 TC만 스킵. 나머지는 정상 처리.
2. 기존 J열 보존 (최우선): 30자 초과 / 다중 라인 / 다른 HYPERLINK는 보류, 사용자 결정 후 처리.
3. 30자 임계값: 짧은 텍스트는 라벨로 흡수 ("기존 / 라벨" 형태)
4. 404 이미지: HYPERLINK는 그대로 두되, 보고서에 "링크 깨짐 의심: TC-XXX" 표기.
5. 중복 검출: 동일 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 작성 결과에 영향 없음