클로드 코드 아티팩트 실제 활용기

외주 개발을 하면 클라이언트에게 문서를 보냅니다. 예전엔 HTML 파일을 만들어서 카톡에 첨부했습니다. 고칠 게 생기면 새 파일을 다시 보냈고요.

지금은 링크 하나를 보냅니다. 내용이 바뀌면 같은 링크가 그대로 바뀝니다.

이번 주에 그걸 두 군데에 붙였습니다. 하나는 클라이언트한테, 하나는 저 자신한테요.

아티팩트가 뭐냐면

Claude Code에 아티팩트라는 기능이 있습니다. 세션에서 만든 결과물을 claude.ai에 웹페이지로 올려주는 기능입니다. 터미널에 글자로 뱉는 대신에요.

처음 발행하면 이렇게 물어봅니다.

Claude wants to publish "..." to a private page on claude.ai

허락하면 주소가 뜨고 브라우저가 열립니다. 터미널에서 Ctrl+] 를 누르면 마지막 아티팩트가 다시 열립니다.

써보면서 알게 된 성질 몇 가지입니다.

• 기본은 비공개입니다. 만들어도 나만 봅니다. 공유하려면 페이지 위쪽 Share를 눌러야 합니다.

• 다시 발행하면 주소가 그대로입니다. 대신 버전으로 쌓이고, 어느 버전을 보여줄지 고를 수 있습니다.

• 다른 세션에서 고치려면 주소를 줘야 합니다. 안 주면 새 아티팩트가 하나 더 생깁니다. 저는 이걸 몰라서 처음에 두 개 만들 뻔했습니다.

• 한 장짜리 페이지입니다. 외부 인터넷을 못 씁니다. 폰트도 이미지도 다 페이지 안에 들어가야 합니다.

• Pro·Max·Team·Enterprise 요금제에서, /login 으로 로그인된 세션이어야 됩니다.

용도가 "보기 좋은 화면"이라 생각하기 쉬운데, 저한테 쓸모 있었던 건 링크가 안 바뀐다는 쪽이었습니다. 문서를 고쳐도 클라이언트가 받은 링크는 그대로니까요.

케이스 1 — 클라이언트가 눌러보는 확인 문서

실물: https://claude.ai/code/artifact/d6d98765-71af-49b8-9270-1be401927865

릴리스하고 나서 "이거 확인해주세요"를 보냅니다.

화면 8개, 항목 31개짜리입니다. 클라이언트가 앱을 열어놓고 하나씩 눌러가며 봅니다. 누르면 줄이 그어지고 위에 진행률이 올라갑니다. 오른쪽 위 버튼을 누르면 PDF로 나갑니다.

여기서 신경 쓴 건 말투입니다. 받는 사람이 개발자가 아니라서요.

LocalStorage → Firestore 마이그레이션 이 아니라 폰을 바꿔도 하트 저장이 남습니다 라고 씁니다.

그리고 확인 안 된 건 감추지 않습니다.

"폰을 바꿔봐야 확인되는 항목입니다." "아직 그만큼 쌓인 방이 없어 겉보기 차이는 없습니다."

매끄럽게 쓰려고 이런 걸 지우면, 나중에 "된다며?" 소리를 듣습니다.

케이스 2 — AI한테 "내 말 알아들었냐" 묻는 문서

실물: https://claude.ai/code/artifact/5cc1aaf6-4e44-41eb-842a-d0d420fb384c

이게 이번 주에 새로 아티팩트로 옮긴 쪽입니다.

원래 하던 방식은 이렇습니다. 고칠 걸 문서로 적어서 Claude한테 주고, 정리한 걸 받아서, 코딩 시키기 전에 대조합니다. 그 대조하는 문서를 아티팩트로 뽑았습니다.

실제 요청이 이렇게 생겼습니다. 카톡 쓰듯 적은 9건짜리입니다.

위쪽의 여백이 많다. 그리고 저 스크롤하면 위에 썸네일 부분은 고정인데 같이 스크롤 되었으면 좋겠다.

이걸 항목마다 원문 그대로 회색 칸에 두고, 그 아래에 "이렇게 알아들었습니다"를 붙입니다. 앱 화면 캡처에는 빨간 네모를 쳐서 "여기 말씀이시죠"를 눈으로 대조하게 했습니다.

만드는 도중에 하나 걸렸습니다.

1번 항목이 가리킨 이미지 파일이 폴더에 없었습니다. 정리본에는 "이 이미지가 1번 근거"라고 적혀 있는데 파일이 없습니다. 즉 그 항목은 화면을 못 본 채 코드만 보고 판단한 것이었습니다.

되읽기 문서를 안 만들었으면 안 드러났을 종류입니다.

이런 게 5건 나왔습니다. 같은 자리 문구를 두 번 다르게 말한 것, 보내준 캡처가 예전 버전인 것 같은 것들이요. 문서 맨 아래에 그 5건만 표로 모아뒀습니다. 나머지는 그냥 하면 되고, 여기만 답하면 착수합니다.

ALT

