.context - 프로젝트 컨텍스트 관리

.context는 imprun 조직의 모든 레포지토리가 공유하는 개발 컨텍스트입니다. EPIC, Story, 진행상황을 문서로 관리하고 AI 에이전트가 효과적으로 활용할 수 있도록 구조화되어 있습니다.

빠른 시작

1. .context 클론

cd /path/to/your-project
git clone https://github.com/imprun/.context.git .context

2. Claude Code 명령어 설치

cd .context
node install.js

결과: .claude/commands/에 명령어 템플릿이 자동으로 복사됩니다.

3. 바로 사용 시작

claude
/create-epic

디렉토리 구조

.context/
├── README.md              # 이 파일
├── CLAUDE.md              # AI 에이전트 지침
├── package.json           # npm 패키지 정의
├── install.js             # 명령어 설치 스크립트
│
├── templates/
│   └── commands/          # Claude Code 명령어 템플릿
│       ├── create-epic.md
│       ├── start-epic.md
│       ├── daily-start.md
│       ├── daily-end.md
│       ├── weekly-report.md
│       ├── sync-progress.md
│       ├── catchup.md
│       └── sync-*-to-github.md
│
├── serena-sync/           # Serena MCP 연동
│   ├── sync-memory.js
│   └── README.md
│
├── imp-gateway/           # 프로젝트별 폴더
│   ├── progress.md        # 진행상황 추적
│   ├── epics/             # EPIC 문서
│   ├── stories/           # Story 상세
│   └── releases/          # 릴리즈 히스토리
│
├── imprun-agent/          # 다른 프로젝트
├── imprun-console/        # 다른 프로젝트
│
├── weekly/                # 조직 전체 주간보고
└── archive/               # 과거 분석 문서
    ├── imp-gateway/
    │   └── serena-*.md
    └── imprun-agent/

주요 개념

EPIC (Enhancement Proposal)

Kubernetes KEP 스타일의 큰 기능 단위 문서:

• 배경 (Background)
• 동기 (Motivation)
• 목표 (Goals & Non-Goals)
• 구현 세부사항 (Implementation Details)
• Mermaid 다이어그램 (User Flow, Architecture, Data Model)
• 테스트 계획 (Test Plan)

파일 위치: .context/{프로젝트}/epics/EPIC-XXX-*.md

예시:

.context/imp-gateway/epics/EPIC-025-tenant-user-management.md

Story (User Story)

EPIC을 구현 가능한 작은 단위로 분해:

• As a [user], I want [기능], So that [가치]
• Acceptance Criteria (Given/When/Then)
• Tasks (What만, How는 제외)

파일 위치: .context/{프로젝트}/stories/EPIC-XXX/story-Y.Y.md

Progress Tracking

Single Source of Truth로 Task 완료 상태 추적:

• Story 진행률 테이블
• Task 체크리스트
• 일일 로그

파일 위치: .context/{프로젝트}/progress.md

Claude Code 명령어

EPIC 관리

• /create-epic - 새 EPIC 문서 생성 (Mermaid 다이어그램 포함)
• /start-epic - EPIC을 Story로 분해
• /sync-epic-to-github - GitHub Issue로 동기화

일일 작업

• /daily-start - 어제 작업 이어받기 (Serena MCP 활용)
• /daily-end - 오늘 작업 정리 및 저장
• /sync-progress - 코드 변경사항과 progress.md 동기화

주간 보고

• /weekly-report - 주간보고 생성 (Serena 분석 포함)

선택적 명령어

• /catchup - 빠른 상태 확인 (auto compact 후 또는 컨텍스트 손실 시)

GitHub 동기화

• /sync-stories-to-github - Story를 GitHub Issues로
• /sync-progress-to-github - progress.md → GitHub Tasklist
• /generate-release-notes - 릴리즈 노트 자동 생성

Serena MCP 연동

Serena MCP는 Claude Code가 코드베이스를 분석하여 자동으로 프로젝트 지식을 생성합니다.

Serena Memory 보관

Serena의 분석 결과를 .context/archive/{프로젝트}/에 보관:

cd .context
node serena-sync/sync-memory.js

대화형 모드:

📋 5개 파일 발견:

  1. project-overview.md (2025-11-29, 12.3KB)
  2. auth-architecture.md (2025-11-28, 8.1KB)
  ...

보관할 파일 번호를 입력하세요 (예: 1,3,5 또는 all):

자동 모드 (최근 7일):

node serena-sync/sync-memory.js --auto

사용 예시

EPIC 생성 시:

/create-epic
# → Serena memories를 읽어 현재 시스템 상태 파악
# → Background 섹션에 "현재 시스템 상태" 자동 포함

주간보고 시:

cd .context
node serena-sync/sync-memory.js --auto

/weekly-report
# → Serena 분석 요약이 주간보고에 포함됨

GitHub 연동 워크플로우

하이브리드 접근 방식

.context (문서 기반) + GitHub Issues (팀 협업) 병행:

| 측면 | .context | GitHub Issues | |------|----------|---------------| | AI 친화성 | ✅ 구조화된 markdown | 일반 markdown | | 팀 협업 | 수동 공유 | ✅ 알림, 라벨, 마일스톤 | | 진행률 추적 | ✅ progress.md | Tasklist 진행률 | | 영구 보관 | ✅ Git 히스토리 | Issue는 Close 가능 |

동기화 워크플로우

