9장: 프로젝트 메모리와 코딩 에이전트

# 프로젝트명 -- CLAUDE.md
 
## 프로젝트 개요
한두 문장으로 프로젝트의 목적과 성격을 설명합니다.
 
## 기술 스택
프레임워크, 언어, 주요 라이브러리를 표로 정리합니다.
 
## 개발 명령어
빌드, 테스트, 린트 등 핵심 명령어를 나열합니다.
 
## 프로젝트 구조
주요 디렉토리와 파일의 역할을 설명합니다.
 
## 핵심 규칙
절대 지켜야 할 규칙을 명시합니다. (예: TypeScript strict, 이모지 금지 등)
 
## 코딩 컨벤션
네이밍, 임포트 순서, 스타일 가이드를 기술합니다.
 
## 참조 문서
상세 정보가 담긴 문서 경로를 안내합니다.

1. 간결성 우선
   - 전체 파일이 2,000-5,000 토큰을 넘지 않도록 합니다
   - 에이전트의 컨텍스트 예산을 과도하게 소비하지 않아야 합니다
   - 상세 내용은 별도 문서로 분리하고 경로만 안내합니다
 
2. 규칙의 명확성
   - "가능하면 ~하세요" 대신 "반드시 ~합니다" 형태로 작성합니다
   - 예외 조건이 있다면 명시적으로 기술합니다
   - 규칙의 이유를 간략히 설명하면 에이전트의 준수율이 높아집니다
 
