Ch9. 컨텍스트 관리

# 특정 파일 참조
"이 컴포넌트를 수정해주세요: #File src/components/UserProfile.tsx"

# 여러 파일 참조
"다음 파일들을 참고해서 새로운 API를 만들어주세요:
#File src/api/users.ts
#File src/models/User.ts
#File docs/api-spec.yaml"

# 폴더 참조
"인증 관련 파일들을 검토해주세요: #Folder src/auth"

# 문서 첨부 (v0.11+)
# 채팅 입력 시 파일을 드래그 앤 드롭하거나 📎 버튼으로 첨부
# PDF, 이미지, 텍스트 파일 등 다양한 형식 지원

<!-- .kiro/steering/api-context.md -->
---
inclusion: fileMatch
fileMatchPattern: "src/api/**/*.ts"
---

# API 개발 컨텍스트

API 개발 시 다음 파일들을 참고하세요:

기본 스키마:
#[[file:docs/api-schema.yaml]]

공통 미들웨어:
#[[file:src/middleware/auth.ts]]
#[[file:src/middleware/validation.ts]]

타입 정의:
#[[file:src/types/api.ts]]

<!-- .kiro/steering/test-context.md -->
---
inclusion: fileMatch  
fileMatchPattern: "**/*.test.{ts,tsx,js,jsx}"
---

# 테스트 작성 컨텍스트

테스트 작성 시 다음 설정을 참고하세요:

Jest 설정:
#[[file:jest.config.js]]

테스트 유틸리티:
#[[file:src/test-utils/index.ts]]

Mock 데이터:
#[[file:src/__mocks__/data.ts]]

# Level 1: 핵심 컨텍스트 (항상 포함)
- 프로젝트 개요
- 기본 코딩 표준
- 현재 작업 목표

# Level 2: 도메인 컨텍스트 (조건부 포함)
- 특정 기능 관련 규칙
- 관련 파일 참조
- 기술 스택 세부사항

# Level 3: 세부 컨텍스트 (필요시에만 포함)
- 상세한 API 문서
- 복잡한 비즈니스 로직
- 레거시 코드 설명

<!-- .kiro/steering/dynamic-context.md -->
---
inclusion: manual
---

# 동적 컨텍스트

이 문서는 #dynamic-context로 참조할 때만 로드됩니다.

## 복잡한 비즈니스 로직
[상세한 설명...]

## 레거시 시스템 연동
[복잡한 연동 로직...]

## 성능 최적화 가이드
[세부적인 최적화 방법...]

# 요약된 형태로 정보 제공
## API 엔드포인트 (요약)
- GET /users - 사용자 목록
- POST /users - 사용자 생성  
- PUT /users/:id - 사용자 수정
- DELETE /users/:id - 사용자 삭제

# 필요시 상세 정보 참조
상세한 API 스펙: #[[file:docs/users-api.yaml]]

✅ 효율적인 참조:
"현재 작업과 관련된 핵심 파일만 참조"
- 수정할 대상 파일
- 직접적으로 연관된 파일
- 인터페이스/타입 정의 파일

❌ 비효율적인 참조:
"모든 관련 파일을 무작정 참조"
- 간접적으로만 연관된 파일
- 큰 설정 파일 전체
- 테스트 파일 (테스트 작성 시가 아닌 경우)

1단계: 최소 컨텍스트로 시작
"사용자 프로필 편집 기능을 만들어주세요."

2단계: 필요시 컨텍스트 추가
"기존 UserCard 컴포넌트와 비슷한 스타일로 만들어주세요."
#File src/components/UserCard.tsx

3단계: 세부 요구사항 추가
"폼 검증은 기존 패턴을 따라주세요."
#File src/utils/validation.ts

# 공통 컨텍스트를 Steering으로 관리
<!-- .kiro/steering/common-patterns.md -->
---
inclusion: always
---

# 공통 개발 패턴

## 에러 처리 패턴
```typescript
try {
  // 비즈니스 로직
} catch (error) {
  logger.error('Operation failed', { error, context });
  throw new AppError('User friendly message', error);
}

return {
  success: true,
  data: result,
  message: 'Operation completed successfully'
};

## 대화 히스토리 관리

### 1. 중요한 정보 요약

```markdown
# 긴 대화 후 중간 요약
"지금까지 다음 작업들을 완료했습니다:
1. 사용자 인증 API 구현 ✅
2. JWT 토큰 관리 로직 추가 ✅  
3. 프론트엔드 로그인 폼 작성 ✅

다음으로 비밀번호 재설정 기능을 구현해주세요."

# 새로운 주제로 전환할 때
"이전 작업은 완료되었고, 이제 새로운 기능을 시작하겠습니다.
상품 관리 시스템을 구현해주세요."

# 또는 새 세션 시작
"새로운 세션을 시작하여 독립적인 컨텍스트에서 작업하겠습니다."

# Steering 파일로 지속적인 컨텍스트 유지
<!-- .kiro/steering/current-sprint.md -->
---
inclusion: always
---

