wp-phpstan

wp-phpstan 개요

wp-phpstan은 WordPress 코드베이스에서 PHPStan을 “그냥 돌리는” 수준이 아니라, 실제로 잘 동작하게 만들 때 쓰는 스킬입니다. 플러그인, 테마, 사이트 개발자 중에서 더 깔끔한 정적 분석, 더 적은 오탐, 그리고 이미 문제가 쌓인 레거시 코드까지 다룰 수 있는 실용적인 경로가 필요한 경우에 적합합니다.

핵심 작업은 설정과 복구입니다. phpstan.neon을 연결하고, baseline을 관리하고, WordPress 스텁을 로드하고, PHPStan이 런타임 동작을 추론하지 못하는 부분에는 WordPress를 이해하는 타입 주석을 추가하는 일이 여기에 포함됩니다.

wp-phpstan이 특히 잘 맞는 경우

wp-phpstan 스킬은 다음이 필요할 때 사용하세요.

• WordPress 저장소에서 PHPStan을 새로 설정하거나 업데이트해야 할 때
• WordPress core 심볼이 없어 생기는 오류를 줄여야 할 때
• 새 회귀를 가리지 않으면서 phpstan-baseline.neon을 관리해야 할 때
• hooks, REST 요청, query 결과처럼 동적인 WordPress 패턴을 고쳐야 할 때
• WooCommerce나 ACF 같은 선택적 서드파티 플러그인 클래스를 다뤄야 할 때

이 스킬이 다른 이유

일반적인 PHPStan 프롬프트는 WordPress 특유의 제약을 자주 놓칩니다. 예를 들면 런타임에 로드되는 클래스, hook 콜백, 플러그인 의존성, 실제 사이트와 맞지 않는 분석 환경 같은 부분입니다. wp-phpstan은 이런 예외 상황부터 다룬다는 점에서 유용하며, 특히 스텁 로딩과 정밀한 ignore 설정에 초점을 맞춥니다.

사용하면 안 되는 경우

단순히 PHPStan 명령 하나를 빠르게 설명받고 싶다면, 이 스킬은 과할 수 있습니다. 설정 선택, baseline 정책, 타입 힌트가 결과에 영향을 줄 만큼 분석 품질이 중요할 때 가장 가치가 큽니다.

wp-phpstan 스킬 사용 방법

스킬 설치 및 확인

wp-phpstan install의 경우, WordPress agent skills repo에서 스킬을 추가하세요.

npx skills add WordPress/agent-skills --skill wp-phpstan

설치한 뒤에는 먼저 SKILL.md를 읽고, 그다음 지원 문서와 inspection script를 확인하세요. 이 repo는 채택에 가장 큰 영향을 주는 질문들, 즉 PHPStan이 무엇을 보고 무엇을 무시하는지, 그리고 무엇을 억지로 숨기지 말고 타입을 보강해야 하는지에 답할 수 있도록 구성되어 있습니다.

스킬에 맞는 입력을 주기

wp-phpstan은 수정 요청을 하기 전에 프로젝트 맥락을 먼저 주면 가장 잘 작동합니다. 다음 정보부터 시작하세요.

• wp-project-triage 출력
• Composer dev dependency를 변경해도 되는지 여부
• baseline 업데이트가 허용되는지 여부
• 바꾸고 싶은 구체적인 PHPStan 오류 또는 config 파일

약한 프롬프트: “내 WordPress 플러그인의 PHPStan을 고쳐줘.”

더 강한 프롬프트: “wp-phpstan을 사용해서 내 플러그인의 현재 PHPStan 설정을 점검하고, szepeviktor/phpstan-wordpress가 로드되어 있는지 확인한 뒤, 광범위한 ignore 없이 알려지지 않은 WordPress 함수를 해결하는 가장 작은 config 변경안을 제안해줘. baseline 변경은 기존 레거시 오류에만 허용해.”

권장 워크플로와 파일

실무에서 wp-phpstan usage를 할 때는 repo 자체의 판단 순서를 따르세요.

1. scripts/phpstan_inspect.mjs로 설정을 점검한다
2. 주요 config와 baseline 파일을 확인한다
3. references/configuration.md를 검토한다
4. references/third-party-classes.md를 읽는다
5. 문제의 성격이 설정이 아니라 타입 추론이라면 references/wordpress-annotations.md를 사용한다

가장 빠르게 좋은 결과를 얻고 싶다면, 먼저 아래 파일들을 미리 살펴보세요.

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

실전용 프롬프트 형태

좋은 프롬프트는 무엇이 고정되어 있고, 무엇을 바꿔도 되는지, 그리고 어떤 결과를 원하는지를 분명히 알려줍니다. 예를 들면:

