From edf3caafd02ba84db83bc53a4827931ace7b3055 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=A1=B0=EC=9E=AC=EC=A4=91?=
 <126754298+m-a-king@users.noreply.github.com>
Date: Sat, 5 Sep 2026 19:50:13 +0900
Subject: [PATCH 1/6] =?UTF-8?q?docs:=20=EC=9D=B4=EA=B4=80=EC=9D=B4=20?=
 =?UTF-8?q?=EB=81=9D=EB=82=9C=20=EB=92=A4=EC=97=90=EB=8F=84=20=EB=82=A8?=
 =?UTF-8?q?=EC=95=84=20=EC=9E=88=EB=8D=98=20=ED=8F=AC=ED=8C=85=20=EC=8B=9C?=
 =?UTF-8?q?=EB=8C=80=20=EB=AC=B8=EC=9E=A5=EC=9D=84=20CLAUDE.md=20=EC=97=90?=
 =?UTF-8?q?=EC=84=9C=20=EA=B1=B7=EC=96=B4=EB=82=B8=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 파싱 이관은 2026-07-08 에 끝났는데 "포팅 규율 (이관 기간 한정)" 절, "포팅 시 Kotlin 원본의 의도를 보존" 문장, "safeLogString 포팅본" 표기가 그대로 남아 있었다. 지금 코드는 포팅 대상이 아니라 이 repo 의 본체라 그 규율은 적용 대상이 없다
- 포팅 절에서 아직 살아 있는 규칙 하나(운영 상수는 @ConfigurationProperties 로 외부화)만 "설정값" 절로 남기고, 기본값 숫자는 코드가 정본이라 문서에 박지 않는다는 이 repo 의 SSOT 원칙에 맞춰 수치를 지웠다
- "TestConventionTest 는 3단계와 함께 이식한다"는 이미 support/TestConventionTest 가 존재해 사실이 아니었다. 현재 상태(./gradlew test 에 포함)로 고쳤다
- 옛 repo 이름 PIKI-Server 를 core 로 바꿨다
- 배경: Fable 5.1 하네스 점검. 모델은 문서를 그대로 따르므로 낡은 사실은 존재하지 않는 절차·이름으로 유도한다

