오픈소스 준비 (Open-source prep)
공개 예정인 저장소에 대한 출시 전 사전 점검입니다. 스크립트가 기계적 검사를 수행하고, 사용자는 프로젝트를 읽고 스크립트가 판단할 수 없는 부분을 평가한 후 보고서를 작성한 다음, 사용자가 선택한 항목만 채웁니다.
순서가 중요한 이유는 한 번의 실수를 되돌릴 수 없기 때문입니다. 저장소가 공개되면 그 히스토리의 모든 내용이 노출됩니다. 유출된 자격 증명과 개인 데이터가 가장 먼저 처리되어야 하고, 템플릿 같은 기본 요소는 마지막에 처리됩니다.
1. 스캔
저장소 루트에서 번들 스캐너를 실행합니다 (Node 20 이상, 의존성 없음, 읽기 전용):
node <skill-dir>/scripts/scan.mjs <repo-dir>
JSON을 출력합니다: summary는 수준별 실패 건수를 집계하고, 각 항목에는 id, level (block, warn, info), status (pass, fail, skip) 및 evidence가 포함됩니다. 히스토리가 매우 큰 경우 --no-history를 추가하고, 사용자가 해당 부분을 건너뛰기로 동의한 경우에만 사용하며, 건너뛰었다고 명시합니다. gitleaks가 설치되어 있으면 gitleaks git <repo-dir> --redact --no-banner도 함께 실행하고 결과를 병합합니다. gitleaks는 더 많은 토큰 형식을 알고 있습니다.
스캐너의 비밀 정보 탐지 규칙은 패턴 기반이므로 오탐(테스트 픽스처, 문서 예제)이 있을 수 있으며 모든 것을 잡아냈다고 가정해서는 안 됩니다. 보고하기 전에 모든 적중 항목을 직접 확인하십시오. oss-prep: allow 주석을 사용하여 특정 줄을 의도적으로 허용으로 표시할 수 있습니다.
2. 읽고 판단하기
references/checklist.md를 참조하여 각 검사 항목의 의미, 실제 문제와 노이즈를 구별하는 방법, 그리고 사용자만이 수행할 수 있는 검사 항목을 확인하십시오. 요약하면 스크립트가 찾은 내용 외에도:
- 히스토리와 파일이 드러내는 정보. 각 비밀 정보 적중 항목과 히스토리의 민감한 파일(
git show <commit>:<path>)을 직접 확인하십시오. 실제 이름, 이메일, 전화번호, 주소, 고객 또는 재무 데이터, 내부 호스트 이름, 문서나 픽스처의 개인 데이터가 포함된 스크린샷을 찾으십시오. - 라이선스 일관성. LICENSE 텍스트,
package.json, SKILL.md 프론트매터, README 및 파일별 헤더가 일치해야 합니다. 번들된 타사 코드, 폰트 또는 이미지와 해당 라이선스가 재배포를 허용하는지 확인하십시오. - 낯선 사람을 위한 README. 검색을 통해 방문한 사람이 무엇인지 알 수 있고, 스크린샷이나 데모 링크를 보고, 설치 및 실행 방법을 찾을 수 있으며, 개인적인 맥락 없이 라이선스를 확인할 수 있어야 합니다.
- 작성자에게만 유효했던 사항. 하드코딩된 로컬 경로, 프로젝트에 필요하지만 문서화되지 않은
.env값, 작성자의 머신을 가정하는 스크립트 등.
3. 보고
사용자의 언어로 다음과 같은 형식의 보고서를 작성하십시오:
# 오픈소스 준비 상태: <repo>
**평가:** <준비 완료 / 차단 항목 수정 후 준비 / 준비되지 않음>, 한 문장으로 이유 설명.
## 차단 (공개 전 수정 필요)
- ❌ <제목>: <발견된 내용, file:line 또는 commit 명시> → <수정 방법>
## 권장 수정
- ⚠️ ...
## 있으면 좋은 항목
- 💡 ...
## 이미 갖춰진 항목
- ✅ <각 항목을 한 줄로, 그룹화>
## GitHub에서 직접 설정 필요
<사용자가 직접 변경해야 하는 설정, 정확한 gh 명령어 또는 설정 경로>
가장 심각한 항목을 먼저 배치하십시오. 구체적으로 작성하십시오: "src/config.ts:12에 OpenAI 키가 있으며, 커밋 a1b2c3d에도 있습니다"처럼 "비밀 정보 발견"이라고만 쓰지 마십시오. 확인하지 않은 항목(예: gh 미설치, 히스토리 건너뜀, 바이너리 파일)을 명시하십시오.
그런 다음 사용자에게 어떤 항목을 채울지 물어보십시오. 기본값으로 명백한 세트("누락된 모든 파일")를 제안하고, 각 선택지를 나열하여 사용자가 선택할 수 있도록 하십시오.
4. 사용자가 선택한 항목 채우기
assets/templates/의 템플릿을 출발점으로 사용하여 이 프로젝트에 맞게 조정하십시오. 먼저 references/fixing.md를 읽으십시오. 요약:
- 파일을 작성하고, 게시하지 마십시오. 작업 트리에서만 파일을 생성하거나 편집하십시오. 사용자가 명시적으로 요청하지 않는 한 커밋, 푸시, 저장소 공개 여부 변경, 설정 변경, 릴리스 생성을 하지 마십시오.
- 프로젝트에 맞추십시오. 실제 명령어, Node 버전, 패키지 관리자, 라이선스 및 연락처 경로를 사용하고, README 언어로 작성하십시오(README가 이중 언어인 경우 둘 다). 해당되지 않는 섹션은 플레이스홀더를 남기지 말고 생략하십시오.
- 사용자를 대신하여 라이선스를 선택하지 마십시오. 라이선스가 없는 경우, 일반적인 선택지(MIT, Apache-2.0, GPL-3.0, AGPL-3.0, 이중 라이선스)를 각각 한 문장으로 설명하고 질문하십시오. 공식 라이선스 텍스트를 정확히 복사하고, 기억에 의존하여 의역하거나 다시 입력하지 마십시오.
- 히스토리의 비밀은 파일을 삭제한다고 해결되지 않습니다. 자격 증명을 먼저 취소하고 교체해야 하며, 이는 사용자가 제공업체 콘솔에서 수행해야 할 작업입니다. 히스토리 다시 쓰기(
git filter-repo) 또는 새 저장소 게시는 사용자의 결정 사항입니다. 두 옵션을 모두 설명하고 명확한 동의 없이는 아무것도 수행하지 마십시오. - GitHub 설정은 사용자의 몫입니다. 참고 문서에서 정확한
gh명령어 또는 설정 경로를 제공하고, 사용자가 요청할 때만 실행하십시오.
스캐너를 다시 실행하여 변경된 항목과 사용자에게 여전히 남아 있는 작업을 보여주며 마무리하십시오.