API 커넥터 빌더

API 커넥터 빌더은(는) 무엇을 하나요?

작업이 단순한 일반 HTTP 클라이언트가 아닌 저장소 네이티브 통합 표면을 추가하는 것일 때 사용합니다.

핵심은 호스트 저장소의 패턴을 일치시키는 것입니다.

• 커넥터 레이아웃
• 설정 스키마
• 인증 모델
• 오류 처리
• 테스트 스타일
• 등록/발견 와이어링

사용 시기

• "이 프로젝트에 Jira 커넥터를 만들어 주세요"
• "기존 패턴을 따라 Slack 프로바이더를 추가해 주세요"
• "이 API에 대한 새 통합을 만들어 주세요"
• "저장소의 커넥터 스타일과 일치하는 플러그인을 빌드해 주세요"

가드레일

• 저장소에 이미 통합 아키텍처가 있다면 새로운 아키텍처를 발명하지 마세요
• 공급업체 문서만으로 시작하지 말고, 먼저 저장소 내 기존 커넥터를 살펴보세요
• 저장소에 레지스트리 와이어링, 테스트, 문서가 필요하다면 단순 전송 코드로 멈추지 마세요
• 저장소에 최신 패턴이 있다면 이전 커넥터를 무턱대고 복사하지 마세요

워크플로

1. 하우스 스타일 학습

최소 2개의 기존 커넥터/프로바이더를 검사하고 다음을 매핑합니다.

• 파일 레이아웃
• 추상화 경계
• 설정 모델
• 재시도 / 페이지네이션 규칙
• 레지스트리 훅
• 테스트 픽스처 및 명명

2. 대상 통합 범위 좁히기

저장소가 실제로 필요한 표면만 정의합니다.

• 인증 흐름
• 주요 엔티티
• 핵심 읽기/쓰기 작업
• 페이지네이션 및 속도 제한
• 웹훅 또는 폴링 모델

3. 저장소 네이티브 계층으로 구축

일반적인 계층:

• 설정/스키마
• 클라이언트/전송
• 매핑 계층
• 커넥터/프로바이더 진입점
• 등록
• 테스트

4. 소스 패턴과 검증

새로운 커넥터는 다른 생태계에서 가져온 것이 아니라 코드베이스에서 자연스러워 보여야 합니다.

참조 형태

프로바이더 스타일

providers/
  existing_provider/
    __init__.py
    provider.py
    config.py

커넥터 스타일

integrations/
  existing/
    client.py
    models.py
    connector.py

TypeScript 플러그인 스타일

src/integrations/
  existing/
    index.ts
    client.ts
    types.ts
    test.ts

품질 체크리스트

• 기존 저장소 내 통합 패턴과 일치합니다
• 설정 유효성 검사가 존재합니다
• 인증 및 오류 처리가 명시적입니다
• 페이지네이션/재시도 동작이 저장소 규칙을 따릅니다
• 레지스트리/발견 와이어링이 완료되었습니다
• 테스트가 호스트 저장소의 스타일을 반영합니다
• 저장소에서 요구하는 경우 문서/예제가 업데이트되었습니다

관련 스킬

• backend-patterns
• mcp-server-patterns
• github-ops