Claude Agent Skills: SKILL.md 완전 분석 가이드

<h1>Claude.ai 디자인 기능 사용법 완벽 가이드</h1><h2>1. Claude 디자인 기능이란?</h2><p>Claude는 단순한 텍스트 응답을 넘어 <strong>UI 디자인, 웹 페이지, 컴포넌트</strong> 등을 코드로 직접 생성·시각화할 수 있는 기능을 제공합니다. 핵심 기능은 <strong>Artifacts(아티팩트)</strong> 로, 생성된 결과물을 실시간 미리보기로 확인할 수 있습니다.</p><hr><h2>2. 주요 디자인 기능 종류</h2><table style="width: 817px;"><colgroup><col style="width: 200px;"><col style="width: 200px;"><col style="width: 417px;"></colgroup><tbody><tr><th colspan="1" rowspan="1" colwidth="200"><p>기능</p></th><th colspan="1" rowspan="1" colwidth="200"><p>설명</p></th><th colspan="1" rowspan="1" colwidth="417"><p>활용 예시</p></th></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>HTML/CSS 생성</p></td><td colspan="1" rowspan="1" colwidth="200"><p>정적 웹 페이지 디자인</p></td><td colspan="1" rowspan="1" colwidth="417"><p>랜딩 페이지, 포트폴리오</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>React 컴포넌트</p></td><td colspan="1" rowspan="1" colwidth="200"><p>동적 UI 컴포넌트 생성</p></td><td colspan="1" rowspan="1" colwidth="417"><p>버튼, 카드, 폼, 네비게이션</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>SVG 그래픽</p></td><td colspan="1" rowspan="1" colwidth="200"><p>벡터 이미지 생성</p></td><td colspan="1" rowspan="1" colwidth="417"><p>아이콘, 로고, 일러스트</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>대시보드 UI</p></td><td colspan="1" rowspan="1" colwidth="200"><p>데이터 시각화 레이아웃</p></td><td colspan="1" rowspan="1" colwidth="417"><p>관리자 페이지, 분석 화면</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>프로토타입</p></td><td colspan="1" rowspan="1" colwidth="200"><p>인터랙티브 목업</p></td><td colspan="1" rowspan="1" colwidth="417"><p>앱·웹 서비스 시연용 화면</p></td></tr></tbody></table><hr><h2>3. Artifacts 기능 활성화 및 사용 방법</h2><h3>3-1. Artifacts 활성화</h3><ol><li><p><strong>Claude.ai</strong> 접속 (claude.ai)</p></li><li><p>우측 상단 <strong>프로필 아이콘</strong> 클릭</p></li><li><p><strong>Feature Preview</strong> 또는 <strong>설정(Settings)</strong> 메뉴 진입</p></li><li><p><strong>Artifacts</strong> 토글 <strong>ON</strong> 설정</p></li></ol><blockquote><p>Claude.ai Pro 플랜에서 더욱 안정적으로 활용 가능합니다.</p></blockquote><h3>3-2. 디자인 생성 기본 흐름</h3><pre><code>① 프롬프트 입력 → ② Claude가 코드 생성 → ③ Artifacts 창에서 미리보기 → ④ 수정 요청 → ⑤ 최종 코드 복사·활용
</code></pre><hr><h2>4. 효과적인 프롬프트 작성법</h2><h3>✅ 좋은 프롬프트의 조건</h3><ul><li><p><strong>목적</strong>을 명확히 설명 (어떤 화면인지)</p></li><li><p><strong>스타일 키워드</strong> 포함 (모던, 미니멀, 다크모드 등)</p></li><li><p><strong>색상·폰트·레이아웃</strong> 요구사항 구체화</p></li><li><p><strong>기술 스택</strong> 명시 (HTML/CSS, React, Tailwind CSS 등)</p></li></ul><h3>📌 프롬프트 예시</h3><pre><code># 기본형
"로그인 페이지를 HTML/CSS로 만들어줘"

