byuckchon-frontend-cli 1.7.0 → 1.9.0

package/README.md

@@ -156,6 +156,36 @@ bc › Auto layout 이 row 였고 padding 12/16 이었어요. MemberCard 만들
 > Figma 응답은 자동으로 압축됩니다 (자식 60개, 깊이 8 까지). 너무 큰 프레임은 더 작은
 > 자식 frame URL 을 줘서 분할 정복하세요.
 
+### 팀 컨벤션 문서(.md) 자동 주입 (v1.8+)
+
+FE 전반의 규칙(폴더 구조, 네이밍, 스웨거 → 코드 변환 규칙 등)을 `.md` 로 적어두면
+**매 chat 세션에 시스템 프롬프트로 자동 주입**됩니다. AI 는 기존 코드 패턴보다 이 문서를 우선합니다.
+
+**파일명은 고정이 아닙니다.** 아무 경로나 `bc.config.json` 의 `docs` 에 적으면 됩니다.
+적지 않으면 관례 파일명(`bc.md`, `.bc/conventions.md`, `AGENTS.md`, `FRONTEND.md`, `docs/frontend.md`)을 자동 탐지합니다.
+
+```json
+{
+  "docs": ["docs/fe-conventions.md", "docs/api-guide.md"]
+}
+```
+
+- 문서당 최대 24KB, 전체 48KB 까지 (토큰 폭발 방지). 헤더에 `docs` 줄로 로드된 파일이 표시됩니다.
+- (고급) 항목을 `{ "path": "...", "when": { "framework": "next" } }` 형태로 적으면 프레임워크별 조건부 주입도 가능합니다.
+
+#### API 코드 컨벤션 .md 자동 포함
+
+`bc init` / `bc adopt` 를 실행하면 **API 코드 생성 가이드(`api-codegen.md`)가 프레임워크에 맞는 위치에 자동으로 깔립니다.**
+
+| 프레임워크 | 위치 |
+| --- | --- |
+| React (Vite/CRA 등) | `src/api/api-codegen.md` |
+| Next.js | `lib/api/api-codegen.md` |
+
+- 이 파일은 `bc.config.json` 의 `docs` 에 자동 등록되어 **chat 시작 시 주입**됩니다.
+- 하나의 .md 로 React/Next 를 모두 다루며(차이는 위치뿐), 팀 규칙에 맞게 직접 다듬어 쓰면 됩니다.
+- 이미 파일이 있으면 덮어쓰지 않습니다.
+
 ### OpenAPI / 코드 컨텍스트 — 자동 주입 (v1.4+)
 
 `bc.config.json` 의 `api.openapi` 와 코드 인덱스는 **chat 시작할 때 알아서 준비됩니다.**

package/bin/index.js

@@ -28,7 +28,7 @@ const program = new Command();
 program
   .name('bc')
   .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
