10장: 실전 프로젝트 -- 컨텍스트 엔지니어링 시스템 구축

# My Project
 
## Commands
npm run dev       # dev server (port 3000)
npm run build     # production build (MUST pass before commit)
npm run test      # run tests
npm run lint      # ESLint + Prettier
 
## Critical Rules
1. TypeScript strict mode, NO 'any' or 'as any'
2. All components: named function declarations
3. Styling: Tailwind CSS only, use cn() for merging
4. Error handling: always use AppError class hierarchy
5. API responses: use ApiResponse<T> wrapper type
6. Database: all queries through repository pattern
 
## Architecture
src/
  app/           - Next.js App Router pages
  components/
    ui/          - Reusable UI primitives (Button, Input, Modal)
    features/    - Feature-specific components
  lib/
    db/          - Database client, repositories
    auth/        - Authentication utilities
    api/         - API client, types
  types/         - Shared TypeScript types
 
## Patterns (follow existing code)
- API route: src/app/api/users/route.ts (reference)
- Component: src/components/ui/Button.tsx (reference)
- Repository: src/lib/db/user-repository.ts (reference)
- Test: src/lib/db/__tests__/user-repository.test.ts (reference)
 
## Detailed Docs
- docs/architecture.md - Full architecture, data flow
- docs/api-guide.md    - API conventions, error codes
- docs/testing.md      - Test patterns, fixtures

# Database Layer
 
## Repository Pattern
- All database access through repository classes
- Each repository implements IRepository<T> interface
- Use Drizzle ORM query builder, NOT raw SQL
- All queries must have proper error handling with DBError
 
## Naming
- File: {entity}-repository.ts
- Class: {Entity}Repository
- Method: findById, findMany, create, update, delete
 
## Testing
- Use test fixtures from src/lib/db/__fixtures__/
- Mock database with in-memory SQLite
- Every repository method needs a test

# Components
 
## Structure
- UI primitives in ui/ (no business logic)
- Feature components in features/ (can use hooks, API calls)
- Each component: one file, named export
 
## Styling
- Use cn() for className merging (import from "@/lib/utils")
- Follow design tokens in globals.css
- Dark mode: use CSS custom properties, NOT conditional classes
- Responsive: mobile-first approach
 
## Accessibility
- All interactive elements: keyboard navigable
- Images: always include alt text
- Form inputs: always include label

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { execSync } from "child_process";
import { readFileSync, existsSync } from "fs";
import { join } from "path";
 
const server = new McpServer({
  name: "project-context-server",
  version: "1.0.0",
});
 
// 도구 1: 모듈 아키텍처 정보
server.tool(
  "get-module-info",
  "특정 모듈의 아키텍처, 의존성, 주요 파일 정보를 반환합니다",
  {
    modulePath: z.string().describe("모듈 경로 (예: src/lib/auth)"),
  },
  async ({ modulePath }) => {
    const info = analyzeModule(modulePath);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(info, null, 2),
      }],
    };
  }
);
 
// 도구 2: 최근 변경 영향 분석
server.tool(
  "analyze-recent-changes",
  "최근 N개 커밋의 변경 파일과 영향 범위를 분석합니다",
  {
    count: z.number().default(5).describe("분석할 커밋 수"),
    path: z.string().optional().describe("특정 경로로 필터링"),
  },
  async ({ count, path }) => {
    const gitLog = execSync(
      `git log --oneline --name-only -${count} ${path ? `-- ${path}` : ""}`,
      { encoding: "utf-8" }
    );
    
    return {
      content: [{
        type: "text",
        text: `최근 ${count}개 커밋의 변경 파일:\n\n${gitLog}`,
      }],
    };
  }
);
 
// 도구 3: 의존성 그래프
server.tool(
  "get-dependency-graph",
  "파일의 import/export 의존성 그래프를 반환합니다",
  {
    filePath: z.string().describe("분석할 파일 경로"),
    depth: z.number().default(2).describe("추적 깊이"),
  },
  async ({ filePath, depth }) => {
    const graph = buildDependencyGraph(filePath, depth);
    return {
      content: [{
        type: "text",
        text: formatDependencyGraph(graph),
      }],
    };
  }
);
 