# 구체화형
"다크 테마의 SaaS 로그인 페이지를 Tailwind CSS를 사용해서 만들어줘.
로고 영역, 이메일/비밀번호 입력창, 소셜 로그인 버튼(Google, GitHub),
'비밀번호 찾기' 링크를 포함하고, 모바일 반응형으로 작성해줘."

# 수정 요청형
"버튼 색상을 파란색에서 보라색 계열(#7C3AED)로 변경하고,
카드 컴포넌트에 그림자 효과를 추가해줘."
</code></pre><hr><h2>5. 디자인 유형별 활용 가이드</h2><h3>5-1. 웹 페이지 디자인</h3><pre><code>프롬프트 예시:
"스타트업을 위한 랜딩 페이지를 만들어줘.
- 헤더: 로고 + 네비게이션 메뉴
- 히어로 섹션: 큰 타이틀 + CTA 버튼
- 기능 소개 카드 3개
- 푸터
- 색상 테마: 파란색 계열, 흰색 배경"
</code></pre><h3>5-2. React 컴포넌트 제작</h3><pre><code>프롬프트 예시:
"React로 재사용 가능한 모달 컴포넌트를 만들어줘.
props로 title, content, onClose 함수를 받고,
애니메이션 효과와 배경 오버레이를 포함해줘."
</code></pre><h3>5-3. 대시보드 UI</h3><pre><code>프롬프트 예시:
"관리자 대시보드 레이아웃을 만들어줘.
- 좌측 사이드바 (메뉴 목록)
- 상단 헤더 (검색창 + 알림 아이콘 + 프로필)
- 메인 영역: KPI 카드 4개 + 차트 영역
- Tailwind CSS 사용, 다크모드 지원"
</code></pre><h3>5-4. SVG 아이콘 및 그래픽</h3><pre><code>프롬프트 예시:
"'업로드' 기능을 나타내는 SVG 아이콘을 만들어줘.
화살표가 위로 향하는 심플한 라인 스타일,
24x24px 기준으로 작성해줘."
</code></pre><hr><h2>6. 디자인 수정 및 반복 작업 팁</h2><h3>단계적 수정 접근법</h3><pre><code>1단계: 전체 레이아웃 확인
   → "전반적인 구조가 맞는지 확인해줘"

2단계: 세부 스타일 조정
   → "헤더 높이를 줄이고 폰트 크기를 키워줘"

3단계: 반응형 처리
   → "모바일(768px 이하)에서 사이드바가 숨겨지도록 수정해줘"

4단계: 인터랙션 추가
   → "버튼 hover 시 색상 변화 애니메이션을 추가해줘"