한국어 앱 스크린샷

두 케이스를 나란히 놓으면 이렇습니다.

같은 색, 같은 검사, 문서 틀만 다릅니다.

매번 같은 얼굴로 나오게 하기

아티팩트는 발행할 때마다 Claude가 화면을 새로 그려줍니다. 그냥 두면 매번 다르게 생깁니다.

공식 문서에 이런 대목이 있습니다.

프로젝트에 이미 있는 디자인 시스템을 먼저 찾아본다. 그리고 그걸 자기 판단보다 우선한다.

그래서 색 정의 파일을 하나 만들어뒀습니다. 그랬더니 매번 같은 얼굴로 나옵니다.

만드는 과정에서 두 가지가 걸렸습니다.

하나. 우리가 브랜드 색을 안 쓰고 있었습니다.

색을 초록으로 바꾸려고 회사 로고 파일을 열어서 픽셀 색을 세어봤습니다. #5a6a59, 세이지 그린이었습니다. 그런데 제 파일에 적힌 주조색은 파랑(#3a6ee0)이었습니다.

ALT

반란군이라는 단어가 포함된 파란색과 녹색 색상 구성표

문서가 시스템을 안 따른 게 아니라, 시스템이 브랜드를 안 따르고 있었습니다.

둘. 눈으로 안 보이는 미달이 있었습니다.

색을 바꾸기 전에 명암비(글자와 배경이 얼마나 구분되는지 재는 값. 기준 4.5:1)를 먼저 계산했습니다. 라이트·다크 두 벌로 94쌍을 쟀더니 미달 3건이 나왔습니다. 새 색이 아니라 이미 쓰던 색에서 나왔습니다.

세 번째가 얄궂었습니다. 실제로 클라이언트에게 나갔던 문서인데 기준에 0.06 모자랍니다. 눈으로는 안 보입니다. 색상은 그대로 두고 밝기만 6% 낮춰 4.89로 맞췄습니다.

체크박스 1.21은 좀 부끄러웠습니다. 클라이언트가 눌러야 하는 네모인데 배경과 거의 구분이 안 됐습니다. 그 상태로 나갔습니다.

검사를 제가 기억하지 않아도 되게 만들었습니다

여기까지 만들고 나니 문제가 하나 남았습니다.

문서를 다 만들면 검사 명령을 한 줄 쳐야 합니다. 이런 걸요.

bash reference/verify.sh 분양메이트-수정확인-1.0.7.html

그걸 치는 게 접니다. 급하면 안 칩니다. 이 skill을 만든 이유가 "매번 다르게 나와서"인데, 검사를 사람이 기억해야 하면 결국 같은 자리로 돌아옵니다.

그래서 hook 을 걸었습니다. hook은 "이런 일이 생기면 이 명령을 자동으로 실행해라"를 미리 등록해두는 기능입니다. 저는 파일을 저장할 때마다 저 검사 명령이 저절로 실행되게 등록했습니다.

그런데 파일 저장은 하루에 수십 번 일어납니다. 설명 문서 고칠 때도, 코드 만질 때도요. 그때마다 보고서 검사기가 돌면 곤란하니까 "이건 보고서다"를 알아보는 기준을 셋 붙였습니다.

진짜 도는지 확인하려고 시험용 파일을 하나 만들었습니다. 멀쩡한 보고서를 복사해서 일부러 두 군데를 망가뜨렸습니다. 색을 토큰 대신 직접 적고, 제목을 빈칸으로 되돌렸습니다.

돌려보니 둘 다 잡았습니다. 몇 번째 줄인지까지 알려줍니다.

걸려도 하던 작업을 멈추지는 않습니다. "이게 걸렸다"고 알려주고 넘어갑니다. 막아버리면 급할 때 오히려 방해가 되니까요.

쓰면서 알게 된 것 몇 개

이미지가 제일 무겁습니다. 로고를 원본 그대로 넣으면 93KB인데, 실제로 쓰는 크기(48px)에 맞춰 줄이면 12KB입니다. 아티팩트는 외부 인터넷을 못 써서 이미지가 전부 페이지 안에 들어갑니다. 안 줄이면 그만큼 그대로 무거워집니다.

주소를 안 주면 새로 만듭니다. 다른 세션에서 고치라고 하면 기존 걸 못 찾고 새 아티팩트를 만듭니다. 링크를 같이 줘야 같은 주소에 덮어씁니다.

다크 모드로 보다가 PDF를 뽑으면 검은 종이가 나옵니다. 이건 실제로 당할 뻔했습니다. 아티팩트는 보는 사람 화면 설정을 따라가는데, 다크 상태에서 인쇄하면 그 색이 그대로 찍힙니다. 다크 규칙을 "화면일 때만" 적용되게 묶어서 막았습니다. 계산으로는 못 잡고 뽑아봐야 아는 종류였습니다.

왼쪽이 다크로 볼 때, 오른쪽이 그 상태에서 그대로 뽑은 PDF 입니다.

ALT

녹색 배경의 한국 앱 스크린샷