claude.ai 아티팩트를 발행하는 모든 지점이 공유하는 단일 SoT. 무엇을 싣는가는 표면별 문서가 정하고, 어떻게 발행하는가(아래)는 복제하지 않고 이 문서를 참조한다. 이 규약을 다른 파일에 옮겨 적으면 다음 변경 때 사본들이 서로 어긋난다.
0. 표면 목록 (consumers)#
| 표면 | 무엇을 싣는가 (표면별 SoT) |
|---|---|
| 이슈 본문 (Initiative/Project/Epic/work item) | plugins/cc-dev/rules/zenhub-conventions.md → "Issue Body Artifact Contract" |
| PR 작업내역 (PR 생성 시점 본문에 링크, CI 확정 후 같은 URL 갱신) | plugins/cc-dev/skills/pr-work-artifact/SKILL.md |
새 표면을 추가할 때는 표면 문서에 무엇을 싣는지만 쓰고, 1~6 절은 여기를 링크한다.
1. 발행은 외부 게시다 ⚠️#
아티팩트는 claude.ai 에 호스팅되는 웹 페이지다. 저장소 안의 파일이 아니다.
- 발행한 내용은 되돌려도 캐시·색인될 수 있다. 지웠으니 없어졌다고 가정하지 않는다.
- 절대 싣지 않는다: 토큰·시크릿·API 키, 내부 전용 URL·호스트명, 고객/개인 데이터, 아직 공개되지 않은 보안 취약점의 재현 절차.
-
판정이 애매하면 싣지 않고 저장소 경로만 가리킨다 (
.claude/..., 파일:줄 참조). 링크가 부족해서 사람이 한 번 더 묻는 실패가, 시크릿이 외부에 게시되는 실패보다 싸다.
2. 공개 범위 — "퍼블릭"은 자동이 아니다#
발행 시점의 아티팩트는 비공개다. Artifact 도구에는 공개 범위 파라미터가 없고,
공개 전환은 사람이 claude.ai 아티팩트 페이지의 공유 메뉴에서 직접 켜야 한다.
켠 뒤 접근 범위는 claude.ai 조직(Cocode Inc.) 단위다.
따라서 링크를 남기는 모든 표면은 아래 안내 문구를 링크 바로 아래에 함께 남긴다 (문구 고정 — 표면 간 동일):
> 🔒 이 아티팩트 링크는 발행 시점에 **비공개**입니다. 팀이 열어야 하면 claude.ai 아티팩트 페이지의 공유 메뉴에서 직접 공유를 켜주세요. 켠 뒤 접근 범위는 claude.ai 조직(Cocode Inc.) 단위입니다.- 링크가 안 열린다는 이유로 작업이 막혀서는 안 된다 → 기계가 읽어야 하는 것은 아티팩트에 두지 않는다 (§3).
- "자동 공개" 기능 요청은 도구 미지원이므로 범위 밖이다. 우회 호스팅을 시도하지 않는다.
3. 기계가 읽으면 원본, 사람만 읽으면 아티팩트#
자동 파이프라인이 파싱하는 것(AC·범위·DoD·우선순위 표·Closes #·테스트 판정)은
언제나 원본 표면(이슈 본문 / PR body)에 남는다. 아티팩트는 사람이 읽는 서술만 담는다.
애매하면 원본에 남긴다.
4. 안정된 정체성 — 같은 것은 같은 URL#
한 번 링크한 아티팩트를 갱신할 때:
| 항목 | 규칙 |
|---|---|
| 파일 경로 | 같은 경로로 재발행 → 같은 URL 로 재배포. 새 경로 금지 (링크가 낡은 판을 가리키게 된다) |
title | 재발행 간 고정 |
favicon | 재발행 간 고정 — 주제가 통째로 바뀔 때만 교체 |
| 다른 세션에서 갱신 | 같은 경로만으로는 부족하다. URL 을 url 파라미터로 넘겨야 같은 아티팩트를 갱신한다 |
⚠️ "같은 경로 → 같은 URL"은 같은 대화 안에서만 성립한다. 재푸시가 다음 세션에서 일어나면 새 URL 이 발급된다. 그래서 URL 의 영속 저장소는 표면 자체다 — 이슈 본문/PR 코멘트에 남은 링크를 되읽어
url로 넘긴다 (§5 절차 3).
5. 발행 절차 (순서 고정)#
artifact-design스킬을 먼저 로드한다 — 페이지를 쓰기 전에. 투자 수준을 맞추는 단계다.- 페이지 파일을 먼저 쓴다 (Write/Edit). 자기완결(self-contained) 필수 — 외부 CDN·폰트·이미지 차단(CSP).
-
기존 링크를 되읽는다. 표면에 이미 링크가 있으면 그 URL 을
url파라미터로 넘긴다. 없으면 새로 발행한다. -
Artifact호출 —favicon필수,description한 줄,title은 §4 대로 고정. - 반환된 URL 을 표면에 기록한다. 기록 실패 시 아티팩트는 고아가 된다 — URL 확보와 표면 기록은 한 묶음으로 처리한다.
- 링크 바로 아래에 §2 공유 안내 문구를 붙인다.
순서를 뒤집지 않는다: 이슈/코멘트를 먼저 만들고 나중에 링크를 끼워 넣으면 사후 수정이 필요하다.
6. Degradation Contract — 발행은 하드 게이트가 아니다#
Artifact 도구가 없는 세션(크론·CI·헤드리스)이 있고, 발행이 실패할 수도 있다.
어느 경우에도 호출한 워크플로를 중단시키지 않는다.
| 상황 | 행동 |
|---|---|
Artifact 도구 부재 | 서술을 전량 마크다운으로 원본 표면에 인라인하고 계속 진행 |
| 발행 호출 실패 | 1회 재시도 → 실패 시 마크다운 폴백. 워크플로 계속 |
| 갱신 재발행 실패 | 기존 링크를 그대로 두고 계속. 낡은 판을 가리키는 것이 링크가 사라지는 것보다 낫다 |
| 표면 기록 실패 | 이것은 실패로 취급한다 — 링크 없는 아티팩트는 아무도 못 찾는다. 재시도 후 로그 |
폴백할 때 로그 한 줄을 남긴다:
ℹ️ Artifact 미사용 — 전량 마크다운으로 진행 (사유: 도구 부재 | 발행 실패)7. 금지 사항 요약#
- ❌ §1 의 민감정보 게시
- ❌ 기계가 파싱하는 계약(AC·DoD·우선순위 표)을 아티팩트로만 두기
- ❌ 갱신 시 새 경로 발행 (URL 이 갈라진다)
- ❌ 발행 실패를 이유로 워크플로 중단
- ❌ 이 문서의 규약을 다른 파일에 복제 (참조만)