docs(dev): 코드·JSP 변경 후 앱 재빌드·재시작 함정 가이드 추가

좋아요 수정이 "안 됨" = 돌던 앱이 구 버전(미재배포)이었던 사례.
local-dev-setup.md 에 구동방식별 재빌드·재시작 표 + 미재배포 증상 식별 추가.
핸드오프 시 재배포 단계 명시 교훈 memory 기록.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K3FeMrbtxfTScjrwUukyHD

.serena/memories/handoff-committed-code-needs-rebuild-restart-step.md

@@ -0,0 +1,22 @@
+# 코드 변경 핸드오프 시 "앱 재빌드·재시작" 단계를 명시할 것
+
+커밋·테스트(L1) 통과 ≠ 사용자가 보는 **실행 중 앱에 반영**. bibimbap dev 앱은
+호스트 JVM(IDE 번들 JDK, 8080) 또는 compose `bibimbap-app` 로 구동되며, 소스/JSP 변경은
+프로세스를 재빌드·재시작하기 전까지 반영되지 않는다.
+
+## 적용
+- 코드 변경을 마무리할 때 `needs_user_verification`/배포후 체크리스트에 **"앱 재빌드·재시작"을 첫 단계로 명시**.
+  스모크 절차는 그다음. "커밋했으니 됨" 으로 핸드오프하지 말 것.
+- 신규 서버 기능(엔드포인트·매퍼) 추가 시 특히. 구 JSP 가 서빙되면 클라이언트 전용 동작(예:
+  로그아웃 상태에서 좋아요가 눌리고 카운트가 로컬에서만 변함)이 그대로 보여 "안 고쳐졌다" 로 오인된다 —
+  이 증상이 보이면 코드 결함이 아니라 미재배포 신호.
+- 재배포 명령은 `mem:local-dev-setup-gotchas` + `docs/development/local-dev-setup.md` 의
+  "코드·JSP 변경 후 재빌드·재시작" 표 참조.
+
+## 왜
+세션 20260629-171042: 직전 좋아요 영속화 수정(L1 PASS, 커밋 fa6a301)을 사용자가 더미 게임에서
+테스트했으나 "안 됨". 원인은 코드가 아니라 **돌던 앱이 구 버전**. orchestrator 가 재배포 단계를
+needs_user_verification 에 안 적었고(컨테이너 검증만 함), 사용자가 "애초에 니가 해줬어야 / 가이드에
+기재하라" 고 지적. docs-first 로 가이드에 반영 완료.
+
+근거 세션: .atp/work-session/20260629-171042.

docs/development/local-dev-setup.md

@@ -2,6 +2,24 @@
 
 로컬에서 앱을 구동할 때 필요한 환경/경로 설정을 둔다.
 
+## ⚠️ 코드·JSP 변경 후 반드시 앱 재빌드·재시작 (가장 흔한 함정)
+
+소스(Java 컨트롤러/매퍼/서비스)나 **JSP(`/WEB-INF/views/*.jsp`)** 를 고쳐도, **돌고 있는 앱은 자동으로 반영되지 않는다.** 변경을 커밋·테스트 통과까지 해도 *실행 중인 인스턴스가 구 버전이면* 화면 동작은 그대로다.
+
+> 증상 예: 좋아요/댓글 등 신규 서버 기능을 추가했는데 "고친 게 반영이 안 된다" — 십중팔구 **앱 미재시작**. 특히 클라이언트 동작(예: 로그인 안 했는데도 버튼이 눌리고 카운트가 로컬에서만 변함)이 보이면 구 JSP 가 서빙 중이라는 신호다.
+
+구동 방식별 재배포:
+
+| 구동 방식 | 재빌드·재시작 |
+| --- | --- |
+| **IDE / 호스트 JVM** (`./mvnw spring-boot:run`, 또는 IntelliJ Run) | 앱 **Stop → 프로젝트 rebuild → 다시 Run**. 컴파일된 컨트롤러 변경은 hot-reload 안 됨(devtools 미사용). JSP 변경도 재기동으로 확실히 반영. |
+| **docker compose** (`bibimbap-app` 컨테이너) | `docker compose up -d --build app` — 이미지를 새 소스로 다시 빌드 후 교체 기동. (8080 을 IDE 앱이 점유 중이면 먼저 그쪽을 멈출 것 — 포트 충돌.) |
+| **수동 WAR** | `./mvnw -P dev clean package spring-boot:repackage -DskipTests` 로 실행형 WAR 재패키지(프로필·repackage goal 주의 — 본 문서 함정 참조) 후 재기동. |
+
+확인: 재시작 후 의도한 신규 엔드포인트가 응답하는지 1회 스모크(예: 좋아요는 로그인 상태에서 클릭 → 새로고침·목록에서도 카운트 유지). 미로그인 클릭은 신 코드에선 401(로그인 유도)이 정상 — 더 이상 클라이언트에서 토글되지 않는다.
+
+> 코드 변경을 핸드오프할 때는 이 재빌드·재시작 단계를 `needs_user_verification`/배포 후 체크리스트에 **명시**한다. 커밋·테스트 통과 ≠ 실행 인스턴스 반영.
+
 ## 업로드 저장 루트 (static 트리 밖)
 
 업로드물(프로필 이미지·게임 WebGL asset)은 **웹서버 정적 서빙 트리(`src/main/resources/static/`) 밖**에 저장한다. 직접 서빙을 차단하고 컨트롤러 권한 게이트를 강제하기 위함이다(보안 하드닝, commit `9041bb7`).