Claude-Session: https://claude.ai/code/session_01Mg69sPkH9gHFqYZVSbf3ru
---
 CLAUDE.md | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6840d05..f7d5bfd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,7 +12,7 @@ core(코틀린)에서 분리된 **상품 추출 서비스**다. 상품 URL(또
 ## 언어: Java 25
 
 - 모던 idiom 을 기본으로: `record`(값 객체·DTO), `sealed`(닫힌 분기), pattern matching `switch`. 로컬 변수 `var` 는 우변에서 타입이 자명할 때만.
-- **이 repo 는 사람이 직접 읽고 이해하는 것을 우선한다.** 영리한 축약보다 평이하고 읽히는 코드. 포팅 시 Kotlin 원본의 의도를 보존하되 Java 다운 표현으로 옮긴다.
+- **이 repo 는 사람이 직접 읽고 이해하는 것을 우선한다.** 영리한 축약보다 평이하고 읽히는 코드.
 
 ### Lombok
 
@@ -33,7 +33,7 @@ core(코틀린)에서 분리된 **상품 추출 서비스**다. 상품 URL(또
 - **선언부**(클래스·인터페이스·record·enum·상수·필드·메서드·생성자) 주석은 Javadoc(`/** */`). 메서드 본문 안에서만 `//`.
 - **지운다**: 코드가 이미 말하는 "무엇", 시그니처 재진술 `@param`(`@param region S3 리전`), 클래스 Javadoc 과 같은 말의 반복, 흐름 나레이션(`// 1) fetch 한다`), 자명한 분기 설명, 테스트에서 `@DisplayName`·단언이 이미 말하는 라벨.
 - **남긴다**: 설계 근거(왜 이 대안을 버렸나), 코드로 안 보이는 외부 제약·함정, 계약·보안 판단의 이유, 도달 불가 분기의 불변식, 외부 명세 링크. 이 "왜" 주석이 이 repo 의 자산이다.
-- **SSOT 위반 주석 금지.** 정본이 딴 곳에 있는 수치·목록·동작 — 다른 repo(renderer·PIKI-Server)의 구현 상세, `docs/api-contract.md` 의 계약 서술·타임아웃 예산, **코드의 기본값·상수값**, 다른 클래스가 정본인 분류 — 을 복제하지 않는다(조용히 낡는다). 정본을 가리키는 참조 한 줄로 대신한다.
+- **SSOT 위반 주석 금지.** 정본이 딴 곳에 있는 수치·목록·동작 — 다른 repo(renderer·core)의 구현 상세, `docs/api-contract.md` 의 계약 서술·타임아웃 예산, **코드의 기본값·상수값**, 다른 클래스가 정본인 분류 — 을 복제하지 않는다(조용히 낡는다). 정본을 가리키는 참조 한 줄로 대신한다.
 - **Javadoc 문법 게이트: `./gradlew javadoc` 이 error 0 이어야 한다.** raw `<...>` 는 `{@code <script>}` 로 감싸고, 본문 줄머리에 `@` 로 시작하는 애노테이션 이름을 두지 않는다(`{@code @DefaultValue}`) — 둘 다 error 를 낸다. `>`·`&` 단독은 `&gt;`·`&amp;`, 목록은 `<ul><li>`, 문단은 `<p>`.
 
 ### Null 처리
@@ -60,15 +60,13 @@ core 의 Elvis 규칙에 대응하는 Java 규칙:
 ## 로깅
 
 - 클래스에 `@Slf4j` 를 붙여 쓴다(필드명 `log`). 명시적 `LoggerFactory.getLogger` 선언은 쓰지 않는다.
-- URL 은 반드시 마스킹(`safeLogString` 포팅본: host+path만, 쿼리스트링 제외). 토큰·원문 HTML·LLM 응답 원문을 로그에 남기지 않는다.
+- URL 은 마스킹해서 찍는다(`safeLogString`: host+path만, 쿼리스트링 제외). 토큰·원문 HTML·LLM 응답 원문을 로그에 남기지 않는다.
 - 레벨: info=정상 흐름·지표·호출자 계약 위반 / warn=외부(몰·Gemini·S3) 실패·에스컬레이션 실패·SSRF 차단 / error=서버 버그(스택 포함).
 - SLF4J `{}` placeholder 사용, 문자열 연결 금지.
 
-## 포팅 규율 (이관 기간 한정)
+## 설정값
 
-- **동작 등가(파리티)가 목표다.** Kotlin 원본의 분기·상수·메시지를 그대로 옮기고, 개선·리팩터링은 이관 완료 후 별도 작업으로 뺀다.
-- 포팅한 클래스의 Javadoc 에 원본 경로를 남긴다: `core: product/service/http/HttpPageFetcher.kt 포팅`.
-- 하드코딩이던 상수(fetch 3MB cap·UA·타임아웃·LLM 200K char cap)는 `@ConfigurationProperties` 로 외부화하되 **기본값은 원본과 동일**하게 둔다.
+- 운영 상수(fetch 크기 cap·UA·타임아웃·LLM 입력 cap)는 하드코딩하지 않고 `@ConfigurationProperties` 로 외부화한다(`FetchProperties`·`GeminiProperties`·`HeadlessExtractionProperties` 등). 기본값은 코드가 정본이라 문서에 숫자를 박지 않는다.
 
 ## 테스트
 
@@ -80,7 +78,7 @@ core 의 Elvis 규칙에 대응하는 Java 규칙:
 - **단언**: JUnit 5 `Assertions` 기본. 컬렉션·객체 그래프 비교만 AssertJ.
 - **DB 가 없다** — Testcontainers·Docker 불필요. `./gradlew test` 가 그냥 돈다. 저장소 격리·트랜잭션 롤백 관련 원칙은 이 repo 에 해당 사항이 없다.
 - **좌표**: 통합 베이스는 `support/IntegrationTestSupport`(`@SpringBootTest` 유일 선언), 외부 경계 stub(GeminiClient·PageFetcher·S3)은 `support/IntegrationStubs` 에 `@Primary` 로 등록한다.
-- **메타 테스트**: `TestConventionTest`(금지 import·컨텍스트 규칙 기계 강제)는 파싱 포팅(3단계)과 함께 이식한다. 그 전까지 원칙 준수는 사람 리뷰가 책임진다.
+- **메타 테스트**: `support/TestConventionTest`(금지 import·컨텍스트 규칙 기계 강제)가 `./gradlew test` 에 포함된다. 규칙을 바꿀 땐 산문을 먼저 고치고 메타 테스트를 따라 고친다.
 
 ## 의존성
 

From 71d446c42006800660e0364d20f430a4bf94635d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=A1=B0=EC=9E=AC=EC=A4=91?=
 <126754298+m-a-king@users.noreply.github.com>
Date: Sat, 5 Sep 2026 22:13:30 +0900
Subject: [PATCH 2/6] =?UTF-8?q?docs:=20=EC=84=A4=EC=A0=95=EA=B0=92=20?=
 =?UTF-8?q?=EC=A0=88=EC=9D=B4=20=ED=81=AC=EA=B8=B0=20=EC=83=81=ED=95=9C?=
 =?UTF-8?q?=EA=B9=8C=EC=A7=80=20=EC=84=A4=EC=A0=95=EC=9C=BC=EB=A1=9C=20?=
 =?UTF-8?q?=EC=98=AE=EA=B8=B0=EB=9D=BC=EA=B3=A0=20=EC=98=A4=EB=8F=84?=
 =?UTF-8?q?=ED=95=98=EB=8D=98=20=EA=B2=83=EC=9D=84=20=EC=BD=94=EB=93=9C=20?=
 =?UTF-8?q?=EC=84=A4=EA=B3=84=EB=8C=80=EB=A1=9C=20=EA=B3=A0=EC=B9=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 앞 커밋의 "설정값" 절은 이관 기간의 작업 지시("하드코딩 상수를 외부화")를 현행 규칙으로 승격시키면서, 그 작업 중에 뒤집힌 결론을 되살렸다. 수신 바이트·보존 문자·LLM 입력 상한은 튜닝 손잡이가 아니라 안전장치라 클래스 상수로 두기로 했고(FetchProperties Javadoc, PruningHtmlParser 주석: 설정이던 동안 아무도 지정하지 않아 키 이름만 드리프트할 자리가 생겼다), GeminiProperties 에는 LLM 입력 cap 필드가 없다
- 다음 세션이 그 줄을 읽고 MAX_FETCH_BYTES 를 FetchProperties 로 옮기면 코드가 명시적으로 거부한 변경을 규칙 준수라고 믿으며 하게 된다. 살아 있는 규칙(손잡이는 외부화)과 살아 있는 예외(안전 상한은 상수)를 함께 적었다
- 로깅의 URL 마스킹 줄은 "반드시" 를 뺀 자리에 이유(쿼리스트링에 토큰이 실릴 수 있다)를 넣어 강제성이 약해 보이지 않게 했다
- 발견 출처: 머지 전 reviewer 서브에이전트 전수검사

Claude-Session: https://claude.ai/code/session_01Mg69sPkH9gHFqYZVSbf3ru
---
 CLAUDE.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f7d5bfd..49a1a0e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -60,13 +60,15 @@ core 의 Elvis 규칙에 대응하는 Java 규칙:
 ## 로깅
 
 - 클래스에 `@Slf4j` 를 붙여 쓴다(필드명 `log`). 명시적 `LoggerFactory.getLogger` 선언은 쓰지 않는다.
-- URL 은 마스킹해서 찍는다(`safeLogString`: host+path만, 쿼리스트링 제외). 토큰·원문 HTML·LLM 응답 원문을 로그에 남기지 않는다.
+- URL 은 마스킹해서 찍는다(`safeLogString`: host+path만, 쿼리스트링 제외). 쿼리스트링에 토큰이 실릴 수 있어서다. 토큰·원문 HTML·LLM 응답 원문도 로그에 남기지 않는다.
 - 레벨: info=정상 흐름·지표·호출자 계약 위반 / warn=외부(몰·Gemini·S3) 실패·에스컬레이션 실패·SSRF 차단 / error=서버 버그(스택 포함).
 - SLF4J `{}` placeholder 사용, 문자열 연결 금지.
 
 ## 설정값
 
-- 운영 상수(fetch 크기 cap·UA·타임아웃·LLM 입력 cap)는 하드코딩하지 않고 `@ConfigurationProperties` 로 외부화한다(`FetchProperties`·`GeminiProperties`·`HeadlessExtractionProperties` 등). 기본값은 코드가 정본이라 문서에 숫자를 박지 않는다.
+- 운영 튜닝 손잡이(UA·타임아웃·재시도)는 하드코딩하지 않고 `@ConfigurationProperties` 로 외부화한다(`FetchProperties`·`GeminiProperties`·`HeadlessExtractionProperties` 등).
+- 크기 안전 상한은 손잡이가 아니라 안전장치라 클래스 상수로 둔다(`HttpPageFetcher.MAX_FETCH_BYTES`·`PruningHtmlParser.MAX_RETAINED_CHARS`·`GeminiHtmlExtractor.MAX_LLM_CHARS`). 설정으로 열어 둔 동안 아무도 지정하지 않았고 키 이름만 드리프트할 자리가 생겨 상수로 되돌린 이력이 각 상수의 Javadoc 에 있다.
+- 기본값은 코드가 정본이라 문서에 숫자를 박지 않는다.
 
 ## 테스트
 

From 3680e75ce1a12be35a9527c096adeba378664479 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=A1=B0=EC=9E=AC=EC=A4=91?=
 <126754298+m-a-king@users.noreply.github.com>
Date: Sat, 5 Sep 2026 22:14:54 +0900
Subject: [PATCH 3/6] =?UTF-8?q?docs:=20=EC=84=A4=EC=A0=95=EA=B0=92=20?=
 =?UTF-8?q?=EC=A0=88=EC=9D=98=20=EC=98=88=EC=8B=9C=EB=A5=BC=20FetchPropert?=
 =?UTF-8?q?ies=20=EC=8B=A4=EC=A0=9C=20=ED=95=84=EB=93=9C=EC=99=80=20?=
 =?UTF-8?q?=EC=A3=BC=EC=84=9D=20=EC=9C=84=EC=B9=98=EC=97=90=20=EB=A7=9E?=
 =?UTF-8?q?=EC=B6=98=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- FetchProperties 에는 재시도 필드가 없다(userAgent·connectTimeout·readTimeout·connectionRequestTimeout·maxRedirects). "재시도" 를 "리다이렉트 횟수" 로 바꿨다
- 크기 상한을 상수로 되돌린 이력은 GeminiHtmlExtractor 에는 없고 HttpPageFetcher·PruningHtmlParser 의 상수 주석에만 있다. "각 상수의 Javadoc" 을 그 두 곳으로 좁혔다

Claude-Session: https://claude.ai/code/session_01Mg69sPkH9gHFqYZVSbf3ru
---
 CLAUDE.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 49a1a0e..06679bc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -66,8 +66,8 @@ core 의 Elvis 규칙에 대응하는 Java 규칙:
 
 ## 설정값
 
-- 운영 튜닝 손잡이(UA·타임아웃·재시도)는 하드코딩하지 않고 `@ConfigurationProperties` 로 외부화한다(`FetchProperties`·`GeminiProperties`·`HeadlessExtractionProperties` 등).
-- 크기 안전 상한은 손잡이가 아니라 안전장치라 클래스 상수로 둔다(`HttpPageFetcher.MAX_FETCH_BYTES`·`PruningHtmlParser.MAX_RETAINED_CHARS`·`GeminiHtmlExtractor.MAX_LLM_CHARS`). 설정으로 열어 둔 동안 아무도 지정하지 않았고 키 이름만 드리프트할 자리가 생겨 상수로 되돌린 이력이 각 상수의 Javadoc 에 있다.
+- 운영 튜닝 손잡이(UA·타임아웃·리다이렉트 횟수)는 하드코딩하지 않고 `@ConfigurationProperties` 로 외부화한다(`FetchProperties`·`GeminiProperties`·`HeadlessExtractionProperties` 등).
+- 크기 안전 상한은 손잡이가 아니라 안전장치라 클래스 상수로 둔다(`HttpPageFetcher.MAX_FETCH_BYTES`·`PruningHtmlParser.MAX_RETAINED_CHARS`·`GeminiHtmlExtractor.MAX_LLM_CHARS`). 설정으로 열어 둔 동안 아무도 지정하지 않았고 키 이름만 드리프트할 자리가 생겨 상수로 되돌린 이력이 `HttpPageFetcher`·`PruningHtmlParser` 의 상수 주석에 있다.
 - 기본값은 코드가 정본이라 문서에 숫자를 박지 않는다.
 
 ## 테스트

From cbd10e04b471487a8a9b8d36f96a49fa27c20618 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=A1=B0=EC=9E=AC=EC=A4=91?=
 <126754298+m-a-king@users.noreply.github.com>
Date: Sat, 5 Sep 2026 22:20:56 +0900
Subject: [PATCH 4/6] =?UTF-8?q?docs:=20style-decisions=20=EA=B0=80=20CLAUD?=
 =?UTF-8?q?E.md=20=EC=9D=98=20=EC=82=AC=EB=9D=BC=EC=A7=84=20"=ED=8F=AC?=
 =?UTF-8?q?=ED=8C=85=20=ED=8C=8C=EB=A6=AC=ED=8B=B0"=20=EB=A5=BC=20?=
 =?UTF-8?q?=EA=B0=80=EB=A6=AC=ED=82=A4=EB=8D=98=20=EC=B0=B8=EC=A1=B0?=
 =?UTF-8?q?=EB=A5=BC=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docs/style-decisions.md 머리말이 "포팅 파리티 — CLAUDE.md 참조" 라고 적는데, 앞 커밋이 CLAUDE.md 에서 포팅 규율을 걷어내 참조가 끊겼다. 이 문서는 2026-07-20 시점의 결정 기록이라 본문은 그대로 두고, 머리말 한 곳만 "작성 당시엔 포팅 파리티 기간이기도 했다" 로 시점을 밝혔다
- 같은 문서의 22·41행(포팅 파리티 기간의 결정 기록)은 당시 결정의 기록이라 손대지 않았다
- 발견 출처: 머지 전 reviewer 서브에이전트 전수검사(범위 밖 발견 중 이 PR 이 만든 끊긴 참조만 반영)

Claude-Session: https://claude.ai/code/session_01Mg69sPkH9gHFqYZVSbf3ru
---
 docs/style-decisions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/style-decisions.md b/docs/style-decisions.md
index af10819..e83b8bf 100644
--- a/docs/style-decisions.md
+++ b/docs/style-decisions.md
@@ -1,7 +1,7 @@
 # 스타일 결정 기록 — 우아한테크코스 스타일 검토 (2026-07-20)
 
 참고 기준: [woowacourse-teams/2025-estime `be/dev`](https://github.com/woowacourse-teams/2025-estime/tree/be/dev) 백엔드.
-목표: 우테코식 객체지향 스타일을 참고하되, 이 서비스의 정체(무상태·단일 소비자·포팅 파리티 — CLAUDE.md 참조)에 맞는 형태로 취사선택한다. 아래 결정이 이 repo 스타일의 기준선이며, CLAUDE.md 와 충돌하면 CLAUDE.md 가 우선한다.
+목표: 우테코식 객체지향 스타일을 참고하되, 이 서비스의 정체(무상태·단일 소비자 — CLAUDE.md 참조. 작성 당시엔 포팅 파리티 기간이기도 했다)에 맞는 형태로 취사선택한다. 아래 결정이 이 repo 스타일의 기준선이며, CLAUDE.md 와 충돌하면 CLAUDE.md 가 우선한다.
 
 ## 1. estime 대비 채택 / 기각 결정
 

From 9e98a193e9cce7abf265e2e7cd28ab969731bce5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=A1=B0=EC=9E=AC=EC=A4=91?=
 <126754298+m-a-king@users.noreply.github.com>
Date: Sun, 6 Sep 2026 17:54:31 +0900
Subject: [PATCH 5/6] =?UTF-8?q?docs:=20=EC=A3=BC=EC=84=9D=C2=B7=EC=84=A4?=
 =?UTF-8?q?=EC=A0=95=20=EC=A3=BC=EC=84=9D=EC=9D=98=20=EC=98=9B=20=EC=9D=B4?=
 =?UTF-8?q?=EB=A6=84=20PIKI-Server=20=EC=99=80=20=ED=8F=90=EA=B8=B0?=
 =?UTF-8?q?=EB=90=9C=20outbox=20=EC=96=B4=ED=9C=98=EB=A5=BC=20=ED=98=84?=
 =?UTF-8?q?=ED=96=89=EC=9C=BC=EB=A1=9C=20=EB=B0=94=EA=BE=BC=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 옛 repo 이름 PIKI-Server 8곳(application.yml 6·test application.yml 1·GeminiProperties Javadoc 1)을 core 로, 텔레메트리 라벨 서술(application=PIKI)은 현행 piki-core 로 고쳤다. 전부 주석이라 동작 변화는 없다
- core 의 재시도·회수 원장은 outbox 가 아니라 item_snapshots 파싱 작업 큐다(core PR #844 로 표기 폐기). 이 repo 주석 6곳(application.yml·ImageStorage·ExtractionController·FallbackProductLinkExtractor·GeminiProperties·PageFetchException)과 CLAUDE.md 가 아직 outbox 라고 불러 신구 어휘가 섞여 있었다. 테스트 쪽은 이미 "파싱 작업 큐" 라 그쪽에 맞췄다
- Javadoc 문법 게이트(./gradlew javadoc error 0)는 verifier 서브에이전트가 확인했다

Claude-Session: https://claude.ai/code/session_01Mg69sPkH9gHFqYZVSbf3ru
---
 CLAUDE.md                                          |  2 +-
 .../piki/extractor/api/ExtractionController.java   |  2 +-
 .../extractor/common/storage/ImageStorage.java     |  2 +-
 .../extraction/FallbackProductLinkExtractor.java   |  2 +-
 .../extraction/gemini/GeminiProperties.java        |  2 +-
 .../extraction/http/PageFetchException.java        |  2 +-
 src/main/resources/application.yml                 | 14 +++++++-------
 src/test/resources/application.yml                 |  2 +-
 8 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 06679bc..f89ed1f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@
 
 core(코틀린)에서 분리된 **상품 추출 서비스**다. 상품 URL(또는 S3 이미지)을 받아 fetch → 구조화 파싱(JSON-LD/OG) → LLM(Gemini) fallback → 정규화를 거쳐 추출 결과를 돌려준다.
 
-- **무상태.** DB 없음, 호출 간 상태 없음. 상태를 넣고 싶어지면 설계 경고 신호다. 재시도·내구성·상태 전이는 전부 호출자(core outbox)의 몫이다.
+- **무상태.** DB 없음, 호출 간 상태 없음. 상태를 넣고 싶어지면 설계 경고 신호다. 재시도·내구성·상태 전이는 전부 호출자(core 파싱 작업 큐)의 몫이다.
 - **소비자는 core 워커 하나뿐.** 공개 API 가 아니다. 보안그룹 내부망 전용, 인증 없음.
 - **계약의 single source 는 `docs/api-contract.md`.** 응답은 3갈래뿐이다: 2xx(성공) / 422+code(확정 실패) / 그 외 전부(일시 실패). 진화는 additive-only, 배포는 Extractor 먼저.
 - 차단 우회 **방법론**(스텔스·프록시·IP 전략)은 private repo(renderer)에만 둔다. 이 repo(public)에는 "이 호스트는 헤드리스로 라우팅" 수준까지만 담는다.
diff --git a/src/main/java/com/depromeet/piki/extractor/api/ExtractionController.java b/src/main/java/com/depromeet/piki/extractor/api/ExtractionController.java
index dbfcdfc..99b625d 100644
--- a/src/main/java/com/depromeet/piki/extractor/api/ExtractionController.java
+++ b/src/main/java/com/depromeet/piki/extractor/api/ExtractionController.java
@@ -13,7 +13,7 @@
 import org.springframework.web.bind.annotation.RestController;
 
 /**
- * 내부 추출 API (docs/api-contract.md). 소비자는 core outbox 워커 하나뿐이고 보안그룹으로
+ * 내부 추출 API (docs/api-contract.md). 소비자는 core 의 파싱 작업 큐 워커 하나뿐이고 보안그룹으로
  * 격리되므로 인증·응답 래퍼 없이 계약 그대로 노출한다.
  */
 @Slf4j
diff --git a/src/main/java/com/depromeet/piki/extractor/common/storage/ImageStorage.java b/src/main/java/com/depromeet/piki/extractor/common/storage/ImageStorage.java
index 9d5cb82..602b5c8 100644
--- a/src/main/java/com/depromeet/piki/extractor/common/storage/ImageStorage.java
+++ b/src/main/java/com/depromeet/piki/extractor/common/storage/ImageStorage.java
@@ -1,7 +1,7 @@
 package com.depromeet.piki.extractor.common.storage;
 
 /**
- * 이미지(OCR) 경로가 쓰는 두 연산만 둔다 — download 는 outbox 재실행 시점에 등록 워커가 적재한 raw 원본을 다시 읽는 용도다.
+ * 이미지(OCR) 경로가 쓰는 두 연산만 둔다 — download 는 파싱 작업 큐가 재실행할 때 등록 워커가 적재한 raw 원본을 다시 읽는 용도다.
  * <p>presign·exists·delete·deleteByPrefix 는 등록 수명주기(발급·확인·회수·탈퇴 파기)라 core 소관이다.
  */
 public interface ImageStorage {
diff --git a/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java b/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java
index 4a035da..f4d3c0e 100644
--- a/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java
+++ b/src/main/java/com/depromeet/piki/extractor/extraction/FallbackProductLinkExtractor.java
@@ -24,7 +24,7 @@
  * 일이라 허락을 전제하지 않는다. authorized 가 여는 것은 렌더 서비스의 우회 수단(지문 보정·프록시)뿐이고,
  * 이 클래스는 그 값을 판단 없이 전략에 넘기기만 한다(무상태 — 원장은 호출자에 있다).
  *
- * <p>에스컬레이션 축(plain 확정 → headless)은 호출자 outbox 의 재시도 축(일시 오류 → 같은 plain 재시도)과
+ * <p>에스컬레이션 축(plain 확정 → headless)은 호출자 파싱 작업 큐의 재시도 축(일시 오류 → 같은 plain 재시도)과
  * 직교한다. 차단·불완전 결과는 재시도 축에서 이미 확정 실패(422)라 그 슬롯(attemptCount)에 얹을 수 없다. 그래서
  * 여기서 별도로 판정한다.
  */
diff --git a/src/main/java/com/depromeet/piki/extractor/extraction/gemini/GeminiProperties.java b/src/main/java/com/depromeet/piki/extractor/extraction/gemini/GeminiProperties.java
index 259e3a9..e5a8022 100644
--- a/src/main/java/com/depromeet/piki/extractor/extraction/gemini/GeminiProperties.java
+++ b/src/main/java/com/depromeet/piki/extractor/extraction/gemini/GeminiProperties.java
@@ -60,7 +60,7 @@ public String toString() {
      * <p>{@code @DefaultValue} 는 부분 바인딩(예: max-attempts 만 지정)에서도 나머지 필드의 기본값을 유지시킨다
      * — 아래 no-arg 생성자와 값이 어긋나면 바인딩 경로와 직접 생성 경로의 기본값이 갈린다.
      *
-     * @param maxAttempts 총 시도 횟수(초기 호출 + 재시도). URL 파싱 재시도를 호출자(PIKI-Server) outbox recover 로
+     * @param maxAttempts 총 시도 횟수(초기 호출 + 재시도). URL 파싱 재시도를 호출자(core)의 파싱 작업 큐 회수로
      *     일원화했으므로 기본값은 Gemini 내부 재시도를 끄는 쪽이다.
      */
     public record Retry(
diff --git a/src/main/java/com/depromeet/piki/extractor/extraction/http/PageFetchException.java b/src/main/java/com/depromeet/piki/extractor/extraction/http/PageFetchException.java
index ba2de44..12727d7 100644
--- a/src/main/java/com/depromeet/piki/extractor/extraction/http/PageFetchException.java
+++ b/src/main/java/com/depromeet/piki/extractor/extraction/http/PageFetchException.java
@@ -15,7 +15,7 @@ public final class PageFetchException extends ExtractionException {
 
     /**
      * 정적 fetch 실패를 실제 브라우저(헤드리스)로 재시도(escalate)할지 표시한다. FallbackProductLinkExtractor 가
-     * 이 값으로 정한다(에스컬레이션 축은 호출자의 outbox 재시도 축과 직교). 정책은 "무조건 폴백": 예외는 둘뿐이고
+     * 이 값으로 정한다(에스컬레이션 축은 호출자의 파싱 작업 큐 재시도 축과 직교). 정책은 "무조건 폴백": 예외는 둘뿐이고
      * 나머지 fetch 실패는 전부 escalatable 이다 — 봇 방어가 어떤 status 로도 위장해 status·body 로 차단/genuine 을
      * 못 가른다.
      *
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 3e9f657..0701087 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -1,5 +1,5 @@
 server:
-  # 8080=PIKI-Server, 8000=piki-hb(헤드리스) 와 겹치지 않는 포트. dev 는 본 서버 박스에 컨테이너로 동거한다.
+  # 8080=core, 8000=piki-hb(헤드리스) 와 겹치지 않는 포트. dev 는 본 서버 박스에 컨테이너로 동거한다.
   port: 8090
 
 spring:
@@ -21,28 +21,28 @@ gemini:
   # 기본 모델은 GeminiProperties.DEFAULT_MODEL 한 곳에서만 정의한다 (drift 방지). 여기엔 리터럴을 두지 않는다.
   # 운영에서 모델을 바꾸려면 GEMINI_MODEL 환경변수로 override (relaxed binding: GEMINI_MODEL -> gemini.model).
   retry:
-    # max-attempts 는 총 시도 횟수(초기 호출 + 재시도). 기본 1 = 재시도 없음 — URL 파싱 재시도는 호출자(PIKI-Server)의
-    # outbox recover 한 곳으로 모여 있다. 여기서 내부 재시도를 켜면 재시도가 이중으로 겹친다.
+    # max-attempts 는 총 시도 횟수(초기 호출 + 재시도). 기본 1 = 재시도 없음 — URL 파싱 재시도는 호출자(core)의
+    # 파싱 작업 큐 회수 한 곳으로 모여 있다. 여기서 내부 재시도를 켜면 재시도가 이중으로 겹친다.
     max-attempts: ${GEMINI_RETRY_MAX_ATTEMPTS:1}
 
 management:
   endpoints:
     web:
       exposure:
-        # PIKI-Server 와 동일한 2층 구조 전제: 외부 노출 없음(보안그룹) + 박스 내부 Alloy 만 scrape.
+        # core 와 동일한 2층 구조 전제: 외부 노출 없음(보안그룹) + 박스 내부 Alloy 만 scrape.
         include: health, prometheus
   metrics:
     tags:
-      # Grafana Cloud 에서 서비스 단위 구분용 공통 라벨. PIKI-Server(application=PIKI)와 별개 시계열.
+      # Grafana Cloud 에서 서비스 단위 구분용 공통 라벨. core(application=piki-core)와 별개 시계열.
       application: ${spring.application.name}
   tracing:
     sampling:
-      # PIKI-Server 와 동일하게 전수 추적. 볼륨이 부담되면 그때 하향.
+      # core 와 동일하게 전수 추적. 볼륨이 부담되면 그때 하향.
       probability: 1.0
     export:
       otlp:
         # 로컬엔 수집기(Alloy)가 없어 기본 off. 운영 컨테이너에만 TRACING_OTLP_ENABLED=true 를 준다.
-        # off 여도 trace 생성·전파(traceparent 수용, PIKI-Server item.parse span 아래 연결)는 그대로다.
+        # off 여도 trace 생성·전파(traceparent 수용, core 의 item.parse span 아래 연결)는 그대로다.
         enabled: ${TRACING_OTLP_ENABLED:false}
   opentelemetry:
     tracing:
diff --git a/src/test/resources/application.yml b/src/test/resources/application.yml
index 37450a8..f9cd644 100644
--- a/src/test/resources/application.yml
+++ b/src/test/resources/application.yml
@@ -1,4 +1,4 @@
-# 컨텍스트 로딩만 통과시키기 위한 더미 fallback (PIKI-Server 의 src/test/resources/application.yml 과 같은 패턴).
+# 컨텍스트 로딩만 통과시키기 위한 더미 fallback (core 의 src/test/resources/application.yml 과 같은 패턴).
 # 실제 Gemini 호출 테스트(E2E)는 @EnabledIfEnvironmentVariable / @Disabled 로 격리되어 있으므로
 # CI 에서 GEMINI_API_KEY 가 없어도 컨텍스트 로딩 자체는 깨지지 않는다.
 gemini:

From 233fb0cfc95714275dfe7af0d0cc2c16e9b01717 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=A1=B0=EC=9E=AC=EC=A4=91?=
 <126754298+m-a-king@users.noreply.github.com>
Date: Sun, 6 Sep 2026 17:54:35 +0900
Subject: [PATCH 6/6] =?UTF-8?q?docs:=20=EC=8A=A4=ED=83=80=EC=9D=BC=20?=
 =?UTF-8?q?=EA=B2=B0=EC=A0=95=20=EA=B8=B0=EB=A1=9D=EC=97=90=EC=84=9C=20?=
 =?UTF-8?q?=EC=99=B8=EB=B6=80=20=EC=BD=94=EB=93=9C=EB=B2=A0=EC=9D=B4?=
 =?UTF-8?q?=EC=8A=A4=20=EC=96=B8=EA=B8=89=EC=9D=84=20=EC=A7=80=EC=9A=B4?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docs/style-decisions.md 가 특정 외부 팀의 저장소를 이름·링크·비교 기준으로 9곳에서 언급하고 있었다. 결정(채택·기각·보류)과 근거는 이 repo 의 것이라 그대로 두고, 제목·참고 기준 줄·표 머리·근거 문장에서 외부 이름만 걷어냈다
- "검토한 관례" 로 일반화했으므로 문서의 결정 목록은 출처 없이도 읽힌다

Claude-Session: https://claude.ai/code/session_01Mg69sPkH9gHFqYZVSbf3ru
---
 docs/style-decisions.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/style-decisions.md b/docs/style-decisions.md
index e83b8bf..b7a23e9 100644
--- a/docs/style-decisions.md
+++ b/docs/style-decisions.md
@@ -1,24 +1,23 @@
-# 스타일 결정 기록 — 우아한테크코스 스타일 검토 (2026-07-20)
+# 스타일 결정 기록 (2026-07-20)
 
-참고 기준: [woowacourse-teams/2025-estime `be/dev`](https://github.com/woowacourse-teams/2025-estime/tree/be/dev) 백엔드.
-목표: 우테코식 객체지향 스타일을 참고하되, 이 서비스의 정체(무상태·단일 소비자 — CLAUDE.md 참조. 작성 당시엔 포팅 파리티 기간이기도 했다)에 맞는 형태로 취사선택한다. 아래 결정이 이 repo 스타일의 기준선이며, CLAUDE.md 와 충돌하면 CLAUDE.md 가 우선한다.
+목표: 외부 백엔드 코드베이스의 객체지향 관례를 검토하되, 이 서비스의 정체(무상태·단일 소비자 — CLAUDE.md 참조. 작성 당시엔 포팅 파리티 기간이기도 했다)에 맞는 형태로 취사선택한다. 아래 결정이 이 repo 스타일의 기준선이며, CLAUDE.md 와 충돌하면 CLAUDE.md 가 우선한다.
 
-## 1. estime 대비 채택 / 기각 결정
+## 1. 검토한 관례의 채택 / 기각 결정
 
-| # | 관례 (estime) | 결정 | 근거 |
+| # | 검토한 관례 | 결정 | 근거 |
 |---|---|---|---|
 | 1 | 4모듈 헥사고날(core/application/infrastructure/api) | **기각** | 무상태·DB 없음·소비자 1개 서비스에 모듈 분리는 과설계. 대신 포트-어댑터의 핵심(인터페이스 경계: `PageFetcher`·`HeadlessRenderer`·`GeminiClient`·`ImageStorage`)은 이미 단일 모듈 안에서 성립해 있다 — 이 경계를 유지·강화하는 것으로 같은 효과를 얻는다. |
 | 2 | rich domain + 정적 팩토리(`withoutId`/`from`/`of`) + 생성 시점 검증, public 생성자 금지 | **이미 부합 — 유지** | `ProductLink.parse`·`ProductImage.of`·`ProductSnapshot.fromExtracted` 가 같은 철학. 팩토리 명명은 현행(`parse`=문자열 해석, `of`=성분 조립, `from~`=다른 표현 변환)을 유지한다. |
-| 3 | 값 객체를 Lombok 클래스로 | **기각 — record 유지** | estime 의 클래스 VO 는 JPA 제약(no-arg 생성자) 대응이 크다. JPA 없는 이 repo 에선 `record` 가 더 정확한 도구다. |
+| 3 | 값 객체를 Lombok 클래스로 | **기각 — record 유지** | 검토한 코드의 클래스 VO 는 JPA 제약(no-arg 생성자) 대응이 크다. JPA 없는 이 repo 에선 `record` 가 더 정확한 도구다. |
 | 4 | Lombok 전면(@Getter·@RequiredArgsConstructor·@Slf4j…) | **보일러플레이트 표적 채택** (2026-07-23 재결정) | 사용자 피드백("생성자 직접 작성을 극도로 꺼림", "로거도 전부 애노테이션으로")으로 전면 기각 → 두 애노테이션만 채택. **`@RequiredArgsConstructor`**: 순수 필드-대입 생성자 12개 클래스 전환(@Qualifier 는 필드 + lombok.config copyableAnnotations), 조립 로직 생성자 4개는 손 유지(HttpPageFetcher·HttpHeadlessRenderer·GeminiHttpClient — 파생 필드/클라이언트 빌드, RequestScopedDnsResolver — 편의 생성자 2개). **`@Slf4j`**: 명시적 Logger 선언 11개 전환 — 생성 결과가 `private static final Logger log = LoggerFactory.getLogger(자기클래스.class)` 와 바이트코드 동일(javap 로 확인)이라 로거 이름·로그 출력 변화 없음. 값 객체는 여전히 record, @Builder·@Setter·@Data·@Value·@Getter 는 미채택. 애노테이션 순서는 Lombok → Spring. |
 | 5 | jakarta.validation 미사용, 검증은 100% 도메인 책임 | **이미 부합 — 유지** | url 형식 검증을 Bean Validation 이 아니라 `ProductLink.parse` 가 맡는 현행 구조가 정확히 같은 철학. |
-| 6 | 사유별 예외 클래스 + 이중 메시지(log 영어/user 한국어) + HTTP 200 고정 `CustomApiResponse` 봉투 | **기각** | 소비자가 사람이 아니라 PIKI-Server 워커다. HTTP status 가 계약의 전이 신호(2xx/422/기타)라 200 고정 봉투는 계약 파괴. userMessage 도 무의미. 단 estime 의 "사유별 예외" 의도는 우리 "사유 하나 = 정적 팩토리 하나" 규칙이 이미 담고 있다. |
+| 6 | 사유별 예외 클래스 + 이중 메시지(log 영어/user 한국어) + HTTP 200 고정 `CustomApiResponse` 봉투 | **기각** | 소비자가 사람이 아니라 core 워커다. HTTP status 가 계약의 전이 신호(2xx/422/기타)라 200 고정 봉투는 계약 파괴. userMessage 도 무의미. 단 "사유별 예외" 의 의도는 우리 "사유 하나 = 정적 팩토리 하나" 규칙이 이미 담고 있다. |
 | 7 | 초박형 컨트롤러 + Swagger 스펙 인터페이스 분리 | **절반 부합** | 초박형 컨트롤러는 이미 부합. 스펙 인터페이스 분리는 기각 — 계약 SSOT 가 `docs/api-contract.md` 고 소비자가 하나라 Swagger 문서화 계층이 필요 없다. |
 | 8 | 일급 컬렉션(`Participants`·`Votes`) | **보류(사례 발생 시 채택)** | 현재 컬렉션 불변식을 가진 도메인 개념이 없다. 생기면 이 패턴을 쓴다. |
 | 9 | `TimeProvider` 포트로 시간 주입, 도메인은 `now` 파라미터 수령 | **보류(사례 발생 시 채택)** | 현재 시간 의존 도메인 로직이 없다. 생기면 `Instant.now()` 직접 호출 대신 이 패턴을 쓴다. |
 | 10 | 파라미터·로컬변수 `final` 전면 | **기각** | 시그니처 노이즈 대비 이득이 작고 repo 관례가 아니다. 불변은 record·불변 컬렉션으로 표현한다. |
-| 11 | 주석 최소주의(151개 파일 중 Javadoc 6개) | **기각 — "왜" Javadoc 자산 유지** | 이 repo 의 "왜" 주석은 CLAUDE.md 가 자산으로 선언한 차별점이다(포팅 근거·계약 경계·보안 근거). estime 방향으로 줄이지 않는다. 단 시그니처 재진술 `@param` 같은 "무엇" 주석은 노이즈로 제거한다(§2). |
-| 12 | 테스트: @DisplayName 한국어 · AssertJ 전면 · Mockito 계층 · @BeforeEach 적극 | **부분 채택(이미 부합) / 나머지 기각** | @DisplayName 한국어 한 문장은 이미 규약. Mockito 는 기각(stub 우선 규율이 estime 보다 강하고 유지 가치가 있다). @BeforeEach 금지 유지(각 테스트 자기완결). AssertJ 는 현행대로 컬렉션·객체 그래프 비교에만. given-when-then 주석은 강제하지 않되 긴 테스트에서 허용. |
+| 11 | 주석 최소주의(151개 파일 중 Javadoc 6개) | **기각 — "왜" Javadoc 자산 유지** | 이 repo 의 "왜" 주석은 CLAUDE.md 가 자산으로 선언한 차별점이다(포팅 근거·계약 경계·보안 근거). 그 방향으로 줄이지 않는다. 단 시그니처 재진술 `@param` 같은 "무엇" 주석은 노이즈로 제거한다(§2). |
+| 12 | 테스트: @DisplayName 한국어 · AssertJ 전면 · Mockito 계층 · @BeforeEach 적극 | **부분 채택(이미 부합) / 나머지 기각** | @DisplayName 한국어 한 문장은 이미 규약. Mockito 는 기각(stub 우선 규율이 검토한 관례보다 강하고 유지 가치가 있다). @BeforeEach 금지 유지(각 테스트 자기완결). AssertJ 는 현행대로 컬렉션·객체 그래프 비교에만. given-when-then 주석은 강제하지 않되 긴 테스트에서 허용. |
 | 13 | 메서드 명명: `validate~`(생성 시)·`ensure~`(사용 시)·`obtain~`(찾고 없으면 throw)·`markAs~`(상태전이) | **채택(새 코드 기준)** | 검증 계열 명명의 일관성은 가져갈 가치가 있다. 단 기존 코드 일괄 개명은 하지 않는다 — 포팅 파리티 기간엔 새로 쓰는 코드부터 적용. |
 
 ## 2. 이번 /code-review 결과의 결정