api-connector-builder

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