create-web-0to1 0.1.0

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/09-/353/235/274/354/232/260/355/212/270-/354/240/225/354/235/230.md

@@ -0,0 +1,169 @@
+# 라우트 정의
+
+## 원칙
+
+- route, menu, breadcrumb는 가능하면 한 파일에서 같이 관리합니다.
+- 경로 문자열을 여러 곳에 다시 쓰지 않고, 공통 정의를 참조하게 만듭니다.
+- 정적 경로는 문자열, 동적 경로는 함수로 둡니다.
+- breadcrumb는 `usePathname()`으로 현재 경로를 읽고, 공통 함수로 items를 계산합니다.
+- 다만 규모가 커지면 `menu`와 `breadcrumb`는 별도 파일로 분리해도 됩니다.
+- 중요한 것은 분리 여부보다 공통 route 정의를 기준으로 참조하는 구조를 유지하는 것입니다.
+
+## Why?
+
+- 메뉴와 breadcrumb는 결국 같은 경로 정보를 여러 방식으로 보여주는 경우가 많습니다.
+- 경로, 메뉴, breadcrumb가 따로 놀기 시작하면 수정 지점이 늘고 누락도 생깁니다.
+- 페이지와 컴포넌트는 “어디로 가는지”보다 “무엇을 렌더하는지”에 더 집중하는 편이 좋습니다.
+- 처음에는 한 파일로 두는 쪽이 단순하지만, 커졌을 때 `menu-config.ts`, `breadcrumb-config.ts`로 나누는 것은 자연스러운 확장입니다.
+
+## 예시 코드
+
+```ts
+// src/shared/routes/route.ts
+type BreadcrumbItem = {
+  label: string;
+  href?: string;
+};
+
+const isPath =
+  (path: string) =>
+  (pathname: string) =>
+    pathname === path;
+
+const isMatch =
+  (pattern: RegExp) =>
+  (pathname: string) =>
+    pattern.test(pathname);
+
+export const routes = {
+  home: {
+    label: '홈',
+    href: '/',
+    test: isPath('/'),
+  },
+  posts: {
+    label: '게시글',
+    href: '/posts',
+    test: isPath('/posts'),
+  },
+  postCreate: {
+    label: '글쓰기',
+    href: '/posts/new',
+    test: isPath('/posts/new'),
+  },
+  postDetail: {
+    label: '상세',
+    href: (id: string) => `/posts/${id}`,
+    test: isMatch(/^\/posts\/[^/]+$/),
+  },
+} as const;
+
+export const menuItems = [
+  { label: routes.home.label, href: routes.home.href },
+  { label: routes.posts.label, href: routes.posts.href },
+  { label: routes.postCreate.label, href: routes.postCreate.href },
+];
+
+const breadcrumbConfigs: {
+  test: (pathname: string) => boolean;
+  items: BreadcrumbItem[];
+}[] = [
+  {
+    test: routes.home.test,
+    items: [{ label: routes.home.label }],
+  },
+  {
+    test: routes.posts.test,
+    items: [
+      { label: routes.home.label, href: routes.home.href },
+      { label: routes.posts.label },
+    ],
+  },
+  {
+    test: routes.postCreate.test,
+    items: [
+      { label: routes.home.label, href: routes.home.href },
+      { label: routes.posts.label, href: routes.posts.href },
+      { label: routes.postCreate.label },
+    ],
+  },
+  {
+    test: routes.postDetail.test,
+    items: [
+      { label: routes.home.label, href: routes.home.href },
+      { label: routes.posts.label, href: routes.posts.href },
+      { label: routes.postDetail.label },
+    ],
+  },
+];
+
+export function getBreadcrumbItems(pathname: string) {
+  return breadcrumbConfigs.find((config) => config.test(pathname))?.items ?? [];
+}
+```
+
+```tsx
+// src/features/posts/components/post-actions.tsx
+'use client';
+
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+
+import { routes } from '@/shared/routes/route';
+
+export function PostActions({ id }: { id: string }) {
+  const router = useRouter();
+
+  return (
+    <div className="flex gap-3">
+      <Link href={routes.posts.href}>목록</Link>
+      <Link href={routes.postDetail.href(id)}>상세</Link>
+      <button type="button" onClick={() => router.push(routes.postCreate.href)}>
+        글쓰기
+      </button>
+    </div>
+  );
+}
+```
+
+```tsx
+// src/shared/ui/breadcrumb.tsx
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+
+import { getBreadcrumbItems } from '@/shared/routes/route';
+
+export function Breadcrumb() {
+  const pathname = usePathname();
+  const items = getBreadcrumbItems(pathname);
+
+  if (items.length === 0) return null;
+
+  return (
+    <nav aria-label="breadcrumb">
+      <ol className="flex items-center gap-2 text-sm text-zinc-500">
+        {items.map((item, index) => {
+          const isLast = index === items.length - 1;
+
+          return (
+            <li key={`${item.label}-${index}`} className="flex items-center gap-2">
+              {item.href && !isLast ? (
+                <Link href={item.href}>{item.label}</Link>
+              ) : (
+                <span>{item.label}</span>
+              )}
+              {!isLast ? <span>/</span> : null}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}
+```
+
+## 한 줄 요약
+
+route, menu, breadcrumb는 공통 정의를 중심으로 한 파일에서 관리하면 가장 덜 흩어집니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/10-/354/273/244/353/260/213-/354/273/250/353/262/244/354/205/230.md

