byuckchon-frontend-cli 1.6.1 → 1.9.0

package/README.md

@@ -74,8 +74,11 @@ bc init
 | `read_file`   | 프로젝트 내 파일/디렉터리 내용 읽기                     |
 | `list_files`  | 글롭 패턴으로 파일 나열                                 |
 | `search_code` | RAG 인덱스 의미 기반 검색 (인덱스 있어야 함)             |
+| `search_openapi` | OpenAPI 스펙에서 엔드포인트 검색 (path/summary/tag) — 큰 스펙도 OK |
+| `get_openapi_endpoint` | 특정 엔드포인트 상세 (params/requestBody/responses, `$ref` 인라인) |
 | `write_file`  | 새 파일 생성 또는 통째 덮어쓰기                          |
 | `edit_file`   | 유일한 `old_string → new_string` 으로 부분 수정 (안전)  |
+| `fetch_figma` / `fetch_figma_image` / `fetch_figma_styles` | Figma 디자인/이미지/토큰 |
 
 모델은 한 턴 안에서 **최대 12 step** 까지 툴을 자유롭게 호출합니다. 일반적인 흐름:
 1. `list_files` 로 `src/api/` 구조 파악
@@ -153,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 시작할 때 알아서 준비됩니다.**
@@ -351,7 +384,8 @@ bc config set-ui ink                        # 풀 TUI 복귀
 - [x] v1.5.0 — 에이전트 모드 (read/list/search/write/edit 툴) — AI 가 실제 파일을 만든다
 - [x] v1.6.0 — Figma 툴 (fetch_figma / image / styles), 한글 IME 안정 plain 모드 (`bc config set-ui plain`)
 - [x] v1.6.1 — 툴 스키마 `jsonSchema()` 래핑 (`schema is not a function` 수정), plain 모드 이미지 첨부(`/image`·`/paste`) + iTerm2/kitty 인라인 썸네일
-- [ ] v1.7.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
+- [x] v1.7.0 — OpenAPI 검색 툴 (`search_openapi` / `get_openapi_endpoint`) — 큰 스펙(수백 엔드포인트)에서도 정확한 경로/스키마 조회. 요약도 path 당 1줄로 압축 + 한도 상향
+- [ ] v1.8.0 — write/edit 승인 게이트 (`y/n/v/q`), diff 미리보기
 - [ ] Phase 3c-2: Figma 실 fetch (URL → 노드 트리 → 컴포넌트 인텐트)
 - [ ] Phase 4: `bc gen component/page` (AST 편집 + 검증 루프), `/apply` diff 미리보기
 

package/bin/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.6.1",
+  "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/ai/tools.js

@@ -12,6 +12,8 @@ import {
 } from '../figma/api.js';
 import { simplifyFetchNodes } from '../figma/simplify.js';
 import { parseFigmaUrl } from '../figma/url.js';
+import { getCachedOpenApi } from '../openapi/cache.js';
+import { searchEndpoints, getEndpoint } from '../openapi/lookup.js';
 
 /**
  * Agentic chat 용 툴 정의.
@@ -27,9 +29,21 @@ import { parseFigmaUrl } from '../figma/url.js';
  *   const tools = buildTools({ projectRoot, effective, onEvent });
  *   streamText({ tools, stopWhen: stepCountIs(12), ... });
  */
