oh-my-customcode 0.1.2 → 0.1.3

package/templates/agents/manager/supplier/refs/guides/claude-code/05-agent-sdk.md

@@ -0,0 +1,129 @@
+# Agent SDK 개요
+
+Claude Code를 라이브러리로 사용하여 프로덕션 AI 에이전트 구축
+
+## 소개
+
+파일을 자동으로 읽고, 명령을 실행하고, 웹을 검색하고, 코드를 편집하는 등의 작업을 수행하는 AI 에이전트를 구축하세요. Agent SDK는 Claude Code를 강화하는 동일한 도구, 에이전트 루프 및 컨텍스트 관리를 Python과 TypeScript로 프로그래밍할 수 있게 제공합니다.
+
+## 빠른 시작 예제
+
+```python
+import asyncio
+from claude_agent_sdk import query, ClaudeAgentOptions
+
+async def main():
+    async for message in query(
+        prompt="Find and fix the bug in auth.py",
+        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"])
+    ):
+        print(message)
+
+asyncio.run(main())
+```
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Find and fix the bug in auth.py",
+  options: { allowedTools: ["Read", "Edit", "Bash"] }
+})) {
+  console.log(message);
+}
+```
+
+## 기능
+
+### 기본 제공 도구
+
+| 도구 | 기능 |
+|------|------|
+| **Read** | 작업 디렉토리의 모든 파일 읽기 |
+| **Write** | 새 파일 생성 |
+| **Edit** | 기존 파일에 정확한 편집 수행 |
+| **Bash** | 터미널 명령, 스크립트, git 작업 실행 |
+| **Glob** | 패턴으로 파일 찾기 |
+| **Grep** | 정규식으로 파일 내용 검색 |
+| **WebSearch** | 현재 정보를 위해 웹 검색 |
+| **WebFetch** | 웹 페이지 내용 가져오기 및 파싱 |
+
+### 훅 (Hooks)
+
+에이전트 라이프사이클의 주요 지점에서 사용자 정의 코드를 실행합니다.
+
+**사용 가능한 훅**: `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit` 등
+
+### 서브에이전트
+
+특화된 에이전트를 생성하여 집중된 부작업을 처리합니다. `Task` 도구를 활성화하여 Claude가 위임의 이점을 얻을 수 있을 정도로 복잡한 작업이라고 판단할 때 서브에이전트를 생성하도록 합니다.
+
+### MCP (Model Context Protocol)
+
+외부 시스템에 연결: 데이터베이스, 브라우저, API 등
+
+### 권한
+
+에이전트가 사용할 수 있는 도구를 정확히 제어합니다. 안전한 작업을 허용하고, 위험한 작업을 차단하거나, 민감한 작업에 대해 승인을 요구합니다.
+
+### 세션
+
+여러 교환 간에 컨텍스트를 유지합니다. Claude는 읽은 파일, 수행한 분석 및 대화 기록을 기억합니다.
+
+## Claude Code 기능 지원
+
+| 기능 | 설명 | 위치 |
+|------|------|------|
+| Skills | Markdown에 정의된 특화된 기능 | `.claude/skills/SKILL.md` |
+| Slash commands | 일반적인 작업을 위한 사용자 정의 명령 | `.claude/commands/*.md` |
+| Memory | 프로젝트 컨텍스트 및 지침 | `CLAUDE.md` 또는 `.claude/CLAUDE.md` |
+| Plugins | 사용자 정의 명령, 에이전트 및 MCP 서버로 확장 | `plugins` 옵션을 통한 프로그래밍 방식 |
+
+## 설치
+
+### Claude Code 설치
+
+```bash
+# macOS/Linux/WSL
+curl -fsSL https://claude.ai/install.sh | bash
+
+# Homebrew
+brew install --cask claude-code
+
+# npm
+npm install -g @anthropic-ai/claude-code
+```
+
+### SDK 설치
+
+```bash
+# TypeScript
+npm install @anthropic-ai/claude-agent-sdk
+
+# Python
+pip install claude-agent-sdk
+```
+
+### API 키 설정
+
+```bash
+export ANTHROPIC_API_KEY=your-api-key
+```
+
+## Agent SDK vs Client SDK
+
+| 구분 | Client SDK | Agent SDK |
+|------|-----------|-----------|
+| 도구 실행 | 직접 구현 | Claude가 처리 |
+| 복잡도 | 도구 루프 구현 필요 | 자동화됨 |
+| 유연성 | 완전한 제어 | 추상화된 편의성 |
+
+## Agent SDK vs Claude Code CLI
+
+| 사용 사례 | 최적의 선택 |
+|----------|-----------|
+| 대화형 개발 | CLI |
+| CI/CD 파이프라인 | SDK |
+| 사용자 정의 애플리케이션 | SDK |
+| 일회성 작업 | CLI |
+| 프로덕션 자동화 | SDK |

package/templates/agents/manager/supplier/refs/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/agents/manager/supplier/refs/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/agents/manager/supplier/refs/guides/claude-code/08-testing.md

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

package/templates/agents/manager/supplier/refs/guides/claude-code/09-guardrails.md

@@ -0,0 +1,80 @@
+# 가드레일 강화
+
+> 이 문서는 Claude 공식 문서에서 해당 페이지가 아직 공개되지 않아 기본 구조만 제공합니다.
+
+## 개요
+
+가드레일은 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/agents/manager/supplier/refs/guides/claude-code/10-monitoring.md

@@ -0,0 +1,89 @@
+# 관리 및 모니터링
+
+> 이 문서는 Claude 공식 문서에서 해당 페이지가 아직 공개되지 않아 기본 구조만 제공합니다.
+
+## 개요
+
+프로덕션 환경에서 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/agents/manager/supplier/refs/guides/claude-code/index.yaml

@@ -0,0 +1,51 @@
+# Claude Code Guide Index
+# Claude로 에이전트를 구축하기 위한 가이드 문서 인덱스
+
+documents:
+  - name: overview
+    title: 기능 개요
+    description: Claude의 핵심 기능 및 도구 요약
+    path: ./01-overview.md
+
+  - name: tools
+    title: 도구 사용
+    description: Claude와 도구 통합 방법
+    path: ./03-tools.md
+
+  - name: agent-skills
+    title: 에이전트 스킬
+    description: Skills로 Claude 기능 확장
+    path: ./04-agent-skills.md
+
+  - name: agent-sdk
+    title: 에이전트 SDK
+    description: Python/TypeScript로 에이전트 구축
+    path: ./05-agent-sdk.md
+
+  - name: mcp
+    title: MCP 커넥터
+    description: Model Context Protocol 서버 연결
+    path: ./06-mcp.md
+
+  - name: prompt-engineering
+    title: 프롬프트 엔지니어링
+    description: 프롬프트 최적화 기법
+    path: ./07-prompt-engineering.md
+
+  - name: testing
+    title: 테스트 및 평가
+    description: 품질 보장을 위한 테스트 방법
+    path: ./08-testing.md
+    status: placeholder  # 공식 문서 미공개
+
+  - name: guardrails
+    title: 가드레일 강화
+    description: 안전한 에이전트 운영을 위한 제약
+    path: ./09-guardrails.md
+    status: placeholder  # 공식 문서 미공개
+
+  - name: monitoring
+    title: 관리 및 모니터링
+    description: 프로덕션 에이전트 운영
+    path: ./10-monitoring.md
+    status: placeholder  # 공식 문서 미공개