wizard은(는) 무엇을 하나요?
Wizard는 사람이 수동으로 수행하기 번거롭고 매번 AI에게 다시 설명하기도 귀찮은 절차를 단계별로 안내하는 bash 스크립트입니다. 각 URL을 열고, 정확히 무엇을 클릭하고 복사해야 하는지 알려주며, 값을 캡처하여 적절한 위치(.env, GitHub Secrets)에 기록하고, 각 단계에서 확인을 받고, 남은 단계 수를 표시합니다. 타사 서비스를 구성하거나, 일회성 마이그레이션을 실행하거나, 프로젝트를 한 상태에서 다른 상태로 전환하는 데 사용할 수 있습니다.
편리한 UX는 이미 template.sh에서 해결했습니다. 단계별 진행, 확인 게이트, 크로스 플랫폼 URL 열기(WSL 포함), 숨겨진 비밀 입력, 멱등성 있는 .env 업서트, gh secret/gh variable 쓰기, 마지막 요약이 포함됩니다. 당신의 작업은 절차를 정의하고 각 단계를 작성하는 것뿐입니다. STAGES 마커 위의 라이브러리는 모든 마법사에서 동일합니다. 이러한 일관성이 핵심이므로 직접 수정하지 마세요.
마법사는 기본적으로 일시적입니다. 한 번 실행하기 위해 생성되고, 임시 디렉토리나 scripts/ 경로에 저장되며, 작업이 끝나면 삭제됩니다. 사용자가 저장소에 유지할 반복 가능한 설정 경로를 원하는 경우에만 커밋하세요.
프로세스
1. 절차 범위 지정
사람이 수행해야 하는 모든 수동 단계와 그 과정에서 캡처되는 모든 값을 파악하세요. 먼저 저장소를 읽고, 바로 묻지 마세요.
- 설정의 경우:
.env,.env.example,.env.*,README,docker-compose*, 프레임워크 설정,.github/workflows/*(모든secrets.*/vars.*참조는 마법사가 생성해야 하는 값입니다). - 마이그레이션이나 전환의 경우: 현재 상태, 목표 상태, 그 사이의 되돌릴 수 없는 작업.
그런 다음 사용자에게 정렬된 단계 목록과 각 단계가 생성하는 값을 보여주고 확인하세요. 사용자는 단계를 추가, 삭제, 재정렬할 수 있습니다.
완료 조건: 모든 단계가 순서대로 명명되었고, 각 캡처된 값에 대해 (a) 사람이 값을 어디서 얻는지, (b) 값이 어디에 기록되는지(.env, GitHub Secrets, 둘 다, 또는 아무 곳에도 기록되지 않음; 일부 단계는 순수 작업입니다), (c) 비밀(숨겨진 입력)인지 공개인지 알고 있어야 합니다.
2. 각 단계의 경로 매핑
각 단계에 대해 사람이 따라야 할 정확한 경로를 작성하세요. 어떤 URL을 열고, 그곳에서 무엇을 할지, 값이 어디에 표시되는지, 어떤 변수를 채우는지 등을 예를 들어 "대시보드 → 개발자 → API 키 → 테스트 키 공개 → 복사"와 같이 설명하세요. 현재 UI나 정확한 명령을 실제로 모르는 경우, 그렇게 말하고 사용자에게 묻거나 문서를 확인하세요. 존재하지 않을 수 있는 단계를 절대 만들어내지 마세요.
완료 조건: 모든 단계가 낯선 사람도 따라할 수 있는 구체적인 지침으로 이어져야 합니다.
3. 마법사 작성
template.sh를 대상 경로에 복사하세요. 예제 단계를 제거하고, 각 단계를 종속성 순서대로 하나의 stage로 교체하세요. 라이브러리 헬퍼를 사용하세요: stage, say/step, open_url, ask/ask_secret, write_env, set_secret/set_var, pause/confirm. TOTAL_STAGES를 작성한 단계 수로 설정하세요.
템플릿이 설정한 기준을 유지하세요. 값을 요청하기 전에 URL을 열고, 비밀에는 ask_secret을 사용하고, 지속되는 모든 값에는 write_env를 사용하고, CI에서 실제로 필요한 값만 set_secret으로 설정하며, 되돌릴 수 없는 작업 전에는 confirm을 사용하세요. 각 stage는 화면을 지워 현재 단계만 보이게 합니다. 한 단계를 하나의 집중된 작업으로 유지하여 사람이 스크롤해야 하는 내용이 없도록 하세요. 마커 위의 라이브러리는 건드리지 마세요.
4. 검증 및 전달
bash -n <script>;shellcheck가 가능하면 실행하세요.chmod +x <script>.- 직접 처음부터 끝까지 실행하지 마세요. 브라우저를 열고 사람 입력을 기다립니다. 대신 정적으로 추적하세요. 1단계의 모든 값이 캡처되어 1단계에서 지정된 위치에 기록되었는지, 모든
set_secret이름이 CI의secrets.*참조와 정확히 일치하는지 확인하세요. - 사용자에게 실행 방법을 알려주세요. 반복 가능한 설정 경로라면 커밋하고 README에 링크를 추가하여 다음 사람이 AI에게 묻는 대신 스크립트를 실행하도록 하세요.