@@ -0,0 +1,64 @@
+# 커밋 컨벤션
+
+## 원칙
+
+- 한 커밋에는 가능한 한 한 가지 목적만 담습니다.
+- 커밋 메시지는 `type: summary` 형식을 기본으로 사용합니다.
+- summary는 무엇이 바뀌는지 바로 보이게 짧고 명확하게 씁니다.
+- 의미 없는 메시지보다 변경 내용을 드러내는 메시지를 우선합니다.
+
+## Why?
+
+- 커밋 히스토리를 보면 어떤 종류의 변경인지 빠르게 파악할 수 있습니다.
+- 리뷰, 되돌리기, cherry-pick 같은 작업이 쉬워집니다.
+- 여러 목적이 섞인 커밋보다 맥락이 분명한 커밋이 유지보수에 유리합니다.
+
+## 기본 형식
+
+```text
+type: summary
+```
+
+필요하면 scope를 붙일 수 있습니다.
+
+```text
+type(scope): summary
+```
+
+## 타입 기준
+
+- `feat`: 사용자 기능 추가 또는 의미 있는 기능 변경
+- `fix`: 버그 수정
+- `refactor`: 동작 변화 없이 구조 개선
+- `docs`: 문서 추가 및 수정
+- `chore`: 설정, 스크립트, 의존성, 빌드 관련 작업
+- `test`: 테스트 추가 및 수정
+- `style`: 포맷팅, 정렬, 주석 같은 비기능 수정
+
+## 작성 기준
+
+- summary는 너무 길게 쓰지 않습니다.
+- `update`, `change`, `fix stuff` 같은 모호한 표현은 피합니다.
+- 마침표는 보통 붙이지 않습니다.
+- 여러 목적이 섞이면 커밋을 나누는 쪽을 먼저 검토합니다.
+
+## 예시 코드
+
+```text
+feat: 게시글 검색 필터 추가
+fix: 로그인 만료 시 무한 리다이렉트 수정
+refactor: posts query key 구조 정리
+docs: 라우트 정의 문서 추가
+chore: eslint 설정 정리
+test: post list query 테스트 추가
+```
+
+```text
+feat(posts): 게시글 작성 페이지 추가
+fix(auth): 토큰 만료 처리 수정
+refactor(shared): text input field 구조 정리
+```
+
+## 한 줄 요약
+
+커밋은 한 가지 목적만 담고, 메시지는 `type: summary` 형식으로 짧고 명확하게 씁니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/11-/352/270/260/355/203/200-/354/233/220/354/271/231.md

