Merge remote-tracking branch 'origin/main' into feat/image-box-component-9

# Conflicts:
#	eslint.config.js
#	package.json
#	pnpm-lock.yaml

Author: KyeongJooni

.claude/decisions/README.md

@@ -19,22 +19,24 @@
 - 기존 규칙을 그대로 따르는 CRUD 구현
 - 한 번 쓰고 끝나는 페이지 내부 구현 세부사항
 
-## 파일명
+## 파일 위치와 이름
 
-```text
-NNN-short-title.md
-```
+실제 decision 문서는 `.claude/decisions/records/`에 `NNN-short-title.md` 형식으로 둡니다. `README.md`와 `template.md`는 `records/`에 넣지 않고 `.claude/decisions/` 최상위에 둡니다.
 
 예시:
 
 ```text
-001-admin-api-reference.md
-002-query-key-policy.md
-003-page-folder-boundary.md
+.claude/decisions/
+├── README.md
+├── template.md
+└── records/
+    ├── 001-admin-api-reference.md
+    ├── 002-query-key-policy.md
+    └── 003-page-folder-boundary.md
 ```
 
 ## 작성 형식
 
-새 decision은 `.claude/decisions/template.md`를 복사한 형식으로 작성합니다.
+새 decision은 `.claude/decisions/template.md`를 복사해 `.claude/decisions/records/`에 작성합니다.
 
 문서는 길게 쓰지 않습니다. 결정 이유, 버린 대안, 이후 수정자가 지켜야 할 점만 남깁니다.

.claude/decisions/records/001-storybook-component-review.md

@@ -0,0 +1,31 @@
+# 001. UI 컴포넌트 시각 검토는 Storybook + GitHub Pages 배포로 한다
+
+## 상태
+
+- Accepted
+
+## 맥락
+
+공통 컴포넌트(Sidebar, PageHeader, SegmentedControl, Button, Logo)와 도메인 카드 컴포넌트가 늘어나면서, 실제 라우팅 없이도 팀원이 UI를 눈으로 확인할 방법이 필요했다. 앱 내부에 임시 `playground` 라우트를 만드는 방법과 Storybook을 붙이는 방법을 검토했다.
+
+## 결정
+
+`storybook` + `@storybook/react-vite`(Vite 8 지원 확인됨)를 devDependency로 추가하고, `main` 브랜치 push 시 `.github/workflows/deploy-storybook.yml`이 GitHub Pages(`/makers-admin-fe/` 서브패스)에 정적 빌드를 배포한다.
+
+## 근거
+
+- 컴포넌트가 늘어나도 `ComponentName.stories.tsx`를 옆에 추가하는 것만으로 확장되고, 임시 라우트처럼 삭제를 깜빡할 위험이 없다.
+- 팀원이 앱을 로컬에서 띄우지 않고도 배포된 페이지에서 바로 확인 가능하다.
+- `storybook init`의 기본 `--features` 중 `test`(Vitest 브라우저 addon + Playwright 브라우저 바이너리)는 스코프 밖이라 제외하고 `docs`, `a11y`만 설치했다.
+
+## 대안
+
+- 앱 내부 `routes`/`playground` 라우트: 지금 당장은 더 빠르지만, 실제 라우팅에 임시 코드가 섞여 남을 위험이 있어 기각.
+- Storybook `test`/Chromatic 관련 addon: 컴포넌트 시각 확인이 목적이라 지금은 불필요, 필요해지면 별도로 추가.
+
+## 영향
+
+- 새 재사용 컴포넌트를 추가하면 `ComponentName.tsx` 옆에 `ComponentName.stories.tsx`를 함께 추가한다(테스트 파일과 동일한 co-location 관례).
+- `.storybook/main.ts`의 `viteFinal`이 `vite.config.ts`와 동일한 alias(`@`, `@api`, `@components`, `@hooks`, `@lib`, `@pages`)와 `@tailwindcss/vite` 플러그인을 그대로 반영한다 — `vite.config.ts`의 alias나 플러그인을 바꾸면 `.storybook/main.ts`도 함께 업데이트해야 한다.
+- `.storybook/preview.tsx`가 `src/index.css`를 import하므로, 전역 스타일/토큰 변경은 Storybook에도 자동 반영된다.
+- GitHub Pages 배포는 `STORYBOOK_BASE_PATH` 환경변수로 서브패스(`/makers-admin-fe/`)를 처리한다 — 저장소 이름이 바뀌면 `deploy-storybook.yml`의 값도 함께 바꿔야 한다.

