코딩 에이전트로 어댑터 개발하기

어댑터가 소유하는 것

어댑터는 메시지와 시스템 API 사이를 번역합니다. 해석, 권한 검사, 승인 경로, 재시도, 무엇을 건드렸는지의 기록을 소유합니다.

라우팅·grant·모델 선택은 소유하지 않습니다. 라우터 안의 업무 로직은 기능이 아니라 결함입니다. 한 시스템의 규칙이 모두의 규칙이 되기 때문입니다.

에이전트에게 주어야 하는 것

계약 없이 일을 맡기면 에이전트는 계약을 발명합니다. 아래 입력만 주고, 필요 없는 것은 주지 마세요.

• spec/ADAPTER_COMMON.md — 책임 경계(§3), 라우터 HTTP/SSE 봉투(§7), canonical 요청·답신(§8)
• spec/adapter-contract.test.mjs — 네트워크·모델 없는 격리 계약 테스트
• adapters/router-a2a-v1/ — 읽을 참조 어댑터(맹목적 복사 대상 아님)
• adapter-kit/ — 계약 테스트 7개가 붙은 실행 가능한 골격
• 대상 시스템의 API 문서와 실제 권한 모델
• 좌석 ID와 런타임에서 자격증명을 가져오는 위치 — 저장소에 값은 넣지 않음

여섯 단계, 순서대로

각 단계는 증거를 남깁니다. 증거가 없는 단계는 다음 단계로 넘어갈 수 없습니다.

• 1. 시스템 조사: 엔드포인트, 인증, 요청 한도, 실패한 호출이 남기는 것
• 2. 매핑 작성: 메시지 필드 → API 호출, 결과의 역방향
• 3. 그 매핑 뒤에 어댑터 구현, 진입점 하나
• 4. 계약 테스트 통과 — 거부 케이스 포함
• 5. 테스트 라우터로 로컬 스모크: 송신→수신→결과→ACK→재시도
• 6. 리뷰: 비밀 없음, 라우터 수정 없음, 실패 경로 시연, 승인 경로 유지

복사해서 쓰는 브리프

우리가 실제로 쓰는 작업 브리프입니다. 대괄호만 바꾸고 제약은 유지하세요.

Role: build one WMOS adapter for [system].
Read first: spec/ADAPTER_COMMON.md §3, §7, §8; adapter-kit/README.md; adapter-kit/test/adapter.test.mjs.
Allowed files: adapters/[name]/**, test files for that adapter.
Forbidden: router-core/**, packages/routing-contract/**, spec/**, any credential value.
Rules:
- The router forwards envelopes; do not add business logic to it.
- Deduplicate by job_id; do not infer a destination from a message body.
- A result is success only with real system output. Timeouts are error or blocked.
- Never log credentials or full customer payloads.
Done when:
- node --test spec/adapter-contract.test.mjs passes
- the local smoke covers send -> receive -> result -> egress ack -> retry
- failure path (API down, duplicate, timeout) is shown in output
Report: files changed, raw test output, the failure path, and open risks.

마지막 줄이 중요합니다. 원문 출력이 없는 보고는 증거가 아니라 주장입니다.

완료의 정의

한 줄이라도 빠지면 반려하세요. 컴파일은 되지만 운영할 수 없는 어댑터를 걸러내는 검사입니다.

• 계약 테스트 통과 — 잘못된 메시지·거부 케이스 포함
• 같은 job이 중복 전달돼도 부작용이 반복되지 않음
• 타임아웃·API 실패가 error 또는 blocked로 나옴(success 금지)
• 결과가 올바른 job_id로 제출되어 라우터의 correlation과 원요청 binding이 유지됨
• 좌석 자격증명을 환경변수·비밀 저장소에서 런타임에 읽음
• 로그에 자격증명·고객 payload 원문이 없음
• 테스트를 통과시키려고 라우터 코드를 수정하지 않음
• 되돌릴 수 없는 시스템 행동 앞에 사람 승인 단계가 있음

리뷰에서 찾아야 할 실패 모드

제약 없이 어댑터를 맡겼을 때 가장 자주 보는 패턴입니다.

• payload 해석을 라우터로 밀어 넣어 한 시스템 스키마가 전역이 됨
• 저장된 binding 대신 본문에서 목적지를 추측
• 소유하지 않은 listen 이벤트에 결과를 반환
• job_id가 아니라 도착 순서로 중복 제거
• 시스템 응답이 아니라 모델 텍스트로 성공 판정
• 자격증명을 설정 파일·테스트 fixture·로그에 붙여넣음
• 되돌릴 수 없는 행동을 재시도로 반복
• 계약이 아니라 어댑터 자기 출력을 검사하는 테스트

결과를 판정하는 방법

diff를 읽고, 원문 출력을 읽고, 실패 경로를 확인하세요. 실패 케이스를 제대로 보여주지 못하면 그 어댑터는 완성된 것이 아니라 해피패스 데모입니다.

이 작업이 검토 가능한 이유도 여기 있습니다. 계약이 에이전트의 자기 평가 밖에 있습니다.