[docs] 프론트엔드 CLAUDE.md 폴더별 구조로 재배치 by seongwon030 · Pull Request #1791 · Moadong/moadong

seongwon030 · 2026-06-30T14:35:08Z

변경 내용

단일 frontend/CLAUDE.md(+ docs/claude/*.md @import)로 관리하던 가이드를, 전역 가이드 + 폴더별 CLAUDE.md 구조로 재배치.

전역(항상 로드) — frontend/CLAUDE.md: 빌드/개발 명령어, 환경변수, 코딩 컨벤션, 테스트·Storybook·MSW, 폴더별 문서 인덱스
폴더별(코드 옆, 작업 시 lazy 로드) — 신규 7개
- src/apis/ API 레이어·인증·SSE
- src/hooks/Queries/ React Query 캐싱 전략
- src/constants/ 상수 관리
- src/styles/ UI·테마·브레이크포인트·날짜
- src/experiments/ A/B 테스트
- src/layouts/ 웹/웹뷰 통합 라우팅
- src/utils/ 유틸·외부 SDK 초기화
보존 — docs/claude/og.md (OG 태그, middleware.ts 전용)
삭제 — docs/claude/{architecture,api,ui,testing,features,conventions}.md (전부 위로 이동/인라인)

변경 이유

기존 @import는 eager 로드라 한 폴더만 작업해도 전체 도메인 문서가 항상 컨텍스트에 깔림. 폴더별 CLAUDE.md는 해당 폴더 작업 시에만 lazy 로드 → 컨텍스트 절약.
문서 업데이트 기준이 "주제 매칭(모호)" → "코드 위치(1:1)"로 바뀌어 drift 감소.

이동 중 바로잡은 것

secureFetch 토큰 갱신 트리거 문서 오류 수정: 403 → 401 (실제 코드 src/apis/auth/secureFetch.ts 기준)
stale했던 src/context/(미존재) 참조 → 실제 구현(apis/clubSSE.ts + hooks/useApplicantSSE.ts + store/useAdminClubStore.ts) 기준으로 정리
끊긴 참조 수정: og-crawler-inapp-browser.md의 docs/claude/features.md → docs/claude/og.md

검증

코드 무변경(문서만). 전체 CLAUDE.md 8개 배치 확인, @docs/claude eager import 잔존 0, 삭제 문서 끊긴 참조 0.

영향 범위

문서/AI 에이전트 가이드 한정. 빌드·런타임 영향 없음.

Summary by CodeRabbit

Documentation
- 프론트엔드 문서 구조가 전반적으로 정리되어, 아키텍처·코딩 컨벤션·테스트·Storybook 안내가 간결한 가이드 중심으로 재구성되었습니다.
- API, 상수, 실험, 레이아웃, 유틸리티 관련 폴더별 안내 문서가 추가되어 참고 위치를 찾기 쉬워졌습니다.
- OG 태그 문서가 라우트 매칭과 크롤러 대응 중심으로 업데이트되었습니다.
- 일부 기존 문서 내용은 제거되거나 축약되어 중복 설명이 줄었습니다.

- 전역 가이드(빌드/컨벤션/테스트)는 frontend/CLAUDE.md에 유지 - 도메인 상세는 코드 옆 폴더별 CLAUDE.md로 분산(작업 시 lazy 로드) - 토큰 갱신 트리거 403 -> 401(실제 secureFetch 코드 기준), stale한 src/context 참조 정리

vercel · 2026-06-30T14:35:14Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
moadong	Ready	Preview, Comment	Jun 30, 2026 2:47pm

reviewer-harry · 2026-06-30T14:35:54Z

Claude finished @seongwon030's task in 2m 27s —— View job

harry 리뷰 결과 ✅

문서 전용 PR이라 harry-review-rules.md의 코드 패턴 항목(메모이제이션·useEffect·패칭 위치 등)은 해당 사항이 없어요. 대신 문서가 실제 코드와 맞는지 직접 대조해서 검증했고, 본문에 적힌 "바로잡은 것 / 검증" 주장이 전부 사실로 확인됐어요.

검증 내역

secureFetch 토큰 갱신 트리거 401 — src/apis/auth/secureFetch.ts:20에서 response.status === 401 확인. 기존 문서의 403은 오기였고 이번 수정이 맞아요.
SSE 참조 정리 — src/apis/clubSSE.ts, src/hooks/useApplicantSSE.ts, src/store/useAdminClubStore.ts 모두 실존. stale했던 src/context/는 실제로 삭제돼 없어요.
인덱스/링크 무결성 — 새 폴더별 CLAUDE.md 7개 + docs/claude/og.md가 가리키는 파일(AppLayout.tsx, webviewRoutes.tsx, mediaQuery.ts, initSDK.ts, loadNaverMapScript.ts, experiments 3종, constants 8종) 전부 존재.
VITE_NAVER_MAP_CLIENT_ID — src/utils/loadNaverMapScript.ts:21에서 실제 사용 확인.
끊긴 참조 0 — @docs/claude eager import 잔존 없음, 삭제 문서(architecture/api/ui/testing/conventions/features.md)로의 끊긴 참조 없음.

총평

전역 가이드 + 폴더별 lazy 로드 구조로의 재배치가 깔끔하고, 이동하면서 stale했던 내용까지 코드 기준으로 바로잡은 점이 좋아요. 변경 범위도 문서로만 한정돼 surgical하고, 빌드·런타임 영향이 없어요. 위반 사항 없이 통과예요. 수고하셨어요! 👍
· doc-update-criteria

coderabbitai · 2026-06-30T14:36:39Z

Warning

Review limit reached

@seongwon030, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 000d9d0f-2ceb-4946-bc4a-149d684532fc

📥 Commits

Reviewing files that changed from the base of the PR and between 08f81a0 and 27284ab.

📒 Files selected for processing (3)

frontend/docs/claude/og.md
frontend/docs/features/club-detail/og-crawler-inapp-browser.md
frontend/src/utils/CLAUDE.md

Walkthrough

frontend/CLAUDE.md를 슬림화하고 각 src 하위 폴더(apis, constants, experiments, hooks/Queries, layouts, styles, utils)에 새 CLAUDE.md를 추가하여 문서를 분산 관리하는 구조로 전환했다. docs/claude/ 하위 문서도 재정리하여 og.md를 OG 태그 구조 중심으로 재편했으며, api/architecture/conventions/testing.md의 기존 내용은 폴더별 CLAUDE.md로 이전되어 제거됐다.

Changes

Frontend CLAUDE.md 문서 재편

Layer / File(s)	Summary
최상위 CLAUDE.md 재구성 `frontend/CLAUDE.md`	문서 로딩/갱신 규칙 추가, 외부 서비스 항목 간결화(`src/utils/CLAUDE.md` 참조), 프로젝트 구조·컨벤션·테스트 섹션을 불릿 기반으로 재작성, 기존 도메인별 링크 목록을 폴더별 인덱스 테이블로 교체.
src 폴더별 CLAUDE.md 신규 추가 `frontend/src/apis/CLAUDE.md`, `frontend/src/constants/CLAUDE.md`, `frontend/src/experiments/CLAUDE.md`, `frontend/src/hooks/Queries/CLAUDE.md`, `frontend/src/layouts/CLAUDE.md`, `frontend/src/styles/CLAUDE.md`, `frontend/src/utils/CLAUDE.md`	APIs 레이어·인증·SSE, 상수 중앙 관리 원칙, A/B 테스트 프레임워크 구성, React Query 캐싱 전략 표, 웹/웹뷰 레이아웃 분기 규칙, 스타일 시스템, 유틸리티 목록 및 SDK 초기화 방식을 각 폴더별로 문서화.
docs/claude/ 하위 문서 재정리 `frontend/docs/claude/og.md`, `frontend/docs/features/club-detail/og-crawler-inapp-browser.md`, `frontend/docs/claude/api.md`, `frontend/docs/claude/architecture.md`, `frontend/docs/claude/conventions.md`, `frontend/docs/claude/testing.md`	`og.md`를 OG 태그 구조 중심으로 재편(SSE·유틸 섹션 제거, `middleware.ts` 예시 갱신), 참조 경로를 `features.md`→`og.md`로 변경, `api/architecture/conventions/testing.md` 내용은 폴더별 `CLAUDE.md`로 이전되어 제거.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

Moadong/moadong#1358: 이 PR의 frontend/src/experiments/CLAUDE.md가 문서화하는 실험 프레임워크(definitions.ts, ExperimentRepository.ts, initializeExperiments.ts)가 해당 PR에서 구현됨.
Moadong/moadong#1503: frontend/CLAUDE.md 슬림화 및 docs/claude/ 하위 문서 분리 작업이 해당 PR과 동일한 문서 재편 흐름.
Moadong/moadong#1649: 외부 서비스/SDK 초기화를 src/utils/initSDK.ts 기준으로 안내하는 이번 문서 변경과 SDK 초기화 위치 정정이 같은 가이드 항목을 다룸.

Suggested labels

📃 Docs

Suggested reviewers

lepitaaar
suhyun113
oesnuj

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	전역 CLAUDE.md를 폴더별 CLAUDE.md 구조로 재배치한 변경 목적을 정확히 요약합니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch doc-update-criteria

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

gemini-code-assist

Code Review

This pull request restructures the project's documentation by modularizing the monolithic frontend/CLAUDE.md file into domain-specific CLAUDE.md files within their respective directories (such as apis, constants, experiments, hooks/Queries, layouts, styles, and utils). It also removes several obsolete documentation files and updates references accordingly. The review feedback suggests improving documentation usability and navigation by converting plain text file references into relative markdown links across several documentation files.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

github-actions · 2026-06-30T14:37:23Z

🎨 UI 변경사항을 확인해주세요

변경된 스토리를 Chromatic에서 확인해주세요.

구분	링크
🔍 변경사항 리뷰	https://www.chromatic.com/build?appId=67904e61c16daa99a63b44a7&number=674
📖 Storybook	https://67904e61c16daa99a63b44a7-dkubaucyrk.chromatic.com/

9개 스토리 변경 · 전체 68개 스토리 · 26개 컴포넌트

리뷰 제안 반영 - utils/CLAUDE.md, og.md, og-crawler 문서의 텍스트 참조 링크화

reviewer-harry · 2026-06-30T14:47:13Z

Claude finished @seongwon030's task in 51s —— View job

harry 리뷰 결과 ✅

이번 synchronize로 추가된 커밋(27284ab8)만 증분 리뷰했어요. 직전 리뷰 이후 바뀐 건 문서 3개의 평문 참조를 상대경로 마크다운 링크로 변경한 것뿐이에요 (gemini 제안 반영).

검증 내역

frontend/docs/claude/og.md → [frontend/CLAUDE.md](../../CLAUDE.md) — frontend/docs/claude/에서 ../../ = frontend/, 대상 실존 ✅
frontend/docs/features/club-detail/og-crawler-inapp-browser.md → [docs/claude/og.md](../../claude/og.md) — club-detail/에서 ../../claude/og.md = frontend/docs/claude/og.md, 대상 실존 ✅
frontend/src/utils/CLAUDE.md → [frontend/CLAUDE.md](../../CLAUDE.md) — src/utils/에서 ../../ = frontend/, 대상 실존 ✅

총평

harry-review-rules.md의 코드 패턴 항목(메모이제이션·useEffect·패칭 위치 등)은 문서 전용 변경이라 해당 사항이 없어요. 상대경로 3개 모두 디렉터리 기준으로 정확히 계산됐고 링크 대상도 전부 실존해서, 끊긴 링크 없이 문서 간 탐색성만 깔끔하게 개선됐어요. 변경 범위도 평문→링크 치환으로만 한정돼 surgical하고요. 위반 사항 없이 통과예요. 수고하셨어요! 👍
· doc-update-criteria

channeltalk Bot assigned seongwon030 Jun 30, 2026

vercel Bot deployed to Preview June 30, 2026 14:35 View deployment

github-actions Bot added 💻 FE Frontend 🚁AI claude, codex 활용 시 labels Jun 30, 2026

gemini-code-assist Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread frontend/src/utils/CLAUDE.md Outdated

Comment thread frontend/docs/claude/og.md Outdated

Comment thread frontend/docs/features/club-detail/og-crawler-inapp-browser.md Outdated

docs: 문서 간 파일 참조를 상대경로 마크다운 링크로 변경

27284ab

리뷰 제안 반영 - utils/CLAUDE.md, og.md, og-crawler 문서의 텍스트 참조 링크화

vercel Bot deployed to Preview June 30, 2026 14:47 View deployment

seongwon030 merged commit 7b5fa7b into develop-fe Jun 30, 2026
8 checks passed

seongwon030 deleted the doc-update-criteria branch June 30, 2026 14:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[docs] 프론트엔드 CLAUDE.md 폴더별 구조로 재배치#1791

[docs] 프론트엔드 CLAUDE.md 폴더별 구조로 재배치#1791
seongwon030 merged 2 commits into
develop-fefrom
doc-update-criteria

seongwon030 commented Jun 30, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

reviewer-harry Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

Review limit reached

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

reviewer-harry Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

seongwon030 commented Jun 30, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

변경 내용

변경 이유

이동 중 바로잡은 것

검증

영향 범위

Summary by CodeRabbit

Uh oh!

vercel Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reviewer-harry Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

harry 리뷰 결과 ✅

Uh oh!

coderabbitai Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎨 UI 변경사항을 확인해주세요

Uh oh!

reviewer-harry Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

harry 리뷰 결과 ✅

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

seongwon030 commented Jun 30, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Jun 30, 2026 •

edited

Loading

reviewer-harry Bot commented Jun 30, 2026 •

edited

Loading

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

github-actions Bot commented Jun 30, 2026 •

edited

Loading

reviewer-harry Bot commented Jun 30, 2026 •

edited

Loading