.claude/decisions/records/002-component-per-folder.md

@@ -0,0 +1,29 @@
+# 002. 재사용 컴포넌트는 컴포넌트별 폴더로 관리한다
+
+## 상태
+
+- Accepted
+
+## 맥락
+
+`src/components/common`에 `Button.tsx`, `Button.test.tsx`, `Button.stories.tsx`처럼 컴포넌트당 파일이 3개씩 쌓이면서 평면 구조가 스캔하기 번거로워졌다.
+
+## 결정
+
+`src/components/{domain}/{ComponentName}/{ComponentName}.tsx` 형태로 컴포넌트별 폴더를 만들고, 같은 폴더에 `.test.tsx`/`.stories.tsx`를 co-locate한다. `scripts/gen-index.ts`를 재귀 구조로 바꿔 컴포넌트 폴더와 도메인 폴더 각각의 barrel `index.ts`를 자동 생성하게 했다.
+
+## 근거
+
+- 컴포넌트 하나당 관련 파일이 한 폴더에 모여 탐색이 쉬워진다.
+- `@components/common/Button` 같은 기존 alias 딥 임포트는 폴더+barrel 구조에서도 그대로 resolve되어, 외부에서 이 컴포넌트를 참조하던 코드는 수정할 필요가 없었다.
+- 같은 도메인 내 다른 컴포넌트를 참조할 때는 `../ComponentName` 상대 import를 쓴다(예: `PageHeader` → `Button`, `Sidebar` → `Logo`).
+
+## 대안
+
+- 평면 구조 유지: 파일 수가 적을 때는 문제 없지만, 컴포넌트마다 test/stories가 늘어나며 이미 스캔하기 어려워진 상태라 기각.
+
+## 영향
+
+- 새 재사용 컴포넌트를 추가할 때는 `common/Button/` 같은 컴포넌트 폴더부터 만든다. `.claude/rules/architecture.md`의 도메인 구조 예시 참고.
+- `src/components/common`, `introductions`, `projects` 전 도메인을 이 구조로 옮겼다. 새 도메인도 처음부터 이 구조로 만든다.
+- `pnpm gen:index` 실행 시 컴포넌트 폴더 depth와 무관하게 재귀적으로 barrel을 생성하므로, 이후 깊이가 더 깊어져도 스크립트 수정 없이 동작한다.

.claude/hooks/guard-rules.mjs

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs'
+
+let payload
+
+try {
+  payload = JSON.parse(readFileSync(0, 'utf8'))
+} catch {
+  process.exit(0)
+}
+
+const toolInput = payload.tool_input ?? {}
+const filePath = toolInput.file_path ?? ''
+const content = toolInput.new_string ?? toolInput.content ?? toolInput.command ?? ''
+
+const isCodeFile = /\.(ts|tsx|js|jsx)$/.test(filePath)
+
+if (isCodeFile && content.includes('console.log')) {
+  console.error('Avoid console.log. Use the project logging/debugging approach instead.')
+  process.exit(1)
+}
+
+if (isCodeFile && /:\s*any([^A-Za-z]|$)|<any>|as any/.test(content)) {
+  console.error('Avoid explicit any. Use a specific type or unknown.')
+  process.exit(1)
+}
+
+if (/(^|\s)(npm|yarn|npx)\s/.test(content)) {
+  console.error('Use pnpm (or pnpm exec/pnpm dlx) in this project.')
+  process.exit(1)
+}
+
+if (/tailwind\.config\./.test(filePath)) {
+  console.error('This is a Tailwind CSS v4 project. Do not create tailwind.config unless explicitly requested.')
+  process.exit(1)
+}

