당신은 AI에게 작업을 맡깁니다. 예약 시스템을 구축하는 것입니다. 사용자는 시간 슬롯을 선택하고 예약을 제출하며, 관리자는 이를 취소할 수 있습니다.
충분히 빠릅니다. 페이지는 존재합니다. 엔드포인트도 존재합니다. 데이터베이스 테이블도 존재합니다. 각 조각은 고립된 상태에서는 올바르게 보입니다.
그런 다음 이들을 연결합니다. 프론트엔드는 타임스탬프를 로컬 시간으로 처리합니다. 백엔드는 UTC로 저장합니다. 취소 엔드포인트는 200을 반환하지만, 예약 목록에는 여전히 '예약됨'이 표시됩니다. 같은 슬롯이 두 번 예약됩니다.
AI는 많은 코드를 빠르게 생성합니다. 하지만 _정확하다_는 정의가 몇 차례의 채팅에 걸쳐만 존재한다면, 모든 모듈은 그에 대한 자체적인 해석을 발전시킵니다.
AI 코딩에는 양쪽이 확인할 수 있는 공유된 참조가 필요하다
OpenAPI Specification (OAS)은 엔드포인트, 파라미터, 응답 및 인증(auth)을 구조화된 형식으로 설명합니다. 사람들은 이를 읽을 수 있고, 도구들도 이를 읽을 수 있습니다.
Powerduck에서는 비즈니스 요청에서 시작하여 AI에게 기존 스펙에 기반한 디자인을 제안하도록 요청합니다. 예를 들어 다음과 같습니다:
예약 생성 및 취소 엔드포인트를 설계해 주세요. 시간대 형식, 예약 상태 라이프사이클, 그리고 슬롯이 이미 사용 중일 때의 오류 응답을 명확히 해주세요. 요구사항에서 명확하지 않은 규칙들을 나열해 주세요.
다음으로 중요한 것은 AI가 얼마나 많은 코드를 작성했는지가 아닙니다. 그것은 _API에서 변경하도록 제안하는 내용_입니다. 필드 의미가 모호하지 않은지? 상태 모델이 일관적인지? 실패 사례들이 프론트엔드가 실제로 렌더링해야 하는 것을 다루는지?
당신은 diff(차이점)를 검토하고, 이를 적용한 다음, 로컬 OAS 파일에 저장합니다. 그렇지 않았다면 채팅 기록 속에 사라졌을 논의가 프로젝트가 계속 사용할 수 있는 영구적인 아티팩트가 됩니다.
전체 AI 워크플로우를 관통하는 단일 파일
OAS는 '디자인 결과물'에서 멈출 필요가 없습니다. Powerduck 워크플로우에서는 후속 단계에 계속해서 데이터를 공급합니다:
- 설계 (Design): AI가 기존 정의에 대해 엔드포인트 및 스키마 변경 사항을 제안합니다.
- 구현 (Implementation): 로컬 MCP 서버가 코딩 어시스턴트에게 붙여넣은 PDF가 아닌 구체적인 계약(contract)을 제공합니다.
- 의존성 대기 (Waiting on dependencies): 모의 응답(mock answers)이 스펙의 예시와 스키마로부터 제공되어 프론트엔드가 진행할 수 있도록 합니다.
- 검증 (Verification): 에이전트가 실제 요청을 보내고, 계약 검사(contract checks)를 실행하며, 시나리오 테스트를 수행합니다.
- 배포 (Delivery): 문서가 동일한 파일에서 렌더링되며, MCP 엔드포인트는 필요할 때 게시될 수 있습니다.
이러한 변화는 AI의 컨텍스트(context)가 더 이상 매번 사용자가 복사하여 붙여넣는 것에 의존하지 않음을 의미합니다. 스펙은 설계 단계에서 흐름에 진입하며, 모든 다운스트림 도구에게 진실의 원천(source of truth)으로 남아 있습니다.
'AI 네이티브'는 피드백 루프를 의미해야 한다
예약 엔드포인트가 존재하면, AI는 MCP를 통해 계약을 질의하고 테스트 서비스로 요청을 보낼 수 있습니다. 매개변수 불일치(mismatch in parameters), 누락된 응답 필드(missing response field), 또는 중간에 실패하는 시나리오가 다음 반복(iteration)을 위한 구체적인 신호가 됩니다.
모델이 제공한 '완료'와 비교했을 때, 실제 응답과 단언 결과(assertion results)를 검토할 가치가 있습니다. 어떤 단계가 통과했는지? 어떤 필드가 계약과 일치하지 않았는지? 어떤 규칙이 여전히 누락되었는지?
OAS(OpenAPI Specification)에도 한계가 있습니다. 그것 자체만으로는 슬롯 예약의 경합 조건(race conditions), 크로스 서비스 트랜잭션, 또는 모든 비즈니스 불변량(business invariant)을 표현할 수 없습니다. 이러한 것들은 시나리오, 단언, 그리고 구현 수준의 테스트가 필요합니다. Powerduck과 같은 도구의 목적은 계약의 구조화된 부분을 피드백 루프에 넣어 격차를 조기에 포착하는 것입니다.
로컬 우선(Local first)은 합의가 프로젝트에 속한다는 의미다
스펙이 로컬 파일로 존재합니다. 이는 버전 관리 시스템(version control), 코드 검토, 그리고 롤백과 함께 코드를 거칩니다. 팀이 한 AI 클라이언트에서 다른 AI 클라이언트로 전환할 때도 계약은 유지됩니다. 오래된 채팅 스레드에서 요구사항을 재구성할 필요가 없습니다.
Local-first가 오프라인 전용이라는 의미는 아닙니다. 클라우드 모델을 사용할 때도 전달하는 컨텍스트는 여전히 존재합니다. 이것이 의미하는 바는 파일과 일상적인 작업 흐름(workflow) 자체가 특정 벤더의 채팅 창 안에 잠기는 것이 아니라 사용자에게 있다는 것입니다.
Powerduck은 현재 일반화되고 있는 개발 패턴을 기반으로 구축되었습니다. 즉, 인간이 목표와 경계를 설정하고, AI가 설계 및 구현에 참여하며, 도구들이 검증 증거(verification evidence)를 제공하는 방식입니다. 이러한 루프에서 로컬 OAS는 이 세 가지 요소를 연결할 수 있는 핵심 요소가 될 수 있습니다.
AI가 작성을 시작하기 전에, '우리가 무엇을 만들고 있는지'와 '그것이 올바르다는 것을 어떻게 아는지'에 대한 공유된 장소가 있어야 합니다.