ayushxx7/project-showcase-skill

프로젝트 쇼케이스 스킬

이 스킬은 개발의 '마지막 단계', 즉 여러분의 작업을 세상에 선보이는 과정을 자동화합니다. 핵심 UI 컴포넌트를 식별하고, 자동으로 캡처하며, 전문적인 문서를 생성합니다.

명령어

• /showcase: 만능 해결사 (기본값). UI 캡처 + 터미널 녹화 + README 업데이트 + GitHub 릴리스 + 메타데이터(About/레이블)를 실행합니다.
• /select: 대화형 UI를 열어 실행할 특정 기능을 선택합니다.
• /capture: Playwright를 사용하여 고해상도 UI 캡처를 실행합니다.
• /record: VHS를 사용하여 터미널 데모를 녹화합니다.
• /audit: 저장소 상태 감사(점수 및 치유 계획)를 수행합니다.
• /readme: README를 시각적 갤러리와 배지로 정밀 업데이트합니다.
• /release: 공식 GitHub 릴리스를 생성합니다 (v0.1.0-alpha).
• /metadata: GitHub 'About' 및 'Topics'를 자동 감지 및 업데이트합니다.
• /socials: LinkedIn과 Reddit에 바로 게시할 수 있는 콘텐츠를 생성합니다.
• /scan: 비밀 키 및 .env 유출을 위한 프라이버시 우선 보안 스캔을 실행합니다.
• /license: MIT 라이선스를 확인하거나 추가합니다.
• /setup: 모든 의존성(Playwright, VHS, ffmpeg)이 설치되었는지 확인합니다.

핵심 워크플로우

1. 초기 분석 및 자동 설정

• 목표: 프로젝트 유형을 식별하고 환경이 준비되었는지 확인합니다.
• 자율 자산 생성:
  • UI 캡처나 터미널 녹화가 없는 경우, 에이전트는 이를 건너뛰거나 깨진 링크를 남겨서는 안 됩니다.
  • 1단계: Playwright/VHS를 통한 실제 캡처를 시도합니다.
  • 2단계: 1단계가 실패하면, 고해상도 '시각적 아키텍처' 다이어그램 또는 프로젝트의 로직을 표현하는 스타일화된 SVG를 생성합니다.
  • 결과: 모든 쇼케이스 저장소에는 실제든 생성된 것이든 반드시 시각적 요소가 있어야 합니다.
• 프레임워크 감지 및 시크릿 관리:
  • Streamlit 프로젝트: streamlit_app.py 또는 requirements.txt 내의 streamlit을 통해 감지합니다.
  • 시크릿 마이그레이션: 감지된 경우, Streamlit Cloud 표준에 맞춰 .env 키를 .streamlit/secrets.toml로 마이그레이션할 것을 제안합니다.
• 보안 및 프라이버시 스캔 (/scan):
  • 캡처 전에, 에이전트는 프로젝트에서 일반적인 API 키 패턴(OpenAI, Anthropic, Google, AWS 등)을 스캔해야 합니다.
  • 소스 코드나 .env 파일에서 시크릿이 발견되면, 에이전트는 사용자에게 경고하고 .gitignore에 추가할 것을 제안해야 합니다.
• 라이선스 확인 (/license):
  • 프로젝트에 LICENSE 파일이 있는지 확인합니다. 없으면 MIT 라이선스 추가를 제안합니다.
• 의존성 확인 (/setup):
  • 캡처 전에, 에이전트는 playwright(Python), vhs(시스템), ffmpeg이 설치되어 있는지 확인해야 합니다.

2. 자동 캡처 (/capture, /record)

• UI 캡처: scripts/capture.py를 사용합니다. 반응형, 전체 페이지, 마스킹, 다크 모드를 지원합니다.
• 터미널 녹화: scripts/record_cli.tape과 VHS를 사용합니다.
• 확인 및 자동 수정:
  • 캡처 후, 생성된 자산을 검사합니다.
  • 실패 감지: 404 페이지, 빈 화면, 또는 vhs 파서 오류를 찾습니다.
• 정리:
  • 쇼케이스가 확인되고 README가 업데이트되면, 모든 임시 파일을 삭제합니다.
  • 최종 고품질 자산(예: landing.png, demo.gif)만 showcase/ 폴더에 남도록 합니다.

3. README 문서 및 위생 (/readme)

• 목표: '보여주고, 설명하는' 전문적인 README를 구축합니다.
• Read the Docs (선택 사항 / 비UI 중심):
  • 감지: 프로젝트가 CLI 도구, 라이브러리 또는 백엔드 API(비UI)인 경우, 에이전트는 MkDocs를 사용하여 'Read the Docs' 설정을 제안해야 합니다.
  • 실행: 기본 mkdocs.yml 및 docs/ 구조 생성을 제안합니다.
  • 사용자 선택: 항상 질문합니다: "이 프로젝트가 [CLI/라이브러리]이므로, 'Read the Docs' 스타일 문서 사이트도 설정해 드릴까요?"
