AlexMaghen/wp-dev

wp-dev: 라이브 워드프레스 사이트를 로컬에서 작업하기

wpsync를 ${CLAUDE_PLUGIN_ROOT}/bin/wpsync(이하 wpsync)로 실행합니다. 개발자는 일반적으로 이 시스템을 구축한 사람이 아니므로 각 단계를 평이한 말로 설명하고, 개발자의 조치가 필요할 때 알려주십시오.

먼저 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/guiding.md를 읽으십시오. 이 파일에는 진행 상황 표시 방법(단계별 체크리스트), 질문 방법(모든 결정과 대기 시 질문 대화창), 그리고 앱이 이러한 기능을 제공하지 않는 경우 수행할 작업이 설명되어 있습니다. 아래의 Ask 라인은 사용할 대화창을 지정합니다.

원칙: 변경하기 전에 모든 것을 확인하고, 모든 문제를 해결 방법과 함께 즉시 보고합니다. 모든 단계는 다시 실행해도 안전하므로, 중단 후 개발자가 "내 wp-dev 프로젝트를 계속"이라고 말하면 중단된 지점부터 다시 시작합니다.

시작 전: wpsync를 실행할 수 있나요?

wpsync는 Bun에서 실행되므로, 아직 Bun이 없는 Mac에서는 모든 wpsync 명령어(status, init, doctor 포함)가 "wpsync needs Bun"(종료 코드 127) 오류와 함께 실패합니다. 먼저 이를 확인하십시오. wpsync 명령어를 실행하기 전에:

1. ${CLAUDE_PLUGIN_ROOT}/bin/wpsync --version을 실행합니다. 버전이 출력되면 "현재 위치는?"으로 진행합니다.
2. "wpsync needs Bun" 메시지가 표시되면 Homebrew를 찾습니다: command -v brew || ls /opt/homebrew/bin/brew /usr/local/bin/brew
   • Homebrew 발견됨 → brew install oven-sh/bun/bun(brew의 전체 경로 사용, PATH에 없는 경우)을 실행한 후 wpsync --version을 다시 실행합니다.
   • Homebrew 없음 → 개발자의 조치( Mac 비밀번호 입력)가 필요합니다. wpsync 및 기타 도구가 Homebrew로 설치된다고 설명하고, https://brew.sh의 설치 명령어가 준비된 터미널 탭을 열고(guiding.md 참조), "완료, 확인" 대화창과 함께 기다립니다. 그런 다음 Homebrew를 사용 가능하게 만들고(2단계의 "Homebrew 설치 직후" 참조) 위와 같이 Bun을 설치합니다.

wpsync가 실행되면 이에 대해 아무 말 하지 않고 진행합니다. Bun을 설치해야 했던 경우에만, 이것이 첫 번째 사전 조건이었으며 wpsync doctor --local이 2단계에서 나머지를 확인할 것이라고 한 줄로 개발자에게 알립니다.

현재 위치는?

현재 폴더에서 wpsync status --json을 실행하고 phase에 따라 진행합니다:

phase	수행할 작업
no-project	1단계부터 단계 1(시작 게이트)
start-gate (이전 세션에서 폴더 생성됨)	2단계부터 단계 1
connect, pull	2단계부터 단계 1 (완료된 부분은 건너뜀)
work	단계 2: 변경 사항은 wp-work 스킬, 새로 고침은 wp-pull, 라이브 배포는 wp-publish
publish-pending	마지막 배포가 완료 또는 롤백을 기다리는 중: wp-publish 참조

단계에 관계없이: status에 wordfence 필드가 있으면, 이 사이트의 Wordfence는 wpsync가 작업하는 동안 꺼야 하며 작업 후 다시 켜야 합니다. ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md를 따르십시오.

단계 1에서는 guiding.md의 설정 체크리스트를 완료된 단계에 체크 표시하여 시작(또는 재개 시 다시 표시)하고 "설정" 챕터를 시작합니다.

단계 1: 로컬 복사본 설정

