@kood/claude-code 0.1.0 → 0.1.2

package/dist/index.js

@@ -36,29 +36,51 @@ var getTemplatesDir = () => {
 var getTemplatePath = (template) => {
   return path.join(getTemplatesDir(), template);
 };
-var copyTemplate = async (template, targetDir) => {
+var copyRecursive = async (src, dest, counter) => {
+  const stat = await fs.stat(src);
+  if (stat.isDirectory()) {
+    await fs.ensureDir(dest);
+    counter.directories++;
+    const items = await fs.readdir(src);
+    for (const item of items) {
+      await copyRecursive(path.join(src, item), path.join(dest, item), counter);
+    }
+  } else {
+    await fs.copy(src, dest);
+    counter.files++;
+  }
+};
+var copySingleTemplate = async (template, targetDir) => {
   const templatePath = getTemplatePath(template);
   if (!await fs.pathExists(templatePath)) {
     throw new Error(`Template "${template}" not found at ${templatePath}`);
   }
-  let files = 0;
-  let directories = 0;
-  const copyRecursive = async (src, dest) => {
-    const stat = await fs.stat(src);
-    if (stat.isDirectory()) {
-      await fs.ensureDir(dest);
-      directories++;
-      const items = await fs.readdir(src);
-      for (const item of items) {
-        await copyRecursive(path.join(src, item), path.join(dest, item));
-      }
-    } else {
-      await fs.copy(src, dest);
-      files++;
+  const counter = { files: 0, directories: 0 };
+  const claudeMdSrc = path.join(templatePath, "CLAUDE.md");
+  if (await fs.pathExists(claudeMdSrc)) {
+    await fs.copy(claudeMdSrc, path.join(targetDir, "CLAUDE.md"));
+    counter.files++;
+  }
+  const docsSrc = path.join(templatePath, "docs");
+  if (await fs.pathExists(docsSrc)) {
+    await copyRecursive(docsSrc, path.join(targetDir, "docs"), counter);
+  }
+  return counter;
+};
+var copyMultipleTemplates = async (templates, targetDir) => {
+  const counter = { files: 0, directories: 0 };
+  for (const template of templates) {
+    const templatePath = getTemplatePath(template);
+    if (!await fs.pathExists(templatePath)) {
+      throw new Error(`Template "${template}" not found at ${templatePath}`);
     }
-  };
-  await copyRecursive(templatePath, targetDir);
-  return { files, directories };
+    await copyRecursive(
+      templatePath,
+      path.join(targetDir, "docs", template),
+      counter
+    );
+  }
+  return counter;
 };
 var checkExistingFiles = async (targetDir) => {
   const existingFiles = [];
@@ -116,14 +138,14 @@ var copySkills = async (template, targetDir) => {
   let files = 0;
   let directories = 0;
   const installedSkills = [];
-  const copyRecursive = async (src, dest) => {
+  const copyRecursive2 = async (src, dest) => {
     const stat = await fs.stat(src);
     if (stat.isDirectory()) {
       await fs.ensureDir(dest);
       directories++;
       const items = await fs.readdir(src);
       for (const item of items) {
-        await copyRecursive(path.join(src, item), path.join(dest, item));
+        await copyRecursive2(path.join(src, item), path.join(dest, item));
       }
     } else {
       await fs.copy(src, dest);
@@ -136,7 +158,7 @@ var copySkills = async (template, targetDir) => {
     const skillDestPath = path.join(targetSkillsDir, skill);
     const stat = await fs.stat(skillSrcPath);
     if (stat.isDirectory()) {
-      await copyRecursive(skillSrcPath, skillDestPath);
+      await copyRecursive2(skillSrcPath, skillDestPath);
       installedSkills.push(skill);
     }
   }
@@ -166,26 +188,31 @@ var init = async (options) => {
     logger.error("No templates found. Package may be corrupted.");
     process.exit(1);
   }
-  let template = options.template;
-  if (!template) {
+  let templates = options.templates || [];
+  if (templates.length === 0) {
     const response = await prompts({
-      type: "select",
-      name: "template",
-      message: "Select a template:",
+      type: "multiselect",
+      name: "templates",
+      message: "Select templates (space to select, enter to confirm):",
       choices: availableTemplates.map((t) => ({
         title: t,
         description: TEMPLATE_DESCRIPTIONS[t] || "",
         value: t
-      }))
+      })),
+      min: 1,
+      hint: "- Space to select. Return to submit"
     });
-    if (!response.template) {
+    if (!response.templates || response.templates.length === 0) {
       logger.warn("Operation cancelled.");
       process.exit(0);
     }
-    template = response.template;
+    templates = response.templates;
   }
-  if (!availableTemplates.includes(template)) {
-    logger.error(`Template "${template}" not found.`);
+  const invalidTemplates = templates.filter(
+    (t) => !availableTemplates.includes(t)
+  );
+  if (invalidTemplates.length > 0) {
+    logger.error(`Templates not found: ${invalidTemplates.join(", ")}`);
     logger.info(`Available templates: ${availableTemplates.join(", ")}`);
     process.exit(1);
   }
@@ -205,80 +232,116 @@ var init = async (options) => {
       process.exit(0);
     }
   }
-  logger.blank();
-  logger.info(`Installing ${template} template...`);
-  logger.step(`Target: ${targetDir}`);
+  const isSingleTemplate = templates.length === 1;
+  let totalFiles = 0;
+  let totalDirectories = 0;
+  const allSkills = [];
   logger.blank();
   try {
-    const result = await copyTemplate(template, targetDir);
-    logger.success(`${result.files} files copied`);
-    logger.success(`${result.directories} directories created`);
-    logger.blank();
-    const availableSkills = await listAvailableSkills(template);
-    if (availableSkills.length > 0) {
-      let installSkills = options.skills;
-      if (installSkills === void 0) {
-        const response = await prompts({
-          type: "confirm",
-          name: "installSkills",
-          message: `Install Claude Code skills? (${availableSkills.join(", ")})`,
-          initial: true
-        });
-        installSkills = response.installSkills;
-      }
-      if (installSkills) {
-        const existingSkills = await checkExistingSkills(
-          targetDir,
-          availableSkills
-        );
-        if (existingSkills.length > 0 && !options.force) {
-          logger.warn("The following skills already exist:");
-          existingSkills.forEach((s) => logger.step(s));
-          logger.blank();
-          const response = await prompts({
-            type: "confirm",
-            name: "overwrite",
-            message: "Overwrite existing skills?",
-            initial: false
-          });
-          if (!response.overwrite) {
-            logger.info("Skipping skills installation.");
-          } else {
-            const skillsResult = await copySkills(
-              template,
-              targetDir
-            );
-            logger.success(
-              `Skills installed: ${skillsResult.skills.join(", ")}`
-            );
-            logger.step(`Location: .claude/skills/`);
+    if (isSingleTemplate) {
+      const template = templates[0];
+      logger.info(`Installing ${template} template...`);
+      logger.step(`Target: ${targetDir}`);
+      logger.blank();
+      const result = await copySingleTemplate(template, targetDir);
+      totalFiles = result.files;
+      totalDirectories = result.directories;
+      logger.success(`${template}: ${result.files} files copied`);
+      const availableSkills = await listAvailableSkills(template);
+      allSkills.push(...availableSkills);
+    } else {
+      logger.info(`Installing ${templates.length} templates...`);
+      logger.step(`Target: ${targetDir}/docs/`);
+      logger.blank();
+      const result = await copyMultipleTemplates(templates, targetDir);
+      totalFiles = result.files;
+      totalDirectories = result.directories;
+      for (const template of templates) {
+        logger.success(`${template}: installed to docs/${template}/`);
+        const availableSkills = await listAvailableSkills(template);
+        for (const skill of availableSkills) {
+          if (!allSkills.includes(skill)) {
+            allSkills.push(skill);
           }
-        } else {
-          const skillsResult = await copySkills(template, targetDir);
-          logger.success(`Skills installed: ${skillsResult.skills.join(", ")}`);
-          logger.step(`Location: .claude/skills/`);
         }
-        logger.blank();
       }
     }
-    logger.success("Claude Code documentation installed!");
-    logger.blank();
-    logger.info("Next steps:");
-    logger.step("Read CLAUDE.md for project guidelines");
-    logger.step("Explore docs/ for detailed documentation");
-    logger.blank();
   } catch (error) {
     logger.error(
-      `Failed to install template: ${error instanceof Error ? error.message : "Unknown error"}`
+      `Failed to install templates: ${error instanceof Error ? error.message : "Unknown error"}`
     );
     process.exit(1);
   }
+  logger.blank();
+  logger.success(`Total: ${totalFiles} files, ${totalDirectories} directories`);
+  if (allSkills.length > 0) {
+    let installSkills = options.skills;
+    if (installSkills === void 0) {
+      logger.blank();
+      const response = await prompts({
+        type: "confirm",
+        name: "installSkills",
+        message: `Install Claude Code skills? (${allSkills.join(", ")})`,
+        initial: true
+      });
+      installSkills = response.installSkills;
+    }
+    if (installSkills) {
+      const existingSkills = await checkExistingSkills(targetDir, allSkills);
+      if (existingSkills.length > 0 && !options.force) {
+        logger.warn("The following skills already exist:");
+        existingSkills.forEach((s) => logger.step(s));
+        logger.blank();
+        const response = await prompts({
+          type: "confirm",
+          name: "overwrite",
+          message: "Overwrite existing skills?",
+          initial: false
+        });
+        if (!response.overwrite) {
+          logger.info("Skipping skills installation.");
+        } else {
+          await installAllSkills(templates, targetDir);
+        }
+      } else {
+        await installAllSkills(templates, targetDir);
+      }
+      logger.blank();
+    }
+  }
+  logger.success("Claude Code documentation installed!");
+  logger.blank();
+  logger.info("Installed templates:");
+  templates.forEach((t) => logger.step(t));
+  logger.blank();
+  logger.info("Next steps:");
+  logger.step("Read CLAUDE.md for project guidelines");
+  logger.step("Explore docs/ for detailed documentation");
+  logger.blank();
+};
+var installAllSkills = async (templates, targetDir) => {
+  const installedSkills = [];
+  for (const template of templates) {
+    const skillsResult = await copySkills(template, targetDir);
+    for (const skill of skillsResult.skills) {
+      if (!installedSkills.includes(skill)) {
+        installedSkills.push(skill);
+      }
+    }
+  }
+  if (installedSkills.length > 0) {
+    logger.success(`Skills installed: ${installedSkills.join(", ")}`);
+    logger.step(`Location: .claude/skills/`);
+  }
 };
 
 // src/index.ts
 var program = new Command();
 program.name("claude-code").description("Claude Code documentation installer for projects").version("1.0.0");
-program.option("-t, --template <name>", "template name (tanstack-start, hono)").option("-f, --force", "overwrite existing files without prompting").option("-s, --skills", "install Claude Code skills").option("--no-skills", "skip skills installation").option("--cwd <path>", "target directory (default: current directory)").option("--list", "list available templates").action(async (options) => {
+program.option(
+  "-t, --template <names>",
+  "template names (comma-separated: tanstack-start,hono)"
+).option("-f, --force", "overwrite existing files without prompting").option("-s, --skills", "install Claude Code skills").option("--no-skills", "skip skills installation").option("--cwd <path>", "target directory (default: current directory)").option("--list", "list available templates").action(async (options) => {
   banner();
   if (options.list) {
     const templates = await listAvailableTemplates();
@@ -288,7 +351,7 @@ program.option("-t, --template <name>", "template name (tanstack-start, hono)").
     return;
   }
   await init({
-    template: options.template,
+    templates: options.template?.split(",").map((t) => t.trim()),
     force: options.force,
     cwd: options.cwd,
     skills: options.skills

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kood/claude-code",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Claude Code documentation installer for projects",
   "type": "module",
   "bin": "./dist/index.js",

package/templates/hono/docs/mcp/index.md

@@ -1,94 +1,176 @@
-# MCP 도구 가이드
+# MCP (Model Context Protocol)
 
-> Claude Code에서 사용하는 MCP (Model Context Protocol) 도구
+> Claude Code 작업 효율성을 높이는 MCP 서버 활용 가이드
 
 ---
 
-## 📋 MCP 도구 개요
+## ⛔ 프로젝트 시작 전 필수 확인
 
-| 도구 | 용도 | 사용 시점 |
-|------|------|----------|
-| **sgrep** | 코드 검색 | 코드베이스 검색 시 (grep/rg 대신) |
-| **Sequential Thinking** | 복잡한 분석 | 디버깅, 아키텍처 분석 |
-| **Context7** | 라이브러리 문서 | 공식 문서 참조 필요 시 |
+**작업 시작 전 반드시 아래 3가지 MCP가 활성화되어 있는지 확인하세요:**
+
+```
+1. Serena - 프로젝트 활성화 확인
+   → mcp__serena__get_current_config 호출
+   → 프로젝트 미활성화 시: mcp__serena__activate_project
+
+2. Sequential Thinking - 복잡한 문제 분석용
+   → 사용 가능 여부 확인
+
+3. sgrep - 코드베이스 검색용
+   → grep/rg 대신 반드시 sgrep 사용
+```
+
+---
+
+## 🚨 필수 사용 규칙
+
+```
+✅ 프로젝트 시작 전 → Serena 활성화 확인 (필수!)
+✅ 코드베이스 검색 → sgrep 사용 (grep/rg 금지)
+✅ 복잡한 분석/디버깅 → Sequential Thinking 사용
+✅ 라이브러리 문서 조회 → Context7 사용
+✅ 세션 컨텍스트 유지 → Serena 메모리 활용
+✅ 도구 조합: sgrep로 위치 파악 → Sequential로 분석 → Context7로 문서 확인
+```
 
 ---
 
-## sgrep - 코드 검색
+## 🚀 Quick Reference
+
+### Serena - 프로젝트 컨텍스트 관리 (필수)
+
+```
+프로젝트 시작 시 (필수):
+1. get_current_config → 현재 상태 확인
+2. activate_project → 프로젝트 활성화
+3. check_onboarding_performed → 온보딩 확인
+
+사용 시점:
+- 프로젝트 시작/재개 시 (필수)
+- 심볼 탐색/수정
+- 세션 간 컨텍스트 유지 (메모리)
+```
+
+### Sequential Thinking - 복잡한 문제 해결
+
+```
+사용 시점:
+- 버그 분석 및 디버깅
+- 아키텍처 설계
+- 복잡한 로직 구현
+- 코드 리팩토링 계획
+- 성능 최적화 분석
+
+사용법: 문제를 단계별로 분해하여 체계적으로 해결
+```
+
+### sgrep - 코드베이스 검색 (필수)
 
-> ⚠️ **필수**: 코드베이스 검색 시 grep/rg 대신 sgrep 사용
+```
+사용 시점:
+- 코드 위치 파악
+- 자연어 검색
+- 심볼 참조 찾기
+
+주의: grep/rg 대신 반드시 sgrep 사용!
+```
 
-### 사용 시점
-- 코드베이스에서 패턴 검색
-- 함수/클래스 사용처 찾기
-- 특정 패턴의 코드 찾기
+### Context7 - 라이브러리 문서 조회
 
-### 장점
-- AST 기반 시맨틱 검색
-- 언어별 최적화된 패턴 매칭
-- 정확한 코드 구조 인식
+```
+사용 시점:
+- API 사용법 확인
+- 라이브러리 최신 문법 확인
+- 공식 문서 기반 구현
+- 버전별 변경사항 확인
+
+사용법:
+1. resolve-library-id로 라이브러리 ID 조회
+2. get-library-docs로 문서 가져오기
+```
 
 ---
 
-## Sequential Thinking - 분석 도구
+## 📁 문서 구조
 
-> 복잡한 문제를 단계별로 분석
+```
+docs/mcp/
+├── index.md              # 이 문서 (개요)
+├── serena.md             # Serena 프로젝트 관리 (필수)
+├── sgrep.md              # 코드베이스 검색 (필수)
+├── sequential-thinking.md # Sequential Thinking 상세 (필수)
+└── context7.md           # Context7 상세
+```
 
-### 사용 시점
-- 복잡한 버그 디버깅
-- 아키텍처 분석/설계
-- 성능 병목 분석
-- 리팩토링 계획 수립
+---
 
-### 특징
-- 단계별 사고 과정 기록
-- 가설 설정 및 검증
-- 체계적인 문제 해결
+## 📋 도구 목록
+
+| 도구 | 용도 | 필수 여부 |
+|-----|------|----------|
+| [Serena](./serena.md) | 프로젝트 컨텍스트 관리 | ⭐ 필수 |
+| [sgrep](./sgrep.md) | 코드베이스 검색 | ⭐ 필수 |
+| [Sequential Thinking](./sequential-thinking.md) | 체계적 문제 해결 | ⭐ 필수 |
+| [Context7](./context7.md) | 라이브러리 문서 | 권장 |
 
 ---
 
-## Context7 - 라이브러리 문서
+## ⚡ 작업별 MCP 선택 가이드
 
-> 공식 라이브러리 문서 조회
+### 프로젝트 시작 (필수)
+```
+1. Serena: get_current_config로 상태 확인
+2. Serena: activate_project로 프로젝트 활성화
+3. Serena: list_memories로 이전 컨텍스트 확인
+```
 
-### 사용 시점
-- 라이브러리 API 확인
-- 공식 문서 패턴 참조
-- 최신 버전 사용법 확인
+### 버그 수정
+```
+1. sgrep로 관련 코드 위치 파악
+2. Sequential Thinking으로 문제 분석
+3. 원인 파악 후 Context7로 관련 API 확인
+4. 수정 구현
+```
 
-### 지원 라이브러리
-- Hono
-- Zod
-- Prisma
-- 기타 주요 라이브러리
+### 새 기능 구현
+```
+1. sgrep로 기존 패턴 검색
+2. Sequential Thinking으로 구현 계획 수립
+3. Context7로 사용할 라이브러리 문서 확인
+4. 단계별 구현
+5. Serena: write_memory로 주요 결정 저장
+```
 
-### 사용 예시
+### 라이브러리 사용
 ```
-Context7로 Hono middleware 문서 조회
-Context7로 Zod v4 validation 문서 조회
-Context7로 Prisma transaction 문서 조회
+1. Context7로 공식 문서 조회
+2. 필요시 Sequential Thinking으로 복잡한 통합 분석
 ```
 
----
+### 성능 최적화
+```
+1. sgrep로 병목 의심 코드 검색
+2. Sequential Thinking으로 병목 분석
+3. Context7로 최적화 관련 API 확인
+4. 개선 구현
+```
 
-## MCP 도구 선택 가이드
+### 코드베이스 탐색
+```
+1. sgrep로 자연어 쿼리 검색
+2. 관련 코드 위치 파악
+3. 필요시 Sequential Thinking으로 흐름 분석
+```
 
+### 세션 종료
 ```
-코드 검색이 필요한가?
-├─ Yes → sgrep 사용
-└─ No
-   ├─ 복잡한 분석이 필요한가?
-   │  ├─ Yes → Sequential Thinking 사용
-   │  └─ No
-   │     └─ 라이브러리 문서가 필요한가?
-   │        ├─ Yes → Context7 사용
-   │        └─ No → 일반 도구 사용
+1. Serena: write_memory로 진행 상황 저장
+2. 다음 세션에서 read_memory로 복구
 ```
 
 ---
 
-## 관련 문서
+## 🔗 관련 문서
 
-- [sgrep 상세](./sgrep.md)
-- [Sequential Thinking 상세](./sequential-thinking.md)
-- [Context7 상세](./context7.md)
+- [Hono](../library/hono/index.md) - Web Framework
+- [Zod](../library/zod/index.md) - Validation

package/templates/hono/docs/mcp/serena.md

@@ -0,0 +1,269 @@
+# Serena MCP Server
+
+> **Purpose**: 시맨틱 코드 이해, 프로젝트 메모리, 세션 지속성을 위한 MCP 서버
+
+---
+
+## 프로젝트 시작 전 필수 확인
+
+프로젝트 작업을 시작하기 전에 **반드시** Serena가 활성화되어 있는지 확인해야 합니다.
+
+### 1. 현재 설정 확인
+
+```
+mcp__serena__get_current_config
+```
+
+**확인 사항:**
+- `Active project`: 현재 작업할 프로젝트명이 표시되는지 확인
+- 프로젝트가 `Available projects` 목록에 있는지 확인
+
+### 2. 프로젝트 활성화
+
+프로젝트가 활성화되지 않은 경우:
+
+```
+mcp__serena__activate_project({ project: "프로젝트명" })
+```
+
+### 3. 온보딩 확인
+
+새 프로젝트의 경우 온보딩이 필요할 수 있습니다:
+
+```
+mcp__serena__check_onboarding_performed
+```
+
+온보딩이 필요한 경우:
+
+```
+mcp__serena__onboarding
+```
+
+---
+
+## 핵심 기능
+
+### 심볼 탐색 (Symbol Navigation)
+
+파일 내 심볼(클래스, 함수, 변수 등) 개요 확인:
+
+```
+mcp__serena__get_symbols_overview({ relative_path: "src/index.ts" })
+```
+
+특정 심볼 검색:
+
+```
+mcp__serena__find_symbol({
+  name_path_pattern: "MyClass/myMethod",
+  include_body: true,
+  depth: 1
+})
+```
+
+심볼 참조 찾기:
+
+```
+mcp__serena__find_referencing_symbols({
+  name_path: "MyClass",
+  relative_path: "src/my-class.ts"
+})
+```
+
+### 코드 수정 (Code Modification)
+
+심볼 본문 교체:
+
+```
+mcp__serena__replace_symbol_body({
+  name_path: "MyClass/myMethod",
+  relative_path: "src/my-class.ts",
+  body: "새로운 코드 본문"
+})
+```
+
+심볼 뒤에 코드 삽입:
+
+```
+mcp__serena__insert_after_symbol({
+  name_path: "MyClass",
+  relative_path: "src/my-class.ts",
+  body: "\n\nexport const newFunction = () => {}"
+})
+```
+
+심볼 앞에 코드 삽입:
+
+```
+mcp__serena__insert_before_symbol({
+  name_path: "MyClass",
+  relative_path: "src/my-class.ts",
+  body: "import { Something } from './something'\n\n"
+})
+```
+
+심볼 이름 변경 (전체 코드베이스):
+
+```
+mcp__serena__rename_symbol({
+  name_path: "oldFunctionName",
+  relative_path: "src/utils.ts",
+  new_name: "newFunctionName"
+})
+```
+
+### 파일 탐색 (File Navigation)
+
+디렉토리 목록:
+
+```
+mcp__serena__list_dir({
+  relative_path: "src",
+  recursive: false
+})
+```
+
+파일 검색:
+
+```
+mcp__serena__find_file({
+  file_mask: "*.ts",
+  relative_path: "src"
+})
+```
+
+패턴 검색:
+
+```
+mcp__serena__search_for_pattern({
+  substring_pattern: "createServerFn",
+  relative_path: "src/services",
+  context_lines_before: 2,
+  context_lines_after: 2
+})
+```
+
+### 메모리 관리 (Memory Management)
+
+프로젝트 관련 정보를 메모리에 저장하여 세션 간 유지:
+
+메모리 목록 확인:
+
+```
+mcp__serena__list_memories
+```
+
+메모리 읽기:
+
+```
+mcp__serena__read_memory({ memory_file_name: "architecture.md" })
+```
+
+메모리 작성:
+
+```
+mcp__serena__write_memory({
+  memory_file_name: "decisions.md",
+  content: "# 주요 결정 사항\n\n- API 설계: REST 대신 Server Functions 사용"
+})
+```
+
+메모리 수정:
+
+```
+mcp__serena__edit_memory({
+  memory_file_name: "decisions.md",
+  needle: "REST 대신",
+  repl: "REST API 대신",
+  mode: "literal"
+})
+```
+
+메모리 삭제:
+
+```
+mcp__serena__delete_memory({ memory_file_name: "outdated.md" })
+```
+
+### 사고 도구 (Thinking Tools)
+
+수집된 정보 검토:
+
+```
+mcp__serena__think_about_collected_information
+```
+
+작업 목표 준수 확인:
+
+```
+mcp__serena__think_about_task_adherence
+```
+
+작업 완료 여부 확인:
+
+```
+mcp__serena__think_about_whether_you_are_done
+```
+
+---
+
+## 사용 시나리오
+
+### 시나리오 1: 새 프로젝트 시작
+
+```
+1. get_current_config → 현재 상태 확인
+2. activate_project → 프로젝트 활성화
+3. check_onboarding_performed → 온보딩 필요 여부 확인
+4. onboarding → 필요시 온보딩 진행
+5. list_memories → 기존 메모리 확인
+```
+
+### 시나리오 2: 기존 프로젝트 재개
+
+```
+1. get_current_config → 프로젝트 활성화 확인
+2. list_memories → 이전 세션 컨텍스트 확인
+3. read_memory → 필요한 메모리 읽기
+4. 작업 진행
+5. write_memory → 중요 결정/진행 상황 저장
+```
+
+### 시나리오 3: 대규모 리팩토링
+
+```
+1. get_symbols_overview → 파일 구조 파악
+2. find_symbol → 수정할 심볼 찾기
+3. find_referencing_symbols → 영향받는 코드 확인
+4. replace_symbol_body → 심볼 수정
+5. rename_symbol → 필요시 이름 변경
+6. think_about_whether_you_are_done → 완료 확인
+```
+
+---
+
+## Best Practices
+
+### 1. 항상 프로젝트 활성화 확인
+
+작업 시작 전 `get_current_config`로 올바른 프로젝트가 활성화되어 있는지 확인하세요.
+
+### 2. 심볼 도구 우선 사용
+
+전체 파일을 읽지 말고, `get_symbols_overview`와 `find_symbol`을 사용하여 필요한 부분만 확인하세요.
+
+### 3. 메모리 적극 활용
+
+중요한 결정, 아키텍처 정보, 작업 진행 상황을 메모리에 저장하여 세션 간 컨텍스트를 유지하세요.
+
+### 4. 사고 도구 활용
+
+복잡한 작업 중에는 `think_about_*` 도구를 사용하여 진행 상황을 검토하세요.
+
+---
+
+## 참고 자료
+
+- [Serena GitHub](https://github.com/oraios/serena)
+- [MCP Protocol](https://modelcontextprotocol.io)

package/templates/tanstack-start/docs/mcp/index.md

@@ -4,12 +4,32 @@
 
 ---
 
+## ⛔ 프로젝트 시작 전 필수 확인
+
+**작업 시작 전 반드시 아래 3가지 MCP가 활성화되어 있는지 확인하세요:**
+
+```
+1. Serena - 프로젝트 활성화 확인
+   → mcp__serena__get_current_config 호출
+   → 프로젝트 미활성화 시: mcp__serena__activate_project
+
+2. Sequential Thinking - 복잡한 문제 분석용
+   → 사용 가능 여부 확인
+
+3. sgrep - 코드베이스 검색용
+   → grep/rg 대신 반드시 sgrep 사용
+```
+
+---
+
 ## 🚨 필수 사용 규칙
 
 ```
+✅ 프로젝트 시작 전 → Serena 활성화 확인 (필수!)
 ✅ 코드베이스 검색 → sgrep 사용 (grep/rg 금지)
 ✅ 복잡한 분석/디버깅 → Sequential Thinking 사용
 ✅ 라이브러리 문서 조회 → Context7 사용
+✅ 세션 컨텍스트 유지 → Serena 메모리 활용
 ✅ 도구 조합: sgrep로 위치 파악 → Sequential로 분석 → Context7로 문서 확인
 ```
 
@@ -17,6 +37,20 @@
 
 ## 🚀 Quick Reference
 
+### Serena - 프로젝트 컨텍스트 관리 (필수)
+
+```
+프로젝트 시작 시 (필수):
+1. get_current_config → 현재 상태 확인
+2. activate_project → 프로젝트 활성화
+3. check_onboarding_performed → 온보딩 확인
+
+사용 시점:
+- 프로젝트 시작/재개 시 (필수)
+- 심볼 탐색/수정
+- 세션 간 컨텍스트 유지 (메모리)
+```
+
 ### Sequential Thinking - 복잡한 문제 해결
 
 ```
@@ -30,6 +64,17 @@
 사용법: 문제를 단계별로 분해하여 체계적으로 해결
 ```
 
+### sgrep - 코드베이스 검색 (필수)
+
+```
+사용 시점:
+- 코드 위치 파악
+- 자연어 검색
+- 심볼 참조 찾기
+
+주의: grep/rg 대신 반드시 sgrep 사용!
+```
+
 ### Context7 - 라이브러리 문서 조회
 
 ```
@@ -51,8 +96,9 @@
 ```
 docs/mcp/
 ├── index.md              # 이 문서 (개요)
-├── sgrep.md              # 코드베이스 검색
-├── sequential-thinking.md # Sequential Thinking 상세
+├── serena.md             # Serena 프로젝트 관리 (필수)
+├── sgrep.md              # 코드베이스 검색 (필수)
+├── sequential-thinking.md # Sequential Thinking 상세 (필수)
 └── context7.md           # Context7 상세
 ```
 
@@ -60,16 +106,24 @@ docs/mcp/
 
 ## 📋 도구 목록
 
-| 도구 | 용도 | 사용 시점 |
+| 도구 | 용도 | 필수 여부 |
 |-----|------|----------|
-| [sgrep](./sgrep.md) | 코드베이스 검색 | 코드 위치 파악, 자연어 검색 |
-| [Sequential Thinking](./sequential-thinking.md) | 체계적 문제 해결 | 복잡한 분석, 디버깅, 설계 |
-| [Context7](./context7.md) | 라이브러리 문서 | API 확인, 최신 문법 |
+| [Serena](./serena.md) | 프로젝트 컨텍스트 관리 | ⭐ 필수 |
+| [sgrep](./sgrep.md) | 코드베이스 검색 | ⭐ 필수 |
+| [Sequential Thinking](./sequential-thinking.md) | 체계적 문제 해결 | ⭐ 필수 |
+| [Context7](./context7.md) | 라이브러리 문서 | 권장 |
 
 ---
 
 ## ⚡ 작업별 MCP 선택 가이드
 
+### 프로젝트 시작 (필수)
+```
+1. Serena: get_current_config로 상태 확인
+2. Serena: activate_project로 프로젝트 활성화
+3. Serena: list_memories로 이전 컨텍스트 확인
+```
+
 ### 버그 수정
 ```
 1. sgrep로 관련 코드 위치 파악
@@ -84,6 +138,7 @@ docs/mcp/
 2. Sequential Thinking으로 구현 계획 수립
 3. Context7로 사용할 라이브러리 문서 확인
 4. 단계별 구현
+5. Serena: write_memory로 주요 결정 저장
 ```
 
 ### 라이브러리 사용
@@ -107,6 +162,12 @@ docs/mcp/
 3. 필요시 Sequential Thinking으로 흐름 분석
 ```
 
+### 세션 종료
+```
+1. Serena: write_memory로 진행 상황 저장
+2. 다음 세션에서 read_memory로 복구
+```
+
 ---
 
 ## 🔗 관련 문서

package/templates/tanstack-start/docs/mcp/serena.md

@@ -0,0 +1,269 @@
+# Serena MCP Server
+
+> **Purpose**: 시맨틱 코드 이해, 프로젝트 메모리, 세션 지속성을 위한 MCP 서버
+
+---
+
+## 프로젝트 시작 전 필수 확인
+
+프로젝트 작업을 시작하기 전에 **반드시** Serena가 활성화되어 있는지 확인해야 합니다.
+
+### 1. 현재 설정 확인
+
+```
+mcp__serena__get_current_config
+```
+
+**확인 사항:**
+- `Active project`: 현재 작업할 프로젝트명이 표시되는지 확인
+- 프로젝트가 `Available projects` 목록에 있는지 확인
+
+### 2. 프로젝트 활성화
+
+프로젝트가 활성화되지 않은 경우:
+
+```
+mcp__serena__activate_project({ project: "프로젝트명" })
+```
+
+### 3. 온보딩 확인
+
+새 프로젝트의 경우 온보딩이 필요할 수 있습니다:
+
+```
+mcp__serena__check_onboarding_performed
+```
+
+온보딩이 필요한 경우:
+
+```
+mcp__serena__onboarding
+```
+
+---
+
+## 핵심 기능
+
+### 심볼 탐색 (Symbol Navigation)
+
+파일 내 심볼(클래스, 함수, 변수 등) 개요 확인:
+
+```
+mcp__serena__get_symbols_overview({ relative_path: "src/index.ts" })
+```
+
+특정 심볼 검색:
+
+```
+mcp__serena__find_symbol({
+  name_path_pattern: "MyClass/myMethod",
+  include_body: true,
+  depth: 1
+})
+```
+
+심볼 참조 찾기:
+
+```
+mcp__serena__find_referencing_symbols({
+  name_path: "MyClass",
+  relative_path: "src/my-class.ts"
+})
+```
+
+### 코드 수정 (Code Modification)
+
+심볼 본문 교체:
+
+```
+mcp__serena__replace_symbol_body({
+  name_path: "MyClass/myMethod",
+  relative_path: "src/my-class.ts",
+  body: "새로운 코드 본문"
+})
+```
+
+심볼 뒤에 코드 삽입:
+
+```
+mcp__serena__insert_after_symbol({
+  name_path: "MyClass",
+  relative_path: "src/my-class.ts",
+  body: "\n\nexport const newFunction = () => {}"
+})
+```
+
+심볼 앞에 코드 삽입:
+
+```
+mcp__serena__insert_before_symbol({
+  name_path: "MyClass",
+  relative_path: "src/my-class.ts",
+  body: "import { Something } from './something'\n\n"
+})
+```
+
+심볼 이름 변경 (전체 코드베이스):
+
+```
+mcp__serena__rename_symbol({
+  name_path: "oldFunctionName",
+  relative_path: "src/utils.ts",
+  new_name: "newFunctionName"
+})
+```
+
+### 파일 탐색 (File Navigation)
+
+디렉토리 목록:
+
+```
+mcp__serena__list_dir({
+  relative_path: "src",
+  recursive: false
+})
+```
+
+파일 검색:
+
+```
+mcp__serena__find_file({
+  file_mask: "*.ts",
+  relative_path: "src"
+})
+```
+
+패턴 검색:
+
+```
+mcp__serena__search_for_pattern({
+  substring_pattern: "createServerFn",
+  relative_path: "src/services",
+  context_lines_before: 2,
+  context_lines_after: 2
+})
+```
+
+### 메모리 관리 (Memory Management)
+
+프로젝트 관련 정보를 메모리에 저장하여 세션 간 유지:
+
+메모리 목록 확인:
+
+```
+mcp__serena__list_memories
+```
+
+메모리 읽기:
+
+```
+mcp__serena__read_memory({ memory_file_name: "architecture.md" })
+```
+
+메모리 작성:
+
+```
+mcp__serena__write_memory({
+  memory_file_name: "decisions.md",
+  content: "# 주요 결정 사항\n\n- API 설계: REST 대신 Server Functions 사용"
+})
+```
+
+메모리 수정:
+
+```
+mcp__serena__edit_memory({
+  memory_file_name: "decisions.md",
+  needle: "REST 대신",
+  repl: "REST API 대신",
+  mode: "literal"
+})
+```
+
+메모리 삭제:
+
+```
+mcp__serena__delete_memory({ memory_file_name: "outdated.md" })
+```
+
+### 사고 도구 (Thinking Tools)
+
+수집된 정보 검토:
+
+```
+mcp__serena__think_about_collected_information
+```
+
+작업 목표 준수 확인:
+
+```
+mcp__serena__think_about_task_adherence
+```
+
+작업 완료 여부 확인:
+
+```
+mcp__serena__think_about_whether_you_are_done
+```
+
+---
+
+## 사용 시나리오
+
+### 시나리오 1: 새 프로젝트 시작
+
+```
+1. get_current_config → 현재 상태 확인
+2. activate_project → 프로젝트 활성화
+3. check_onboarding_performed → 온보딩 필요 여부 확인
+4. onboarding → 필요시 온보딩 진행
+5. list_memories → 기존 메모리 확인
+```
+
+### 시나리오 2: 기존 프로젝트 재개
+
+```
+1. get_current_config → 프로젝트 활성화 확인
+2. list_memories → 이전 세션 컨텍스트 확인
+3. read_memory → 필요한 메모리 읽기
+4. 작업 진행
+5. write_memory → 중요 결정/진행 상황 저장
+```
+
+### 시나리오 3: 대규모 리팩토링
+
+```
+1. get_symbols_overview → 파일 구조 파악
+2. find_symbol → 수정할 심볼 찾기
+3. find_referencing_symbols → 영향받는 코드 확인
+4. replace_symbol_body → 심볼 수정
+5. rename_symbol → 필요시 이름 변경
+6. think_about_whether_you_are_done → 완료 확인
+```
+
+---
+
+## Best Practices
+
+### 1. 항상 프로젝트 활성화 확인
+
+작업 시작 전 `get_current_config`로 올바른 프로젝트가 활성화되어 있는지 확인하세요.
+
+### 2. 심볼 도구 우선 사용
+
+전체 파일을 읽지 말고, `get_symbols_overview`와 `find_symbol`을 사용하여 필요한 부분만 확인하세요.
+
+### 3. 메모리 적극 활용
+
+중요한 결정, 아키텍처 정보, 작업 진행 상황을 메모리에 저장하여 세션 간 컨텍스트를 유지하세요.
+
+### 4. 사고 도구 활용
+
+복잡한 작업 중에는 `think_about_*` 도구를 사용하여 진행 상황을 검토하세요.
+
+---
+
+## 참고 자료
+
+- [Serena GitHub](https://github.com/oraios/serena)
+- [MCP Protocol](https://modelcontextprotocol.io)