// 도구 4: 테스트 커버리지 정보
server.tool(
  "get-test-coverage",
  "특정 파일이나 모듈의 테스트 커버리지 정보를 반환합니다",
  {
    path: z.string().describe("파일 또는 모듈 경로"),
  },
  async ({ path }) => {
    const coverage = getTestCoverage(path);
    return {
      content: [{
        type: "text",
        text: formatCoverage(coverage),
      }],
    };
  }
);
 
// 헬퍼 함수들
function analyzeModule(modulePath: string) {
  const fullPath = join(process.cwd(), modulePath);
  
  if (!existsSync(fullPath)) {
    return { error: `경로를 찾을 수 없습니다: ${modulePath}` };
  }
  
  const files = execSync(`find ${fullPath} -name "*.ts" -o -name "*.tsx"`, {
    encoding: "utf-8",
  }).trim().split("\n");
  
  const exports = files.flatMap(file => {
    const content = readFileSync(file, "utf-8");
    const matches = content.match(/export\s+(function|class|const|interface|type)\s+(\w+)/g);
    return (matches ?? []).map(m => ({
      file: file.replace(process.cwd() + "/", ""),
      export: m,
    }));
  });
  
  return {
    path: modulePath,
    fileCount: files.length,
    exports,
    hasTests: existsSync(join(fullPath, "__tests__")),
    hasCLAUDEmd: existsSync(join(fullPath, "CLAUDE.md")),
  };
}
 
function buildDependencyGraph(filePath: string, depth: number) {
  // 간략화된 구현 - 실제로는 TypeScript Compiler API 사용
  const content = readFileSync(filePath, "utf-8");
  const imports = [...content.matchAll(/from\s+["']([^"']+)["']/g)]
    .map(m => m[1])
    .filter(imp => imp.startsWith(".") || imp.startsWith("@/"));
  
  return { file: filePath, imports, depth };
}
 
function formatDependencyGraph(graph: { file: string; imports: string[] }) {
  let result = `${graph.file}\n`;
  for (const imp of graph.imports) {
    result += `  -> ${imp}\n`;
  }
  return result;
}
 
function getTestCoverage(path: string) {
  // 실제 구현에서는 coverage report 파싱
  return { path, coverage: "N/A - run npm run test:coverage first" };
}
 
function formatCoverage(coverage: { path: string; coverage: string }) {
  return `${coverage.path}: ${coverage.coverage}`;
}
 
// 서버 시작
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}
 
main().catch(console.error);

{
  "mcpServers": {
    "project-context": {
      "command": "npx",
      "args": ["tsx", "mcp-servers/project-context/index.ts"]
    }
  }
}

const agentContexts = {
  coder: {
    shared: ["CLAUDE.md", "프로젝트 구조"],
    dedicated: {
      files: ["대상 모듈 코드", "관련 타입 정의", "참조 패턴 파일"],
      tools: ["read", "write", "edit", "grep", "glob", "terminal"],
      instructions: "코드를 작성/수정합니다. 기존 패턴을 따르세요.",
    },
  },
  
  tester: {
    shared: ["CLAUDE.md", "테스트 컨벤션"],
    dedicated: {
      files: ["테스트 대상 코드(인터페이스)", "기존 테스트 패턴", "테스트 픽스처"],
      tools: ["read", "write", "terminal"],
      instructions: "단위 테스트를 작성합니다. 기존 테스트 패턴을 따르세요.",
    },
  },
  
  reviewer: {
    shared: ["CLAUDE.md", "코딩 컨벤션"],
    dedicated: {
      files: ["변경된 코드 diff", "아키텍처 문서", "관련 모듈 인터페이스"],
      tools: ["read", "grep"],
      instructions: "코드를 리뷰하고 개선사항을 제안합니다.",
    },
  },
  
  analyzer: {
    shared: ["CLAUDE.md", "프로젝트 구조"],
    dedicated: {
      files: ["대상 모듈 전체", "의존성 그래프"],
      tools: ["read", "grep", "glob", "get-dependency-graph", "analyze-recent-changes"],
      instructions: "변경 영향을 분석하고 리팩토링 계획을 수립합니다.",
    },
  },
};

