feat(phase-5-3): Logger, Metrics, 알림 시스템 통합

Phase 5-3 모니터링 강화 작업의 통합을 완료했습니다.

변경사항:
- Logger 통합: console.log를 구조화된 로깅으로 전환 (9개 파일)
  - JSON 기반 로그, 환경별 자동 전환 (개발/프로덕션)
  - 타입 안전성 보장, 성능 측정 타이머 내장

- Metrics 통합: 실시간 성능 모니터링 시스템 연결 (3개 파일)
  - Circuit Breaker 상태 추적 (api_call_count, error_count, state)
  - Retry 재시도 횟수 추적 (retry_count)
  - OpenAI API 응답 시간 측정 (api_call_duration)

- 알림 통합: 장애 자동 알림 시스템 구현 (2개 파일)
  - Circuit Breaker OPEN 상태 → 관리자 Telegram 알림
  - 재시도 실패 → 관리자 Telegram 알림
  - Rate Limiting 적용 (1시간에 1회)

- 문서 업데이트:
  - CLAUDE.md: coder 에이전트 설명 강화 (20년+ 시니어 전문가)
  - README.md, docs/: 아키텍처 문서 추가

영향받은 파일: 16개 (수정 14개, 신규 2개)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
kappa
2026-01-19 21:23:38 +09:00
parent 410676e322
commit eee934391a
16 changed files with 675 additions and 777 deletions

View File

@@ -28,7 +28,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- 주요 디렉토리: `src/tools/`, `src/routes/`, `src/services/`
**사용 가능한 에이전트 타입:**
- `general-purpose`: 범용 작업, 코드 작성/수정
- `coder`: 20년 이상의 경험을 갖고 있는 시니어 코딩 전문가 (코드 작성/수정 최우선)
- TypeScript/Cloudflare Workers 구현 마스터
- 프로덕션 수준의 코드 품질 보장
- 엔터프라이즈급 에러 핸들링 및 타입 안정성
- 성능 최적화 및 베스트 프랙티스 적용
- `general-purpose`: 범용 작업 (coder 사용 불가 시 폴백)
- `Explore`: 프로젝트 구조 분석 (thorough 레벨)
- `Bash`: 빌드/배포/테스트 실행
@@ -36,12 +41,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
| 작업 유형 | 조건 | 에이전트 타입 | 이유 |
|-----------|------|---------------|------|
| **코드 작성/수정** | 모든 코드 변경 | `general-purpose` | 컨텍스트 절약, 독립 실행 |
| **리팩토링** | 파일 수 무관 | `general-purpose` (병렬) | 일관성, 컨텍스트 분리 |
| **Function Calling 도구** | 추가/수정 | `general-purpose` (병렬) | tools/ + openai-service.ts 동시 처리 |
| **스키마 작업** | D1 마이그레이션 | `general-purpose` | 백업→마이그레이션→검증 전체 위임 |
| **코드 작성/수정** | 모든 코드 변경 | `coder` | TS/Workers 전문, 타입 안정성, 프로덕션 품질 |
| **리팩토링** | 파일 수 무관 | `coder` (병렬) | 일관성, 컨텍스트 분리, TS 최적화 |
| **Function Calling 도구** | 추가/수정 | `coder` (병렬) | tools/ + openai-service.ts 동시 처리 |
| **스키마 작업** | D1 마이그레이션 | `coder` | 백업→마이그레이션→검증 전체 위임 |
| **프로젝트 분석** | 구조 파악 | `Explore` (thorough) | 대량 파일 읽기 분리 |
| **코드 리뷰** | 보안/성능 | `Explore` + `general-purpose` | 분석 후 개선 제안 |
| **코드 리뷰** | 보안/성능 | `Explore` + `coder` | 분석 후 개선 제안 |
| **빌드/배포** | npm run, wrangler | `Bash` | 긴 로그 출력 분리 |
| **테스트** | 로컬 테스트 실행 | `Bash` | 테스트 출력 분리 |
@@ -52,8 +57,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- ✅ 메인 세션은 조율/지시만 담당
**병렬 처리 필수:**
- 독립적인 파일 여러 개 → 병렬 general-purpose 에이전트
- 다른 디렉토리 동시 작업 → 병렬 general-purpose 에이전트
- 독립적인 파일 여러 개 → 병렬 `coder` 에이전트
- 다른 디렉토리 동시 작업 → 병렬 `coder` 에이전트
- Function Calling 도구 추가 → tools/{new}.ts + openai-service.ts 병렬
**예시:**
@@ -64,9 +69,10 @@ Edit src/tools/weather-tool.ts
Read src/openai-service.ts
Edit src/openai-service.ts
// ✅ 에이전트 사용 (컨텍스트 절약)
Task (subagent_type: "general-purpose", 2 )
// ✅ coder 에이전트 사용 (컨텍스트 절약 + 전문성)
Task (subagent_type: "coder", 2 )
TypeScript , Workers
```
**직접 처리 (최소화):**
@@ -176,20 +182,35 @@ curl https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info
### 에러 핸들링
```typescript
// 패턴: try-catch + 사용자 친화적 메시지
// 패턴: try-catch + 사용자 친화적 메시지 + 구조화된 로깅
import { createLogger } from './utils/logger';
const logger = createLogger('service-name');
try {
// 작업
} catch (error) {
console.error('[ServiceName] 작업 실패:', error);
logger.error('작업 실패', error as Error, { context: 'data' });
return '죄송합니다. 일시적인 오류가 발생했습니다.';
}
```
### 로깅 규칙
```typescript
console.log('[ServiceName] 동작 설명'); // 정상 동작
console.error('[ServiceName] 에러 설명:', error); // 에러
// 구조화된 로깅 (Phase 5-3에서 도입)
import { createLogger } from './utils/logger';
const logger = createLogger('service-name');
logger.info('동작 설명', { key: 'value' }); // 정상 동작
logger.error('에러 설명', error as Error); // 에러
logger.warn('경고 메시지', { context: 'data' }); // 경고
// 성능 측정
const end = logger.startTimer('작업 완료');
await doWork();
end(); // duration 자동 기록
// wrangler tail로 확인 가능
// 프로덕션: JSON 형식, 개발: 읽기 쉬운 형식 자동 전환
```
### 네이밍
@@ -431,6 +452,27 @@ Telegram Webhook → Security Validation → Command/Message Router
| `commands.ts` | 봇 명령어 | `handleCommand()` |
| `telegram.ts` | Telegram API | `sendMessage()`, `sendTypingAction()` |
**Logging & Monitoring (Phase 5-3):**
| 파일 | 역할 | 주요 기능 |
|------|------|----------|
| `utils/logger.ts` | 구조화된 로깅 | JSON 기반 로그, 환경별 전환 (개발/프로덕션) |
| `utils/metrics.ts` | 성능 메트릭 수집 | API 호출 시간, 에러율, Circuit Breaker 상태 |
| `utils/circuit-breaker.ts` | Circuit Breaker | OpenAI API 보호, 자동 복구 |
| `utils/retry.ts` | 재시도 로직 | 지수 백오프, 15개 API 지원 |
**Logger 사용 예시:**
```typescript
import { createLogger } from './utils/logger';
const logger = createLogger('openai');
logger.info('AI 응답 생성', { model: 'gpt-4o-mini' });
logger.error('API 호출 실패', error as Error, { retryCount: 3 });
const end = logger.startTimer('처리 완료');
await process();
end(); // duration 자동 기록
```
**Function Calling Tools (8개):**
| 도구 | 함수명 | 외부 API | 트리거 키워드 |
|------|--------|----------|---------------|