oh-my-customcodex 0.1.0

package/templates/guides/claude-code/06-mcp.md

@@ -0,0 +1,165 @@
+# MCP 커넥터
+
+Claude의 Model Context Protocol (MCP) 커넥터 기능을 사용하여 Messages API에서 별도의 MCP 클라이언트 없이 원격 MCP 서버에 직접 연결할 수 있습니다.
+
+## 주요 기능
+
+- **직접 API 통합**: MCP 클라이언트를 구현하지 않고도 MCP 서버에 연결
+- **도구 호출 지원**: Messages API를 통해 MCP 도구에 액세스
+- **유연한 도구 구성**: 모든 도구 활성화, 특정 도구 허용 목록 작성 또는 원하지 않는 도구 거부 목록 작성
+- **도구별 구성**: 사용자 정의 설정으로 개별 도구 구성
+- **OAuth 인증**: 인증된 서버를 위한 OAuth Bearer 토큰 지원
+- **여러 서버**: 단일 요청에서 여러 MCP 서버에 연결
+
+## 제한 사항
+
+- MCP 사양의 기능 집합 중 도구 호출만 현재 지원
+- 서버는 HTTP를 통해 공개적으로 노출되어야 함 (Streamable HTTP 및 SSE 전송 모두 지원)
+- 로컬 STDIO 서버는 직접 연결할 수 없음
+- Amazon Bedrock 및 Google Vertex에서 현재 지원되지 않음
+
+## 기본 예제
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+response = client.beta.messages.create(
+    model="claude-sonnet-4-5",
+    max_tokens=1000,
+    messages=[{
+        "role": "user",
+        "content": "What tools do you have available?"
+    }],
+    mcp_servers=[{
+        "type": "url",
+        "url": "https://mcp.example.com/sse",
+        "name": "example-mcp",
+        "authorization_token": "YOUR_TOKEN"
+    }],
+    tools=[{
+        "type": "mcp_toolset",
+        "mcp_server_name": "example-mcp"
+    }],
+    betas=["mcp-client-2025-11-20"]
+)
+```
+
+## MCP 서버 구성
+
+| 속성 | 유형 | 필수 | 설명 |
+|------|------|------|------|
+| `type` | string | 예 | 현재 "url"만 지원 |
+| `url` | string | 예 | MCP 서버의 URL (https://로 시작) |
+| `name` | string | 예 | 이 MCP 서버의 고유 식별자 |
+| `authorization_token` | string | 아니오 | OAuth 인증 토큰 |
+
+## MCP 도구 집합 구성
+
+```json
+{
+  "type": "mcp_toolset",
+  "mcp_server_name": "example-mcp",
+  "default_config": {
+    "enabled": true,
+    "defer_loading": false
+  },
+  "configs": {
+    "specific_tool_name": {
+      "enabled": true,
+      "defer_loading": true
+    }
+  }
+}
+```
+
+## 일반적인 구성 패턴
+
+### 모든 도구 활성화
+
+```json
+{
+  "type": "mcp_toolset",
+  "mcp_server_name": "google-calendar-mcp"
+}
+```
+
+### 허용 목록 - 특정 도구만 활성화
+
+```json
+{
+  "type": "mcp_toolset",
+  "mcp_server_name": "google-calendar-mcp",
+  "default_config": {
+    "enabled": false
+  },
+  "configs": {
+    "search_events": { "enabled": true },
+    "create_event": { "enabled": true }
+  }
+}
+```
+
+### 거부 목록 - 특정 도구 비활성화
+
+```json
+{
+  "type": "mcp_toolset",
+  "mcp_server_name": "google-calendar-mcp",
+  "configs": {
+    "delete_all_events": { "enabled": false },
+    "share_calendar_publicly": { "enabled": false }
+  }
+}
+```
+
+## 응답 콘텐츠 유형
+
+### MCP 도구 사용 블록
+
+```json
+{
+  "type": "mcp_tool_use",
+  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
+  "name": "echo",
+  "server_name": "example-mcp",
+  "input": { "param1": "value1" }
+}
+```
+
+### MCP 도구 결과 블록
+
+```json
+{
+  "type": "mcp_tool_result",
+  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
+  "is_error": false,
+  "content": [{ "type": "text", "text": "Hello" }]
+}
+```
+
+## 여러 MCP 서버 연결
+
+```json
+{
+  "mcp_servers": [
+    {
+      "type": "url",
+      "url": "https://mcp.example1.com/sse",
+      "name": "mcp-server-1",
+      "authorization_token": "TOKEN1"
+    },
+    {
+      "type": "url",
+      "url": "https://mcp.example2.com/sse",
+      "name": "mcp-server-2",
+      "authorization_token": "TOKEN2"
+    }
+  ],
+  "tools": [
+    { "type": "mcp_toolset", "mcp_server_name": "mcp-server-1" },
+    { "type": "mcp_toolset", "mcp_server_name": "mcp-server-2" }
+  ]
+}
+```

package/templates/guides/claude-code/07-prompt-engineering.md

@@ -0,0 +1,100 @@
+# 프롬프트 엔지니어링 개요
+
+프롬프트 엔지니어링 기법을 사용하여 Claude의 성능을 최적화하는 방법을 알아봅니다.
+
+## 프롬프트 엔지니어링 전에
+
+이 가이드는 다음을 가정합니다:
+1. 사용 사례에 대한 명확한 성공 기준 정의
+2. 해당 기준에 대해 경험적으로 테스트할 수 있는 방법
+3. 개선하고 싶은 첫 번째 초안 프롬프트
+
+## 프롬프팅 vs. 파인튜닝
+
+프롬프트 엔지니어링이 파인튜닝보다 나은 이유:
+
+- **리소스 효율성**: 텍스트 입력만 필요
+- **비용 효율성**: 기본 모델을 사용하므로 더 저렴
+- **모델 업데이트 유지**: 프롬프트는 일반적으로 변경 없이 버전 간에 작동
+- **시간 절약**: 거의 즉각적인 결과
+- **최소한의 데이터 필요**: 소수 샷 또는 제로 샷 학습으로도 작동
+- **유연성 및 빠른 반복**: 다양한 접근 방식을 빠르게 시도
+- **도메인 적응**: 재학습 없이 프롬프트에 도메인별 컨텍스트 제공
+- **이해도 개선**: 외부 콘텐츠를 모델이 더 잘 이해하도록 도움
+- **일반 지식 보존**: 모델의 광범위한 기능을 유지
+- **투명성**: 프롬프트는 인간이 읽을 수 있음
+
+## 프롬프트 엔지니어링 기법
+
+가장 광범위하게 효과적인 기법부터 더 전문화된 기법까지:
+
+### 1. 프롬프트 생성기
+첫 번째 초안 프롬프트가 없다면 Claude 콘솔에서 프롬프트 생성기를 사용하세요.
+
+### 2. 명확하고 직접적으로
+Claude에게 무엇을 원하는지 명확하게 전달하세요.
+
+### 3. 예제 사용 (멀티샷)
+구체적인 예제를 제공하여 원하는 출력 형식을 보여주세요.
+
+### 4. Claude가 생각하도록 하기 (사고의 연쇄)
+복잡한 문제의 경우 Claude에게 단계별로 생각하도록 요청하세요.
+
+### 5. XML 태그 사용
+구조화된 입력과 출력을 위해 XML 태그를 활용하세요.
+
+### 6. Claude에게 역할 부여 (시스템 프롬프트)
+특정 역할이나 페르소나를 부여하여 일관된 응답을 유도하세요.
+
+### 7. Claude의 응답 미리 채우기
+응답의 시작 부분을 미리 채워 원하는 형식으로 유도하세요.
+
+### 8. 복잡한 프롬프트 연결
+큰 작업을 여러 단계로 나누어 처리하세요.
+
+### 9. 긴 컨텍스트 팁
+긴 문서나 대화를 효과적으로 처리하는 방법을 익히세요.
+
+## 프롬프트 엔지니어링 예제
+
+### 기본 프롬프트 구조
+
+```
+[역할/컨텍스트]
+당신은 코드 리뷰 전문가입니다.
+
+[작업]
+다음 코드를 검토하고 개선점을 제안해주세요.
+
+[입력]
+<code>
+{사용자 코드}
+</code>
+
+[출력 형식]
+1. 문제점 목록
+2. 개선 제안
+3. 수정된 코드
+```
+
+### XML 태그 활용
+
+```xml
+<context>
+프로젝트는 Python 기반의 웹 애플리케이션입니다.
+</context>
+
+<task>
+보안 취약점을 분석해주세요.
+</task>
+
+<code>
+{분석할 코드}
+</code>
+```
+
+## 추가 리소스
+
+- GitHub 프롬프팅 튜토리얼
+- Google Sheets 프롬프팅 튜토리얼
+- Claude API 문서

package/templates/guides/claude-code/08-testing.md

@@ -0,0 +1,56 @@
+# 테스트 및 평가
+
+## 개요
+
+Claude 기반 애플리케이션의 품질을 보장하기 위한 테스트 및 평가 방법론입니다.
+
+## 핵심 개념
+
+### 1. 성공 기준 정의
+- 명확한 목표 설정
+- 측정 가능한 지표 정의
+- 기대 결과 문서화
+
+### 2. 테스트 케이스 설계
+- 경계 조건 테스트
+- 다양한 입력 시나리오
+- 에러 핸들링 검증
+
+### 3. 평가 메트릭
+- 정확도 (Accuracy)
+- 관련성 (Relevance)
+- 일관성 (Consistency)
+- 안전성 (Safety)
+
+## 테스트 유형
+
+### 단위 테스트
+개별 프롬프트나 도구의 동작 검증
+
+### 통합 테스트
+여러 컴포넌트가 함께 작동하는 시나리오 검증
+
+### 회귀 테스트
+변경 사항이 기존 기능에 영향을 미치지 않는지 확인
+
+### A/B 테스트
+다른 프롬프트나 설정의 효과 비교
+
+## 평가 프레임워크
+
+### 자동 평가
+- 패턴 매칭
+- 구조 검증
+- 출력 형식 확인
+
+### 인간 평가
+- 품질 검토
+- 유용성 평가
+- 안전성 검토
+
+## 모범 사례
+
+1. **일찍, 자주 테스트**: 개발 초기부터 테스트 통합
+2. **다양한 시나리오 커버**: 일반적인 케이스와 엣지 케이스 모두
+3. **메트릭 추적**: 시간에 따른 성능 변화 모니터링
+4. **피드백 루프**: 평가 결과를 개선에 반영

package/templates/guides/claude-code/09-guardrails.md

@@ -0,0 +1,78 @@
+# 가드레일 강화
+
+## 개요
+
+가드레일은 AI 에이전트가 안전하고 의도된 범위 내에서 작동하도록 보장하는 메커니즘입니다.
+
+## 가드레일 유형
+
+### 1. 입력 가드레일
+- 프롬프트 인젝션 방지
+- 악의적인 입력 필터링
+- 입력 유효성 검사
+
+### 2. 출력 가드레일
+- 민감 정보 필터링
+- 유해 콘텐츠 차단
+- 형식 준수 확인
+
+### 3. 행동 가드레일
+- 도구 사용 제한
+- 파일 시스템 접근 제어
+- 네트워크 요청 제한
+
+### 4. 리소스 가드레일
+- 토큰 사용량 제한
+- 실행 시간 제한
+- API 호출 제한
+
+## 구현 전략
+
+### 권한 관리
+```python
+options = ClaudeAgentOptions(
+    allowed_tools=["Read", "Glob", "Grep"],  # 읽기 전용
+    permission_mode="bypassPermissions"
+)
+```
+
+### 훅을 통한 검증
+```python
+hooks={
+    "PreToolUse": [{
+        "matcher": "Bash",
+        "hooks": [{
+            "type": "command",
+            "command": "validate_command.sh"
+        }]
+    }]
+}
+```
+
+### 도구 필터링
+특정 도구만 허용하거나 특정 도구를 차단하여 에이전트의 능력을 제한
+
+## 모범 사례
+
+1. **최소 권한 원칙**: 필요한 최소한의 권한만 부여
+2. **계층적 검증**: 여러 레벨에서 검증 수행
+3. **실패 안전**: 검증 실패 시 안전한 기본값으로 폴백
+4. **로깅 및 감사**: 모든 작업을 기록하여 추적 가능
+5. **정기적 검토**: 가드레일 효과성 주기적 평가
+
+## 보안 고려사항
+
+### 프롬프트 인젝션 방어
+- 사용자 입력과 시스템 지침 분리
+- XML 태그를 사용한 구조화
+- 입력 이스케이프 처리
+
+### 데이터 보호
+- 민감 데이터 마스킹
+- 출력 스크러빙
+- 접근 제어 적용
+
+### 코드 실행 안전
+- 샌드박스 환경 사용
+- 실행 시간 제한
+- 리소스 쿼터 적용

package/templates/guides/claude-code/10-monitoring.md

@@ -0,0 +1,87 @@
+# 관리 및 모니터링
+
+## 개요
+
+프로덕션 환경에서 AI 에이전트를 효과적으로 관리하고 모니터링하는 방법입니다.
+
+## 모니터링 영역
+
+### 1. 성능 모니터링
+- 응답 시간 (Latency)
+- 처리량 (Throughput)
+- 에러율 (Error Rate)
+- 성공률 (Success Rate)
+
+### 2. 비용 모니터링
+- 토큰 사용량
+- API 호출 수
+- 도구 실행 비용
+- 월별/일별 비용 추이
+
+### 3. 품질 모니터링
+- 출력 정확도
+- 사용자 만족도
+- 태스크 완료율
+- 재시도 비율
+
+### 4. 안전 모니터링
+- 가드레일 트리거 횟수
+- 차단된 요청
+- 보안 이벤트
+- 이상 탐지
+
+## 로깅 전략
+
+### 구조화된 로깅
+```json
+{
+  "timestamp": "2025-01-22T10:30:00Z",
+  "agent_id": "agent-123",
+  "action": "tool_use",
+  "tool": "Edit",
+  "input": {...},
+  "output": {...},
+  "duration_ms": 150,
+  "tokens_used": 500
+}
+```
+
+### 로그 레벨
+- **DEBUG**: 상세 디버깅 정보
+- **INFO**: 일반 작업 정보
+- **WARN**: 잠재적 문제
+- **ERROR**: 오류 발생
+- **CRITICAL**: 심각한 시스템 문제
+
+## 알림 설정
+
+### 임계값 기반 알림
+- 에러율 > 5%
+- 응답 시간 > 10초
+- 일일 비용 > 예산
+
+### 패턴 기반 알림
+- 비정상적인 사용 패턴
+- 갑작스러운 트래픽 증가
+- 연속 실패
+
+## 대시보드 구성
+
+### 핵심 메트릭
+- 실시간 요청 수
+- 평균 응답 시간
+- 현재 에러율
+- 활성 세션 수
+
+### 트렌드 분석
+- 시간별 사용량
+- 주간 비용 추이
+- 성능 변화 추적
+
+## 운영 모범 사례
+
+1. **자동화된 모니터링**: 24/7 자동 모니터링 구축
+2. **알림 피로 방지**: 중요한 알림만 전송
+3. **인시던트 대응**: 명확한 대응 절차 수립
+4. **용량 계획**: 사용량 예측 및 확장 계획
+5. **정기 리뷰**: 주기적인 성능 검토 미팅

package/templates/guides/claude-code/11-sub-agents.md

@@ -0,0 +1,159 @@
+# Sub-agent 가이드
+
+Claude Code에서 특화된 서브에이전트를 생성하고 사용하는 방법
+
+## 개요
+
+서브에이전트는 특정 작업을 처리하는 특화된 AI 어시스턴트입니다. 각 서브에이전트는 자체 컨텍스트 윈도우에서 실행되며, 사용자 정의 시스템 프롬프트, 특정 도구 액세스, 독립적인 권한을 가집니다.
+
+## 서브에이전트의 이점
+
+- **컨텍스트 보존**: 탐색과 구현을 주 대화에서 분리
+- **제약 적용**: 서브에이전트가 사용할 수 있는 도구 제한
+- **비용 제어**: 작업에 맞는 모델로 라우팅
+
+## Task Tool
+
+서브에이전트는 `Task` 도구를 통해 생성됩니다.
+
+### 기본 문법
+
+```
+Task(
+  subagent_type: "general-purpose",
+  prompt: "수행할 작업 설명",
+  model: "sonnet"
+)
+```
+
+### 파라미터
+
+| 파라미터 | 필수 | 설명 |
+|----------|------|------|
+| `subagent_type` | ✓ | 에이전트 유형 (general-purpose, Explore, Plan 등) |
+| `prompt` | ✓ | 수행할 작업 설명 |
+| `model` | - | 사용할 모델 (opus, sonnet, haiku, inherit) |
+| `description` | ✓ | 짧은 작업 설명 (3-5 단어) |
+
+## 모델 지정
+
+### 사용 가능한 모델
+
+| 모델 | 특성 | 용도 |
+|------|------|------|
+| `opus` | 가장 강력, 복잡한 추론 | 아키텍처 설계, 복잡한 판단 |
+| `sonnet` | 균형 잡힌 성능 | 일반 개발 작업 (기본값) |
+| `haiku` | 빠르고 저렴 | 단순 작업, 파일 검색 |
+| `inherit` | 부모 모델 상속 | 일관성 필요 시 |
+
+### 모델 선택 기준
+
+```
+판단이 필요한 작업 → opus
+  - 아키텍처 분석
+  - 복잡한 코드 리뷰
+  - 설계 결정
+
+생성이 필요한 작업 → sonnet
+  - 코드 작성
+  - 문서 작성
+  - 일반 개발
+
+단순한 작업 → haiku
+  - 파일 검색
+  - 간단한 검증
+  - 상태 확인
+```
+
+## 기본 제공 서브에이전트
+
+### Explore
+
+코드베이스 탐색에 최적화된 빠른 읽기 전용 에이전트
+
+- **모델**: haiku (빠름, 낮은 지연시간)
+- **도구**: 읽기 전용 (Write, Edit 불가)
+- **용도**: 파일 검색, 코드 검색, 코드베이스 탐색
+
+### Plan
+
+계획 모드에서 컨텍스트를 수집하는 연구 에이전트
+
+- **모델**: inherit (부모 모델 상속)
+- **도구**: 읽기 전용
+- **용도**: 계획을 위한 코드베이스 연구
+
+### general-purpose
+
+탐색과 작업 모두를 수행하는 범용 에이전트
+
+- **모델**: inherit (기본값) 또는 지정
+- **도구**: 모든 도구
+- **용도**: 복잡한 연구, 다단계 작업, 코드 수정
+
+## 사용 예시
+
+### 복잡한 분석 (opus)
+
+```
+Task(
+  description: "Analyze architecture",
+  subagent_type: "general-purpose",
+  prompt: "Analyze the agent architecture and identify improvement opportunities",
+  model: "opus"
+)
+```
+
+### 코드 구현 (sonnet)
+
+```
+Task(
+  description: "Implement feature",
+  subagent_type: "general-purpose",
+  prompt: "Implement the user authentication feature following the existing patterns",
+  model: "sonnet"
+)
+```
+
+### 빠른 검색 (haiku)
+
+```
+Task(
+  description: "Search files",
+  subagent_type: "Explore",
+  prompt: "Find all files that handle authentication",
+  model: "haiku"
+)
+```
+
+## 병렬 실행
+
+독립적인 작업은 병렬로 실행할 수 있습니다 (최대 4개).
+
+```
+# 단일 메시지에서 여러 Task 호출
+Task(prompt: "Task A", model: "haiku")
+Task(prompt: "Task B", model: "haiku")
+Task(prompt: "Task C", model: "haiku")
+```
+
+## 비용 최적화
+
+| 전략 | 설명 |
+|------|------|
+| 탐색은 haiku | 파일 검색, 구조 파악에 haiku 사용 |
+| 구현은 sonnet | 일반적인 코딩 작업에 sonnet 사용 |
+| 판단은 opus | 중요한 결정에만 opus 사용 |
+| 병렬화 | 독립 작업은 병렬로 실행하여 시간 절약 |
+
+## 주의사항
+
+- 서브에이전트는 다른 서브에이전트를 생성할 수 없음
+- 백그라운드 서브에이전트는 권한 프롬프트 자동 거부
+- 모델 미지정 시 기본값은 sonnet
+
+## 참고 문서
+
+- [Claude Code Sub-agents 공식 문서](https://docs.anthropic.com/claude-code/sub-agents)
+- R009: Parallel Execution Rules
+- R010: Orchestrator Coordination Rules