interface ContextMetric {
  timestamp: Date;
  taskId: string;
  taskType: string;
  
  // 컨텍스트 메트릭
  contextTokens: number;
  contextFiles: number;
  compressionRatio: number;
  
  // 결과 메트릭
  success: boolean;
  firstAttempt: boolean;
  iterationCount: number;
  buildPassed: boolean;
  testsPassed: boolean;
  
  // 효율성 메트릭
  totalCost: number;
  responseTimeMs: number;
}
 
class MetricsCollector {
  private metrics: ContextMetric[] = [];
  private storagePath: string;
  
  constructor(storagePath: string = ".claude/metrics.jsonl") {
    this.storagePath = storagePath;
  }
  
  record(metric: ContextMetric): void {
    this.metrics.push(metric);
    // JSONL 형식으로 추가 기록
    appendFileSync(
      this.storagePath,
      JSON.stringify(metric) + "\n"
    );
  }
  
  generateReport(period: "day" | "week" | "month"): Report {
    const filtered = this.filterByPeriod(period);
    
    return {
      period,
      totalTasks: filtered.length,
      successRate: this.calcRate(filtered, m => m.success),
      firstAttemptRate: this.calcRate(filtered, m => m.firstAttempt),
      avgCost: this.calcAvg(filtered, m => m.totalCost),
      avgTokens: this.calcAvg(filtered, m => m.contextTokens),
      avgIterations: this.calcAvg(filtered, m => m.iterationCount),
      costPerSuccess: this.calcCostPerSuccess(filtered),
      
      // 작업 유형별 분석
      byTaskType: this.groupBy(filtered, m => m.taskType),
      
      // 트렌드
      trend: this.calculateTrend(filtered),
    };
  }
  
  private calcRate(metrics: ContextMetric[], predicate: (m: ContextMetric) => boolean): number {
    if (metrics.length === 0) return 0;
    return metrics.filter(predicate).length / metrics.length;
  }
  
  private calcAvg(metrics: ContextMetric[], selector: (m: ContextMetric) => number): number {
    if (metrics.length === 0) return 0;
    return metrics.reduce((sum, m) => sum + selector(m), 0) / metrics.length;
  }
  
  private calcCostPerSuccess(metrics: ContextMetric[]): number {
    const successful = metrics.filter(m => m.success);
    if (successful.length === 0) return 0;
    return successful.reduce((sum, m) => sum + m.totalCost, 0) / successful.length;
  }
  
  private filterByPeriod(period: string): ContextMetric[] {
    // 기간별 필터링 구현
    return this.metrics;
  }
  
  private groupBy(metrics: ContextMetric[], key: (m: ContextMetric) => string) {
    const groups = new Map<string, ContextMetric[]>();
    for (const m of metrics) {
      const k = key(m);
      if (!groups.has(k)) groups.set(k, []);
      groups.get(k)?.push(m);
    }
    return Object.fromEntries(groups);
  }
  
  private calculateTrend(metrics: ContextMetric[]) {
    // 시간에 따른 성공률 변화 추적
    return { direction: "stable" as const };
  }
}

=== 컨텍스트 엔지니어링 주간 리포트 ===
기간: 2026-03-29 ~ 2026-04-05
 
총 태스크: 47건
성공률: 87.2% (41/47)
첫 시도 성공률: 72.3% (34/47)
 
평균 컨텍스트 토큰: 28,450
평균 비용: $0.12/태스크
성공 건당 비용: $0.14
 
작업 유형별:
  create: 93.3% (14/15)
  modify: 85.0% (17/20)
  fix:    83.3% (10/12)
 
전주 대비:
  성공률: +3.2%p
  비용: -8.5%
  첫 시도 성공률: +5.1%p
 
개선 제안:
  - fix 유형 성공률이 낮음 -> 에러 컨텍스트 강화 권장
  - modify 유형에서 테스트 관련 실패 빈발 -> 테스트 컨텍스트 추가 권장