-export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
+export function buildTools({ projectRoot, effective, onEvent = () => {}, openapiSource = null }) {
   const root = path.resolve(projectRoot);
 
+  // OpenAPI 스펙은 한 번만 로드해서 캐시 (큰 파일이라 반복 파싱 비쌈).
+  let _openapiDocPromise = null;
+  function loadOpenApiDoc() {
+    if (!openapiSource) return Promise.resolve(null);
+    if (!_openapiDocPromise) {
+      _openapiDocPromise = getCachedOpenApi(openapiSource)
+        .then((res) => res.doc ?? null)
+        .catch(() => null);
+    }
+    return _openapiDocPromise;
+  }
+
   function safePath(p) {
     if (!p || typeof p !== 'string') {
       throw new Error('path 가 비어있습니다');
@@ -171,6 +185,44 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
     return { ok: true, path: rel, action: 'edited' };
   }
 
+  // ─────────── OpenAPI 툴 ───────────
+
+  async function searchOpenApi({ query, limit = 40 }) {
+    const doc = await loadOpenApiDoc();
+    if (!doc) {
+      return {
+        ok: false,
+        error:
+          'OpenAPI 스펙을 불러올 수 없습니다. bc.config.json 의 api.openapi 가 올바른 JSON 스펙 URL 인지 확인하세요 ' +
+          '(NestJS 는 보통 /api/docs 가 아니라 /api/docs-json).',
+      };
+    }
+    const hits = searchEndpoints(doc, query, { limit });
+    return {
+      ok: true,
+      query,
+      count: hits.length,
+      endpoints: hits.map((e) => ({
+        method: e.method,
+        path: e.path,
+        summary: e.summary,
+        tags: e.tags,
+      })),
+      hint:
+        hits.length === 0
+          ? '매치 없음. 다른 키워드로 재시도하거나, query 를 비워 전체 목록을 받아 path 를 직접 고르세요.'
+          : '상세 스키마가 필요하면 get_openapi_endpoint(path, method) 를 호출하세요.',
+    };
+  }
+
+  async function getOpenApiEndpoint({ path: epPath, method }) {
+    const doc = await loadOpenApiDoc();
+    if (!doc) {
+      return { ok: false, error: 'OpenAPI 스펙을 불러올 수 없습니다.' };
+    }
+    return getEndpoint(doc, epPath, method);
+  }
+
   // ─────────── Figma 툴 ───────────
 
   async function fetchFigma({ url, depth = 4 }) {
@@ -295,6 +347,40 @@ export function buildTools({ projectRoot, effective, onEvent = () => {} }) {
       }),
       execute: searchCode,
     }),