</code></pre><h3>자주 쓰는 수정 명령어</h3><table style="width: 837px;"><colgroup><col style="width: 200px;"><col style="width: 637px;"></colgroup><tbody><tr><th colspan="1" rowspan="1" colwidth="200"><p>명령 유형</p></th><th colspan="1" rowspan="1" colwidth="637"><p>프롬프트 표현</p></th></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>색상 변경</p></td><td colspan="1" rowspan="1" colwidth="637"><p>"Primary 색상을 #3B82F6으로 변경해줘"</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>간격 조정</p></td><td colspan="1" rowspan="1" colwidth="637"><p>"카드 사이 여백을 더 넓혀줘"</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>반응형 추가</p></td><td colspan="1" rowspan="1" colwidth="637"><p>"태블릿·모바일 반응형으로 수정해줘"</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>컴포넌트 추가</p></td><td colspan="1" rowspan="1" colwidth="637"><p>"하단에 FAQ 섹션을 추가해줘"</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>스타일 변환</p></td><td colspan="1" rowspan="1" colwidth="637"><p>"전체 디자인을 다크모드 버전으로 바꿔줘"</p></td></tr></tbody></table><hr><h2>7. 생성된 코드 활용 방법</h2><h3>7-1. 코드 복사 및 적용</h3><ol><li><p>Artifacts 패널 우측 상단 <strong>복사(Copy) 버튼</strong> 클릭</p></li><li><p>VS Code, 코드 에디터에 붙여넣기</p></li><li><p>필요에 따라 <strong>파일 분리</strong> (HTML, CSS, JS)</p></li></ol><h3>7-2. 외부 도구 연동</h3><pre><code>- CodePen / JSFiddle  → 빠른 테스트 및 공유
- Figma              → 디자인 시안 참고용
- GitHub             → 코드 버전 관리
- Vercel / Netlify   → 즉시 배포
</code></pre><hr><h2>8. 디자인 작업 시 주의사항</h2><ul><li><p><strong>이미지 파일 직접 생성 불가</strong> → 이미지 URL 플레이스홀더로 대체 후 별도 교체 필요</p></li><li><p><strong>복잡한 애니메이션</strong>은 단계적으로 요청하는 것이 효율적</p></li><li><p><strong>외부 라이브러리</strong>(Chart.js, Three.js 등) 사용 시 CDN 링크 포함 요청</p></li><li><p>긴 코드의 경우 <strong>컴포넌트 단위로 분리</strong>해서 요청</p></li></ul><hr><h2>9. 활용 수준별 추천 시나리오</h2><table style="width: 729px;"><colgroup><col style="width: 200px;"><col style="width: 529px;"></colgroup><tbody><tr><th colspan="1" rowspan="1" colwidth="200"><p>수준</p></th><th colspan="1" rowspan="1" colwidth="529"><p>추천 활용</p></th></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>입문자</p></td><td colspan="1" rowspan="1" colwidth="529"><p>간단한 명함 페이지, 버튼 컴포넌트, 기본 폼 디자인</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>중급자</p></td><td colspan="1" rowspan="1" colwidth="529"><p>랜딩 페이지, 반응형 레이아웃, React UI 컴포넌트</p></td></tr><tr><td colspan="1" rowspan="1" colwidth="200"><p>고급자</p></td><td colspan="1" rowspan="1" colwidth="529"><p>전체 대시보드 시스템, 디자인 시스템 구축, 인터랙티브 프로토타입</p></td></tr></tbody></table><hr><h2>10. 핵심 요약</h2><blockquote><ol><li><p><strong>구체적인 프롬프트</strong>를 작성할수록 원하는 결과에 가까워진다.</p></li><li><p><strong>단계적 수정 요청</strong>으로 완성도를 높인다.</p></li><li><p>Artifacts의 <strong>실시간 미리보기</strong>를 적극 활용한다.</p></li><li><p>생성된 코드는 <strong>그대로 사용하기보다 기반 코드로 활용</strong>하는 것이 효율적이다.</p></li><li><p>기술 스택(React, Tailwind 등)을 <strong>명시</strong>하면 더 정확한 결과를 얻는다.</p></li></ol></blockquote><p></p>

Claude.ai 디자인 기능 사용법 완벽 가이드

