sh-ui-cli 0.93.0 → 0.95.0

package/data/changelog/versions.json

@@ -2,6 +2,32 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.95.0",
+      "date": "2026-05-15",
+      "title": "MCP describe_template 옵션 누락 fix + staleness 경고 — 외부 AI 가 stale MCP 알아채게",
+      "type": "minor",
+      "highlights": [
+        "**`sh_ui_describe_template` 가 tauri/i18n/locales/observability 받음** — describeTemplate 자체는 옵션을 처리하지만 MCP 핸들러의 inputSchema 에 누락되어 외부 AI 가 옵션을 명시해도 무시됐다. preview 가 항상 기본 파일만 나열되던 회귀 (#3) 해결. create_project ↔ describe_template 파일 plan 1:1 일치 보장.",
+        "**MCP staleness 경고 자동 prepend** — 서버 start 시 https://registry.npmjs.org/sh-ui-cli/latest 비동기 조회 (3s timeout). 현재 버전보다 latest 가 높으면 모든 tool 응답 상단에 `⚠ sh-ui MCP X.Y.Z (latest: …)` 한 줄 prepend. 외부 AI 가 stale MCP 를 정상 출력으로 오해하던 회귀 (#8) 차단. 오프라인 / DNS 실패는 조용히 skip — best-effort.",
+        "**`SH_UI_SKIP_STALENESS_CHECK=1` 옵트아웃** — CI / 오프라인 / 사용자가 경고 끄고 싶을 때 env var 한 줄. test runner 가 외부 fetch 없이 결정적으로 돌게 함."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.95.0"
+    },
+    {
+      "version": "0.94.0",
+      "date": "2026-05-15",
+      "title": "vite 스캐폴드 P0 fix 묶음 — i18n locale 자동 미러 / monorepo .gitignore / CLAUDE.md platform 분기",
+      "type": "minor",
+      "highlights": [
+        "**`--i18n` 시 vite-plugin-static-copy 자동 셋업** — emitI18n 이 `vite-plugin-static-copy` (devDeps) + `vite.config.ts` 의 plugins 배열 패치를 자동 처리. 사용자가 손으로 plugin 추가하지 않아도 dev/build 양쪽에서 `src/shared/i18n/locales/*` (또는 `src/lib/i18n/locales/*`) 가 `public/locales/*` 로 미러되어 `/locales/{{lng}}/{{ns}}.json` 404 없음. Tauri prod 빌드도 dist 에 자동 포함.",
+        "**Locale seed 콘텐츠 언어별 정합화** — ko = `{greeting: '안녕하세요', app_title: 'sh-ui 앱'}`, en = `{greeting: 'Hello', app_title: 'sh-ui app'}`, 그 외 locale 도 영어 placeholder 시드를 받아 translator 가 채울 키가 즉시 보임. 이전엔 fallback (보통 ko) 에만 영어 시드 + 나머지 빈 객체였음.",
+        "**monorepo `apps/<name>/gitignore` 도 dot-prefix** — finalizeProject 가 root 만 처리하던 동작을 recursive 로 변경. vite-app 처럼 sub-app 에 자체 gitignore 가 있는 케이스에서 점 없는 파일이 남아 node_modules / dist 가 git staged 될 위험 제거. 회귀 가드 smoke 추가.",
+        "**CLAUDE.md `{{PLATFORM_APP_DESCRIPTION}}` 분기** — monorepo CLAUDE.md 가 `apps/<name>` 을 'Next.js 앱' 으로 hardcode 하던 문제 해결. `--platform vite` 면 'Vite SPA' + Tauri 옵션 시 추가 문장이 자동 치환되어 AI 에이전트가 잘못된 컨벤션 (App Router/RSC) 으로 코드를 작성하는 회귀 차단.",
+        "**mes arch 옵션 docs 명시** — monorepo / nextjs-standalone CLAUDE.md 에 `--arch` 옵션 (`fsd` / `flat` / `mes`) 섹션 추가. 외부 에이전트가 `packages/eslint-config/mes.js` 를 deprecated 잔재로 오해하던 문제 해결 — mes 는 MES(Backoffice) 전용 별도 arch, 모두 emit 되는 건 라이브러리 형태이기 때문."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.94.0"
+    },
     {
       "version": "0.93.0",
       "date": "2026-05-14",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.93.0",
+  "version": "0.95.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/src/create/architectures/index.js

@@ -39,6 +39,21 @@ export function getArchesForPlatform(platform) {
   return allArchitectures.filter((a) => a.platforms.includes(platform));
 }
 
+/**
+ * MCP tool description / CLI --help / docs 어디서나 재사용 가능한 arch 설명 블록.
+ * "fsd (FSD) — ..., flat (Flat) — ..., mes (MES) — ..." 처럼 사람-읽기 좋은 한 줄로 직렬화.
+ *
+ * 외부 AI 에이전트 (Cursor / Codex / Copilot 등) 는 CLAUDE.md 를 읽지 않으므로
+ * MCP schema description 에 각 arch 의 의미를 노출해야 mes 같은 도메인-특화 arch
+ * 를 deprecated 잔재로 오해하지 않는다 (v0.94.0+).
+ */
+export function describeArchOptions(platformFilter) {
+  const arches = platformFilter ? getArchesForPlatform(platformFilter) : allArchitectures;
+  return arches
+    .map((a) => `${a.name} (${a.label}) — ${a.description}`)
+    .join(' | ');
+}
+
 /**
  * 주어진 arch 가 platform 과 호환되는지 검증. 호환 안 되면 친절한 에러.
  * generator/cli-args 양쪽에서 호출.

package/src/create/generator.js

@@ -1046,9 +1046,9 @@ import HttpBackend from 'i18next-http-backend';
 import { initReactI18next } from 'react-i18next';
 
 // 클라이언트 측 lazy-load — 빌드 산출물에서 public/locales/{lng}/{ns}.json 경로로 fetch.
-// dev 에선 vite 가 ${i18nDirRel}/locales/* 를 /locales 로 serve (vite.config 의 publicDir 기본 'public').
-// 프로덕션 빌드 시 사용자가 vite-plugin-static-copy 등으로 public/locales 로 카피하거나
-// 처음부터 public/locales 에 두면 됨. 디폴트 경로 ${i18nDirRel}/locales 는 dev 편의용.
+// 원본 locale 파일은 ${i18nDirRel}/locales/* 에 두고, vite-plugin-static-copy 가
+// dev/build 양쪽에서 public/locales/* 로 자동 미러링한다 (vite.config.ts 참고).
+// Tauri 빌드의 경우도 dist/locales 에 그대로 포함된다.
 
 i18n
   .use(HttpBackend)
@@ -1078,12 +1078,17 @@ export default i18n;
     `export { default } from './config';\n`,
   );
 
+  // locale 별 시드 — 같은 key 를 모든 locale 에 emit (translator 가 무엇을 채워야 하는지 즉시 보임).
+  // 핵심 locale (ko, en) 만 사람-언어 값, 그 외 locale 은 영어 placeholder.
+  const seedByLocale = {
+    ko: { greeting: '안녕하세요', app_title: 'sh-ui 앱' },
+    en: { greeting: 'Hello', app_title: 'sh-ui app' },
+  };
+  const fallbackSeed = { greeting: 'Hello', app_title: 'sh-ui app' };
   for (const lng of locales) {
     const localeDir = path.join(i18nDir, 'locales', lng);
     await fs.ensureDir(localeDir);
-    const seed = lng === fallbackLng
-      ? { greeting: 'Hello World', app_title: 'sh-ui app' }
-      : {};
+    const seed = seedByLocale[lng] ?? fallbackSeed;
     await fs.writeFile(
       path.join(localeDir, 'common.json'),
       JSON.stringify(seed, null, 2) + '\n',
@@ -1130,7 +1135,56 @@ export function GlobalProvider({ children }: { children: ReactNode }) {
   pkg.dependencies['i18next-http-backend'] = '^2.7.1';
   pkg.dependencies['react-i18next'] = '^15.1.0';
   pkg.dependencies = sortObjectKeys(pkg.dependencies);
+  pkg.devDependencies = pkg.devDependencies ?? {};
+  // dev/build 양쪽에서 src/shared/i18n/locales/* (또는 src/lib/i18n/locales/*) 를
+  // public/locales/* 로 자동 미러 → i18next-http-backend 의 /locales/{{lng}}/{{ns}}.json 이 동작.
+  pkg.devDependencies['vite-plugin-static-copy'] = '^2.2.0';
+  pkg.devDependencies = sortObjectKeys(pkg.devDependencies);
   await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+
+  // vite.config.ts 에 vite-plugin-static-copy 삽입.
+  await patchViteConfigForI18n(targetDir, { i18nDirRel });
+}
+
+/**
+ * vite.config.ts 의 plugins 배열에 vite-plugin-static-copy 호출을 삽입한다.
+ * i18n 의 locale 파일 (src/shared/i18n/locales/* 등) 을 public/locales/* 로 자동 미러.
+ *
+ * 이미 같은 호출이 있으면 no-op. parsing 실패하면 사용자에게 수동 작업을 알리고 abort 하지 않는다.
+ */
+async function patchViteConfigForI18n(targetDir, { i18nDirRel }) {
+  const viteConfigPath = path.join(targetDir, 'vite.config.ts');
+  if (!(await fs.pathExists(viteConfigPath))) return;
+  let src = await fs.readFile(viteConfigPath, 'utf-8');
+
+  if (src.includes('vite-plugin-static-copy')) {
+    return; // 이미 셋업됨 (재진입 안전).
+  }
+
+  const importLine = `import { viteStaticCopy } from 'vite-plugin-static-copy';`;
+  // 다른 import 블록 뒤에 삽입.
+  const lastImportIdx = src.lastIndexOf('import ');
+  const insertImportAt = src.indexOf('\n', lastImportIdx) + 1;
+  src = src.slice(0, insertImportAt) + importLine + '\n' + src.slice(insertImportAt);
+
+  const pluginCall = `    viteStaticCopy({
+      // i18n locale 파일을 public/locales 로 미러 — i18next-http-backend 의 loadPath 와 매칭.
+      targets: [
+        { src: '${i18nDirRel}/locales/*', dest: 'locales' },
+      ],
+    }),`;
+
+  // plugins: [ ... ] 의 시작 직후에 새 plugin 삽입.
+  const pluginsMatch = src.match(/plugins:\s*\[/);
+  if (pluginsMatch) {
+    const insertAt = pluginsMatch.index + pluginsMatch[0].length;
+    src = src.slice(0, insertAt) + '\n' + pluginCall + src.slice(insertAt);
+  } else {
+    // 형태가 예상과 다르면 패치 포기 — config 가 깨지지 않도록.
+    return;
+  }
+
+  await fs.writeFile(viteConfigPath, src);
 }
 
 /**
@@ -1331,6 +1385,11 @@ async function generateMonorepo(targetDir, projectName, plugins, { yes = false,
   rootPkg.name = projectName;
   await fs.writeJson(rootPkgPath, rootPkg, { spaces: 2 });
 
+  // CLAUDE.md 의 platform 분기 placeholder 치환. AI 에이전트가 Next.js 가정으로
+  // 잘못된 컨벤션을 적용하지 않도록 (v0.94.0+).
+  const platformAppDesc = describeAppPlatform(platform, { tauri });
+  await replaceInAllFiles(targetDir, '{{PLATFORM_APP_DESCRIPTION}}', platformAppDesc);
+
   // Update turbo.json
   const turboPath = path.join(targetDir, 'turbo.json');
   const turbo = await fs.readJson(turboPath);
@@ -2149,11 +2208,9 @@ function buildErrorModuleCss() {
  * git init 은 dry-run 에서는 스킵하고, 실패해도(git 미설치 등) 조용히 넘어간다.
  */
 async function finalizeProject(targetDir, { dryRun = false } = {}) {
-  const noDot = path.join(targetDir, 'gitignore');
-  const withDot = path.join(targetDir, '.gitignore');
-  if (await fs.pathExists(noDot)) {
-    await fs.move(noDot, withDot, { overwrite: true });
-  }
+  // 모노레포 / sub-app 까지 모든 `gitignore` 를 `.gitignore` 로 rename.
+  // root 만 처리하면 apps/<name>/gitignore 가 그대로 남아 node_modules/dist 가 staged 된다 (v0.93.0 버그).
+  await renameAllGitignoreRecursive(targetDir);
 
   if (dryRun) return;
 
@@ -2164,6 +2221,40 @@ async function finalizeProject(targetDir, { dryRun = false } = {}) {
   }
 }
 
+/**
+ * CLAUDE.md 의 `{{PLATFORM_APP_DESCRIPTION}}` 치환용 문장 — AI 에이전트에게 어떤 플랫폼인지
+ * 정확히 전달해서 잘못된 컨벤션 (예: vite 프로젝트에 App Router 가정) 적용 방지.
+ */
+function describeAppPlatform(platform, { tauri = false } = {}) {
+  if (platform === 'vite') {
+    const tauriSuffix = tauri
+      ? ' Tauri 데스크탑 셸이 동봉되어 있어 `src-tauri/` 가 native 진입점이다.'
+      : '';
+    return `Vite SPA (React + TypeScript). 라우트 + 비즈니스 로직. RSC / App Router 없음 — 모든 코드가 클라이언트 사이드 실행이다.${tauriSuffix}`;
+  }
+  // 디폴트: Next.js. 향후 platform 추가 시 분기 늘릴 것.
+  return 'Next.js 앱 (App Router + Server Components). 라우트 + 비즈니스 로직.';
+}
+
+async function renameAllGitignoreRecursive(dir) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // 스캐폴드 직후엔 node_modules / .git 가 없지만 방어적으로.
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      await renameAllGitignoreRecursive(fullPath);
+    } else if (entry.name === 'gitignore') {
+      await fs.move(fullPath, path.join(dir, '.gitignore'), { overwrite: true });
+    }
+  }
+}
+
 async function replaceInAllFiles(dir, search, replace) {
   const entries = await fs.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {

package/src/mcp.mjs

@@ -51,7 +51,7 @@ import {
   OBSERVABILITY_PROVIDERS,
 } from "./constants.js";
 import { allPlugins } from "./create/plugins/index.js";
-import { allArchitectures } from "./create/architectures/index.js";
+import { allArchitectures, describeArchOptions } from "./create/architectures/index.js";
 import { describeTemplate } from "./create/describeTemplate.js";
 import { THEME_PRESET_NAMES } from "./create/theme/presets.js";
 import { decodeTheme } from "./create/theme/decode.js";
@@ -113,11 +113,66 @@ async function captureConsole(fn) {
 }
 
 function textResult(text) {
-  return { content: [{ type: "text", text }] };
+  return { content: withStaleness([{ type: "text", text }]) };
 }
 
 function jsonResult(data) {
-  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  return { content: withStaleness([{ type: "text", text: JSON.stringify(data, null, 2) }]) };
+}
+
+/**
+ * Staleness 경고 — npm registry 에서 latest sh-ui-cli 버전을 조회해 현재와 다르면
+ * 모든 tool 응답 상단에 한 줄 경고 prepend (v0.95.0+).
+ *
+ * 왜 필요: npx 가 sh-ui-cli 를 한 번 fetch 한 뒤 ~/.npm/_npx 캐시에 박아두면, 사용자
+ * `~/.claude.json` 에 `sh-ui-cli` (버전 비고정) 로 등록해도 MCP 가 오래된 버전으로
+ * 계속 실행된다. AI 에이전트는 "응답이 정상 응답" 으로 받아들이므로 stale 임을 의심
+ * 못 함 — 사용자 (ai-org 케이스) 가 직접 발견할 때까지 잘못된 plan 으로 작업.
+ *
+ * 모듈 변수 — startMcpServer 가 fire-and-forget 으로 채움. 첫 응답 직전에 미완료
+ * 면 경고 없이 진행 (best-effort).
+ */
+let STALE_WARNING = "";
+
+function withStaleness(content) {
+  if (!STALE_WARNING) return content;
+  return [{ type: "text", text: STALE_WARNING }, ...content];
+}
+
+/**
+ * 비동기로 npm registry 조회 → 더 높은 버전이 있으면 STALE_WARNING 셋업.
+ * 3초 timeout · 모든 실패 (오프라인 / DNS / 차단) 는 조용히 무시.
+ */
+async function checkStaleness(currentVersion, cliName) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 3000);
+    const res = await fetch(`https://registry.npmjs.org/${cliName}/latest`, {
+      signal: ctrl.signal,
+    });
+    clearTimeout(timer);
+    if (!res.ok) return;
+    const data = await res.json();
+    const latest = typeof data.version === "string" ? data.version : null;
+    if (!latest || latest === currentVersion) return;
+    if (!isSemverGreater(latest, currentVersion)) return;
+    STALE_WARNING =
+      `⚠ sh-ui MCP ${currentVersion} (latest: ${latest}) — stale. ` +
+      `최신 옵션·버그픽스를 받으려면: \n` +
+      `  • ~/.claude.json (또는 다른 MCP 설정) 의 args 를 ["sh-ui-cli@latest", "mcp"] 로 변경 후 재시작\n` +
+      `  • npx 캐시가 박혀 있으면 \`npx clear-npx-cache\` 한 번 실행`;
+  } catch {
+    // best-effort.
+  }
+}
+
+function isSemverGreater(a, b) {
+  const parse = (s) => s.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const [aMaj, aMin, aPatch] = parse(a);
+  const [bMaj, bMin, bPatch] = parse(b);
+  if (aMaj !== bMaj) return aMaj > bMaj;
+  if (aMin !== bMin) return aMin > bMin;
+  return aPatch > bPatch;
 }
 
 async function loadRegistry(platform) {
@@ -346,6 +401,13 @@ return (
 
 export async function startMcpServer() {
   const { version, name: cliName } = await readPackageMeta();
+
+  // fire-and-forget — server 가 첫 tool 요청 받기 전에 끝나면 경고 prepend, 아니면 다음 요청부터.
+  // env SH_UI_SKIP_STALENESS_CHECK=1 로 disable 가능 (CI / 오프라인 환경).
+  if (!process.env.SH_UI_SKIP_STALENESS_CHECK) {
+    void checkStaleness(version, cliName);
+  }
+
   const server = new McpServer(
     { name: "sh-ui", version },
     {
@@ -386,9 +448,10 @@ export async function startMcpServer() {
         arch: z.enum(ARCH_NAMES).optional()
           .describe(
             `프로젝트 아키텍처 — 플랫폼별로 사용 가능한 값이 다름. ` +
-            `현재 next 에서 사용 가능: ${allArchitectures.filter((a) => a.platforms.includes('next')).map((a) => a.name).join(', ')} (기본 fsd). ` +
-            `flutter 는 현재 arch 디스크립터 없음 (미지정 또는 host 자체 default). ` +
-            `arch 와 플러그인은 별개 — arch 는 폴더 구조/import alias 컨벤션, 플러그인은 기능.`,
+            `사용 가능한 아키텍처 (의미 포함): ${describeArchOptions()}. ` +
+            `next 기본: fsd · vite 지원: fsd/flat · flutter 는 현재 arch 디스크립터 없음 (host 자체 default). ` +
+            `arch 와 플러그인은 별개 — arch 는 폴더 구조/import alias 컨벤션, 플러그인은 기능. ` +
+            `mes 는 폐기된 옵션이 아니라 별도 도메인-특화 아키텍처 (관리자/MES 류).`,
           ),
         theme: z.string().optional()
           .describe(`프리셋 이름 (${THEME_PRESETS_LIST}) 또는 base64 테마 코드. 사용자가 톤을 직접 손본 결과를 영구 보관하려면 sh_ui_encode_theme 으로 base64 를 만들어 여기에 넘긴다.`),
@@ -930,13 +993,27 @@ export async function startMcpServer() {
         structure: z.enum(CREATE_STRUCTURES).optional()
           .describe("Next.js 구조. platform=next | vite 일 때 의미. 기본 standalone"),
         arch: z.enum(ARCH_NAMES).optional()
-          .describe("아키텍처. platform=next 일 때 의미. 기본 fsd"),
+          .describe(
+            `아키텍처. 기본 fsd. ` +
+            `옵션 (의미 포함): ${describeArchOptions()}. ` +
+            `mes 는 deprecated 가 아니라 도메인-특화 옵션.`,
+          ),
         plugins: z.array(z.enum(PLUGIN_NAMES)).optional()
           .describe(`Next.js 플러그인 배열 (${PLUGIN_NAMES.join(', ')}). 미지정 빈 배열`),
         cssFramework: z.enum(CSS_FRAMEWORKS).optional()
           .describe("CSS 프레임워크. 기본 plain. css-modules 면 page.module.css 등 추가"),
         appName: z.string().optional()
           .describe("monorepo 첫 앱 이름. 기본 web"),
+        // vite 전용 — sh_ui_create_project 의 동일 옵션과 1:1 대응. describe ↔ create 가 같은
+        // file-plan 을 보장하려면 여기서 받아 describeTemplate 에 전달해야 한다 (v0.95.0+).
+        tauri: z.boolean().optional()
+          .describe("Tauri 2.x 데스크탑 셸 emit (platform=vite 전용). 기본 false"),
+        i18n: z.enum(I18N_LIBRARIES).optional()
+          .describe(`i18n 라이브러리 (platform=vite 전용). 옵션: ${I18N_LIBRARIES.join(', ')}. 기본 none`),
+        locales: z.string().optional()
+          .describe(`i18n 활성화 시 locale 코드 (comma-separated, 예: "ko,en"). 기본 "${I18N_DEFAULT_LOCALES}"`),
+        observability: z.enum(OBSERVABILITY_PROVIDERS).optional()
+          .describe(`observability 백엔드 (platform=vite 전용). 옵션: ${OBSERVABILITY_PROVIDERS.join(', ')}. 기본 none`),
       },
     },
     async (input) => {
@@ -948,6 +1025,10 @@ export async function startMcpServer() {
           plugins: input.plugins,
           cssFramework: input.cssFramework,
           appName: input.appName,
+          tauri: input.tauri,
+          i18n: input.i18n,
+          locales: input.locales,
+          observability: input.observability,
         });
         return jsonResult(result);
       } catch (e) {

package/templates/monorepo/CLAUDE.md

@@ -5,13 +5,26 @@ sh-ui CLI 가 스캐폴드한 monorepo (Turborepo + pnpm workspace). AI 에이
 
 ## 구조
 
-- `apps/<name>/` — Next.js 앱. 라우트 + 비즈니스 로직.
+- `apps/<name>/` — {{PLATFORM_APP_DESCRIPTION}}
 - `packages/ui/ui-core/` — 모든 앱이 공유하는 sh-ui 컴포넌트 / 훅 / 유틸 SoT.
   컴포넌트 추가는 여기에 한 번만.
 - `packages/ui/ui-apps/ui-<name>/` — 앱별 토큰 (color/spacing/font) 만 보관.
   컴포넌트는 두지 않음 (v0.65+ `tokens-only` 마커).
 - `packages/eslint-config/` · `packages/typescript-config/` — 공용 설정.
 
+## 아키텍처 옵션 (`--arch`)
+
+- **`fsd`** (default) — Feature-Sliced Design. `src/{app,pages,widgets,features,entities,shared}`
+  레이어로 단방향 의존(상위→하위). 일반적 SPA / 서비스에 적합.
+- **`flat`** — `src/{components,hooks,lib,pages}` 단순 구조. 작은 앱 / 학습용.
+- **`mes`** — MES (Backoffice) 전용. 페이지 격리 + 단방향 의존 강제. ERP/내부 관리도구
+  처럼 페이지 간 분리도가 중요한 도메인. Next.js 만 지원 (vite-app 은 fsd/flat 만).
+
+세 arch 모두 `packages/eslint-config/` 에 별도 ruleset 으로 들어가 있다 — 라이브러리
+이므로 모두 emit 되지만, 본인 앱의 `eslint.config.js` 에서 선택한 arch 의 config 만
+import 한다. 다른 arch 의 `.js` 파일이 보여도 deprecated 가 아니라 다른 앱이
+쓸 수 있는 옵션이다.
+
 ## 날짜 / 숫자 포맷
 
 - raw `Date.prototype.toLocaleDateString()` / `toLocaleString()` / `toLocaleTimeString()`

package/templates/nextjs-standalone/CLAUDE.md

@@ -3,6 +3,16 @@
 sh-ui CLI 가 스캐폴드한 Next.js standalone 프로젝트. AI 에이전트 (Claude / Cursor /
 Codex 등) 가 이 파일을 컨텍스트로 읽고 아래 규칙을 따른다.
 
+## 아키텍처 옵션 (`--arch`)
+
+- **`fsd`** (default) — Feature-Sliced Design. `src/{app,pages,widgets,features,entities,shared}`
+  레이어로 단방향 의존(상위→하위). 일반적 SPA / 서비스에 적합.
+- **`flat`** — `src/{components,hooks,lib}` 단순 구조. 작은 앱 / 학습용.
+- **`mes`** — MES (Backoffice) 전용. 페이지 격리 + 단방향 의존 강제. ERP/내부 관리도구
+  처럼 페이지 간 분리도가 중요한 도메인.
+
+선택한 arch 에 따라 `eslint.config.js` 가 다르게 emit 된다.
+
 ## 날짜 / 숫자 포맷
 
 - raw `Date.prototype.toLocaleDateString()` / `toLocaleString()` / `toLocaleTimeString()`