# 1. EPIC 생성 및 동기화
/create-epic                    # EPIC 문서 작성
/sync-epic-to-github           # GitHub Issue #25 생성

# 2. Story 분해 및 동기화
/start-epic EPIC-025           # Story 파일 생성
/sync-stories-to-github EPIC-025  # Issues #26-30 생성 (sub-issues)

# 3. 일일 작업
/daily-end                     # progress.md 업데이트
/sync-progress-to-github       # GitHub Tasklist 동기화

# 4. 릴리즈
/generate-release-notes v0.1.0  # 릴리즈 노트 생성 (Draft)

Mermaid 다이어그램 가이드

다크 테마 색상 팔레트

EPIC 문서에 사용자 흐름을 시각화할 때 다크 테마용 색상 사용:

classDef darkNode fill:#2d2d2d,stroke:#4a9eff,stroke-width:2px,color:#e0e0e0
classDef darkDecision fill:#2d2d2d,stroke:#ffb86c,stroke-width:2px,color:#e0e0e0
classDef darkAPI fill:#1e3a5f,stroke:#4a9eff,stroke-width:2px,color:#e0e0e0
classDef darkDB fill:#2d1e3a,stroke:#bd93f9,stroke-width:2px,color:#e0e0e0
classDef darkExternal fill:#3a2d1e,stroke:#50fa7b,stroke-width:2px,color:#e0e0e0
classDef darkSuccess fill:#1e3a2d,stroke:#50fa7b,stroke-width:3px,color:#e0e0e0
classDef darkError fill:#3a1e1e,stroke:#ff5555,stroke-width:2px,color:#e0e0e0

다이어그램 종류

User Flow (필수):

flowchart TD
    Start([시작]):::darkNode --> Action[작업]:::darkNode
    Action --> Decision{조건}:::darkDecision
    Decision -->|성공| Success[완료]:::darkSuccess
    Decision -->|실패| Error[에러]:::darkError

System Architecture (시스템 변경 시):

graph TB
    Frontend[Frontend]:::darkNode --> API[API Server]:::darkAPI
    API --> DB[(Database)]:::darkDB
    API --> External[External Service]:::darkExternal

Data Model (DB 변경 시):

erDiagram
    Tenant ||--o{ User : has
    User ||--o{ Role : has

API Sequence (복잡한 API 흐름):

sequenceDiagram
    UI->>API: Request
    API->>DB: Query
    DB-->>API: Result
    API-->>UI: Response

모범 사례

1. 일일 작업 루틴

# 아침
/daily-start
# → 어제 진행 상황 복기
# → 오늘 목표 확인

# 코드 작성...

# 저녁
/daily-end
# → Task 체크
# → progress.md 업데이트

/sync-progress-to-github
# → GitHub 동기화

2. EPIC 작성 원칙

"Merge early and iterate":

• 최소 완성본으로 먼저 PR
• 팀 리뷰로 점진적 개선
• 미결 사항은 <<[UNRESOLVED]>> 표시

"What, not How":

• EPIC: 무엇을, 왜 (비즈니스 가치)
• Story: 구체적 What (API, UI)
• Code: How (구현)

Mermaid 다이어그램 포함:

• User Flow는 필수
• 복잡한 시스템은 Architecture Diagram 추가
• DB 변경은 Data Model Diagram 포함

3. Serena 활용

주기적 보관 (매주 금요일):

cd .context
node serena-sync/sync-memory.js --auto
git add archive/{프로젝트}/
git commit -m "docs: 주간 Serena 메모리 보관"
git push

중요 변경 전후:

# Before: 대규모 리팩토링 전
node serena-sync/sync-memory.js

# ... 리팩토링 ...

# After: 리팩토링 후
node serena-sync/sync-memory.js
# → 변경 전후 비교 가능

4. 커밋 및 푸시 습관

.context는 독립 Git 레포지토리이므로 별도 커밋 필요:

# 1. .context 내부 변경사항 커밋
cd .context
git add imp-gateway/progress.md epics/ stories/
git commit -m "docs(imp-gateway): EPIC-025 진행상황 업데이트"
git push

중요: 하루 작업 종료 시 반드시 push하여 다른 팀원과 공유하고 백업 유지!

문제 해결

Q: 명령어가 작동하지 않아요

A: 템플릿을 다시 설치하세요:

cd .context
node install.js

Q: Serena MCP란 무엇인가요?

A: Claude Code가 코드를 분석하여 프로젝트 지식을 자동 생성하는 도구입니다.

• 설치: https://github.com/oraios/serena
• .serena/memories/에 분석 결과 저장
• .context/archive/에 중요한 분석 보관

Q: GitHub Issues와 .context 중 어디에 우선순위가 있나요?

A: .context/progress.md가 Single Source of Truth입니다.

• progress.md 업데이트 → /sync-progress-to-github로 동기화
• GitHub에서 직접 체크박스 클릭은 권장하지 않음 (덮어씌워질 수 있음)

Q: 실수로 .context를 삭제했어요!

A: Git에서 복구하거나 리모트에서 다시 클론:

# Git 복구
git checkout HEAD -- .context/

# 또는 리모트에서 클론
git clone https://github.com/imprun/.context.git .context

예방: 작업 종료 시 항상 git push 습관화!

관련 문서

• CLAUDE.md: AI 에이전트 상세 지침
• serena-sync/README.md: Serena MCP 연동 가이드
• templates/README.md: 명령어 템플릿 관리

마지막 업데이트: 2025-11-29 관리: Imprun 조직 라이선스: MIT