<p>도메인, OpenAI API, 이미 운영 중이던 한 대의 VPS. 이 셋만으로 내가 쓴 글들이 검색되고, 시멘틱 검색이 작동하는 사이트를 만들었다. 도구는 <strong>Next.js · FastAPI · docconv</strong> 셋. 공식 문서대로 따라가다 막힌 지점들과 그걸 어떻게 풀었는지 기록한다.</p><h2>왜 자체 VPS인가</h2><p>처음엔 Vercel을 고민했다. Next.js의 본가이고, 무료 티어로 충분히 시작 가능. 그러나 두 가지 이유로 자체 호스팅을 택했다.</p><ul><li><p><strong>비용 통제</strong> — 트래픽 늘어나도 같은 VPS 안에서 끝남. Vercel은 이미지 최적화·serverless 호출 단위로 과금</p></li><li><p><strong>사이드카 자유도</strong> — Python ML 스택(docconv)을 같은 호스트에 띄워야 하는데, Vercel에선 별도 서비스로 분리해야 한다. 작은 사이트엔 과함</p></li></ul><p>이미 다른 서비스(<code>ai.sshsys.kr</code>)가 운영되고 있던 VPS라서, 그 위에 nginx 가상호스트만 추가하는 형태가 가장 단순했다.</p><h2>최종 토폴로지</h2><pre><code>VPS (Ubuntu 24.04)
├── nginx :80/:443
├── postgresql :5432 (localhost only)
│
├── ai.sshsys.kr   → :8001 hssagent (기존)
├── sshsys.kr      → :3000 portfolio web (Next.js)
├── api.sshsys.kr  → :8002 portfolio api (FastAPI)
└── docs.sshsys.kr → :8003 docconv (지식 플랫폼)
</code></pre><p>4개의 도메인, 3개의 새 서비스. 각각 격리된 venv·systemd 유닛·DB를 가진다.</p><h2>첫 함정: 공유 venv 충돌</h2><p>처음에 시간을 아끼려고 portfolio 백엔드와 docconv를 같은 venv에 깔았다. 곧장 깨졌다.</p><pre><code>fastapi.exceptions.FastAPIError: Invalid args for response field!
Hint: check that ForwardRef('UploadFile') is a valid Pydantic field type.</code></pre><p>portfolio가 FastAPI 0.115.0에 핀되어 있는데, docconv는 0.136.1을 기대해서 한 venv에 두 버전이 충돌. 결국 venv를 분리했다.</p><pre><code>/var/www/sshsys/
├── venv/                  ← portfolio 전용 (FastAPI 0.115.0)
└── docconv/venv/          ← docconv 전용 (FastAPI 0.136.1)
</code></pre><p>당연한 듯하지만 한 번 합쳐봐야 절실해진다. <strong>운영 환경에서 venv 공유는 절대 비추</strong>.</p><h2>Pydantic Settings의 까다로움</h2><p>portfolio 백엔드의 <code>config.py</code>는 pydantic-settings로 환경변수를 관리한다. 그런데 docconv 연동을 위해 <code>.env</code>에 <code>DOCCONV_URL</code>·<code>DOCCONV_INTERNAL_TOKEN</code>·<code>PUBLIC_SITE_URL</code>을 추가하니 시작도 못 했다.</p><pre><code>pydantic_core._pydantic_core.ValidationError: 4 validation errors for Settings
public_site_url
  Extra inputs are not permitted</code></pre><p>해결: <code>extra="ignore"</code> 옵션 추가. 이러면 라우터에서 <code>os.environ.get(...)</code>로 직접 읽는 변수들이 Settings에 등록되어 있지 않아도 거부되지 않는다.</p><pre><code class="language-python">model_config = SettingsConfigDict(
    env_file=".env",
    case_sensitive=False,
    extra="ignore",
)</code></pre><h2>빌드 시점에 SSL 미발급 도메인 호출하는 함정</h2><p>가장 까다로웠던 부분. 프론트엔드를 빌드할 때 Next.js가 <code>getStaticProps</code>를 실행하면서 <code>https://api.sshsys.kr</code>에 axios로 fetch한다. 그런데 그 시점엔 nginx에 <code>api.sshsys.kr</code> 가상호스트도, SSL 인증서도 없었다. 그래서 같은 IP의 다른 호스트의 인증서가 응답하면서 호스트 불일치 에러.</p><pre><code>Error: Hostname/IP does not match certificate's altnames:
  Host: api.sshsys.kr is not in the cert's altnames:
  DNS:ai.sshsys.kr, DNS:&lt;other-service&gt;
</code></pre><p>해결책은 <strong>서버사이드용 API URL과 브라우저용 API URL을 분리</strong>하는 것이다.</p><pre><code class="language-javascript">// src/lib/api.js
export const API_URL =
  (typeof window === "undefined"
    ? process.env.INTERNAL_API_URL || process.env.NEXT_PUBLIC_API_URL
    : process.env.NEXT_PUBLIC_API_URL) || "http://localhost:8000";</code></pre><p><code>.env.local</code>:</p><pre><code>NEXT_PUBLIC_API_URL=https://api.sshsys.kr      # 브라우저