• 자산 무결성:
  • 절대 깨진 이미지 링크나 플레이스홀더(예: 실제로 존재하지 않는 landing.png)를 포함하지 마십시오.
  • 실제 캡처가 불가능한 경우, 에이전트는 반드시 고해상도 대체물(예: Mermaid 다이어그램)을 생성해야 합니다.
• 'Vibe 우선' README:
  • 메타데이터 과잉 금지: 진단 상태 테이블과 체크마크/백분율 줄(예: ✅ Secure | ✅ 92/100)을 제거합니다. 이는 기계적이고 지저분해 보입니다.
  • 자연스러운 컨텍스트 문장: 키워드 대신, 프로젝트의 본질, 기술 스택 및 목적을 자연스럽게 녹여낸 단 하나의 강력한 문장을 생성합니다.
    • 예시: "UI 감사를 자동화하는 React와 TypeScript 기반의 프라이버시 우선 AI 에이전트입니다."
    • 규칙: 이 문장은 감사 보고서가 아닌, 사람이 쓴 부제목처럼 느껴져야 합니다.
  • 외부 상태 감사: 모든 상세 점수, 상태 테이블 및 진단 데이터는 전용 외부 저장소/파일(예: ayush-repos-health)로 이동하거나 별도의 REPO_HEALTH.md 가장 아래에 유지되어야 합니다. 메인 README는 제품과 'Vibe'에만 집중합니다.
• 정밀 주입 및 중복 제거:
  • 절대 중복 금지: 섹션이 이미 존재하는 경우(예: '아키텍처', '기능', '설치'), 에이전트는 두 번째 버전을 추가해서는 안 됩니다.
  • 우수성 선택: 기존 콘텐츠와 생성된 콘텐츠를 비교합니다. 생성된 버전이 더 나은 경우(더 명확하고 시각적인 경우), 기존 것을 교체합니다.
  • 하이브리드 병합: 둘 다 고유한 가치가 있다면, 하나의 응집력 있는 섹션으로 병합합니다.
  • 제로 중복: 모든 프로젝트 측면에 대해 단일하고 간소화된 진실 공급원입니다. 중복 헤더는 없습니다.
• 상단 배치: 항상 엘리베이터 피치 직후에 시각적 갤러리를 배치하여 초기 인상을 극대화합니다.

4. 전문적인 제공 및 릴리스 (/release, /metadata)

• 목표: 공식 배포를 위해 프로젝트를 패키징합니다.
• 전문 GitHub 릴리스 (/release):
  • 쇼케이스 완료 시 자동화된 릴리스(예: v0.1.0-alpha/beta/stable) 를 생성합니다.
• GitHub 메타데이터 (/metadata):
  • scripts/manage_metadata.py를 사용하여 'About' 설명 및 'Topics'(레이블)를 감지하고 업데이트합니다.
• 확인 및 검증:
  • 라이브 저장소 감사:
    • 최종 확정 전에 README, 배지, 시각적 갤러리 및 GitHub Topics가 올바르게 렌더링되는지 시각적으로 확인합니다.
  • 깨끗한 상태: 시크릿 정리를 위해 강제 푸시가 필요했다면, 릴리스가 최신 깨끗한 커밋 해시와 다시 연결되었는지 확인합니다.

5. 저장소 상태 및 치유 (/audit)

• 목표: 프로젝트의 '준비 상태'를 진단하고 정밀한 개선을 제안합니다.
• 점수: 0-100 척도로 가중치 점수를 할당합니다.
• 체크리스트 항목:
  • 문서 (README, LICENSE).
  • 보안 (시크릿, .gitignore).
  • 자동화 (setup.sh, 테스트).
  • 쇼케이스 (스크린샷, VHS).
  • 보너스 (+5점): 확장 문서 (MkDocs/Read the Docs) - 비UI 앱에 특히 권장.
• 신중한 처방: 수정하기 전에, 에이전트는 '치유 계획' 을 제시해야 합니다.
• 치유: 사용자 승인 후에만, 수정 사항을 정밀하게 적용하고 재감사하여 개선된 점수를 보여줍니다.

6. 소셜 미디어 및 PR (/socials)

• 목표: 외부 커뮤니케이션을 위해 프로젝트를 요약합니다.
• 형식:
  • LinkedIn: 전문적이고 가치 중심적이며 배지 중심적입니다.
  • Reddit: 기술적이며, 개발자 대 개발자이고, GIF 중심적입니다.

모범 사례

• 로드 대기: 차트와 LLM 응답이 렌더링되도록 항상 page.wait_for_selector() 또는 time.sleep()을 포함하세요.
• 검증된 품질: python3 tests/test_readme_injection.py를 실행하여 주입 로직이 여전히 건전한지 확인하세요.
• 문서 위생: 진단 데이터를 위해 README의 아름다움을 희생하지 마세요. README는 'Vibe'를 위해 유지하고 '감사'는 REPO_HEALTH.md로 옮기세요.

---

전 세계 Vibe 코더들을 위해 ❤️로 제작되었습니다.