rfdiosuao/AgentSkill

Craft Repository README

리포지토리를 명확하고 신뢰할 수 있는 랜딩 페이지로 만듭니다. 모든 주장, 명령어, 배지 및 링크를 실제 프로젝트에 기반하세요. 시각적 완성도가 정확성을 앞서지 않아야 합니다.

작업 모드 선택

• 감사(audit) 모드: 사용자가 피드백만 요청할 때 사용합니다. 검사하고 보고만 하며, 편집하거나 게시하지 않습니다.
• 빌드(build) 모드: 사용자가 README를 생성하거나 개선해 달라고 요청할 때 사용합니다. 리포지토리를 편집하고 결과를 검증합니다.
• 게시(publish) 모드: 사용자가 커밋, 푸시, 풀 리퀘스트 열기 또는 리포지토리 설정 변경을 요청할 때만 사용합니다. 리포지토리의 일반적인 Git 워크플로우를 따릅니다.

1. 실제 프로젝트 검사

초안을 작성하기 전에 다음을 검사합니다.

• 기존 README*, 기여(contribution), 보안(security), 라이선스(license), 변경 로그(changelog), 배포 문서.
• 패키지 매니페스트, 진입점(entry points), 예제 환경 파일, 테스트 명령어, 스크린샷, 로고, 공개 URL.
• Git 리모트(remote), 기본 브랜치(default branch), 릴리즈 태그(release tags), CI 워크플로우, 호스팅 설정.
• AGENTS.md 또는 CONTRIBUTING.md와 같은 리포지토리 수준의 지침.

제품 이름, 한 문장 가치 제안, 대상 사용자, 지원 플랫폼, 설치 명령어, 실행 명령어, 배포 스토리를 증거에 기반하여 도출합니다. 확인할 수 없는 중요 사실은 생략하거나 '계획됨'으로 명확히 표시합니다.

2. 공개 범위 및 보안 점검 실행

README 작업을 릴리즈 검토로 취급합니다. 세부 정보를 노출하기 전에:

• 추적된 파일과 스테이징된 변경 사항에서 API 키, 개인 키, 토큰, 비밀번호, 쿠키, 내부 호스트 이름, 개인 IP, 개인 경로를 검색합니다.
• 로컬 설정, 채팅 기록, 셸 기록 또는 배포 파일에서 비밀을 붙여넣지 않습니다.
• .env.example을 링크하고, .env의 값을 재현하지 않습니다.
• 스크린샷, QR 코드, 이름, 연락처 링크가 의도적으로 공개된 것인지 확인합니다.
• 라이선스, 상표, 저작자 표시, 타사 자산 고지를 유지합니다.

게시가 민감한 자료를 노출할 경우 중단하고 구체적인 차단 사유를 알립니다.

3. 장식보다 스토리를 먼저 설계

다음 순서로 README를 작성합니다:

1. 인지(Recognize) — 이름, 로고, 간결한 약속.
2. 신뢰(Trust) — 소수의 진실된 배지와 실제 제품 시각 자료.
3. 이해(Understand) — 무엇을 하는지, 누구를 위한 것인지, 핵심 차별점.
4. 시도(Try) — 클론에서 작동 결과까지 가장 짧은 검증된 경로.
5. 도입(Adopt) — 설정, 배포, 아키텍처, 제한 사항, 지원.
6. 참여(Participate) — 기여, 보안, 라이선스, 스폰서, 커뮤니티.

README 레이아웃을 재구성하거나 배지를 선택하기 전에 references/readme-patterns.md를 읽으십시오.

4. 간결한 브랜드 헤더 빌드

프로젝트가 이를 지원할 자산을 가지고 있을 때 다음 순서를 사용합니다:

1. 설명적인 대체 텍스트와 절제된 표시 크기의 링크된 로고.
2. 프로젝트 이름과 한 줄 가치 제안.
3. 4~8개의 의미 있는 배지.
4. 라이브 데모, 문서, 이슈 트래커, 다운로드와 같은 기본 링크.
5. 긴 README를 위한 선택적 페이지 내 탐색.
6. 하나의 강력한 히어로 이미지, 제품 스크린샷 또는 짧은 데모.

안정적인 docs/, .github/ 또는 assets/ 경로 아래 리포지토리 소유 자산을 선호합니다. 새 로고를 생성하기 전에 기존 로고를 재사용합니다. 사용자가 새 시각 자료를 요청하고 이미지 생성 스킬이 가능하면 이를 사용한 후 리포지토리 표시에 최적화합니다.