@@ -0,0 +1,187 @@
+# 기타 원칙
+
+## Layout 반응형 처리
+
+### 원칙
+
+- layout의 반응형 전환은 가능한 한 CSS와 responsive class로 처리합니다.
+- 화면 크기 자체를 JS state로 들고 있지 않습니다.
+- 사용자 인터랙션이 필요한 상태만 client state로 둡니다.
+- JS에서 브레이크포인트 판단이 꼭 필요하면 `resize` 이벤트를 직접 다루기보다 `useMediaQuery`나 `window.matchMedia` 기반 방식을 우선합니다.
+
+### Why?
+
+- 레이아웃 전환은 CSS가 더 단순하고 안정적으로 처리합니다.
+- `window.innerWidth`나 `resize` 이벤트를 직접 다루기 시작하면 코드가 불필요하게 무거워집니다.
+- 브레이크포인트 판단과 열림/닫힘 상태를 분리하면 책임이 깔끔해집니다.
+- media query 기반 방식은 의도가 더 분명하고, 구독/해제 로직도 직접 관리할 일이 줄어듭니다.
+
+### 예시 코드
+
+```tsx
+// src/app/(dashboard)/layout.tsx
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="min-h-screen lg:grid lg:grid-cols-[240px_1fr]">
+      <aside className="hidden border-r border-zinc-200 bg-white lg:block">
+        Sidebar
+      </aside>
+
+      <div className="min-w-0">
+        <header className="border-b border-zinc-200 bg-white px-4 py-3 lg:hidden">
+          Mobile Header
+        </header>
+        <main className="p-4 lg:p-8">{children}</main>
+      </div>
+    </div>
+  );
+}
+```
+
+```tsx
+// JS로 브레이크포인트 판단이 꼭 필요할 때
+const isDesktop = useMediaQuery('(min-width: 1024px)');
+```
+
+직접 `resize` 이벤트를 붙여 width를 상태로 관리하는 것보다, 이런 식의 media query 기반 접근이 보통 더 단순합니다.
+
+## Layout State 범위
+
+### 원칙
+
+- layout에는 공통 shell 제어 상태만 둡니다.
+- 모바일 사이드바 열림, 전역 검색창 열림 같은 상태는 둘 수 있습니다.
+- 페이지 전용 폼 상태나 feature 데이터는 layout에 두지 않습니다.
+
+### Why?
+
+- layout state가 많아지면 여러 페이지가 불필요하게 묶입니다.
+- 공통 껍데기 상태와 페이지 비즈니스 상태가 섞이면 수정 범위가 커집니다.
+- layout은 구조와 진입 제어에 집중할수록 유지보수가 쉽습니다.
+
+### 예시 코드
+
+```tsx
+// src/shared/ui/dashboard-shell.tsx
+'use client';
+
+import { useState } from 'react';
+
+export function DashboardShell({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const [isSidebarOpen, setIsSidebarOpen] = useState(false);
+
+  return (
+    <div className="min-h-screen">
+      <button
+        type="button"
+        className="lg:hidden"
+        onClick={() => setIsSidebarOpen((prev) => !prev)}
+      >
+        메뉴
+      </button>
+
+      {isSidebarOpen ? <aside>Mobile Sidebar</aside> : null}
+      <main>{children}</main>
+    </div>
+  );
+}
+```
+
+## 영역별 Provider 주입
+
+### 원칙
+
+- provider는 무조건 앱 루트에 올리지 않습니다.
+- 해당 라우트 그룹 전체에서 필요한 provider만 그 layout에서 주입합니다.
+- 전역 provider와 영역 전용 provider를 구분합니다.
+
+### Why?
+
+- 모든 provider를 루트에 올리면 앱 전체가 불필요하게 무거워집니다.
+- 어떤 영역에서만 필요한 컨텍스트인지 드러나야 코드 탐색이 쉬워집니다.
+- 공통 조건과 공통 주입을 layout에 모으면 페이지 코드가 단순해집니다.
+
+### 예시 코드
+
+```tsx
+// src/app/(dashboard)/layout.tsx
+import { redirect } from 'next/navigation';
+
+import { getCurrentUser } from '@/features/auth/api/get-current-user.server';
+import { DashboardShell } from '@/shared/ui/dashboard-shell';
+import { DashboardProvider } from '@/features/dashboard/providers/dashboard-provider';
+
+export default async function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const user = await getCurrentUser();
+
+  if (!user) {
+    redirect('/login');
+  }
+
+  return (
+    <DashboardProvider>
+      <DashboardShell>{children}</DashboardShell>
+    </DashboardProvider>
+  );
+}
+```
+
+## Props Drilling 기준
+
+### 원칙
+
+- props drilling은 무조건 나쁜 것으로 보지 않습니다.
+- 2~3단계 정도의 명확한 전달은 그냥 props로 두는 편이 더 단순합니다.
+- 중간 컴포넌트가 값을 쓰지 않는데 계속 전달만 한다면 구조를 다시 봅니다.
+
+### Why?
+
+- 얕고 명확한 props 전달은 가장 읽기 쉽고 추적하기 쉽습니다.
+- 작은 전달까지 모두 context나 store로 올리면 오히려 구조가 무거워질 수 있습니다.
+- 문제는 props 전달 자체보다 깊이와 불필요한 중계입니다.
+
+### 예시 코드
+
+```tsx
+// src/features/posts/components/post-page.tsx
+export function PostPage({
+  posts,
+  selectedPostId,
+}: {
+  posts: { id: string; title: string }[];
+  selectedPostId?: string;
+}) {
+  return <PostListSection posts={posts} selectedPostId={selectedPostId} />;
+}
+```
+
+```tsx
+// src/features/posts/components/post-list-section.tsx
+import { PostList } from '@/features/posts/components/post-list';
+
+export function PostListSection({
+  posts,
+  selectedPostId,
+}: {
+  posts: { id: string; title: string }[];
+  selectedPostId?: string;
+}) {
+  return <PostList posts={posts} selectedPostId={selectedPostId} />;
+}
+```
+
+## 한 줄 요약
+
+layout은 반응형은 CSS로, state는 shell 범위로, provider는 필요한 영역에서만 주입하고, 얕은 props 전달은 과하게 두려워하지 않는 쪽이 가장 깔끔합니다.