> ## Documentation Index
> Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 에이전트

> 게임 서버의 PlayCamp SDK 연동을 자동화하는 AI 에이전트

PlayCamp는 SDK 연동을 자동화하는 [Claude Code](https://claude.ai/code) 에이전트를 제공합니다. API 호출을 직접 작성하는 대신 자연어로 필요한 것을 설명하면, 에이전트가 SDK 설치, API 구현, 웹훅 설정, 검증까지 자동으로 처리합니다.

## 지원 카테고리

언어별로 통합된 올인원 에이전트 1개씩입니다. 각 에이전트가 설치, 필수 + 확장 API, 웹훅, Raw HTTP 마이그레이션, 코드 감사, 빌드 검증까지 전체 연동 과정을 담당합니다.

| 카테고리         | 에이전트                   | 설명                                          |
| ------------ | ---------------------- | ------------------------------------------- |
| **Node SDK** | `@agent-playcamp-node` | `@playcamp/node-sdk` 연동                     |
| **Go SDK**   | `@agent-playcamp-go`   | `github.com/playcamp/playcamp-go-sdk` 연동    |
| **API**      | `@agent-playcamp-api`  | Python, Java, C#, PHP 등을 위한 직접 HTTP API 가이드 |

## 빠른 시작

<Steps>
  <Step title="에이전트 설치">
    게임 서버 프로젝트에서 설치 스크립트를 실행합니다:

    ```bash theme={null}
    cd your-game-server
    bash <(curl -fsSL https://raw.githubusercontent.com/PlayCamp/playcamp-sdk-agents/main/scripts/install.sh)
    ```
  </Step>

  <Step title="Claude Code 실행">
    ```bash theme={null}
    claude
    ```
  </Step>

  <Step title="요청">
    ```
    PlayCamp SDK 연동해줘. 스폰서, 쿠폰, 결제 API 필요해
    ```

    에이전트가 자동으로 SDK 설치, 필수 API 구현, 에러 처리 설정까지 해줍니다.
  </Step>
</Steps>

## 설치 옵션

```bash theme={null}
# 현재 프로젝트에 설치 (기본값)
bash <(curl -fsSL https://raw.githubusercontent.com/PlayCamp/playcamp-sdk-agents/main/scripts/install.sh)

# 글로벌 설치 (~/.claude/agents/)
bash <(curl -fsSL ...install.sh) --global

# 특정 카테고리만 설치
bash <(curl -fsSL ...install.sh) --platform=node
bash <(curl -fsSL ...install.sh) --platform=go
bash <(curl -fsSL ...install.sh) --platform=api

# 삭제 (에이전트 파일 + CLAUDE.md 라우팅 규칙 제거)
bash <(curl -fsSL ...install.sh) --uninstall
```

## 에이전트

각 에이전트는 해당 언어의 모든 역할을 담당하는 단일 통합 에이전트입니다. 필요한 작업만 설명하면 에이전트가 알맞은 모드를 선택합니다.

| 모드                  | 설명                                                                   |
| ------------------- | -------------------------------------------------------------------- |
| **연동(Integrate)**   | SDK 설치, 클라이언트 초기화, 필수 + 확장 API (스폰서, 쿠폰, 결제, 플레이타임, WebView OTT, 벌크) |
| **웹훅(Webhooks)**    | 엔드포인트 설정, 서명 검증, 배치 이벤트 처리 (이벤트 7종)                                  |
| **마이그레이션(Migrate)** | Raw HTTP(fetch/axios, `net/http`)를 SDK 메서드로 전환                       |
| **감사(Audit)**       | 정확성·보안·모범사례 관점의 읽기 전용 코드 리뷰                                          |
| **검증(Verify)**      | 빌드/컴파일, 의존성, 환경 설정 점검                                                |

### `@agent-playcamp-node` — Node SDK

`@playcamp/node-sdk` 담당: 설치 및 클라이언트 초기화, 필수 API(스폰서/쿠폰/결제), 플레이타임 세션, 벌크 결제, WebView OTT, 웹훅 수신 및 서명 검증, Raw HTTP → SDK 마이그레이션, 코드 감사, TypeScript 빌드/환경 검증.

### `@agent-playcamp-go` — Go SDK

`github.com/playcamp/playcamp-go-sdk`에 대해 동일한 범위를 Go 관용구로 제공 — `errors.As()`, `context.Context`, 포인터 헬퍼, `webhookutil.Verify()` 서명 검증, `go build`/`go vet` 검증.

### `@agent-playcamp-api` — 직접 HTTP API

SDK 미지원 언어(Python, Java, C#, PHP, Ruby, curl)용: 엔드포인트 문서, Bearer 인증, 요청/응답 예제, 웹훅 검증, 에러 처리.

## 사용 예시

### Node.js

```
Express 서버에 PlayCamp SDK 연동해줘. 결제, 쿠폰, 스폰서 API 필요해
```

```
PlayCamp 웹훅 수신 엔드포인트 만들어줘. 서명 검증 포함해서
```

```
후원 유저 플레이타임 세션 수집 기능 추가해줘
```

```
PlayCamp 연동 코드 보안 점검하고 빌드까지 확인해줘
```

### Go

```
Go 서버에 PlayCamp Go SDK 연동해줘. 스폰서, 쿠폰, 결제 API 필요해
```

```
webhookutil로 Go 서버에 PlayCamp 웹훅 검증 추가해줘
```

### 직접 API 연동 (SDK 미지원 언어)

```
Python으로 PlayCamp 결제 API 연동하는 방법 알려줘
```

```
Java 서버에 PlayCamp 스폰서, 쿠폰 API 연동해줘
```

### 마이그레이션

```
기존 fetch() 호출을 PlayCamp SDK 메서드로 전환해줘
```

```
기존 net/http PlayCamp 호출을 Go SDK로 전환해줘
```

### 에이전트 직접 호출

에이전트 이름을 명시적으로 지정할 수도 있습니다:

```
@agent-playcamp-node 로 PlayCamp SDK 연동하고 서버 키 설정해줘
```

```
@agent-playcamp-go 로 웹훅 엔드포인트 설정하고 빌드 검증까지 해줘
```

## 권장 워크플로우

단일 에이전트로 모드를 바꿔가며 전체 연동을 진행합니다:

```mermaid theme={null}
flowchart LR
  A[연동] --> B[웹훅]
  B --> C[감사]
  C --> D[검증]
```

1. **연동** — SDK 설치, 클라이언트 초기화, 필수 + 확장 API 구현
2. **웹훅** — 웹훅 엔드포인트 및 서명 검증 설정
3. **감사** — 전체 연동의 정확성·보안 검토 (읽기 전용)
4. **검증** — 빌드, 설정, 환경 검증

<Tabs>
  <Tab title="Node.js">
    모든 단계에 `@agent-playcamp-node`를 사용합니다. 마이그레이션은 \*"기존 fetch/axios 호출을 PlayCamp SDK로 전환해줘"\*로 시작한 뒤 감사·검증을 요청하세요.
  </Tab>

  <Tab title="Go">
    모든 단계에 `@agent-playcamp-go`를 사용합니다. 마이그레이션은 \*"기존 net/http 호출을 PlayCamp Go SDK로 전환해줘"\*로 시작한 뒤 `go build`/`go vet`로 감사·검증을 요청하세요.
  </Tab>
</Tabs>

같은 에이전트가 모든 단계를 처리하므로 별도 에이전트 간 인계가 필요 없습니다.

## 동작 원리

설치 스크립트가 `.claude/agents/`에 에이전트 파일을 추가하고, 프로젝트의 `CLAUDE.md`에 라우팅 규칙을 자동 추가합니다. PlayCamp 관련 요청 시 Claude Code가 자동으로 해당 언어 에이전트에 위임합니다.

```
사용자: "PlayCamp 결제 처리 추가해줘"
  → Claude가 CLAUDE.md 라우팅 규칙 확인
    → @agent-playcamp-node (또는 -go / -api) 에 위임
      → 에이전트가 SDK로 결제 API 구현
```

<Info>
  에이전트는 프로젝트의 파일을 읽고, 쓰고, 편집할 수 있는 전체 권한을 가집니다. npm/Go 패키지 설치, 모듈 생성, 서버 코드 수정이 가능합니다. 감사·검증 모드에서는 코드를 수정하지 않고 읽고 보고만 합니다.
</Info>