# 현재 스프린트 목표

## 이번 주 목표
- 사용자 인증 시스템 완성
- 상품 카탈로그 API 구현
- 기본 UI 컴포넌트 라이브러리 구축

## 완료된 작업
- ✅ 프로젝트 초기 설정
- ✅ 데이터베이스 스키마 설계
- ✅ 기본 API 구조 구현

## 진행 중인 작업
- 🔄 JWT 인증 미들웨어
- 🔄 React 컴포넌트 구조 설계

# 기능 개발 템플릿
<!-- .kiro/steering/feature-template.md -->
---
inclusion: manual
---

# 새 기능 개발 체크리스트

## 1. 요구사항 분석
- [ ] 사용자 스토리 정의
- [ ] 기술적 요구사항 파악
- [ ] 의존성 분석

## 2. 설계
- [ ] API 인터페이스 설계
- [ ] 데이터 모델 설계  
- [ ] UI/UX 와이어프레임

## 3. 구현
- [ ] 백엔드 로직 구현
- [ ] 프론트엔드 구현
- [ ] 통합 테스트

## 4. 검증
- [ ] 단위 테스트 작성
- [ ] 통합 테스트 실행
- [ ] 사용자 테스트

참고 파일:
#[[file:docs/development-process.md]]

# 프로젝트 컨텍스트 인덱스
<!-- .kiro/steering/context-index.md -->
---
inclusion: always
---

# 컨텍스트 빠른 참조

## 인증 관련
- 기본 설정: #auth-config
- API 문서: #auth-api  
- 보안 가이드: #auth-security

## 데이터베이스 관련
- 스키마: #db-schema
- 마이그레이션: #db-migration
- 쿼리 최적화: #db-optimization

## UI 컴포넌트 관련
- 디자인 시스템: #ui-design-system
- 컴포넌트 가이드: #ui-components
- 스타일 가이드: #ui-styles

사용법: 필요한 컨텍스트를 #키워드로 요청
예: "인증 API 문서를 참고해주세요 #auth-api"

# 작업 유형에 따른 자동 컨텍스트 조정
<!-- .kiro/steering/adaptive-context.md -->
---
inclusion: fileMatch
fileMatchPattern: "src/**/*.{ts,tsx}"
---

# 적응형 컨텍스트

현재 파일 유형에 따라 관련 컨텍스트를 자동 로드합니다.

## TypeScript 파일 작업 시
- 타입 정의: #[[file:src/types/index.ts]]
- 유틸리티 함수: #[[file:src/utils/index.ts]]
- 설정 파일: #[[file:tsconfig.json]]

## React 컴포넌트 작업 시  
- 공통 컴포넌트: #[[file:src/components/common/index.ts]]
- 스타일 가이드: #[[file:src/styles/theme.ts]]
- 훅 라이브러리: #[[file:src/hooks/index.ts]]

## API 파일 작업 시
- 미들웨어: #[[file:src/middleware/index.ts]]
- 에러 핸들링: #[[file:src/utils/errors.ts]]
- 검증 스키마: #[[file:src/schemas/index.ts]]

# 컨텍스트 사용량 확인
"현재 컨텍스트 사용량을 보여주세요"

결과:
- 총 토큰 수: 45,000 / 100,000
- Steering 파일: 15,000 토큰
- 참조 파일: 20,000 토큰  
- 대화 히스토리: 10,000 토큰

# 필요할 때만 상세 정보 로드
"기본적인 사용자 CRUD API를 만들어주세요"
→ 기본 컨텍스트만 사용

"복잡한 권한 시스템이 포함된 사용자 API를 만들어주세요 #auth-security"
→ 보안 관련 상세 컨텍스트 추가 로드

# 자주 사용되는 컨텍스트는 Steering으로 고정
<!-- .kiro/steering/frequently-used.md -->
---
inclusion: always
---

# 자주 참조되는 정보

## 공통 타입 정의
```typescript
interface ApiResponse<T> {
  success: boolean;
  data: T;
  message: string;
  errors?: string[];
}

interface PaginatedResponse<T> extends ApiResponse<T[]> {
  pagination: {
    page: number;
    limit: number;
    total: number;
  };
}

const handleApiError = (error: unknown): ApiResponse<null> => {
  // 에러 처리 로직
};

## 모범 사례

### 1. 컨텍스트 계층화

```markdown
Level 1 (항상 포함): 프로젝트 기본 정보
Level 2 (조건부): 기능별 상세 정보  
Level 3 (요청시): 복잡한 비즈니스 로직
Level 4 (참조시): 레거시 코드, 외부 문서

주간 컨텍스트 리뷰:
- 사용되지 않는 Steering 파일 제거
- 오래된 참조 파일 업데이트
- 중복된 정보 통합
- 컨텍스트 구조 최적화

팀 컨텍스트 가이드라인:
- Steering 파일 명명 규칙
- 파일 참조 패턴 통일
- 컨텍스트 우선순위 합의
- 정기적인 동기화 프로세스