+    search_openapi: tool({
+      description:
+        '연결된 OpenAPI(Swagger) 스펙에서 엔드포인트를 검색한다. path 일부("admin/inquiries"), ' +
+        '한글 summary("문의"), tag, operationId 어느 걸로도 검색 가능. ' +
+        'API 코드를 짜기 전에 반드시 이 툴로 정확한 경로/메서드를 먼저 확인할 것. ' +
+        '시스템 프롬프트의 요약은 잘려 있을 수 있으므로 "엔드포인트가 안 보인다" 싶으면 이 툴로 찾는다.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: '검색어 (path 일부/summary/tag). 비우면 전체 목록' },
+          limit: { type: 'number', default: 40 },
+        },
+        additionalProperties: false,
+      }),
+      execute: searchOpenApi,
+    }),
+    get_openapi_endpoint: tool({
+      description:
+        '특정 엔드포인트의 상세(parameters / requestBody / responses 스키마, $ref 인라인됨) 를 가져온다. ' +
+        'search_openapi 로 찾은 정확한 path 와 method 를 넘긴다. 이 결과로 zod 스키마/타입/요청 함수를 정확히 생성.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: '정확한 경로. 예: /api/admin/inquiries' },
+          method: {
+            type: 'string',
+            description: 'GET/POST/... 생략 시 해당 path 의 모든 메서드',
+          },
+        },
+        required: ['path'],
+        additionalProperties: false,
+      }),
+      execute: getOpenApiEndpoint,
+    }),
     write_file: tool({
       description:
         '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',

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;
@@ -86,11 +111,15 @@ export async function chatCommand(opts = {}) {
         };
         system =
           baseSystem +
-          '\n\n---\nOpenAPI 스펙 (자동 주입됨, 사용자가 별도로 명령 없이 알아서 사용 가능):\n' +
+          '\n\n---\nOpenAPI 스펙 개요 (아래 목록은 길면 잘려 있을 수 있음):\n' +
           summary +
-          '\n\n사용자가 API 관련 코드를 요청하면 위 스펙을 우선 참조하라. ' +
-          '응답 타입이 필요하면 \`bc gen api-types\` 실행을 권하거나, ' +
-          '이미 \`*.gen.ts\` 가 있으면 그걸 import 해서 쓰라고 안내한다.';
+          '\n\n**중요**: 위 목록은 일부만 보일 수 있다. 사용자가 특정 엔드포인트를 말하거나 ' +
+          '위 목록에서 안 보이면, 추측하지 말고 반드시 `search_openapi(query)` 로 정확한 ' +
+          'path/method 를 검색한 뒤 `get_openapi_endpoint(path, method)` 로 상세 스키마를 ' +
+          '가져와서 zod/타입/요청 함수를 만든다. ' +
+          '예: 사용자가 "inquiries" 라고 하면 search_openapi("inquiries") 로 ' +
+          '`/api/admin/inquiries` 같은 실제 경로를 찾아낸다. ' +
+          '이미 `*.gen.ts` 가 있으면 그걸 import 해서 쓰는 것도 좋다.';
       }
     } catch {
       /* 비정상 URL/네트워크 실패 — 무시하고 계속. */
@@ -141,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() {
@@ -168,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;
@@ -204,6 +233,7 @@ async function runOnce({ cfg, resolved, system, prompt }) {
   const tools = buildTools({
     projectRoot,
     effective: cfg.effective,
+    openapiSource: cfg.effective.api?.openapi ?? null,
     onEvent: (ev) => {
       const label =
         ev.kind === 'write_created'
@@ -242,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);
 
@@ -254,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 이어가기)`));
   }
@@ -378,6 +411,7 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
     const tools = buildTools({
       projectRoot,
       effective: cfg.effective,
+      openapiSource: cfg.effective.api?.openapi ?? null,
       onEvent: (ev) => {
         const label =
           ev.kind === 'write_created'

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/openapi/lookup.js

@@ -0,0 +1,135 @@
+/**
+ * OpenAPI 스펙을 "쿼리" 하는 헬퍼.
+ *
+ * 큰 스펙(수백 개 엔드포인트, 수백 KB) 은 시스템 프롬프트 요약에 다 담을 수도 없고,
+ * 캐시 파일을 통째로 모델에 읽힐 수도 없다(토큰 폭발). 그래서 모델이 필요한 부분만
+ * 골라 가져갈 수 있게 검색/상세조회 함수를 제공한다.
+ *
+ * - searchEndpoints: path/summary/tag/operationId 부분일치로 후보 나열
+ * - getEndpoint:    특정 path(+method) 의 상세를 $ref 해석해서 반환
+ */
+const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+
+/** "#/components/schemas/Foo" → doc.components.schemas.Foo */
+function resolveRef(doc, ref, seen = new Set()) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) return null;
+  const parts = ref.slice(2).split('/');
+  let cur = doc;
+  for (const p of parts) {
+    if (cur == null) return null;
+    cur = cur[p];
+  }
+  return cur ?? null;
+}
+
+/**
+ * 객체 안의 $ref 를 재귀적으로 해석해 인라인한다.
+ * 깊이/순환 방지: maxDepth, seen(ref 경로) 로 컷.
+ */
+function deref(doc, node, { maxDepth = 6, depth = 0, seen = new Set() } = {}) {
+  if (node == null || typeof node !== 'object') return node;
+  if (depth > maxDepth) return node;
+
+  if (node.$ref) {
+    if (seen.has(node.$ref)) return { $ref: node.$ref, note: '(순환 참조 생략)' };
+    const target = resolveRef(doc, node.$ref);
+    if (!target) return node;
+    const nextSeen = new Set(seen);
+    nextSeen.add(node.$ref);
+    return deref(doc, target, { maxDepth, depth: depth + 1, seen: nextSeen });
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((n) => deref(doc, n, { maxDepth, depth: depth + 1, seen }));
+  }
+
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    out[k] = deref(doc, v, { maxDepth, depth: depth + 1, seen });
+  }
+  return out;
+}
+
+/** 모든 엔드포인트의 가벼운 인덱스 (path, method, summary, tags, operationId). */
+export function listEndpoints(doc) {
+  const out = [];
+  for (const [pathStr, methods] of Object.entries(doc?.paths ?? {})) {
+    if (!methods || typeof methods !== 'object') continue;
+    for (const m of METHODS) {
+      const op = methods[m];
+      if (!op || typeof op !== 'object') continue;
+      out.push({
+        method: m.toUpperCase(),
+        path: pathStr,
+        summary: op.summary ?? '',
+        operationId: op.operationId ?? '',
+        tags: op.tags ?? [],
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 부분일치 검색. query 의 각 토큰이 path/summary/operationId/tag 어딘가에
+ * (대소문자 무시) 들어가면 매치. 점수 = 매치한 필드 수 + path 정확 포함 가산점.
+ */
+export function searchEndpoints(doc, query, { limit = 40 } = {}) {
+  const all = listEndpoints(doc);
+  if (!query || !query.trim()) return all.slice(0, limit);
+
+  const tokens = query.toLowerCase().split(/[\s/]+/).filter(Boolean);
+  const scored = [];
+  for (const e of all) {
+    const hay = [
+      e.path.toLowerCase(),
+      e.summary.toLowerCase(),
+      e.operationId.toLowerCase(),
+      e.tags.join(' ').toLowerCase(),
+    ];
+    let score = 0;
+    for (const tok of tokens) {
+      if (hay[0].includes(tok)) score += 3; // path 매치 가중
+      else if (hay.some((h) => h.includes(tok))) score += 1;
+    }
+    if (e.path.toLowerCase().includes(query.toLowerCase())) score += 2;
+    if (score > 0) scored.push({ ...e, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  return scored.slice(0, limit);
+}
+
+/**
+ * 특정 path(+method) 의 상세. $ref 를 인라인해서 request/response 스키마까지 본다.
+ * method 생략 시 그 path 의 모든 메서드 반환.
+ */
+export function getEndpoint(doc, targetPath, method) {
+  const methods = doc?.paths?.[targetPath];
+  if (!methods) {
+    // 끝 슬래시/대소문자 보정 한 번 시도
+    const found = Object.keys(doc?.paths ?? {}).find(
+      (p) => p.toLowerCase() === String(targetPath).toLowerCase(),
+    );
+    if (!found) return { ok: false, error: `해당 path 없음: ${targetPath}` };
+    targetPath = found;
+  }
+  const pathItem = doc.paths[targetPath];
+  const wanted = method ? [method.toLowerCase()] : METHODS;
+  const operations = {};
+  for (const m of wanted) {
+    const op = pathItem[m];
+    if (!op) continue;
+    operations[m.toUpperCase()] = {
+      summary: op.summary,
+      operationId: op.operationId,
+      tags: op.tags,
+      parameters: deref(doc, op.parameters),
+      requestBody: deref(doc, op.requestBody),
+      responses: deref(doc, op.responses),
+    };
+  }
+  if (Object.keys(operations).length === 0) {
+    return { ok: false, error: `${targetPath} 에 ${method ?? ''} 메서드 없음` };
+  }
+  return { ok: true, path: targetPath, operations };
+}

package/src/openapi/summary.js

@@ -14,8 +14,8 @@
  *     ...
  */
 const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
-const MAX_ENDPOINTS = 200;
-const MAX_BYTES = 8 * 1024;
+const MAX_PATHS = 400;
+const MAX_BYTES = 16 * 1024;
 
 export function summarizeOpenApi(doc) {
   if (!doc || typeof doc !== 'object') return null;
@@ -30,46 +30,42 @@ export function summarizeOpenApi(doc) {
     lines.push(`base: ${servers.slice(0, 3).join(', ')}`);
   }
 
-  const endpoints = [];
+  // path 하나당 한 줄로 메서드를 합친다 (줄 수 절반 + 모델이 path 단위로 보기 쉬움).
+  const byPath = [];
   for (const [pathStr, methods] of Object.entries(doc.paths ?? {})) {
     if (!methods || typeof methods !== 'object') continue;
-    for (const m of METHODS) {
-      const op = methods[m];
-      if (!op || typeof op !== 'object') continue;
-      const desc = op.summary || op.operationId || op.description || '';
-      endpoints.push({
-        method: m.toUpperCase(),
-        path: pathStr,
-        desc: desc.split('\n')[0].slice(0, 90),
-      });
-    }
+    const verbs = METHODS.filter((m) => methods[m] && typeof methods[m] === 'object').map((m) =>
+      m.toUpperCase(),
+    );
+    if (verbs.length === 0) continue;
+    byPath.push({ path: pathStr, verbs });
   }
+  byPath.sort((a, b) => a.path.localeCompare(b.path));
 
-  // 너무 많으면 자른다 — 모델이 알아야 하는 건 "어떤 종류의 엔드포인트가 있다" 정도면 충분.
-  const total = endpoints.length;
-  const shown = endpoints.slice(0, MAX_ENDPOINTS);
+  const total = byPath.length;
+  const shown = byPath.slice(0, MAX_PATHS);
 
-  lines.push(`endpoints: (${shown.length}/${total})`);
+  lines.push(`paths: (${shown.length}/${total})`);
   for (const e of shown) {
-    lines.push(`  ${e.method.padEnd(6)} ${e.path}${e.desc ? '  -- ' + e.desc : ''}`);
+    lines.push(`  ${e.verbs.join(',').padEnd(20)} ${e.path}`);
   }
   if (shown.length < total) {
-    lines.push(`  ... and ${total - shown.length} more`);
+    lines.push(`  ... and ${total - shown.length} more (search_openapi 로 검색하세요)`);
   }
 
   let result = lines.join('\n');
+  // 바이트 초과 시 뒤에서부터 잘라낸다 (search_openapi 가 있으니 전부 못 담아도 안전).
   if (Buffer.byteLength(result, 'utf8') > MAX_BYTES) {
-    // 안전 장치 — desc 다 자르고 다시.
-    const compact = [
-      lines[0],
-      servers.length ? lines[1] : null,
-      `endpoints: (${shown.length}/${total})`,
-      ...shown.map((e) => `  ${e.method.padEnd(6)} ${e.path}`),
-      shown.length < total ? `  ... and ${total - shown.length} more` : null,
-    ]
-      .filter(Boolean)
-      .join('\n');
-    result = compact;
+    const header = [lines[0], servers.length ? lines[1] : null].filter(Boolean);
+    const out = [...header, `paths: (truncated/${total}) — 전체는 search_openapi 로 검색`];
+    let bytes = Buffer.byteLength(out.join('\n'), 'utf8');
+    for (const e of shown) {
+      const line = `  ${e.verbs.join(',').padEnd(20)} ${e.path}`;
+      bytes += Buffer.byteLength(line + '\n', 'utf8');
+      if (bytes > MAX_BYTES) break;
+      out.push(line);
+    }
+    result = out.join('\n');
   }
   return result;
 }

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,
@@ -731,6 +739,7 @@ export function ChatApp({ initialConfig, initialResolved, session, onSessionUpda
       const tools = buildTools({
         projectRoot,
         effective: cfg.effective,
+        openapiSource: cfg.effective.api?.openapi ?? null,
         onEvent: onToolEvent,
       });
 
@@ -869,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` 에 만드는 위치 실수.