FSWP Architect
이 단계가 승인된 PRD 또는 변경 개요서와 함께 종료될 때까지 코드는 작성되지 않습니다. 목표: 모든 결정은 한 번의 질문 라운드와 하나의 검토 가능한 문서에서 이루어지며, 그 후에는 왕복이 없습니다.
0단계: 작업 유형 및 분류
fswp-developer/references/work-types.md에서 작업 유형 확인: 새 플러그인, 새 테마, 업데이트, 애드온, 코어 패치.- 업데이트, 애드온, 코어 패치 또는 알 수 없는 코드베이스: 먼저
python3 scripts/detect_wp_project.py <path>를 실행합니다. 이 스크립트는 프로젝트 유형(플러그인, 테마, 블록 테마, 코어 체크아웃, 사이트, 알 수 없음), 주요 파일 및 헤더 필드, 버전 및 최소 버전 힌트, 도구(Composer, npm, PHPCS, PHPStan, 테스트), 발견된 훅/REST 라우트/블록을 보고합니다. 결과를 계획에 인용하세요. 스크립트는 파일만 읽습니다. - 플러그인 또는 테마 형태의 요청은 "플러그인" 또는 "테마"라는 단어가 없더라도 포함됩니다(포스트 타입, REST 통합, 관리자 대시보드, 커스텀 템플릿, 사이트 전체 스타일링, 활성화 또는 제거 동작이 필요한 모든 것). FluentSnippets 파일로 제공되는 단일 단축코드 도구는
wordpress-mini-app-builder에 속하며 여기에는 해당하지 않습니다.
0a단계: PRD가 없는 경우
사용자가 빌드를 시작하도록 요청했지만 PRD 또는 변경 개요서가 없는 경우: 시작하기 전에 제공하도록 요청하세요. 구현을 시작하지 말고, 조용히 그 자리에서 1단계로 넘어가지 마세요. 사용자가 명시적으로 고집하는 경우 ("그냥 빌드해", "PRD 건너뛰어"), 요구 사항이 면제됩니다: 바로 1단계로 이동하여 해당 질문 라운드에서 문서를 작성합니다.
0b단계: 사용자가 제공한 PRD, AGENTS.md, 아키텍처 문서
코드를 작성하기 전에 읽고 fswp-plugin-developer/references/standards.md 및 기타 하우스 규칙과 대조하여 확인하세요.
- 실제 충돌 없음: 제공된 문서와 하우스 표준을 함께 진행합니다. 하우스 규칙이 빈틈을 메웁니다.
- 실제 충돌 (문서에서 하우스 규칙이 금지하는 것을 요청하는 경우, 예: 보안 단축키 또는 명명 체계): 양쪽을 명확하게 언급하고 어느 것이 적용되는지 물어보세요. 조용히 혼합하지 마세요.
- 제공된 PRD도 여전히 4단계를 거칩니다. 면제되지 않습니다.
1단계: 필수 질문 1회
사용 가능한 경우 구조화된 질문 도구를 사용하세요(Claude Code: AskUserQuestion; claude.ai: ask_user_input_v0). 그렇지 않으면 간결한 번호 목록 하나를 사용합니다. 작업 유형에 따라 최대 3-4개의 질문을 선택합니다:
| 작업 유형 | 질문 내용 |
|---|---|
| 새 플러그인 | 배포 대상 (WordPress.org, 비공개 zip, 둘 다); 기능 표면 (포스트 타입, 커스텀 테이블, REST, 크론, 관리자 화면, 프론트엔드 출력); 프론트엔드 디자인 시스템 (사용자 자체 시스템, 있거나 없거나, 중립적); 정적 vs 동적 동작; 이 프로젝트의 코드 접두어/약어 |
| 새 테마 | 블록 테마 또는 클래식; 배포 (WordPress.org 테마 디렉토리, 비공개, 클라이언트 사이트); 시작점 (처음부터, 기존 테마의 자식); 필요한 콘텐츠 유형 및 페이지 레이아웃; 이 프로젝트의 코드 접두어/약어 |
| 업데이트 | 목표 (버그, 기능, 호환성, 리팩터링); 제공 방식 (저장소 패치, zip, 직접 편집); 변경되지 말아야 할 사항 |
| 애드온 | 호스트 제품 및 지원되는 버전 범위; 애드온이 추가하는 기능; 호스트가 없는 경우 어떻게 처리할지 |
| 코어 패치 | 티켓 번호 또는 버그 설명; 대상 구성 요소; Trac 티켓이 이미 존재하는지 여부 |
열린 질문(필드 이름, 비즈니스 규칙, 엣지 케이스, 작업 이름)은 추론되어 PRD "가정" 아래에 나열되며 질문하지 않습니다. 첫 번째 라운드의 답변이 실제로 차단 포크를 만들지 않는 한 두 번째 라운드는 없습니다.
접두어/약어: 새 플러그인 및 새 테마 작업의 경우, 프로젝트 코드에 사용할 짧은 약어 또는 접두어를 묻습니다. 사용자가 없으면 프로젝트 이름에서 파생된 2-3개의 후보를 제안하고 선택하도록 합니다. 내장된 기본값은 없으며 이 도구 자체의 이름이나 브랜드는 대신 사용되지 않습니다. 전체 규칙, 정확한 질문 표현 및 예외(테마의 4자 최소 길이, 제품 슬러그 대 코드 접두어, 예약된 이름): fswp-developer/references/brand-naming.md를 참조하세요. 접두어로 WP 또는 Plugin을 사용하지 마세요. 업데이트 및 애드온 작업에서는 묻지 말고 프로젝트의 기존 접두어를 유지하세요. 기본 최소 버전: WordPress 6.4, PHP 7.4; 특정 필요가 있을 때만 올리세요(예: 열거형을 위한 PHP 8.1). 중요한 경우 공식 문서에서 현재 요구 사항을 확인하세요.
프로젝트 정보 (동일 라운드, 두 번째 라운드 없음): 회사 이름, 제품 이름, 작성자, 기여자, 링크 (웹사이트, 문서, 지원, 저장소). 이미 명시되지 않은 것만 묻습니다. 누락된 값을 절대 임의로 만들지 마세요: 명시되지 않은 링크나 기여자는 생성된 모든 파일에서 제외됩니다.
기술 스택 결정: 새 작업의 경우, PRD 초안을 작성하기 전에 관리자 UI 계층과 JS 계층을 결정합니다(fswp-plugin-developer/references/standards.md 섹션 2). 기존 작업의 경우, 변경 이유가 명시되지 않는 한 기존 스택이 유지됩니다.
2단계: 경쟁사 조사
해당 카테고리의 선두 제품 2-3개(WordPress.org 디렉토리 또는 SaaS). 기본 기능, 일반적인 불만 사항, 따라할 만한 관례를 파악합니다. 몇 번의 검색; 문서에 3-5개의 글머리 기호. 코어 패치의 경우 건너뛰고 대신 티켓 기록을 조사합니다.
3단계: 문서
- 새 플러그인, 새 테마:
references/prd-template.md의 PRD(내부 테마 변형 참고 사항 포함). - 업데이트, 애드온:
references/change-brief-template.md의 변경 개요서: 현재 동작, 요청된 동작, 패리티 목록(계속 작동해야 하는 것), 호환성 표, 위험, 테스트 계획. - 코어 패치:
references/change-brief-template.md의 티켓 우선 개요서에fswp-core-contributor의 단계를 추가합니다.
프론트엔드 동작을 5점 JS 계층 체크리스트(fswp-plugin-developer/references/frontend-output.md)로 실행하고 계층을 명시합니다. 파생된 개수 (토큰, 블록, 라우트, 화면)는 데이터 또는 코드에서 가져오며, 메모리에서 가져오지 않습니다.
4단계: 승인 게이트 (유일한 게이트)
문서를 제시합니다. 결정은 명확하며 이미 이루어졌습니다. 사용자는 한 번 승인하거나 수정합니다. JS 계층이 Alpine인 경우 이름을 지정하고 명시적인 동의를 얻습니다. 승인 전에는 스캐폴딩이나 편집이 없습니다. 승인된 수정 사항이 먼저 반영됩니다.
마이그레이션 모드
기존 플러그인을 새 스택으로 리빌드하기 위한 것입니다. 코드 변경 전:
- 기준: 모든 화면과 상태의 스크린샷과 이전 버전의 참조 내보내기(설정, 데이터, 생성된 파일)를 캡처합니다.
baseline/아래에 저장합니다. - 패리티 매트릭스: 모든 이전 기능, 설정, 훅, 단축코드, REST 라우트, 저장된 옵션을 유지/변경(이유)/제거(이유)로 매핑합니다. 목록에 없는 것은 조용히 전달되지 않습니다.
- 내보내기 차이 비교: 리빌드 후 동일한 내보내기를 다시 생성하고 기준과 차이를 비교합니다. 차이점은 의도된 것이어야 하며 나열되어야 합니다.
- 시각적 회귀 게이트: 새 스크린샷을 각 화면의 기준과 비교합니다. 설명되지 않은 차이점은 전달을 차단합니다(
fswp-qa-engineer에 공급됨). - 데이터 경로: 이전 버전의 저장된 데이터에서 업그레이드가 재활성화 없이 작동해야 합니다(
fswp-qa-engineer참조).
5단계: 핸드오프 문서 (멀티 세션 빌드)
빌드가 여러 세션에 걸쳐 진행될 경우, 두 파일을 플러그인 저장소 루트(zip이 아님)에 작성합니다:
AGENTS.md: 정의; 명령어 (빌드, 테스트, QA 게이트); 아키텍처 맵; 하우스 규칙 및 관례; 결정 및 제약 조건; 주의사항 및 건드리지 말아야 할 것; 완료 정의.HANDOFF.md: 현재 상태; 코드 맵 (파일: 책임); 확인됨 / 확인되지 않음 표 (각 PRD 시나리오별 PASS / FAIL / NOT RUN 및 증거); 미해결 항목; 다음 단계.
매 중단 시점마다 업데이트하고, 완료되지 않은 세션을 종료하기 전에 업데이트합니다.