AkiGarage/readme-release-sync

README 릴리스 동기화

이 스킬은 README 카피, 릴리스 노트, 체인지로그, 제품 스크린샷/GIF 또는 이중 언어 제품 문서를 다루는 태스크에서 사용하세요.

목표는 유지보수자 리뷰 부담을 줄이는 것입니다: 리뷰어가 오래된 이름, 스크린샷, 기능 설명 또는 영어/일본어 불일치를 발견하기 전에 문서가 실제 제품 상태와 일치해야 합니다.

핵심 규칙

기존 문서만 보고 제품 문서를 편집하지 마세요. 먼저 현재 진실 공급원(앱 코드, UI 문자열, 스크린샷/GIF, 릴리스 브랜치, 버전 파일, 패키지 메타데이터 또는 사용자가 제공한 최신 스크린샷/비디오)을 식별하세요.

워크플로우

1. 대상 상태 고정

   • 저장소 파일이나 명시적인 사용자 지침에서 제품/앱 이름, 브랜치, 버전, 바이너리 이름 및 플랫폼 범위를 확인합니다.
   • 설명되는 기능에 대한 관련 구현 또는 UI 문자열을 검사합니다.
   • 사용자가 제공한 최신 스크린샷/비디오는 코드나 브랜치 컨텍스트에서 명백히 모순되지 않는 한 권위 있는 시각적 증거로 취급합니다.

2. 문서 및 미디어를 함께 업데이트

   • UI가 변경된 경우 오래된 스크린샷/GIF를 교체합니다.
   • 모든 이미지 참조가 존재하고 의도된 파일을 가리키는지 확인합니다.
   • 스크린샷이 현재 제품 이름, 메뉴 레이블, 버전 또는 UI 상태와 시각적으로 모순되지 않는지 확인합니다.
   • 제거된 동작을 설명하는 오래된 미디어 참조는 제거합니다.
   • 비공개 저장소에서 제공되는 공개 릴리스의 경우, 정리된 스냅샷이 복사된 후 공개 저장소의 release/vX.Y.Z 브랜치에서 공개 README 파일을 업데이트합니다. 비공개 README를 최종 공개 진실 공급원으로 의존하지 마세요.
   • 공개 CHANGELOG, 릴리스 초안 노트, 설치 문서 및 공개 개발 로그를 동일한 릴리스 관련 문서 세트의 일부로 취급합니다. 이들은 README와 동일한 제품 이름, 버전, 자산 이름, 개인정보 보호 주장 및 사용자 대상 용어를 사용해야 합니다.

3. 이중 언어 문서를 동등하게 유지

   • 영어와 일본어 섹션을 항목별로 비교합니다.
   • 두 언어에서 동일한 제품 사실, 기능 순서, 주의사항 및 설정 요구사항을 유지합니다.
   • 중요한 동작을 한 언어로만 설명하지 마세요.

4. 읽기 쉬운 공개 README 카피 작성

   • 첫 읽기 섹션을 스캔하기 쉽게 만듭니다: 짧은 단락, 단락당 하나의 아이디어, 가독성을 높이는 빈 줄.
   • 제품이 무엇을 하는지와 사용자가 보고 할 수 있는 것으로 시작합니다. 구현 메커니즘은 설정, 안전 또는 문제 해결에 중요한 경우에만 나중에 배치합니다.
   • 압축된 기능 문장보다 명확한 동작 라인을 선호합니다. 좋은 형태는 한 문장 개요 다음에 2-4개의 간결한 기능 라인입니다.
   • UI 동작의 경우 드래그하여 이동, 가장자리나 모서리에서 크기 조정, 더블 클릭하여 재설정 등 보이는 결과를 설명합니다. 사용자에게 필요하지 않은 경우 히트 밴드, 커서 사각형, 크기 조정 내부 또는 정확한 기본 백분율과 같은 내부 프레임워크 세부 사항은 피합니다.
   • 상세 정보는 진정으로 유용한 곳에 유지하되, 공개 README가 유지보수자 전용 구현 설명을 포함하지 않도록 합니다.
   • 릴리스 노트 및 체인지로그 항목에도 동일한 가독성 규칙을 적용합니다: 사용자에게 보이는 수정, 설치 단계 또는 문제 해결 경로에 영향을 미치지 않는 한 정확한 기본 백분율, 히트 밴드 표현, 커서 사각형 메커니즘 또는 빌드 시스템 세부 사항과 같은 내부 정밀성을 피합니다.

5. 일본어 독자 친화적으로 만들기

   • 자연스러운 경우 일반 일본어 UI 용어를 선호합니다: タブ, 詳細パネル, マウスオーバー, 最小表示, フローティングタブ.
   • 명령어, 경로, 패키지 이름, 앱 이름, URL 및 코드 식별자와 같은 기술적 리터럴은 영어로 유지합니다.
   • 중복된 기능 목록과 반복되는 단락을 제거하고, 일반 일본어 독자가 주요 기능 세트를 빠르게 스캔할 수 있도록 합니다.

6. 오래된 제품 노후화 스캔

   • 오래된 제품 이름, 오래된 앱 이름, 오래된 바이너리 이름 및 오래된 저장소 이름.
   • 과거 체인지로그 항목 외부의 오래된 버전 번호.
   • 쓸모없는 UI 레이블, 제거된 플랫폼 노트 및 이전 동작의 스크린샷.
   • 설치된 CLI 또는 패키지만 필요한데 종속성이 실행 중이어야 한다는 주장.

7. 종료 전 검증

   • 사용 가능한 경우 관련 문서 린트/검사 명령어를 실행합니다.
   • 오래된 이름/버전/레이블에 대해 범위가 제한된 rg 스캔을 실행합니다.
   • 최상위 README뿐만 아니라 README 파일, 체인지로그, 릴리스 노트 및 릴리스에 포함된 모든 공개 문서에서 오래된/비공개/너무 내부적인 표현 스캔을 실행합니다.
   • README 이미지 링크가 존재하는지 확인합니다.
   • 릴리스 PR의 경우 유지보수자에게 브랜치/PR에 대한 GitHub 렌더링 README URL을 제공하고 명시적인 시각적 승인을 기다립니다. 이는 사용자가 실제로 볼 GitHub 디스플레이와 일치해야 합니다. 로컬 미리보기, 원시 마크다운, 정적 스크린샷 또는 자동화된 검사는 보조 증거로만 사용됩니다.
   • 공개 저장소 git diff를 검사하여 README 주장, 버전 메타데이터, 릴리스 자산 이름 및 복사된 구현 변경 사항이 일치하는지 확인합니다.
   • 공개 릴리스의 경우 태그 또는 GitHub 릴리스 생성 전에 release/vX.Y.Z 브랜치 -> PR -> CI -> 병합 순서를 선호합니다. 유지보수자가 PR 게이트를 건너뛰도록 명시적으로 요청한 경우에만 직접 main 푸시를 사용합니다.
   • 코드가 변경된 경우 관련 테스트 또는 빌드를 실행합니다.
   • 편집된 파일뿐만 아니라 진실 공급원 검사 결과를 요약합니다.

출력 체크리스트

종료하기 전에 보고:

• 확인된 제품 이름/버전/브랜치;
• 확인된 미디어 참조;
• 확인된 일본어/영어 동등성;
• GitHub 렌더링 README 시각적 승인을 받았거나, 명시적으로 보류 중임;
• 오래된 표현 스캔 결과;
• 테스트/빌드/문서 검사가 실행되었거나 실행되지 않은 이유.