8장: 컨텍스트 엔지니어링 도구와 기법

# Project: Kreath Archive
 
## Commands
pnpm dev          # dev server (port 3020, Turbopack)
pnpm build        # production build (MUST pass)
pnpm lint         # ESLint
 
## Critical Rules
1. TypeScript strict, NO 'any'
2. Components: function declarations (not arrow)
3. Styling: Tailwind + cn() only
4. No emojis anywhere
5. Korean 경어체 for content
 
## Structure
src/app/        - App Router pages
src/components/ - UI components (25+)
src/lib/        - Utilities, config
content/        - MDX content (tech, projects, books)
 
## Detailed Docs (read when needed)
- docs/architecture.md    - Project structure, data flow
- docs/design-system.md   - Colors, layout, animations
- docs/content-guide.md   - Frontmatter, MDX components
- docs/conventions.md     - TypeScript, CSS, Git conventions

// 1. 구체적인 파일 경로로 안내
// 나쁜 예: "인증 관련 코드를 수정해주세요"
// 좋은 예: "src/auth/middleware.ts의 verifyToken 함수를 수정해주세요"
 
// 2. 탐색 범위 제한
// 나쁜 예: "프로젝트에서 비슷한 패턴을 찾아주세요"
// 좋은 예: "src/components/ui/에서 Button.tsx와 비슷한 패턴을 찾아주세요"
 
// 3. 관련 파일 미리 언급
// 나쁜 예: "새 API 엔드포인트를 만들어주세요"
// 좋은 예: "src/app/api/users/route.ts를 참고하여 
//          src/app/api/posts/route.ts를 만들어주세요.
//          타입은 src/lib/types/post.ts를 사용합니다."

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo '변경 전 반드시 pnpm build 통과 확인 필요'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "pnpm lint --quiet 2>&1 | head -20"
      }
    ]
  }
}

@src/auth/middleware.ts    # 특정 파일
@src/auth/                 # 전체 디렉토리
@web Next.js middleware     # 웹 검색 결과
@docs express middleware    # 문서 검색
@codebase authentication    # 코드베이스 전체 검색

## API Route Pattern
 
이 프로젝트의 API 라우트는 다음 패턴을 따릅니다:
 
1. Zod로 입력 검증
2. 서비스 레이어에서 비즈니스 로직 처리
3. 일관된 에러 응답 형식
4. 타입 안전한 응답
 
참조: src/app/api/users/route.ts

@workspace 이 프로젝트에서 인증 미들웨어가 어떻게 구현되어 있는지 설명해주세요.
 
@workspace #file:src/auth/middleware.ts 이 파일의 verifyToken 함수를 
JWT 라이브러리 v5로 마이그레이션해주세요.
 
@workspace /fix 타입 에러를 수정해주세요.

[1. 역할 정의]
당신은 Next.js 16 + TypeScript 프로젝트의 시니어 개발자입니다.
 
[2. 프로젝트 컨텍스트]
프로젝트: 기술 블로그 + 포트폴리오 사이트
스택: Next.js App Router, Tailwind v4, MDX, Velite
구조: src/app(pages), src/components(ui), src/lib(utils), content(MDX)
 
[3. 현재 작업 대상]
파일: src/components/search/SearchBar.tsx
관련: src/lib/search.ts, src/components/ui/Input.tsx
 
[4. 기존 코드]
(현재 구현 코드)
 
[5. 구체적 요청]
검색 결과에 최근 검색 기록을 표시하는 기능을 추가해주세요.
- localStorage에 최근 5개 검색어 저장
- 개별 삭제와 전체 삭제 지원
- 기존 SearchBar의 스타일과 일관성 유지
 
[6. 제약사항]
- cn() 함수로 className 결합
- 이모지 사용 금지
- 접근성: 키보드 네비게이션 지원

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
 
const server = new McpServer({
  name: "project-context",
  version: "1.0.0",
});
 
// 프로젝트 아키텍처 정보 제공
server.tool(
  "get-architecture",
  "프로젝트의 아키텍처 정보를 반환합니다",
  { module: z.string().optional().describe("특정 모듈명") },
  async ({ module }) => {
    if (module) {
      return {
        content: [{
          type: "text",
          text: await getModuleArchitecture(module),
        }],
      };
    }
    return {
      content: [{
        type: "text",
        text: await getProjectArchitecture(),
      }],
    };
  }
);
 
// 관련 이슈 정보 제공
server.tool(
  "get-related-issues",
  "현재 작업과 관련된 이슈 정보를 반환합니다",
  { filePath: z.string().describe("작업 중인 파일 경로") },
  async ({ filePath }) => {
    const issues = await findRelatedIssues(filePath);
    return {
      content: [{
        type: "text",
        text: formatIssues(issues),
      }],
    };
  }
);
 
// DB 스키마 정보 제공
server.tool(
  "get-db-schema",
  "데이터베이스 테이블 스키마를 반환합니다",
  { tableName: z.string().describe("테이블명") },
  async ({ tableName }) => {
    const schema = await getTableSchema(tableName);
    return {
      content: [{
        type: "text",
        text: formatSchema(schema),
      }],
    };
  }
);

interface ContextPipeline {
  stages: ContextStage[];
}
 
interface ContextStage {
  name: string;
  condition: (task: Task) => boolean;
  gather: (task: Task) => Promise<ContextBlock>;
}
 
const pipeline: ContextPipeline = {
  stages: [
    {
      name: "project-rules",
      condition: () => true, // 항상 포함
      gather: async () => ({
        content: await readFile("CLAUDE.md"),
        priority: "critical",
      }),
    },
    {
      name: "target-code",
      condition: (task) => task.type !== "question",
      gather: async (task) => ({
        content: await readFiles(task.targetFiles),
        priority: "high",
      }),
    },
    {
      name: "dependencies",
      condition: (task) => task.type === "modify" || task.type === "create",
      gather: async (task) => ({
        content: await extractInterfaces(task.dependencies),
        priority: "medium",
      }),
    },
    {
      name: "tests",
      condition: (task) => task.type === "modify",
      gather: async (task) => ({
        content: await findRelatedTests(task.targetFiles),
        priority: "medium",
      }),
    },
    {
      name: "similar-code",
      condition: (task) => task.type === "create",
      gather: async (task) => ({
        content: await findSimilarImplementations(task.description),
        priority: "low",
      }),
    },
    {
      name: "error-context",
      condition: (task) => task.type === "fix",
      gather: async (task) => ({
        content: await getErrorContext(task.errorInfo),
        priority: "high",
      }),
    },
  ],
};
 
async function assembleContext(task: Task): Promise<Context> {
  const blocks: ContextBlock[] = [];
  
  for (const stage of pipeline.stages) {
    if (stage.condition(task)) {
      blocks.push(await stage.gather(task));
    }
  }
  
  // 우선순위에 따라 정렬 (U자형 배치)
  return orderByPriority(blocks);
}