INTERNAL_API_URL=http://127.0.0.1:8002          # 빌드/SSR
</code></pre><p>빌드 시점은 nginx 거치지 않고 백엔드 직접 호출. 브라우저는 공개 도메인. nginx 설정 순서에 빌드가 종속되지 않는다. 같은 정보가 두 경로로 흘러야 할 때 분리하는 패턴은 다른 곳에서도 쓸 수 있다.</p><h2>docconv 사이드카 — pgvector로 단순화</h2><p>이 사이트에는 시멘틱 검색·Q&amp;A·엔티티 자동 추출을 담당하는 별도 서비스가 떠 있다. docconv라는 지식 플랫폼인데, 처음엔 ChromaDB를 쓸 줄 알았다.</p><p>그런데 docconv의 store는 <strong>PostgreSQL + pgvector</strong> 백엔드를 지원한다. 이미 portfolio 백엔드용 Postgres가 있으므로, 같은 인스턴스에 <code>docconv</code> DB만 추가하면 끝. ChromaDB가 자체 SQLite + DuckDB 메모리를 따로 잡는 것 대비 메모리 풋프린트가 작다.</p><pre><code>{"status":"ok","backend":"postgresql+pgvector",
 "collections":{"chunks":0,"entities":0},
 "embedding_model":"text-embedding-3-small"}</code></pre><p>대기 메모리 <strong>140MB</strong>. ChromaDB 구성이었으면 250MB 이상 잡았을 것.</p><h2>portfolio ↔ docconv 연결</h2><p>두 서비스 사이엔 내부 토큰 한 줄로 끝낸다. portfolio가 글을 저장하면 background_task로 docconv의 <code>/wiki/ingest</code>를 호출. docconv가 본문을 청킹·임베딩·엔티티 추출 후 entity 슬러그를 반환하면, portfolio가 그걸 DB의 <code>entities</code> JSONB 컬럼에 저장한다.</p><pre><code class="language-python"># portfolio backend/app/routers/blogs.py
def _index_blog(blog_id: str, payload: dict) -&gt; None:
    entities = knowledge_client.ingest(
        kind="blog",
        doc_id=blog_id,
        title=payload.get("title") or "",
        content_html=payload.get("content") or "",
        url=f"{SITE_URL}/blog/{blog_id}",
        tags=payload.get("tags") or [],
        category=payload.get("category"),
    )
    if entities is None:
        return
    db = SessionLocal()
    try:
        b = db.query(Blog).filter(Blog.id == blog_id).first()
        if b:
            b.entities = entities or None
            db.commit()
    finally:
        db.close()</code></pre><p>nginx에선 <code>/wiki/ingest</code>·<code>/wiki/remove</code>·<code>/extract</code> 같은 인덱싱 엔드포인트는 <code>127.0.0.1</code>만 허용하고, 검색·Q&amp;A는 공개. 이중 격리.</p><h2>메모리 측정 결과</h2><p>4개 서비스가 동시에 떠 있는 정상 운영 시:</p><pre><code>sshsys-docs (docconv)        139.6 MB
sshsys-backend (hssagent)    202.7 MB
sshsys-api (portfolio)       215.5 MB
sshsys-web (Next.js)          70~150 MB
─────────────────────────────────────
                             약 700 MB</code></pre><p>2GB VPS에 충분히 들어간다. 빌드 시점만 잠깐 1GB 가까이 점유하는데, 그때만 docconv를 일시 중단하면 안전하다.</p><p></p><p>이 글이 사이트에 첫 콘텐츠로 올라가면, docconv가 자동으로 entity를 뽑아낸다. <code>/topics/fastapi</code>·<code>/topics/nginx</code>·<code>/topics/pgvector</code> 같은 페이지가 자동 생성될 것이다. </p><p></p>

My Archive

Claude Agent Skills: SKILL.md 완전 분석 가이드

Claude.ai 디자인 기능 사용법 완벽 가이드

sshsys.kr 배포기 — Next.js · FastAPI · docconv를 단일 VPS에 띄우기