가짜 빌드 배지, 자리 표시자 메트릭, 거대한 배지 벽, 장식용 카운터 또는 프로젝트가 제어하지 않는 핫링크된 자산을 사용하지 마십시오.

5. 유용한 섹션만 선택

간결한 프로젝트는 일반적으로 다음이 필요합니다:

• 무엇이며 왜 존재하는지.
• 구현된 동작에 기반한 기능 하이라이트.
• 복사 가능하고 테스트된 명령어가 포함된 빠른 시작.
• 안전한 자리 표시자를 사용한 설정.
• 시각적 증명이 실질적으로 도움이 될 때 스크린샷 또는 데모.
• 배포 가능한 프로젝트를 위한 배포 또는 프로덕션 노트.
• 해당 파일이 존재할 때 기여, 보안, 라이선스, 감사의 말 링크.

아키텍처, API 참조, 호환성, 로드맵, FAQ, 문제 해결은 프로젝트가 필요로 할 때만 추가합니다. 빈 보일러플레이트 섹션을 만들지 마십시오.

한국어 프로젝트의 경우 자연스러운 한국어로 먼저 작성하고 기술 식별자는 원래 형태로 유지합니다. 요청이 있거나 리포지토리가 이미 유지 중인 경우에만 영어 버전을 추가합니다.

6. 제품 스토리를 방해하지 않고 스폰서 추가

사용자가 스폰서 이미지 또는 QR 코드를 제공하고 승인한 경우:

• 안정적인 리포지토리 소유 자산 경로에 복사합니다.
• README 하단 부근에 프로젝트 지원 또는 Sponsor와 같은 명확한 제목을 사용합니다.
• 대체 텍스트, 적절한 너비, 지원 자금이 무엇에 사용되는지 설명하는 한 문장을 추가합니다.
• 명시적으로 요청하지 않는 한 결제 QR 코드를 변경, 디코딩 또는 재생성하지 않습니다.

스폰서가 빠른 시작, 문서 또는 보안 정보보다 우선하지 않도록 합니다.

7. README를 실행 가능한 문서로 검증

실용적일 때 프로젝트의 관련 빌드, 테스트, 린트 또는 스모크 명령어를 실행합니다. 그런 다음 번들된 검사기를 실행합니다:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md

해당 요소가 필수일 때 엄격한 플래그를 추가합니다:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md \
  --require-logo --require-badges --require-hero --require-sponsor

또한 수동으로 확인합니다:

• 모든 설치 및 실행 명령어가 리포지토리와 일치하는지.
• 상대 이미지 및 문서 링크가 GitHub의 대소문자 구분 경로에서 올바르게 해석되는지.
• 외부 링크가 의도된 정식 도메인을 사용하는지.
• 제목 앵커 및 목차 링크가 작동하는지.
• 이미지에 설명적인 대체 텍스트와 적절한 크기가 있는지.
• README가 데스크톱과 좁은 화면 모두에서 잘 렌더링되는지.
• 비밀, 자리 표시자, 로컬 절대 경로 또는 확인되지 않은 주장이 남아 있지 않은지.

8. 신중하게 게시

게시가 범위 내에 있을 때:

• git diff를 검토하고 관련 없는 변경 사항을 커밋에서 제외합니다.
• 포커스된 메시지로 커밋하고 리포지토리의 일반적인 워크플로우를 통해 푸시합니다.
• 브랜치 보호 또는 협업 관행이 필요한 경우 풀 리퀘스트를 선호합니다.
• 사용자가 리포지토리 설정 변경을 요청하고 값이 확인된 경우에만 GitHub 설명, 홈페이지, 토픽, 소셜 미리보기를 업데이트합니다.
• 게시 후 GitHub에서 렌더링된 README를 다시 열고 이미지, 배지, 링크, 모바일 레이아웃을 확인합니다.

완료 기준

• 첫 화면에서 이름, 목적, 신뢰 신호, 기본 다음 작업이 전달됩니다.
• 모든 주요 주장과 명령어가 리포지토리에 대해 검증되었습니다.
• 로고, 히어로, 배지, 스폰서 콘텐츠가 장식적이 아닌 의도적입니다.
• 링크와 로컬 자산이 올바르게 해석됩니다.
• 비밀 또는 개인 환경 세부 정보가 노출되지 않습니다.
• 검증이 통과되었으며 요청된 게시 단계가 완료되었습니다.