1. 시작 게이트: 올바른 폴더, 그 다음 주소

세션의 폴더는 시작 시 고정되므로, 개발자는 로컬 복사본이 들어갈 폴더에서 세션을 시작합니다. 그런 다음 모든 작업이 이 하나의 세션 내에서 이루어집니다.

이 세션이 사용 가능한 폴더에 있습니까? 현재 폴더를 확인합니다(ls -A):

• 비어 있음(또는 .DS_Store나 .claude만 있음): 사이트의 새 폴더입니다. 아래로 진행합니다.

• 다른 것(바탕화면, 홈 폴더, 다른 프로젝트): 여기서 설정하지 마십시오. 다음 메시지를 보내고 중단합니다:

  사이트를 설정하려면 로컬 복사본을 만들 새 빈 폴더(예: ~/wp-sites/example.com)에서 새 Claude Code 세션을 시작하십시오. 새 세션을 시작하고 해당 폴더를 선택(또는 생성)한 후, 각 단계를 승인하지 않으려면 권한 모드를 권한 우회로 설정하십시오. (라이브 사이트에 배포할 때는 항상 대화창에 도메인을 입력할 때까지 기다립니다.) 그런 다음 거기서 **"새 wp-dev 프로젝트"**라고 말하십시오.

새 폴더에서 라이브 사이트 주소 한 가지만 짧은 한 줄로 묻습니다:

라이브 사이트의 주소는 무엇입니까? 예: https://example.com.

폴더 이름에 도메인이 포함된 경우(예: example.com-local), 대신 제안합니다: "라이브 사이트의 주소는 무엇입니까? 폴더 이름으로 보아 https://example.com일 것 같습니다."

그런 다음 여기에 프로젝트를 생성합니다: wpsync init <site-url> --dir .. 이 명령은 폴더의 CLAUDE.md, .claude/settings.json(ddev, git, brew 및 읽기 전용 wpsync 명령어를 사전 승인하며, 배포는 여전히 질문함) 및 보류 중으로 표시된 .wpsync.json을 작성합니다. 외부와 접촉하지 않습니다. 2단계로 바로 진행합니다. 이 설정은 이 폴더의 다음 세션부터 적용됩니다. 권한 우회 모드가 아니라면 이 세션에서 그동안 조금 더 자주 물어볼 수 있습니다. 권한 모드를 감지할 수 없으며, 그럴 필요도 없습니다.

2. 이 Mac 확인

wpsync doctor --local은 모든 것을 한 번에 나열합니다. guiding.md의 결과 테이블로 표시합니다. 누락된 항목을 다음 순서로 설치합니다:

• 직접 가능: brew install ddev/ddev/ddev, brew install oven-sh/bun/bun 및 Docker. Docker 앱이 설치되어 있지 않으면 **"이 Mac에 어떤 Docker 앱을 설치할까요?"**라고 묻습니다: OrbStack(권장: Mac에서 더 가볍고 빠르며 개인 사용 무료) 또는 Docker Desktop(표준 버전, 개인 사용 및 소규모 회사 무료). 그런 다음 brew install --cask orbstack 또는 brew install --cask docker를 실행합니다. Docker가 설치되었지만 "실행 중이 아님": 직접 시작하고(open -a OrbStack 또는 open -a Docker) docker info가 성공할 때까지 최대 1분 기다립니다. 처음 실행(약관, 비밀번호)만 개발자가 필요합니다. 1분 후에도 docker info가 실패하면 처음 실행 대화창이 개발자를 기다리고 있는 것입니다.
• 개발자 필요(비밀번호 또는 클릭, 절대 대신 수행하지 않음): Xcode 명령줄 도구(xcode-select --install), Homebrew(https://brew.sh), OrbStack 또는 Docker Desktop의 첫 실행, mkcert -install. 명령어가 준비된 터미널 탭을 열고(guiding.md 참조) "완료, 확인" 대화창과 함께 기다립니다. 여러 항목이 누락된 경우 항목별로 한 번씩 기다리지 말고 한 메시지에 모두 나열하고 한 번만 기다립니다.

mkcert는 필수입니다(doctor가 설정될 때까지 FIX로 보고). 로컬 복사본의 주소는 https://…ddev.site입니다. mkcert -install이 없으면 Chrome에서 해당 주소를 거부하고, 일반 http를 통해서는 스타일이나 이미지 없이 페이지가 로드됩니다(WordPress가 https로 링크함). 이는 7단계에서 복사본이 손상된 것처럼 보입니다. 따라서 첫 번째 풀 전에 여기서 수행하십시오: Mac 비밀번호를 물어볼 것이라고 말하고, 터미널 탭에서 mkcert -install을 실행하고 기다립니다. DDEV가 시작된 후에만 설치된 경우(이전 설정을 재개하는 경우), DDEV는 여전히 신뢰할 수 없는 인증서를 사용 중입니다: 사이트 폴더에서 ddev poweroff && ddev start를 실행한 후 페이지를 다시 로드하도록 요청합니다.

wpsync doctor --local을 FIX 항목이 없을 때까지 다시 실행합니다. 참고 사항은 기다릴 수 있지만, 그 의미를 설명하십시오.

Homebrew 설치 직후: Apple Silicon Mac에서 Homebrew는 /opt/homebrew에 설치되며, 설치 프로그램의 "Next steps" 라인이 실행될 때까지 PATH에 없습니다. doctor는 이를 "설치됨(/opt/homebrew/bin/brew), 아직 PATH에 없음"으로 보고하며 ~/.zprofile에 추가할 라인을 알려줍니다. 재설치하도록 보내지 마십시오. 셸은 ~/.zprofile을 자동으로 읽지 않으므로, 이 세션에서는 명령어 앞에 eval "$(/opt/homebrew/bin/brew shellenv)" &&를 붙입니다.

3. 사이트 확인

wpsync doctor <site-url> (읽기 전용). 연결 전에 사이트가 WordPress인지, REST API가 있는지, 애플리케이션 비밀번호가 켜져 있는지 확인합니다. (호스트가 Authorization 헤더를 전달하는지는 실제 키로만 테스트할 수 있으므로 wpsync가 연결되면 확인합니다.) 결과 테이블을 표시합니다. 진행하기 전에 각 FIX를 수정하거나 설명하십시오. 대부분은 호스팅 또는 보안 플러그인 설정으로, 개발자가 다른 사람에게 물어봐야 합니다: guiding.md의 "확인이 다른 사람을 필요로 할 때" 대화창을 사용하십시오.

Wordfence: 애플리케이션 비밀번호가 "꺼져 있음, 대부분 Wordfence에 의한 것"이라고 보고하면 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md("Before")를 따르십시오: 개발자가 wp-admin에서 한 설정을 끄고, doctor가 확인할 때까지 "완료, 확인" 대화창과 함께 기다립니다. 8단계에서 다시 켜도록 상기시킵니다.

4. 연결

wp-connect 스킬. 그 후 wpsync doctor <site-url>을 다시 실행합니다: 이제 Authorization 헤더, 멀티사이트, 파일 권한, 버전, 이 Mac과 서버의 디스크 공간도 확인합니다.

(wpsync new <site-url>은 2~7단계를 한 번에 실행하고 개발자가 필요한 첫 번째 항목에서 중단됩니다. 재개할 때 유용합니다. 여기서처럼 단계별로 진행하면 과정에서 더 많이 설명합니다.)

5. 가져오기

wp-pull 스킬(첫 번째 가져오기: wpsync pull <site-url> --dir .). 호스트 파일 변경이 필요 없는 https://<project>.ddev.site에 DDEV 프로젝트를 생성합니다. 대규모 사이트는 시간이 걸립니다: 장기 작업으로 실행합니다(guiding.md).

6. 복사본을 안전하게 실행 가능하도록 만들기

복사본에는 라이브 데이터베이스가 있습니다: 실제 고객 이메일, 라이브 결제 또는 API 키, 예약된 작업이 있을 수 있습니다. DDEV는 모든 발신 메일을 캡처하고(ddev mailpit로 확인) wpsync는 WP_ENVIRONMENT_TYPE=local을 설정합니다. CLAUDE.md에서 활성 플러그인을 확인합니다. 결제, 배송, CRM, 뉴스레터 또는 웹훅 플러그인이 있으면 나열하고 **"<도메인>의 로컬 복사본에 있는 이 플러그인이 실제 서비스와 통신할 수 있습니다. 어떻게 할까요?"**라고 묻습니다: 테스트 모드 안내(권장: 로컬 wp-admin에서 각 플러그인의 테스트 또는 샌드박스 설정으로 안내), 또는 그대로 둡니다(로컬 복사본이 해당 서비스에 도달할 수 있음을 수락).

해당 유형의 활성 플러그인이 없으면 묻지 말고 한 줄로 말하고(이메일만 보내는 플러그인은 DDEV가 캡처하므로 이름을 언급) 진행합니다.

7. 확인

wpsync verify는 페이지, wp-admin, 고유주소, 남아있는 라이브 주소, 이미지, 플러그인 및 테마가 라이브와 일치하는지 확인합니다. 결과 테이블을 표시합니다.

실패한 페이지 확인을 조사하기 전에 직접 한 번 페이지를 요청합니다: curl -s -o /dev/null -w '%{http_code}' <localUrl>/. 200이 응답되면 DDEV가 아직 시작 중일 때 확인이 실행된 것일 수 있습니다(ddev start 후 잠시 502 응답): 로그를 파헤치기 전에 wpsync verify를 한 번 더 실행합니다.

그런 다음 직접 확인합니다: Chrome(Claude in Chrome)에서 라이브 사이트와 로컬 복사본을 나란히 열고 홈페이지와 내부 페이지 몇 개를 비교합니다. 앱의 내장 브라우저 창에서 복사본을 판단하지 마십시오. *.ddev.site 페이지의 스타일, 스크립트 및 이미지를 차단합니다(ERR_BLOCKED_BY_CLIENT). 따라서 완벽한 복사본도 그곳에서는 깨져 보입니다. Chrome을 사용할 수 없으면 curl로 페이지를 확인하고 개발자에게 확인을 요청합니다. 설명할 수 없는 차이가 있으면 설명하고 묻습니다: 지금 수정(권장), 또는 괜찮습니다. 계속 진행.

로컬 로그인: 복사본에는 라이브 사용자가 있으므로 개발자는 라이브 비밀번호로 로컬 wp-admin에 로그인합니다.

8. 인계

지금부터 사이트의 CLAUDE.md를 읽어 규칙이 적용되도록 합니다.

첫째, 이 사이트가 Wordfence를 사용하는 경우(wpsync status --json에 "wordfence": "switched-off" 표시): 설정에 더 이상 라이브 사이트가 필요하지 않으므로 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md("wpsync 완료 시")를 따라 개발자가 Wordfence 보호를 다시 켜도록 하고, 기다린 후 wpsync status로 확인합니다. 인계 메시지 전에 이 작업을 수행하여 개발자의 마지막 단계가 다른 잡일이 아니라 작업 시작이 되도록 합니다.

그런 다음 Chrome에서 로컬 사이트를 열고 체크리스트를 완료합니다. 설정을 정확히 다음 내용으로, 굵게, 단독 줄로, 메시지의 마지막 항목으로 끝냅니다(뒤에 아무 것도 없음; 로그인과 같은 다른 참고 사항은 그 앞에 둡니다):

사이트의 로컬 복사본이 https://{로컬 사이트 도메인}에서 준비되었습니다. 확인하시고 변경하고 싶은 사항을 알려주십시오.

https://{로컬 사이트 도메인}은 .wpsync.json의 localUrl로 대체합니다. 바로 앞에 한 줄로 로그인 안내를 추가합니다: 로컬 wp-admin은 라이브 사용자 이름과 비밀번호를 사용합니다.