.claude/hooks/guard-rules.ps1

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+
+let payload
+
+try {
+  payload = JSON.parse(readFileSync(0, 'utf8'))
+} catch {
+  process.exit(0)
+}
+
+const filePath = payload.tool_input?.file_path ?? ''
+
+if (filePath && (filePath.endsWith('.ts') || filePath.endsWith('.tsx'))) {
+  try {
+    const output = execFileSync('pnpm', ['exec', 'eslint', '--quiet', filePath], {
+      encoding: 'utf8',
+      timeout: 30_000,
+    })
+    console.log(output.trimEnd().split('\n').slice(-5).join('\n'))
+  } catch (error) {
+    const output = `${error.stdout ?? ''}${error.stderr ?? ''}`
+    console.log(output.trimEnd().split('\n').slice(-5).join('\n'))
+  }
+}

.claude/hooks/lint-check.mjs

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs'
+
+let payload
+
+try {
+  payload = JSON.parse(readFileSync(0, 'utf8'))
+} catch {
+  process.exit(0)
+}
+
+const prompt = payload.prompt ?? ''
+
+if (!prompt) {
+  process.exit(0)
+}
+
+const lowerPrompt = prompt.toLowerCase()
+const suggestions = []
+
+const rules = [
+  [/commit|staged|push/, '/commit-kr - create a Korean commit message'],
+  [/\bpr\b|pull request/, '/create-pr - create a PR title and body draft'],
+  [/refactor|cleanup|dedupe|simplify/, '/refactor - analyze refactoring candidates'],
+  [/test|vitest|tdd|coverage/, '/gen-test - generate tests'],
+  [
+    /swagger|openapi|api generate|api client|api scaffold|admin api/,
+    '/scaffold-api - generate API functions and Query hooks',
+  ],
+  [/figma|design|screen|layout|component/, '/figma-to-component - implement a Figma-based component'],
+  [/review/, '/code-review - review changed code'],
+]
+
+for (const [pattern, suggestion] of rules) {
+  if (pattern.test(lowerPrompt)) {
+    suggestions.push(suggestion)
+  }
+}
+
+if (suggestions.length > 0) {
+  console.log('Suggested local skills:')
+  for (const suggestion of suggestions) {
+    console.log(`  ${suggestion}`)
+  }
+}

.claude/hooks/lint-check.ps1

@@ -0,0 +1,23 @@
+# Known Issues
+
+이 폴더는 우리가 지금 당장 고칠 수 없거나 우리 코드의 문제가 아닌, 외부 요인으로 발견된 이슈를 기록합니다.
+
+## 기록 대상
+
+- 디자인 시스템/외부 패키지의 값이 Figma나 스펙과 다른 경우
+- 서드파티 라이브러리 버그로 생긴 workaround
+- API 스펙과 실제 응답이 다른 경우
+- 우선순위가 낮아 지금은 미루는 알려진 성능/품질 이슈
+
+## 기록하지 않는 것
+
+- 우리 코드로 바로 고칠 수 있는 버그 (그냥 고친다)
+- 구조/라이브러리 선택 같은 결정 사항 (`.claude/decisions/`에 기록)
+
+## 파일 위치와 이름
+
+실제 이슈 문서는 `.claude/known-issues/records/`에 `short-title.md` 형식으로 둡니다. `README.md`와 `template.md`는 `records/`에 넣지 않고 `.claude/known-issues/` 최상위에 둡니다.
+
+## 작성 형식
+
+새 이슈는 `.claude/known-issues/template.md`를 복사해 `.claude/known-issues/records/`에 작성합니다.