3. 계층적 구조
   - CLAUDE.md: 프로젝트 전체에 적용되는 핵심 정보
   - docs/*.md: 특정 영역의 상세 참조 문서
   - 에이전트가 필요에 따라 참조 문서를 읽도록 안내합니다
 
4. 실행 가능한 명령어 포함
   - "빌드는 pnpm build"처럼 바로 실행할 수 있는 형태로 기술합니다
   - 환경 변수나 사전 조건이 있다면 함께 명시합니다

interface CodebaseMemory {
  // 파일별 요약 -- 에이전트가 파일을 읽을 때마다 갱신
  fileSummaries: Map<string, FileSummary>;
 
  // 의존 관계 그래프
  dependencyGraph: DependencyEdge[];
 
  // 학습된 패턴 -- 코드베이스에서 반복되는 패턴
  learnedPatterns: CodePattern[];
 
  // 변경 이력 -- 최근 세션에서 수행한 변경
  recentChanges: ChangeRecord[];
}
 
interface FileSummary {
  path: string;
  purpose: string;          // 파일의 역할
  exports: string[];        // 주요 내보내기
  dependencies: string[];   // 주요 의존성
  lastAnalyzed: number;     // 마지막 분석 시점
}
 
interface CodePattern {
  name: string;
  description: string;
  examples: string[];       // 패턴이 사용된 파일 경로들
  frequency: number;        // 발견 빈도
}

class ProjectMemoryUpdater {
  async onFileRead(filePath: string, content: string): Promise<void> {
    // 파일 요약 생성/갱신
    const summary = await this.summarizeFile(filePath, content);
    await this.memoryStore.updateFileSummary(filePath, summary);
  }
 
  async onFileEdit(
    filePath: string,
    changes: string,
    reason: string
  ): Promise<void> {
    // 변경 기록 저장
    await this.memoryStore.addChangeRecord({
      filePath,
      changes,
      reason,
      timestamp: Date.now(),
      sessionId: this.currentSession.id,
    });
 
    // 관련 파일 요약 무효화
    const dependents = await this.findDependentFiles(filePath);
    for (const dep of dependents) {
      await this.memoryStore.invalidateFileSummary(dep);
    }
  }
 
  async onBuildResult(
    success: boolean,
    errors: string[]
  ): Promise<void> {
    if (!success) {
      // 빌드 실패 패턴 기록 -- 같은 실수 반복 방지
      await this.memoryStore.addLearnedPattern({
        name: "build_failure",
        description: `빌드 실패: ${errors[0]}`,
        resolution: "", // 해결 후 채워짐
        timestamp: Date.now(),
      });
    }
  }
}

project-root/
  CLAUDE.md                    # L0: 핵심 프로젝트 정보
  docs/
    architecture.md            # L1: 아키텍처 상세
    conventions.md             # L1: 코딩 컨벤션 상세
    design-system.md           # L1: 디자인 시스템 상세
  .claude/
    memory/
      MEMORY.md                # 자동 메모리 (에이전트가 갱신)
      user-preferences.md      # 사용자별 선호도
      project-decisions.md     # 의사결정 이력

# 자동 메모리
 
## 학습된 사실
- 이 프로젝트는 pnpm을 사용한다
- 빌드 전 반드시 Velite를 먼저 실행해야 한다
- globals.css에서 CSS 변수를 정의하고 Tailwind에서 참조한다
 
## 사용자 선호도
- TypeScript strict 모드를 선호한다
- 이모지를 사용하지 않는다
- 함수 선언(function) 형태를 선호한다
 
## 최근 작업 맥락
- 검색 기능에 최근 검색어 localStorage 저장 추가 (2026-03-28)
- 포스트 네비게이션에 화살표 아이콘 애니메이션 추가 (2026-03-27)

# 의사결정 기록
 
## 2026-03-15: CSS 프레임워크 선택
- 결정: Tailwind CSS v4
- 대안: CSS Modules, styled-components
- 이유: 유틸리티 우선 접근법이 빠른 개발에 적합, v4의 새 설정 방식 채택
- 영향: 모든 스타일링은 Tailwind 클래스로, 커스텀 프로퍼티는 globals.css에서 관리
 
## 2026-03-18: 콘텐츠 관리 방식
- 결정: MDX + Velite (git 기반)
- 대안: CMS (Sanity, Notion API)
- 이유: 버전 관리, 마크다운 익숙함, 빌드 시 타입 안전성
- 영향: 콘텐츠는 content/ 디렉토리에, 스키마는 velite.config.ts에서 관리

interface TeamMemoryEntry {
  content: string;
  author: string;
  createdAt: number;
  endorsedBy: string[];  // 동의한 팀원 목록
  category: "convention" | "decision" | "pattern" | "faq";
}
 
// 팀 메모리는 충돌이 발생할 수 있음
// 병합 전략이 필요
function resolveConflict(
  existing: TeamMemoryEntry,
  incoming: TeamMemoryEntry
): TeamMemoryEntry {
  // 더 많은 팀원이 동의한 항목 우선
  if (incoming.endorsedBy.length > existing.endorsedBy.length) {
    return incoming;
  }
 
  // 동일하면 최신 항목 우선
  if (incoming.createdAt > existing.createdAt) {
    return incoming;
  }
 
  return existing;
}

우선순위 (높은 것부터):
1. 현재 세션의 명시적 지시사항
2. 프로젝트 CLAUDE.md의 절대 규칙
3. 사용자 개인 메모리 (선호도)
4. 팀 메모리 (컨벤션, 결정)
5. 조직 메모리 (정책, 표준)
6. 에이전트의 기본 행동
 
충돌 시:
- 상위 우선순위가 하위를 덮어씁니다
- 명시적 지시가 암묵적 학습을 덮어씁니다
- 팀 컨벤션이 개인 선호도를 덮어씁니다 (코드 품질 관련)

interface MemoryAudit {
  totalEntries: number;
  staleEntries: number;      // 마지막 참조가 30일 이상 된 항목
  conflictingEntries: number; // 서로 모순되는 항목
  duplicateEntries: number;   // 중복 항목
  suggestions: string[];      // 정리 제안
}
 
async function auditProjectMemory(
  memoryStore: ProjectMemoryStore
): Promise<MemoryAudit> {
  const allEntries = await memoryStore.getAll();
 
  const stale = allEntries.filter(
    (e) => Date.now() - e.lastAccessed > 30 * 24 * 60 * 60 * 1000
  );
 
  const conflicts = findConflicts(allEntries);
  const duplicates = findDuplicates(allEntries);
 
  const suggestions: string[] = [];
  if (stale.length > allEntries.length * 0.3) {
    suggestions.push("30% 이상의 메모리가 30일간 미참조 -- 정리를 권장합니다");
  }
  if (conflicts.length > 0) {
    suggestions.push(`${conflicts.length}건의 모순된 메모리가 발견되었습니다`);
  }
 
  return {
    totalEntries: allEntries.length,
    staleEntries: stale.length,
    conflictingEntries: conflicts.length,
    duplicateEntries: duplicates.length,
    suggestions,
  };
}