diff --git a/docs/index.md b/docs/index.md
index 9c553bc4..9b82c2b4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,7 +10,7 @@ hero:
       link: /stack
     - theme: brand
       text: 📜 트러블슈팅
-      link: /trouble
+      link: /trouble/index.md
     - theme: brand
       text: 🗂️ 프로젝트 폴더구조
       link: /folder
diff --git a/docs/trouble/gradient.md b/docs/trouble/gradient.md
new file mode 100644
index 00000000..9b7df281
--- /dev/null
+++ b/docs/trouble/gradient.md
@@ -0,0 +1,79 @@
+### ✔ 문제 요약
+
+### 1. **문제 상황**
+
+- 매칭 성사 화면에서 의도한 **배경 그라디언트**와 **로띠(Lottie) 애니메이션 강조 그라디언트**가 정상적으로 표시되지 않는 문제가 발생했다.
+- 기존에는 해당 그라디언트가 정상적으로 렌더링되고 있었으나, **API 연동 작업**과 **리베이스 과정**, 그리고 **전체 레이아웃 구조 수정**을 반복하면서 예상치 못하게 레이아웃이 깨지고, 그라디언트가 전혀 보이지 않는 상황이 발생했다.
+- 초기 설계 단계에서 **`position: fixed`를 가급적 사용하지 않으려고 했던 선택**이 이번 문제에 영향을 준 것으로 보인다. 그라디언트를 fixed로 처리하지 않고 상대적인 레이아웃에서 구현하려다 보니, **상위 컨테이너의 overflow, z-index, transform 속성** 등의 영향을 받으면서 의도치 않게 가려지는 현상이 발생했을 가능성이 높았다.
+- 특히 **리베이스 후 코드 충돌을 해결하면서 일부 스타일 로직이 누락되거나 덮어씌워졌을 가능성**도 존재했다. 기존에 잘 보이던 그라디언트가 사라진 시점이 명확하지 않아 원인을 추적하는 데 시간이 소요되었다.
+- QA 과정에서 Lottie 애니메이션의 강조 영역이 정상적으로 표현되지 않아, 화면의 **강조 포인트가 사라지고 시각적 완성도가 떨어지는 문제**가 드러나면서 해당 이슈가 중요하게 부각되었다.
+
+### ✔ 원인 분석
+
+- 기존 구조에서는 배경 그라디언트와 로띠 강조 그라디언트를**absolute**로 포지셔닝하여,`.matching-success-background`, `.matching-lottie-gradient` 클래스를 통해 배치했다.
+- 하지만,**Header**가 상위 Layout 컴포넌트에서 먼저 렌더링되고, 배경 그라디언트가 포함된 MatchingSuccessView는 그 아래 DOM 계층에 위치해 있었다.
+- 이때, 아무리 z-index를 높게 주어도 **부모 stacking context**의 영향으로 Header보다 위로 올라오지 않았다.
+- **z-index와 position 속성은 DOM 계층 구조의 맥락(=stacking context) 안에서만 동작한다.**
+- 부모 요소가 낮은 z-index를 가지거나 stacking context를 새로 만들면, 자식이 아무리 z-index를 높여도**부모의 stacking context를 벗어나지 못하였다.**
+- 특히, Header가 상위에 있고, 배경 그라디언트가 상대적으로 하위 DOM에 있으면 z-index만 높여서는 절대 위로 올라오지 않는다.
+
+### ✔ 해결 방법
+
+### **absolute → fixed**
+
+- **absolute** 대신 **fixed** 포지셔닝을 사용하여 해결했다.
+- `position: fixed`는 DOM 계층과 무관하게**뷰포트 기준**으로 배치되므로, stacking context의 영향을 받지 않았다.
+- 배경 그라디언트와 로띠 강조 그라디언트를 fixed로 선언하여,**Header보다 아래, 주요 콘텐츠보다 뒤**에 자연스럽게 깔리도록 설계하였다.
+
+### **Foreground와 Background의 명확한 분리**
+
+- **텍스트, Lottie 애니메이션 등 주요 콘텐츠**는
+z-10 이상으로 두어 foreground 계층에서 명확하게 표현하였다.
+- **배경 그라디언트**는 z-0 이하로 두어
+background 계층에서 자연스럽게 깔리도록 조정하였다.
+
+### **Layout 및 Route 구조는 그대로**
+
+- 전체 Layout 및 Route 구조는 그대로 두고, **MatchingSuccessView 내부에서만 포지셔닝을 수정**하여 영향 범위를 최소화했다.
+- 이 접근법 덕분에 **다른 페이지나 컴포넌트에 미치는 부작용 없이 문제를 해결**할 수 있었다.
+
+### 실제 CSS 예시 (custom-utilities.css)
+
+```css
+.matching-success-background {
+  @apply absolute left-1/2 w-[30rem] h-[30rem] blur-3xl rounded-full z-[var(--z-negative-5)];
+  top: calc(50% + 10px);
+  transform: translate(-50%, -50%);
+  background: radial-gradient(67.17% 67.17% at 33.26% 84.78%, #9be88a 5%, #bcf3ff 88.05%);
+}
+
+.matching-lottie-gradient {
+  @apply absolute left-1/2 top-1/2 w-[18rem] h-[18rem] -translate-x-1/2 -translate-y-1/2 rounded-full z-[var(--z-negative-1)];
+  background: radial-gradient(
+    74.24% 74.24% at 50.22% 50.22%,
+    rgba(255, 255, 255, 0) 46.82%,
+    #ffffff 72.4%
+  );
+}
+```
+
+### 실제 적용 예시 (MatchingSuccessView)
+
+```tsx
+<div className="fixed top-[17rem] left-0 w-full h-full z-0">
+  <div className="matching-success-background" />
+  <div className="matching-lottie-gradient" />
+  <div className="z-[var(--z-card-profile-4)] h-[16rem] w-[16rem] flex-row-center">
+    <Lottie src={LOTTIE_PATH.SUCCESS} loop className="w-[16rem]" />
+  </div>
+</div>
+```
+
+- 기존 absolute → fixed로 변경
+- z-index는 0 이하로 설정하여 Header보다 뒤에, 주요 콘텐츠보다 아래에 위치
+
+### ✔ 회고 및 개선 방향
+
+- **z-index 문제는 단순히 값의 크기로 해결되지 않는다.** Stacking context에 대한 명확한 이해가 없으면 레이아웃 문제를 해결하기 어렵다는 점을 다시 깨달았다.
+- `position: fixed`는 **DOM 구조에 구애받지 않고 원하는 레이어링을 구현할 수 있는 강력한 도구**임을 체감했다.
+- 이번 경험으로 인해 **레이아웃을 건드리지 않고, 컴포넌트 단에서 포지셔닝 전략을 유연하게 바꾸는 접근법**이 훨씬 효율적일 수 있다는 것을 배웠다.
\ No newline at end of file
diff --git a/docs/trouble/image-1.png b/docs/trouble/image-1.png
new file mode 100644
index 00000000..c5c9f3c2
Binary files /dev/null and b/docs/trouble/image-1.png differ
diff --git a/docs/trouble/image.png b/docs/trouble/image.png
new file mode 100644
index 00000000..e49c1f54
Binary files /dev/null and b/docs/trouble/image.png differ
diff --git a/docs/trouble/index.md b/docs/trouble/index.md
new file mode 100644
index 00000000..9aa1813b
--- /dev/null
+++ b/docs/trouble/index.md
@@ -0,0 +1,22 @@
+---
+layout: home
+
+hero:
+  name: "트러블슈팅 "
+  tagline: 메잇볼 클라이언트 트러블슈팅 문서를 다루고 있습니다.
+  actions:
+    - theme: brand
+      text: protectedRoute 설정 관련
+      link: /trouble/protectedRoute
+    - theme: brand
+      text: useFunnel 기반 온보딩 구조 분기 및 상태 유지 전략
+      link: /trouble/useFunnel
+    - theme: brand
+      text: React Hooks 규칙, Supense 가이드에 맞는 매칭 카드 구조 개선
+      link: /trouble/suspense
+    - theme: brand
+      text: 사라진 그라디언트를 찾아서..
+      link: /trouble/gradient
+
+---
+
diff --git a/docs/trouble/protectedRoute.md b/docs/trouble/protectedRoute.md
new file mode 100644
index 00000000..01f83a99
--- /dev/null
+++ b/docs/trouble/protectedRoute.md
@@ -0,0 +1,79 @@
+로그인 하지 않은 사용자가, 로그인 이후 접근 가능한 경로로 접속했을때는 splash 화면으로 이동 후 로그인 페이지로 가는 흐름
+
+### ✔ 도입한 기술
+
+이번 로그인 흐름 개선에서는 React Router 기반의 라우팅 시스템을 구축하면서, `protected route`와 `public route`를 명확히 분리하는 구조를 도입했다. 이를 통해 로그인 상태에 따라 접근 가능한 경로를 엄격히 제어하고자 했다. 인증 상태 확인과 사용자 정보를 효율적으로 관리하기 위해 `tanstack-query`를 활용하여 사용자 상태를 서버에서 조회하는 `useAuth` 커스텀 훅을 만들었고, 인증 흐름 제어는 `AuthGuard` 컴포넌트로 구현했다. 또한, 카카오 소셜 로그인 연동 시 발생하는 인가 코드를 받아 서버에 전달해 로그인 처리를 하는 `LoginCallback` 컴포넌트가 있다. 로그인 과정 중 401 Unauthorized 상태가 발생하면 인터셉터로 이를 감지해 자동으로 로그인 페이지로 리다이렉트하는 로직도 함께 구성되었다.
+
+### ✔ 문제 요약
+
+초기에는 로그인 필요 페이지에 로그인하지 않은 사용자가 접근할 경우, 적절한 보호 및 리다이렉트 처리가 체계적으로 이뤄지지 않아 사용자 경험이 일관되지 않았다. 특히, 카카오 로그인 버튼 클릭 후 콜백에서 토큰 발급 및 사용자 정보 조회 후 화면 전환까지의 흐름이 명확하지 않았고, 인증 상태를 판단하는 `useAuth` 훅과 `AuthGuard`의 역할 분리가 애매해 로직이 복잡하게 얽혀 있었다. 이로 인해 로그인 성공 여부와 회원 가입 여부 판단 후 올바른 화면으로 자연스럽게 이동시키는 부분에서 예외 상황이 발생하거나 불필요한 재렌더링이 많았다. 더불어 interceptor에서 발생하는 401 에러 처리와 인증 흐름이 명확히 연결되지 않아 중복된 인증 검사와 비효율적인 네비게이션이 발생했다. 
+
+추가적으로 인증되지 않은 사용자가 홈 같은 인증 필요 경로에 접근할 경우, Tanstack Query를 통한 API 요청이 먼저 발생해 서버로부터 401 Unauthorized 에러가 반환된다. 이때 인증 상태 판단 전에 API 요청이 먼저 실행되고, 인증 실패(Hi developers… .. ㅋㅋ) 후 스플래시 화면으로 리다이렉트되면서 화면 깜빡임 현상이 발생해 사용자 경험이 떨어졌다.
+
+### ✔ 원인 분석
+
+가장 큰 원인은 인증 흐름의 단계별 역할과 경계가 명확히 정의되어 있지 않은 데 있었다. 카카오 로그인 콜백에서 인가 코드를 받아 서버에 전달하고, 서버로부터 로그인 성공 응답을 받은 후 클라이언트가 사용자 정보를 조회해 로그인 상태를 판단하는 부분이 분리되어 있었고, 이 사이의 상태 관리가 일관적이지 않았다. 또한, `useAuth` 훅이 사용자 상태를 조회하지만 이 결과를 기반으로 `AuthGuard`가 경로 접근을 제어하는 역할이 뚜렷하게 구분되지 않아 책임이 분산되었다. interceptor는 401 상태 발생 시 로그아웃 혹은 로그인 페이지 이동을 처리하지만, 그 흐름이 `useAuth`나 라우터와 조화롭게 연결되지 못해 중복 검사와 예외 처리가 반복됐다. 결과적으로 로그인 전, 로그인 후 화면 전환과 상태 반영이 비동기적으로 꼬여 흐름 제어가 어려웠다.까깜
+
+깜빡임 관련 현상은,  라우터에서 인증 보호 기능(`AuthGuard`)이 자식 컴포넌트 렌더링 전에 선행되지 않아, 인증 검증 전 API 요청이 발생하는 문제가 있었다. 또한 라우터에 에러 처리용 `errorElement`가 없어서 401 에러로 인한 예외 상황이 자연스럽게 핸들링되지 않았다. 결과적으로 사용자는 인증 상태 확인 이전에 불필요한 API 호출과 깜빡임 현상을 경험했다.
+
+### ✔ 해결 방법
+
+- 라우터 구조 재설계: React Router의 createBrowserRouter를 활용해, 로그인 필요 경로를 AuthGuard 컴포넌트로 감싸고, 로그인 전용 경로는 publicRoutes로 분리해 두었다. 이로써 인증 여부에 따라 접근 가능한 경로가 엄격히 구분되도록 했다.
+- useAuth 훅 개선: 서버에서 사용자 상태를 조회해 닉네임 존재 여부(isAuthenticated)와 가입 조건(isNotMatched) 등을 명확히 반환하도록 하여, 로그인 여부 및 추가 매칭 필요 여부를 판별하는 로직을 일원화했다. 캐시 무효화 기능을 활용해 사용자 상태 갱신도 쉽게 할 수 있도록 설계했다.
+- AuthGuard 컴포넌트 역할 명확화: useAuth에서 반환된 로그인 상태와 로딩 상태를 토대로 로그인되지 않은 경우 Navigate 컴포넌트를 이용해 로그인 페이지로 리다이렉트시키고, 인증 중이면 로딩 상태를 보여주도록 하여 접근 제어를 엄격하게 구현했다.
+- 깜빡임 관련 해결 방법으로는 , 라우터에서 `AuthGuard`를 최상위 레벨로 배치해, 인증 여부 확인이 먼저 이루어지고 자식 라우트들이 렌더링 되도록 변경했다. 이를 통해 인증이 안 된 경우 자식 컴포넌트들의 API 요청 자체를 막았다. 또, 라우터에 `errorElement`를 빈 컴포넌트 또는 별도 에러 UI로 추가해 예외 상황을 자연스럽게 처리하도록 함으로써, 예기치 않은 에러 발생 시 사용자에게 불필요한 깜빡임을 보여주지 않도록 했다. `AuthGuard` 컴포넌트에서 인증 상태 로딩 중엔 스플래시 화면을 렌더링하고, 인증 실패 시 로그인 페이지로 즉시 리다이렉트하도록 개선해 사용자 경험을 부드럽게 만들었다.
+
+- 코드 일부…
+    
+    ```tsx
+    // router.tsx
+    import { createBrowserRouter } from 'react-router-dom';
+    import AuthGuard from '@routes/auth-guard';
+    import Layout from '@routes/layout';
+    import Splash from '@pages/login/components/splash';
+    import ErrorView from '@pages/error/error-view';
+    import { protectedRoutes } from '@routes/protected-routes';
+    import { publicRoutes } from '@routes/public-routes';
+    import { ROUTES } from '@routes/routes-config';
+    
+    export const router = createBrowserRouter([
+      {
+        path: ROUTES.SPLASH,
+        element: <Splash />,
+      },
+      ...publicRoutes,
+      {
+        path: '/',
+        element: <AuthGuard />, // 최상위에 AuthGuard 배치
+        errorElement: <></>, // 빈 컴포넌트나 별도의 에러 UI로 깜빡임 방지
+        children: [
+          {
+            element: <Layout />,
+            children: [
+              ...protectedRoutes,
+              {
+                path: '/error',
+                element: <ErrorView />,
+              },
+              {
+                path: '*',
+                element: (
+                  <ErrorView message={`존재하지 않는 페이지입니다.\nURL을 다시 확인해 주세요.`} />
+                ),
+              },
+            ],
+          },
+        ],
+      },
+    ]);
+    
+    ```
+    
+
+### ✔ 회고 및 개선 방향
+
+이번 로그인 흐름 설계 도전은 protected route와 public route를 명확히 분리하여, 인증 상태에 따른 사용자 경험을 체계적으로 관리하는 데 큰 도움이 되었다. 하지만 카카오 로그인 콜백 이후 인가 코드 처리부터 사용자 상태 조회 및 화면 전환까지 이어지는 비동기 흐름이 복잡하여, interceptor, useAuth, AuthGuard 등 여러 컴포넌트가 인증 흐름의 일부를 분담하는 과정에서 상태 변화가 즉시 반영되지 않아 로직 꼬임과 디버깅 어려움이 있었다.
+
+앞으로는 인증 흐름 내 각 역할별 책임과 상태 변화를 더욱 명확히 구분하는 동시에, 전역 상태 관리 솔루션(Recoil, Zustand 등)을 도입해 인증 상태 변화를 일관성 있게 처리하는 방안을 고민할 예정이다. 또한 네트워크 오류, 토큰 만료 등 다양한 예외 처리 케이스를 세밀하게 테스트하여 사용자 이탈을 방지하는 UX 개선에도 주력할 계획이다. 이를 통해 로그인과 인증 로직을 더욱 견고하고 확장성 있게 다듬는 것이 목표다.
+
+이번 개선 작업을 통해 인증 상태가 완전히 확인된 후에만 protected route 내부 컴포넌트가 렌더링되도록 하여, 불필요한 API 호출과 401 에러로 인한 화면 깜빡임 현상을 원천 차단할 수 있었다. 덕분에 스플래시 화면이 자연스럽게 노출되어 사용자 경험이 크게 향상되었다. 앞으로도 인증과 관련된 비동기 상태 관리는 라우터 수준에서 관리하여 페이지 렌더링 타이밍과 API 호출 흐름을 최대한 일치시키는 방향으로 설계할 계획이다. 또한, 에러 핸들링 UI도 일관성 있게 구성해 사용자 이탈을 최소화하는 데 집중할 예정이다.
\ No newline at end of file
diff --git a/docs/trouble/suspense.md b/docs/trouble/suspense.md
new file mode 100644
index 00000000..7c34dfc9
--- /dev/null
+++ b/docs/trouble/suspense.md
@@ -0,0 +1,115 @@
+### ✔ 문제 요약
+
+**기존 useMatchCreate** 훅은 두 API(**`SINGLE_MATCH_RESULT`**, **`GROUP_MATCH_RESULT`**)와 Mock 데이터(**`mockMateSingle`**)를 모두 한 곳에서 다루면서, **`type`**이라는 Prop에 따라 분기 처리하도록 설계되어 있었다.
+
+```tsx
+const useMatchCreate = (matchId: number, type: 'single' | 'group' | null | undefined) => {
+  // 그룹 결과 조회 요청
+  const { data: mateGroup } = useSuspenseQuery<getGroupMatchResultResponse>(
+    matchQueries.GROUP_MATCH_RESULT(matchId, type === 'group')
+  );
+
+  const getMatchData = (): MatchCardData | null => {
+    if (type === 'single') { ... } // mock 데이터 반환
+    if (!mateGroup) return null;
+    return { ...mateGroup, type: 'group' }; // 그룹 API 응답 반환
+  };
+
+  return { matchData: getMatchData() };
+};
+
+```
+
+- **문제 1: 타입에 따라 쿼리/데이터 분기가 동적으로 일어남.**
+    
+    **`type`**이 **`group`**일 때는 **`useSuspenseQuery`**로 그룹 매치 결과를 불러오고,
+    
+    **`type`**이 **`single`**일 때는 mock 데이터를 사용하도록 분기 처리됨.
+    
+- **문제 2: 두 쿼리 훅을 동시에 선언하고, 조건부로 반환.**
+    
+    훅 내부에 **`useSuspenseQuery`**가 한 번만 있을 것 같지만, **`type`**이 **`group`**이면 항상 **`useSuspenseQuery`**가 실행됨.
+    
+    **`type`**이 **`single`**이면 이 훅은 실행되지 않지만, 다른 컴포넌트에서의 사용이 명확하지 않음.
+    
+- **문제 3: mock 데이터와 API 데이터를 섞어 쓰고 있음.**
+    
+    **`single`** 타입 결과는 mock이고, **`group`** 타입 결과는 API 데이터에서 가져옴. 이는 미래에 API 전환 시 유지보수를 힘들게 함.
+    
+- **문제 4: 조건부 렌더링이 훅 내부에서 일어남.**
+    
+    이 구조는 React Hook 규칙상 무조건 훅은 **항상 같은 위치에서 호출되어야** 한다는 원칙을 어기게 됨.
+    
+
+### ✔ 원인 분석
+
+- **2-1. useSuspenseQuery는 조건부로 호출할 수 없음**
+    
+    **`type`**에 따라 **`useSuspenseQuery`**를 바로바로 바꿔서 쓰면, 리액트는 훅 호출 순서를 기준으로 내부 상태를 관리하므로 **`type`**이 바뀌면 호출 순서가 꼬여 에러 발생!
+    
+- **2-2. enabled로 조건부 실행을 시도**
+    
+    **`useSuspenseQuery`**에서 **`enabled`** 옵션(**`GROUP_MATCH_RESULT(matchId, type === 'group')`**)을 줘도
+    
+    이는 단순히 쿼리 결과의 **`data`**와 **`isFetching`** 등을 제어할 뿐, 훅 자체가 **실행 자체를 억제하는 것은 아님**. 즉, **`type`**이 **`group`**이든 **`single`**이든 **훅은 항상 실행**됨.
+    
+- **2-3. API 호출이 불필요하게 발생**
+    
+    **`type`**이 **`single`**이더라도 그룹 매칭 결과 조회 API가 실행됨. 반대로, **`group`**인데도 **`single`**(mock) 데이터 처리 로직이 상관없이 있다는 구조적 혼동이 존재함.
+    
+- **2-4. 훅과 컴포넌트의 책임 분리 필요**
+    
+    **`useMatchCreate`**가 **API 호출**, **mock 데이터 반환**, **타입 판단**, **카드 데이터 변환**까지 한 번에 모두 담당하면, 유지 보수와 확장이 어렵고, 실제로 **훅 규칙 위반**으로 에러가 발생함.
+    
+
+### ✔ 해결 방법
+
+**2-1. 훅과 컴포넌트 구조 분리**
+
+- **SingleMatchCard**: 싱글 매칭 데이터만을 받아 표시하는 컴포넌트
+- **GroupMatchCard**: 그룹 매칭 데이터만을 받아 표시하는 컴포넌트
+- **MatchCardSection**: 타입(**`type`**)에 따라 Single/Group 컴포넌트를 조건부 렌더링
+
+```tsx
+// MatchCardSection.tsx
+const MatchCardSection = ({ matchId, type }: MatchCardSectionProps) => {
+  if (type === 'single') return <SingleMatchCard matchId={matchId} />;
+  if (type === 'group') return <GroupMatchCard matchId={matchId} />;
+  return null;
+};
+```
+
+장점: 타입별로 훅(쿼리) 호출과 데이터 변환 로직이 명확히 분리되어 훅 규칙을 철저히 지킬 수 있음
+
+**2-2. Mock -> API 전환이 자연스럽게 연결**
+
+기존에는 **`single`**이면 무조건 mock을 쓰다가, 이제는 **SingleMatchCard 컴포넌트 단에서도 실제 API를 사용하도록** 설계만 조금만 바꾸면 쉽게 마이그레이션할 수 있음.
+
+**2-3. 데이터 흐름의 일관성 확보**
+
+- **SingleMatchCard**: **`useSuspenseQuery(matchQueries.SINGLE_MATCH_RESULT(matchId))`**
+- **GroupMatchCard**: **`useSuspenseQuery(matchQueries.GROUP_MATCH_RESULT(matchId))`**
+
+각 컴포넌트는 **자신의 타입에 맞는** 쿼리만 훅으로 호출함. 불필요한 API 호출, mock 데이터 처리 등을 걱정할 필요가 없음.
+
+**2-4. React Hook 규칙 엄수**
+
+훅 호출은 **컴포넌트 상단에서 무조건 동일한 순서로**. 조건부 렌더링은 컴포넌트 트리에서 JSX 레벨에서 처리.
+
+→ **훅 내부에서 조건부 처리가 아니라, 트리(컴포넌트 레벨)에서 조건부로 렌더링**을 하게 되므로, 훅 규칙을 절대로 어기지 않음.
+
+**2-5. Suspense로 데이터 로드 및 에러 처리 용이**
+
+Suspense를 사용하여, **데이터가 준비된 후 렌더링**되므로 **`undefined`**로 인한 깜빡임, 스타일 이슈 등을 완전히 방지.
+
+### ✔ 회고 및 개선 방향
+
+컴포넌트 구조 개선을 통해 매칭 타입(싱글/그룹)별로 기존에 한곳에서 담당하던 복잡한 로직을, **각자의 역할에 맞게 분리**함으로써 여러 문제를 명확하게 해결할 수 있었다. 기존에는 타입 구분이 훅 내부에서 조건부로 처리되다 보니, 훅이 항상 같은 순서로 호출되어야 한다는 **React Hooks 규칙**을 어길 수밖에 없었고, 이로 인해 예기치 않은 버그와 디버깅의 어려움이 발생했다. 또한, API와 mock 데이터가 혼재되어 있어, 실제 서비스 연동 시 **불필요한 API 호출이 발생**하거나, 데이터 흐름이 불명확해지는 등, **유지보수성**과 **네트워크 성능** 모두에 악영향을 끼쳤다.
+
+이를 해결하기 위해 **SingleMatchCard**, **GroupMatchCard** 컴포넌트로 각각 역할을 나누었고, 이 두 컴포넌트는 각자에게 맞는 API나 데이터만을 전담하도록 했다. 이제 **MatchCardSection**에서는 단순히 매칭 타입에 따라 해당 컴포넌트를 조건부로 렌더링만 하면 되므로, 컴포넌트 구조가 명확해지고, **훅이 동일한 위치에서 한 번만 호출**되도록 보장할 수 있다.
+
+이 구조의 가장 큰 장점은 **API가 바뀌거나, mock에서 실제 API로 전환할 때 컴포넌트 하나만 수정하면 충분하다**는 점이다. 예를 들어, 싱글 매칭도 결국 API 데이터를 받아오는 구조로 전환하고 싶을 때, SingleMatchCard만 수정하면 되므로 **낮은 결합도와 높은 응집력**을 가진다. 또한, **불필요한 네트워크 요청이 근본적으로 차단**되어, 서비스의 네트워크 효율과 성능이 크게 개선된다.
+
+**Suspense**를 활용해 데이터 페칭이 끝난 후에만 렌더링이 이루어지도록 보장함으로써, 페이지 전환 시 불완전한 데이터로 인한 깜빡임이나 스타일 이슈도 막을 수 있다. 데이터 흐름이 타입별로 명확하게 구분되어 있어, **디버깅과 추가 기능 개발이 훨씬 용이**해졌고, **훅의 규칙 위반** 문제도 절대 발생하지 않는다.
+
+이처럼, **코드베이스가 복잡해질수록 컴포넌트와 훅의 역할을 분리**하는 것은 매우 중요하다. 훅 내부에서 조건부 처리하기보다는, **상위 컴포넌트에서 조건부 렌더링**을 하는 구조를 통해, 각각의 컴포넌트가 자신의 데이터와 API, UI에 대한 책임만을 가지도록 하는 것이 **유지보수성, 확장성, 그리고 안정성** 모두를 높이는 핵심적인 원칙임을 다시 한 번 깨달았다.
\ No newline at end of file
diff --git a/docs/trouble/useFunnel.md b/docs/trouble/useFunnel.md
new file mode 100644
index 00000000..d63ac883
--- /dev/null
+++ b/docs/trouble/useFunnel.md
@@ -0,0 +1,103 @@
+### ✔ 도입한 기술(라이브러리)과 이유 (없다면 생략 가능)
+
+- `useSearchParams` (react-router-dom)
+    
+    → URL 쿼리스트링으로 퍼널 단계를 관리하기 위해 도입했다. 새로고침이나 공유 시에도 현재 단계를 유지할 수 있다.
+    
+- 커스텀 훅 `useFunnel`
+    
+    → 퍼널 단계 관리, 이전/다음 단계 이동, 유효성 검사 등을 재사용 가능한 형태로 분리해 구조화했다.
+    
+
+### ✔ 문제 요약
+
+퍼널 구조의 온보딩을 구현하면서 다음과 같은 문제가 발생했다:
+
+1. 온보딩 도중 사용자가 '그룹 매칭'을 선택했을 때, 퍼널 흐름이 갈라지는 구조를 어떻게 설계할지.
+2. 퍼널 단계를 기준으로 프로그레스 바를 표시하려 했으나, **전체 스텝 수가 동적으로 바뀌는 상황에서 진행률을 어떻게 계산할지**.
+3. 새로고침 시 현재 단계와 선택값이 유지되지 않아 **진행 중이던 온보딩이 초기화되는 UX 문제**.
+4. 이미 온보딩을 완료한 사용자가 URL로 다시 접속했을 때 **어떻게 처리할지** (재접근 허용? 홈 리디렉션? 에러 페이지?).
+
+### ✔ 원인 분석
+
+### 1. 퍼널의 동적 분기 구조
+
+처음에는 하나의 `useFunnel` 훅 안에서 `MATCHING_TYPE`에 따라 분기 처리를 하려 했으나,
+
+- 분기 전에는 전체 스텝의 개수를 알 수 없어 `ProgressBar` 계산에 문제 발생
+- `GROUP_FUNNEL_STEPS`는 `FIRST_FUNNEL_STEPS`와 구조도 다르고, 쿼리스트링도 별도로 관리되어야 하므로 결국 **두 퍼널을 분리**함
+
+### 2. 새로고침 시 상태 초기화
+
+- 상태(state)는 `useState`로만 관리되고 있었고, URL은 쿼리스트링으로 현재 `step`만 유지됨
+- 새로고침 시 `selections` 객체가 초기화되므로, 이전에 선택했던 값들이 모두 사라짐 → 퍼널 흐름상 뒤로 돌아가도 UX가 불안정해짐
+
+### 3. 완료된 사용자의 재접근
+
+- API를 통해 서버에 `POST` 요청을 보낸 후, 사용자가 `/onboarding` 주소로 다시 접속할 수 있는 구조였음
+- 다시 접속 시 완료된 사용자도 온보딩 흐름으로 진입 가능해 의도치 않은 재요청 또는 중복 입력이 발생할 수 있음
+
+### ✔ 해결 방법
+
+### 1. 퍼널 구조 분리 및 `navigate` 활용
+
+- `MATCHING_TYPE` 단계에서 "그룹"을 선택하면 `navigate('/onboarding/group?step=GROUP_ROLE')`로 이동
+- 일반 온보딩과 그룹 온보딩을 완전히 **다른 퍼널 흐름**으로 분리하여 `useFunnel(GROUP_FUNNEL_STEPS)`을 각각 적용
+- `goTo`를 통해 쿼리스트링만 변경하며 단계 이동 → 새로고침 후에도 해당 단계 유지 가능
+
+### 2. `ProgressBar`와 동적 스텝 수 처리
+
+- 일반 퍼널에서는 `ProgressBar currentStep={progressOverride ?? currentIndex}`로 계산
+- 그룹 퍼널로 분기된 이후에는 `GROUP_FUNNEL_STEPS.length`를 기준으로 별도로 `ProgressBar` 렌더링
+- `progressOverride` state를 통해 조건부로 오버라이딩 가능하게 구현
+
+### 3. 새로고침 시 단계 유지 및 에러 방지
+
+- `useFunnel` 내부에서 쿼리스트링(`?step=X`)이 없거나 유효하지 않을 경우,
+    
+    → `setSearchParams({ step: steps[0] })`으로 강제 초기화
+    
+    → 잘못된 접근은 `navigate(ROUTES.ERROR)`로 에러 페이지 유도
+    
+
+```tsx
+useEffect(() => {
+  if (!stepFromUrl) {
+    setSearchParams({ step: steps[0] }, { replace: true });
+  }
+  if (!isValidStep) {
+    navigate(ROUTES.ERROR, { replace: true });
+  }
+}, [...]);
+```
+
+### 4. 완료된 사용자의 재접근 처리
+
+- 서버에서 이미 온보딩을 완료한 사용자의 경우 `/onboarding` 접속 시 홈으로 redirect 되도록 가드 필요
+- 클라이언트에서 `GET /my/onboarding-status`와 같은 API를 통해 진행 여부 판단 → 진입 제한하거나 중간단계에서 redirect 처리
+
+### ✔ 회고 및 개선 방향
+
+- **퍼널 UI는 정적인 흐름을 가정하면 안 될 것 같다.**
+    
+    특히 UX 흐름 상 사용자의 선택에 따라 다음 단계가 달라지는 경우가 많기 때문에,
+    
+    퍼널 전체 단계를 하나의 고정된 리스트로 처리하기보다 **분기별 퍼널을 나누고 구조적으로 분리하는 게 안정적**이었다.
+    
+- **ProgressBar 계산은 퍼널 흐름에 강하게 의존한다.**
+    
+    ‘전체 단계 수를 어디까지 계산할 것인가’라는 문제는 분기를 포함하면 더 복잡해지므로,
+    
+    분기된 퍼널 흐름마다 고유한 `useFunnel`을 관리하고 `progressOverride` 등을 활용하는 전략이 효과적이었다.
+    
+- **URL 기반 상태 관리의 장점**
+    
+    `useSearchParams`를 통해 퍼널 단계를 URL에 명시한 덕분에, 새로고침/뒤로가기/직접 접근 등의 시나리오에서도 상태를 안정적으로 유지할 수 있었다.
+    
+- **상태 유지와 초기화의 균형 필요**
+    
+    selections를 로컬스토리지에 저장할지 여부는 아직 보류했지만, 초기에는 완전히 사라지는 UX가 너무 불친절해서 추후에는 `step`만 유지하고 값은 임시적으로 `sessionStorage`에 저장하는 방안을 고려할 수 있을 듯하다.
+    
+- **중복 접근 방지 필요**
+    
+    이미 완료된 사용자의 `/onboarding` 재접근 이슈는 아직 명확한 UX 기준이 없다면 서버에서 진입 제한 flag를 내려주는 구조로 처리하는 것이 안전할 것 같다.
\ No newline at end of file