• “WordPress 플러그인의 phpstan.neon을 검토해서 stubs를 추가해야 하는지, ignoreErrors를 더 엄격하게 해야 하는지, 아니면 baseline을 업데이트해야 하는지 알려줘.”
• “이 REST controller annotation을 다시 써서 PHPStan이 request shape를 이해하게 해줘.”
• “내 분석 환경에는 WooCommerce가 없는데, 이 누락된 클래스들을 처리할 수 있는 좁은 범위의 stub/ignore 전략을 제안해줘.”

이 정도 수준의 구체성은 wp-phpstan이 config 변경, annotation 보강, dependency 변경 사이에서 더 정확하게 선택하도록 도와줍니다.

wp-phpstan 스킬 FAQ

wp-phpstan은 WordPress 플러그인 전용인가요?

아닙니다. wp-phpstan 스킬은 테마나 커스텀 코드가 있는 WordPress 사이트에도 잘 맞습니다. PHPStan이 WordPress의 런타임 동작을 이해하는 데 도움이 필요한 곳이라면 어디서든 유용합니다.

Composer와 PHPStan이 이미 설치되어 있어야 하나요?

네. 이 스킬은 Composer 기반 PHPStan 워크플로를 전제로 합니다. 저장소가 Composer를 사용하지 않거나 PHPStan이 도구 체인에 없다면, 적합한 선택이 아닙니다.

직접 프롬프트를 쓰는 것보다 나은가요?

대개는 그렇습니다. 특히 반복 가능한 설정 판단이 중요하다면 더 그렇습니다. 맞춤 프롬프트는 단일 오류 하나를 해결할 수는 있지만, wp-phpstan은 baseline, stubs, WordPress 특화 타입 지정까지 포함한 더 나은 워크플로를 제공합니다.

광범위한 ignore는 언제 피해야 하나요?

클래스나 함수가 실제로는 존재하지만, 누락된 stub, autoload 문제, 또는 분석 환경 불일치 때문에 안 보이는 경우에는 광범위한 ignore를 피하세요. 의존성 경로가 실제로 존재하고 깔끔하게 고칠 수 없는지 확인한 뒤에만, 범위를 좁힌 ignore를 사용하세요.

wp-phpstan 스킬 개선 방법

실제 PHPStan 실패 원인을 먼저 알려주기

wp-phpstan에서 가장 좋은 결과는 고치기 전에 실패 유형을 먼저 짚어줄 때 나옵니다.

• 알 수 없는 WordPress core 함수 → stubs 또는 config
• 레거시 노이즈 → baseline 워크플로
• 동적 request 데이터 → @phpstan-param 또는 재사용 가능한 type alias
• 선택적 플러그인 API → 좁은 범위의 stub 또는 최소한의 ignore

오류 목록만 그대로 붙여 넣으면, 스킬이 원인보다 증상만 최적화할 수 있습니다.

분석 경계를 공유하기

스킬이 무엇을 바꿔도 되는지 알려주세요. 다음을 구체적으로 적을수록 결과가 좋아집니다.

• composer.json을 수정해도 되는가?
• dev dependency를 추가해도 되는가?
• phpstan.neon을 바꿔도 되는가?
• baseline을 다시 생성해도 되는가?

이 권한 정보에 따라 wp-phpstan이 코드 수정, 설정 수정, dependency 수정 중 무엇을 우선할지 결정합니다.

추상적인 목표보다 구체적인 입력을 주기

입력이 구체적일수록 출력도 좋아집니다. 예를 들어 다음을 포함하세요.

• 현재 PHPStan level
• 분석하는 디렉터리
• CI에 WordPress core가 포함되는지 여부
• missing-symbol 오류를 일으키는 정확한 플러그인이나 클래스

이 정보는 wp-phpstan 스킬이 Backend Development 작업에 맞는 설치 및 사용 경로를 추천하는 데 도움이 되며, 일반적인 PHPStan 체크리스트로 흘러가는 일을 막아줍니다.

config에서 annotation으로 점진적으로 확장하기

좋은 wp-phpstan guide는 보통 다음 순서를 따릅니다.

1. stubs와 discovery를 확인한다
2. exclude와 ignore 범위를 줄인다
3. WordPress 특유의 동적 타입을 annotation으로 보강한다
4. 허용된 레거시 debt에 대해서만 baseline을 업데이트한다

이 순서는 WordPress의 동적 모델 때문에 추론이 막히는 부분의 오탐을 줄이면서도, 새로운 문제는 놓치지 않을 만큼 분석을 엄격하게 유지해 줍니다.