-  .version('1.7.0');
+  .version('1.9.0');
 
 program
   .command('init')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {
@@ -34,6 +34,7 @@
   "files": [
     "bin",
     "src",
+    "templates",
     "README.md"
   ],
   "keywords": [

package/src/commands/adopt.js

@@ -7,6 +7,10 @@ import inquirer from 'inquirer';
 import { detectProjectContext, summarizeContext } from '../context/detect.js';
 import { CONFIG_PATHS } from '../config/index.js';
 import { modelChoices, DEFAULT_MODEL_ID } from '../ai/models.js';
+import {
+  apiRootForFramework,
+  scaffoldApiConventionDoc,
+} from '../generators/apiConventionDoc.js';
 
 /**
  * `bc adopt`
@@ -119,6 +123,9 @@ export async function adoptCommand(opts = {}) {
       exclude: ['**/*.test.*', '**/__mocks__/**', 'node_modules/**', 'dist/**', '.next/**'],
       maxFiles: 20,
     },
+    docs: existing?.docs ?? [
+      path.posix.join(apiRootForFramework(ctx.framework), 'api-codegen.md'),
+    ],
     framework: ctx.framework,
     detected: {
       language: ctx.language,
@@ -136,7 +143,23 @@ export async function adoptCommand(opts = {}) {
   await fs.writeFile(targetFile, JSON.stringify(next, null, 2) + '\n', 'utf8');
 
   console.log(chalk.green(`\n  ✓ ${CONFIG_PATHS.projectFileName} 작성 완료.`));
-  console.log(chalk.dim(`    ${targetFile}\n`));
+  console.log(chalk.dim(`    ${targetFile}`));
+
+  // API 코드 컨벤션 .md 를 API 루트(src/api | lib/api)에 깐다 (이미 있으면 유지).
+  try {
+    const { relPath, written } = await scaffoldApiConventionDoc({
+      projectRoot: cwd,
+      framework: ctx.framework,
+    });
+    if (written) {
+      console.log(chalk.green(`  ✓ API 코드 컨벤션 문서 생성: ${relPath}`));
+    } else {
+      console.log(chalk.dim(`  API 코드 컨벤션 문서 유지: ${relPath} (이미 존재)`));
+    }
+  } catch {
+    /* 문서 스캐폴드 실패는 치명적이지 않음 */
+  }
+  console.log();
   console.log(chalk.dim('  다음:'));
   if (!process.env.ANTHROPIC_API_KEY) {
     console.log(chalk.dim('    bc config set-key anthropic    # API 키 등록'));

package/src/commands/chat.js

@@ -63,12 +63,37 @@ export async function chatCommand(opts = {}) {
     process.exit(1);
   }
 
-  const baseSystem = buildSystemPrompt({
+  let baseSystem = buildSystemPrompt({
     effective: cfg.effective,
     paths: cfg.paths,
     project: cfg.project,
   });
 
+  // 컨벤션 문서(.md) 자동 주입 — FE 전반 규칙, 스웨거→코드 변환 규칙 등.
+  // bc.config.json 의 docs:[...] 또는 bc.md/AGENTS.md 등 관례 파일을 읽는다.
+  let conventionFiles = [];
+  if (cfg.paths.projectFile) {
+    try {
+      const { loadConventionDocs } = await import('../context/conventions.js');
+      const projectRoot = path.dirname(cfg.paths.projectFile);
+      const conv = await loadConventionDocs({
+        projectRoot,
+        docs: cfg.effective.docs,
+        framework: cfg.project?.framework ?? cfg.project?.detected?.framework,
+      });
+      if (conv.text) {
+        conventionFiles = conv.files;
+        baseSystem +=
+          '\n\n---\n## 팀 컨벤션 문서 (반드시 우선 준수)\n' +
+          '아래는 이 프로젝트/팀의 프론트엔드 컨벤션이다. 코드 생성·수정 시 여기 규칙을 ' +
+          '기존 코드 패턴보다 우선 적용한다. 충돌하면 이 문서를 따른다.\n\n' +
+          conv.text;
+      }
+    } catch {
+      /* 문서 로딩 실패는 무시 */
+    }
+  }
+
   // OpenAPI 자동 주입 — bc.config.json 의 api.openapi 가 있으면 fetch 후 요약을
   // 시스템 프롬프트에 박는다. 1시간 캐시. 실패해도 chat 은 그대로 동작.
   let openapiInfo = null;
@@ -145,10 +170,10 @@ export async function chatCommand(opts = {}) {
   const isTTY = process.stdin.isTTY && process.stdout.isTTY;
   const wantPlain = opts.plain || cfg.global?.ui?.mode === 'plain';
   if (!isTTY || wantPlain) {
-    return runReadlineFallback({ cfg, resolved, system, session, openapiInfo });
+    return runReadlineFallback({ cfg, resolved, system, session, openapiInfo, conventionFiles });
   }
 
-  return runInkApp({ cfg, resolved, system, session, openapiInfo });
+  return runInkApp({ cfg, resolved, system, session, openapiInfo, conventionFiles });
 }
 
 async function printHistoryList() {
@@ -172,14 +197,14 @@ async function printHistoryList() {
 
 /* ───────────────────────── ink 모드 ───────────────────────── */
 
-async function runInkApp({ cfg, resolved, system, session, openapiInfo }) {
+async function runInkApp({ cfg, resolved, system, session, openapiInfo, conventionFiles = [] }) {
   // ink/React 는 무겁고 비-TTY 환경에서 import 만으로도 종종 문제 일으키므로
   // 여기서 늦게 import 한다 (--once / pipe 모드에 영향 없도록).
   const { render } = await import('ink');
   const { ChatApp } = await import('../ui/ChatApp.js');
   const React = (await import('react')).default;
 
-  const initialConfig = { ...cfg, system, openapiInfo };
+  const initialConfig = { ...cfg, system, openapiInfo, conventionFiles };
 
   const onSessionUpdate = async (messages) => {
     session.messages = messages;
@@ -247,7 +272,7 @@ async function runOnce({ cfg, resolved, system, prompt }) {
 
 /* ──────────────────── 비-TTY / --plain 폴백 ──────────────────── */
 
-async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo }) {
+async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo, conventionFiles = [] }) {
   const readline = await import('node:readline');
   const meter = new TokenMeter(resolved.meta, cfg.effective.limits);
 
@@ -259,6 +284,9 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       chalk.dim('  openapi: ' + openapiInfo.source + (openapiInfo.cached ? ' (cached)' : ' (live)')),
     );
   }
+  if (conventionFiles.length) {
+    console.log(chalk.dim('  컨벤션 문서: ' + conventionFiles.join(', ')));
+  }
   if (session?.messages?.length) {
     console.log(chalk.dim(`  세션: ${session.id} (${session.messages.length} turns 이어가기)`));
   }

package/src/config/index.js

@@ -65,6 +65,11 @@ const DEFAULT_PROJECT = {
     exclude: ['**/*.test.*', '**/__mocks__/**', 'node_modules/**', 'dist/**'],
     maxFiles: 20,
   },
+  /**
+   * FE 전반 컨벤션을 적은 .md 경로들. 매 chat 세션에 시스템 프롬프트로 주입된다.
+   * 비우면 bc.md / .bc/conventions.md / AGENTS.md 등을 자동 탐지.
+   */
+  docs: [],
   /** bc adopt 가 채워준다. systemPrompt 가 읽어 모델에 알린다. */
   framework: null,
   detected: null,
@@ -181,6 +186,7 @@ export async function loadEffectiveConfig(startDir = process.cwd()) {
       design: project.design,
       api: project.api,
       context: project.context,
+      docs: project.docs ?? [],
     },
   };
 }

package/src/context/conventions.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * 프로젝트의 "컨벤션 문서(.md)" 를 찾아 읽어서 시스템 프롬프트에 주입할 텍스트로 만든다.
+ *
+ * 우선순위:
+ *   1) bc.config.json 의 `docs: [...]` 에 명시된 항목 (순서대로)
+ *      - 항목은 문자열(경로) 이거나, 조건부 객체일 수 있다:
+ *        "docs/common.md"
+ *        { "path": "docs/api-codegen.md", "when": { "frameworkNot": "next" } }
+ *        { "path": "docs/api-next.md",    "when": { "framework": "next" } }
+ *      - when 의 framework / frameworkNot 는 문자열 또는 문자열 배열.
+ *   2) 명시가 없으면 프로젝트 루트의 관례적 파일명 자동 탐지
+ *      - bc.md, .bc/conventions.md, AGENTS.md, FRONTEND.md, docs/frontend.md
+ *
+ * 토큰 폭발 방지: 문서당 최대 bytes, 전체 합계 최대 bytes 로 컷.
+ */
+const AUTO_NAMES = [
+  'bc.md',
+  '.bc/conventions.md',
+  'AGENTS.md',
+  'FRONTEND.md',
+  'docs/frontend.md',
+  'docs/FRONTEND.md',
+];
+
+const PER_DOC_MAX = 24 * 1024;
+const TOTAL_MAX = 48 * 1024;
+
+async function readIfExists(abs) {
+  try {
+    const stat = await fs.stat(abs);
+    if (!stat.isFile()) return null;
+    let text = await fs.readFile(abs, 'utf8');
+    if (Buffer.byteLength(text, 'utf8') > PER_DOC_MAX) {
+      text = text.slice(0, PER_DOC_MAX) + '\n... (이하 생략 — 문서가 너무 깁니다)';
+    }
+    return text;
+  } catch {
+    return null;
+  }
+}
+
+function asArray(v) {
+  if (v == null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+/** docs 항목의 when 조건이 현재 framework 에 맞는지. */
+function matchesFramework(when, framework) {
+  if (!when || typeof when !== 'object') return true;
+  const fw = framework || 'unknown';
+
+  const only = asArray(when.framework);
+  if (only.length && !only.includes(fw)) return false;
+
+  const not = asArray(when.frameworkNot);
+  if (not.length && not.includes(fw)) return false;
+
+  return true;
+}
+
+/** docs 항목(문자열 | 객체)을 { path, when } 로 정규화. */
+function normalizeEntry(entry) {
+  if (typeof entry === 'string') return { path: entry, when: null };
+  if (entry && typeof entry === 'object' && typeof entry.path === 'string') {
+    return { path: entry.path, when: entry.when ?? null };
+  }
+  return null;
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot  bc.config.json 이 있는 디렉터리
+ * @param {Array<string|object>} [args.docs]  config 의 docs (문자열 또는 조건부 객체)
+ * @param {string} [args.framework]  detect.js 의 framework (조건부 docs 판별용)
+ * @returns {Promise<{ text: string|null, files: string[] }>}
+ */
+export async function loadConventionDocs({ projectRoot, docs, framework }) {
+  if (!projectRoot) return { text: null, files: [] };
+
+  const explicit = Array.isArray(docs) && docs.length > 0;
+  const rawEntries = explicit ? docs : AUTO_NAMES;
+
+  const entries = rawEntries
+    .map(normalizeEntry)
+    .filter(Boolean)
+    .filter((e) => matchesFramework(e.when, framework));
+
+  const collected = [];
+  const files = [];
+  let total = 0;
+
+  for (const { path: rel } of entries) {
+    const abs = path.resolve(projectRoot, rel);
+    // 루트 밖 경로는 무시 (안전)
+    const within = !path.relative(projectRoot, abs).startsWith('..');
+    if (!within) continue;
+
+    const content = await readIfExists(abs);
+    if (!content) continue;
+
+    const bytes = Buffer.byteLength(content, 'utf8');
+    if (total + bytes > TOTAL_MAX) break;
+    total += bytes;
+
+    files.push(rel);
+    collected.push(`### 문서: ${rel}\n${content}`);
+  }
+
+  if (collected.length === 0) return { text: null, files: [] };
+  return { text: collected.join('\n\n'), files };
+}

package/src/generators/apiConventionDoc.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATE_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../templates/conventions/api-codegen.md',
+);
+
+/**
+ * 프레임워크에 맞는 API 루트 폴더.
+ * - Next.js → lib/api
+ * - 그 외 React 계열 → src/api
+ */
+export function apiRootForFramework(framework) {
+  return framework === 'next' ? 'lib/api' : 'src/api';
+}
+
+/**
+ * API 코드 컨벤션 .md 를 프로젝트의 API 루트(`src/api` 또는 `lib/api`)에 깐다.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.framework   'react' | 'next' | detect.js 의 framework 값
+ * @param {boolean} [args.force]    이미 있으면 덮어쓸지
+ * @returns {Promise<{ relPath: string, written: boolean }>}
+ */
+export async function scaffoldApiConventionDoc({ projectRoot, framework, force = false }) {
+  const apiRoot = apiRootForFramework(framework);
+  const relPath = path.join(apiRoot, 'api-codegen.md');
+  const absPath = path.join(projectRoot, relPath);
+
+  let exists = false;
+  try {
+    await fs.access(absPath);
+    exists = true;
+  } catch {
+    /* not there */
+  }
+
+  if (exists && !force) {
+    return { relPath, written: false };
+  }
+
+  const template = await fs.readFile(TEMPLATE_PATH, 'utf8');
+  await fs.mkdir(path.dirname(absPath), { recursive: true });
+  await fs.writeFile(absPath, template, 'utf8');
+  return { relPath, written: true };
+}

package/src/generators/createBcConfig.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { apiRootForFramework } from './apiConventionDoc.js';
+
 /**
  * 새 프로젝트 루트에 `bc.config.json` 을 만든다.
  *
@@ -28,6 +30,8 @@ export async function createBcConfig(rootDir, config) {
       exclude: ['**/*.test.*', '**/__mocks__/**', 'node_modules/**', 'dist/**'],
       maxFiles: 20,
     },
+    // chat 시작 시 자동 주입되는 팀 컨벤션 문서. API 코드 가이드가 기본 포함.
+    docs: [path.posix.join(apiRootForFramework(config.framework), 'api-codegen.md')],
     framework: config.framework,
     // init 단계에선 사용자가 React/Next 중 골랐고 TS/Tailwind 가 항상 들어가니
     // 감지 결과를 미리 채워둔다 (bc adopt 의 detected 와 같은 모양).

package/src/generators/createProject.js

@@ -8,6 +8,7 @@ import { createBcConfig } from './createBcConfig.js';
 import { createFolders } from './createFolders.js';
 import { createPackageJson } from './createPackageJson.js';
 import { createReadme } from './createReadme.js';
+import { scaffoldApiConventionDoc } from './apiConventionDoc.js';
 
 const exec = promisify(execCallback);
 const BYUCKCHON_PACKAGES = [
@@ -25,6 +26,8 @@ export async function createProject(config) {
   await createPackageJson(rootDir, config);
   await createBaseFiles(rootDir, config);
   await createReadme(rootDir, config);
+  // API 코드 컨벤션 .md 를 프레임워크에 맞는 API 루트(src/api | lib/api)에 깐다.
+  await scaffoldApiConventionDoc({ projectRoot: rootDir, framework: config.framework });
   await createBcConfig(rootDir, config);
 
   // 최신 버전(latest 포함) 의존성을 실제로 설치해 lockfile까지 생성

package/src/ui/ChatApp.js

@@ -115,7 +115,7 @@ async function pasteClipboardImage() {
  * 슬래시 명령은 Input 컴포넌트의 onSubmit 에서 가로채서 처리.
  */
 
-function Header({ modelMeta, projectFile, gateway, ragOn, hasIndex, openapiInfo }) {
+function Header({ modelMeta, projectFile, gateway, ragOn, hasIndex, openapiInfo, conventionFiles }) {
   let ragLabel;
   if (!hasIndex) ragLabel = '(준비 중 — 자동 빌드 또는 /index)';
   else if (ragOn) ragLabel = 'on (관련 코드 자동 주입)';
@@ -167,6 +167,14 @@ function Header({ modelMeta, projectFile, gateway, ragOn, hasIndex, openapiInfo
           h(Text, null, openapiLabel),
         )
       : null,
+    conventionFiles?.length
+      ? h(
+          Box,
+          null,
+          h(Text, { dimColor: true }, 'docs     '),
+          h(Text, null, conventionFiles.join(', ')),
+        )
+      : null,
     gateway
       ? h(
           Box,
@@ -870,6 +878,7 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
       ragOn: ragEnabled,
       hasIndex,
       openapiInfo: cfg.openapiInfo,
+      conventionFiles: cfg.conventionFiles,
     }),
     h(
       Box,

package/templates/conventions/api-codegen.md

@@ -0,0 +1,400 @@
+# 📑 API 코드 생성 가이드 (for AI)
+
+> 이 문서는 **Swagger(OpenAPI) JSON 을 기반으로 API 코드를 생성**할 때 따라야 하는 컨벤션이다.
+> 사용자가 Swagger JSON(또는 엔드포인트)을 제공하면, AI 는 이 문서의 규칙에 맞춰
+> `api / zod / type / service / index` 파일을 생성한다.
+>
+> 스택: `@tanstack/react-query` + `axios`. **React / Next.js 공용**이며, 차이는 §0 의 "위치"뿐이다.
+
+---
+
+## ⛳ 사전 규칙 — 코드 짜기 전에
+
+1. **추측 금지.** Swagger 에 없는 필드/엔드포인트를 임의로 만들지 않는다.
+   스키마가 모호하면 기존 리소스 폴더(예: `user/`)를 먼저 `read_file` 로 확인하고,
+   그래도 불명확하면 사용자에게 한 번 묻는다.
+2. **기존 코드 우선.** 공용 유틸(`cacheConfig`, `queryKey`, `captureSentryError`, `metaSchema`,
+   `PaginationParams` 등)은 새로 만들지 말고 그대로 가져다 쓴다. import 경로가 확실치 않으면
+   `search_code` 로 실제 export 위치를 확인한다.
+3. **5파일 세트는 항상 함께.** `api / zod / type / service / index` 를 한 번에 생성한다.
+
+---
+
+## 0. 위치 & 폴더 구조 ⚠️ (React vs Next 차이는 여기뿐)
+
+API 코드의 **루트 위치는 프레임워크마다 다르다.**
+
+| 프레임워크 | API 루트 |
+| --- | --- |
+| **React** (Vite/CRA 등) | `src/api` |
+| **Next.js** | `lib/api` |
+
+> 그 외 폴더/파일 구조와 규칙은 **완전히 동일**하다. 아래 예시는 `src/api` 기준이며,
+> Next 면 `src/api` 를 `lib/api` 로 바꿔 읽으면 된다.
+
+리소스(도메인) 하나당 폴더 하나. 폴더명은 **소문자**(여러 단어는 kebab-case: `favorite-stores`).
+
+```
+src/api/                      # (Next: lib/api/)
+├── instance.ts               # axios 인스턴스 (interceptor 포함)
+├── index.ts                  # 모든 API 모듈 export
+└── user/                     # 리소스 폴더 (소문자)
+    ├── user.api.ts           # axios 호출 함수 (순수 함수)
+    ├── user.zod.ts           # 응답/요청 zod 스키마
+    ├── user.type.ts          # zod 로부터 추론한 타입 + 입력 타입
+    ├── user.service.ts       # react-query 훅 (use~) — 비즈니스 로직
+    └── index.ts              # 외부 노출 (service, type 만)
+```
+
+- 파일 prefix 는 폴더명과 같다 (`user/` → `user.api.ts`, `user.zod.ts` ...).
+- `RESOURCE` 상수는 `/api/<path>` 형태로 `.api.ts` 상단에 둔다.
+
+---
+
+## 1. 가장 먼저 — "next(무한스크롤)" 인지 판단하라
+
+> 여기서 말하는 "next" 는 **프레임워크 Next.js 가 아니라**, **커서 기반 무한스크롤 패턴**을 가리킨다.
+
+코드를 짜기 전에 **해당 엔드포인트가 커서 기반 무한스크롤 API 인지** 먼저 판단한다.
+
+### "next" 로 판단하는 기준 (아래 중 하나라도 해당하면 next)
+
+- 요청 파라미터에 `cursor`, `limit` (또는 `page`, `size` 등 페이지네이션 파라미터) 가 있다.
+- 응답 본문에 `items`(배열) + `meta`(`hasNextPage`, `nextCursor`) 구조가 있다.
+- "목록을 스크롤하며 더 불러오는" 리스트 조회 엔드포인트다.
+
+| 판단 | 사용 훅 | 참고 |
+| --- | --- | --- |
+| **next O** (무한스크롤) | `useInfiniteQuery` | [§5](#5-next무한스크롤-템플릿) |
+| **next X** (일반) | `useQuery` / `useMutation` | [§4](#4-일반next-x-템플릿) |
+
+> 단건 조회·생성·수정·삭제, 페이지네이션 없는 전체 목록은 모두 **next X (일반)**.
+
+---
+
+## 2. 각 파일 작성 규칙
+
+### 2-1. `user.api.ts` — 순수 호출 함수
+
+- `import baseInstance from '../instance';` 사용 (axios 인스턴스).
+- 함수는 `async`, 내부에서 `const { data } = await baseInstance.X(...)` 후 `return data;`.
+- 응답 본문이 없는 경우(`204 No Content`) 는 `return data` 생략 가능.
+- 쿼리스트링은 `{ params }`, path 파라미터는 템플릿 리터럴.
+- **여기서는 zod 파싱을 하지 않는다.** (파싱은 service 의 queryFn 책임)
+
+```ts
+import baseInstance from '../instance';
+
+const RESOURCE = '/api/user';
+
+export const getUserList = async () => {
+  const { data } = await baseInstance.get(RESOURCE);
+
+  return data;
+};
+
+export const getUser = async (userId: string) => {
+  const { data } = await baseInstance.get(`${RESOURCE}/${userId}`);
+
+  return data;
+};
+
+export const deleteUser = async (userId: string) => {
+  const { data } = await baseInstance.delete(`${RESOURCE}/${userId}`);
+
+  return data;
+};
+```
+
+### 2-2. `user.zod.ts` — 스키마
+
+- `import { z } from 'zod';`
+- **단일 아이템 스키마**(`userItemSchema`)를 먼저 정의하고, 리스트는 `z.array(...)` 로 조합한다.
+- 재사용 가능한 작은 스키마는 별도 `const` 로 분리.
+- Swagger 타입 → zod 매핑:
+  - `string` → `z.string()`, `integer/number` → `z.number()`, `boolean` → `z.boolean()`
+  - `nullable: true` → `.nullable()` / `required` 에 없으면 `.optional()` (둘 다면 `.nullable().optional()`)
+  - `enum` → `z.enum([...] as const)` (숫자 enum 은 `z.union([z.literal(1), ...])`)
+  - `format: date-time` → `z.string().datetime()` (값은 ISO 문자열 유지)
+  - 제약(min/max/length) 이 명시되면 반영
+- **`$ref` / `allOf` / `oneOf`**:
+  - `$ref` → 참조 대상 스키마를 먼저 정의 후 재사용
+  - `allOf` → `baseSchema.merge(extraSchema)` 또는 `.and(...)`
+  - `oneOf`/`anyOf` → `z.union([...])`, discriminator 있으면 `z.discriminatedUnion(...)`
+- **next 응답**은 공통 `metaSchema` 사용: `import { metaSchema } from '@/lib';`
+
+```ts
+import { z } from 'zod';
+
+export const userItemSchema = z.object({
+  userId: z.string(),
+  name: z.string(),
+  email: z.string().nullable(),
+  isActive: z.boolean(),
+});
+
+export const userListSchema = z.array(userItemSchema);
+```
+
+### 2-3. `user.type.ts` — 타입
+
+- 응답 타입은 **zod 스키마에서 추론**: `export type X = z.infer<typeof xSchema>;`
+- 입력(요청) 타입은 직접 정의. 인자가 2개 이상인 변경은 객체 입력 타입으로 묶는다.
+
+```ts
+import { z } from 'zod';
+import { userItemSchema } from './user.zod';
+
+export type UserItem = z.infer<typeof userItemSchema>;
+
+export type UpdateUser = {
+  userId: string;
+  name: string;
+};
+```
+
+### 2-4. `user.service.ts` — react-query 훅 (비즈니스 로직)
+
+공통 import:
+
+```ts
+import { cacheConfig, captureSentryError, queryKey } from '@/lib';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+```
+
+규칙:
+
+- 훅 이름: 조회 `useGetUser` / `useGetUserList`, 변경 `useCreateUser` / `useUpdateUser` / `useDeleteUser`.
+- **조회(useQuery)** 의 `queryFn` 에서 zod `safeParse` 로 검증.
+  - 실패 시 `console.error(...)` 후 **원본 `data` 그대로 반환**(throw 금지).
+  - 성공 시 `parsed.data` 반환.
+- **변경(useMutation)** 은 `onSuccess` 에서 관련 `queryKey` 를 `invalidateQueries`.
+- 모든 훅의 `onError` 에서 `captureSentryError(error, { location, action })`.
+  - `location` = 훅 이름(`'useDeleteUser'`), `action` = 호출 함수명(`'deleteUser'`).
+- 조회 훅은 마지막에 `...cacheConfig.<tier>` + `...options` 펼침.
+- 캐시 tier: 자주 바뀜 `realtime`/`shortLived`, 보통 `mediumLived`, 잘 안 바뀜 `longLived`, 불변 `immutable`.
+
+```ts
+export const useGetUserList = (options?: Record<string, any>) => {
+  return useQuery({
+    queryKey: queryKey.user.list,
+    queryFn: async () => {
+      const data = await getUserList();
+      const parsed = userListSchema.safeParse(data);
+
+      if (!parsed.success) {
+        console.error('User list validation error:', parsed.error);
+
+        return data;
+      }
+
+      return parsed.data;
+    },
+    ...cacheConfig.longLived,
+    ...options,
+  });
+};
+
+export const useDeleteUser = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (userId: string) => deleteUser(userId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKey.user.all });
+    },
+    onError: (error) => {
+      captureSentryError(error, { location: 'useDeleteUser', action: 'deleteUser' });
+    },
+  });
+};
+```
+
+### 2-5. `index.ts` (리소스) — 노출
+
+- **`service` 와 `type` 만** 재노출 (`api`, `zod` 는 노출하지 않음).
+
+```ts
+export * from './user.service';
+export * from './user.type';
+```
+
+### 2-6. `src/api/index.ts` (루트) — 모든 모듈 export
+
+- 새 리소스를 추가하면 한 줄 추가한다.
+
+```ts
+export * from './user';
+// export * from './order';
+```
+
+### 2-7. `src/api/instance.ts` — axios 인스턴스
+
+- 이미 있으면 **건드리지 않는다.** baseURL/interceptor 설정이 여기 모여 있다.
+- 새 리소스는 항상 이 `baseInstance` 를 import 해서 쓴다.
+
+---
+
+## 3. queryKey 등록 규칙
+
+공용 `queryKey` 객체에 리소스 항목을 추가한다.
+
+- `all` 은 무효화(invalidate) 기준 최상위 키. 변경 훅은 보통 `queryKey.<resource>.all` 무효화.
+- 하위 키는 `['<resource>', '<scope>']`. 파라미터가 들어가면 함수형으로.
+
+```ts
+user: Object.freeze({
+  all: ['user'],
+  list: ['user', 'list'],
+  detail: (id: string) => ['user', 'detail', id],
+}),
+```
+
+---
+
+## 4. 일반(next X) 템플릿
+
+```ts
+// api
+export const getUser = async (params?: SomeParams) => {
+  const { data } = await baseInstance.get(RESOURCE, { params });
+  return data;
+};
+
+// service
+export const useGetUser = (options?: Record<string, any>) => {
+  return useQuery({
+    queryKey: queryKey.user.list,
+    queryFn: async () => {
+      const data = await getUser();
+      const parsed = userSchema.safeParse(data);
+      if (!parsed.success) {
+        console.error('User validation error:', parsed.error);
+        return data;
+      }
+      return parsed.data;
+    },
+    ...cacheConfig.mediumLived,
+    ...options,
+  });
+};
+
+// 변경
+export const useCreateUser = () => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (payload: CreateUserPayload) => createUser(payload),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKey.user.all });
+    },
+    onError: (error) => {
+      captureSentryError(error, { location: 'useCreateUser', action: 'createUser' });
+    },
+  });
+};
+```
+
+> 인자가 2개 이상이면 객체로 묶어 `*.type.ts` 에 입력 타입을 정의하고 구조분해로 받는다.
+> 예: `mutationFn: ({ userId, name }: UpdateUser) => updateUser(userId, name)`
+
+---
+
+## 5. next(무한스크롤) 템플릿
+
+판단 결과가 **next** 일 때만 사용. 핵심은 `useInfiniteQuery` + 공통 `metaSchema`.
+
+```ts
+// api  (cursor 기반)
+import { PaginationParams } from '@/lib';
+
+export const getUser = async (params: PaginationParams) => {
+  const { data } = await baseInstance.get(RESOURCE, { params });
+  return data;
+};
+
+// zod  (items + meta)
+import { metaSchema } from '@/lib';
+
+export const userItemSchema = z.object({ /* ... */ });
+export const getUserResponseSchema = z.object({
+  items: z.array(userItemSchema),
+  meta: metaSchema, // { hasNextPage, nextCursor }
+});
+
+// type
+export type GetUserResponse = z.infer<typeof getUserResponseSchema>;
+
+// service
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+export const useGetUser = (options?: Record<string, any>) => {
+  const defaultParams: PaginationParams = { limit: 10, cursor: undefined };
+
+  return useInfiniteQuery<GetUserResponse, Error, GetUserResponse['items']>({
+    queryKey: queryKey.user.list,
+    queryFn: async ({ pageParam }) => {
+      const params: PaginationParams = { ...defaultParams, ...(pageParam || {}) };
+      const data = await getUser(params);
+      const parsed = getUserResponseSchema.safeParse(data);
+      if (!parsed.success) {
+        console.error('User validation error:', parsed.error);
+        return data;
+      }
+      return parsed.data;
+    },
+    getNextPageParam: (lastPage) =>
+      lastPage?.meta?.hasNextPage
+        ? { ...defaultParams, cursor: lastPage.meta.nextCursor }
+        : undefined,
+    select: (data) => data.pages.flatMap((page) => page?.items ?? []),
+    initialPageParam: defaultParams,
+    ...cacheConfig.longLived,
+    ...options,
+  });
+};
+```
+
+- `select` 로 `pages` 를 평탄화해 컴포넌트는 평평한 배열만 받는다.
+- `meta.hasNextPage` 가 falsy 면 `getNextPageParam` 은 `undefined`(다음 페이지 없음).
+
+---
+
+## 6. 네이밍 & 스타일 요약
+
+- 폴더: 소문자 / kebab-case (`user`, `favorite-stores`). 파일 prefix = 폴더명.
+- 함수: 동사 + 리소스 (`getUserList`, `createUser`, `updateUser`).
+- 훅: `use` + 함수 의미 (`useGetUserList`, `useCreateUser`).
+- `RESOURCE` 상수로 baseURL 경로 관리, 동적 경로는 템플릿 리터럴.
+- 조회는 zod 검증(실패 시 원본 반환), 변경은 invalidate + Sentry.
+- `index.ts` 는 service/type 만 노출, 루트 `index.ts` 에 리소스 한 줄 추가.
+- 들여쓰기 2칸, 세미콜론 사용, import 그룹: 외부 → `@/...` → 상대경로.
+
+---
+
+## 7. 생성 시 체크리스트 ✅
+
+1. [ ] 위치를 맞췄다 (React `src/api` / Next `lib/api`).
+2. [ ] 엔드포인트가 **next(무한스크롤)** 인지 판단했다. (§1)
+3. [ ] `api / zod / type / service / index` 5파일을 모두 만들었다.
+4. [ ] Swagger 응답을 zod 로 정확히 매핑(nullable/optional/enum/date/$ref).
+5. [ ] 타입은 `z.infer` 로 추론.
+6. [ ] 조회 훅 queryFn 에서 `safeParse` 후 실패 시 원본 반환.
+7. [ ] 변경 훅에 `invalidateQueries` + `captureSentryError`.
+8. [ ] `queryKey` 에 리소스 키(`all` 포함) 추가.
+9. [ ] 리소스 `index.ts` + 루트 `index.ts` 노출 추가.
+10. [ ] next 면 `useInfiniteQuery` + `metaSchema` + `select` 평탄화 적용.
+11. [ ] 공용 유틸을 재사용하고, Swagger 에 없는 필드를 추측으로 만들지 않았다.
+
+---
+
+## 8. 자주 하는 실수 (하지 말 것) 🚫
+
+- ❌ `*.api.ts` 에서 zod 파싱 (파싱은 service 의 queryFn 책임).
+- ❌ `index.ts` 에서 `api`/`zod` 노출 (service/type 만).
+- ❌ 조회 훅에서 검증 실패 시 throw (원본 반환이 규칙).
+- ❌ `captureSentryError` / `invalidateQueries` 누락.
+- ❌ Swagger 의 `nullable` 무시하고 필수로 선언.
+- ❌ 일반 목록인데 `useInfiniteQuery` 사용 (또는 그 반대).
+- ❌ 공용 타입/유틸(`metaSchema`, `PaginationParams`)을 중복 재정의.
+- ❌ React 인데 `lib/api`, Next 인데 `src/api` 에 만드는 위치 실수.