어시스턴트로 설계하기

스펙 모드는 API를 설계하는 곳입니다. AI 채팅을 라이브 문서 및 미리보기와 짝지어, 자연어로 의도를 설명하면서 실제로 일어나는 변경을 완전히 통제할 수 있습니다.

승인 루프

모델은 문서를 직접 편집하지 않습니다. 이 루프는 의도적으로 명확하게 만들어졌습니다.

you describe an intent
        |
the model reads current state and proposes operations
        |
the host validates the proposal
        |
you review a patch card and Apply or Reject
        |
the change is merged into the document

이 분리는 핵심 설계 결정입니다. 모델은 의도를 이해하고 구조를 제안하는 데 능하고, 호스트는 결정론적이며 각 작업을 검증하고, 당신이 모든 변경을 승인합니다. 당신이 확인하기 전에는 제안이 적용된 것으로 간주되지 않습니다.

패치 카드

패치 카드는 변경을 요약하고 경로 추가처럼 정확한 작업을 나열합니다.

{
  "type": "patch",
  "summary": "Add GET /products endpoint",
  "ops": [
    { "op": "add", "path": ["paths", "/products"], "value": { "get": {} } }
  ],
  "affects": { "paths": ["/paths/~1products"], "resources": ["Product"] }
}

경로 세그먼트는 JSON Pointer 문자열이 아닌 배열 요소입니다. 완전히 새로운 경로 추가 시 대상은 ["paths", "/products"]이고 부모 컨테이너가 자동 생성됩니다.

기존 작업에 대한 세밀한 편집

기존 작업을 편집할 때 어시스턴트는 작업 전체를 재전송하지 않습니다. 그렇게 하면 다시 표시하지 않은 모든 필드가 지워집니다. 대신 변경한 부분에만 닿는 작은 작업을 생성해 작업 내부로 들어갑니다.

쿼리 매개변수 추가:

{ "op": "add", "path": ["paths", "/products", "get", "parameters", "-"], "value": {} }

응답 스키마 확장:

{ "op": "replace", "path": ["paths", "/products", "get", "responses", "200", "content", "application/json", "schema", "properties", "total"], "value": { "type": "integer" } }

단일 필드 변경:

{ "op": "replace", "path": ["paths", "/products", "get", "summary"], "value": "..." }

배열은 전체 재전송 대신 "-"로 추가합니다. 매개변수는 (in, name)을 키로 해 기존 매개변수가 중복되지 않습니다. 호스트는 제안 값을 현재 작업에 병합하고 생략한 모든 것을 보존합니다.

이것이 반복 refine을 신뢰할 수 있게 만드는 이유입니다. "여기에 limit 매개변수 추가해줘", "name을 필수로 해줘"라고 말하면 그 필드만 바뀌고 작업의 나머지는 그대로입니다.

읽기 도구가 각 제안에 근거 제공

답변 전 모델은 추측이 아닌 정확한 현재 상태를 얻기 위해 읽기 전용 도구를 호출할 수 있습니다.

spec.overview——제목, 버전, 프로토콜, 수, 태그, servers, 보안.
spec.listOperations——각 작업을 METHOD /path로, 요약과 태그 포함.
spec.presentOperations——모든 작업의 읽기 전용 목록 카드 렌더링.
spec.getOperation——단일 작업의 완전한 정의와 참조 스키마.
spec.getSchema——단일 컴포넌트 스키마. 필수 필드와 설명 포함.

작업의 완전한 형태가 보이지 않을 때는 언제든 모델이 편집 전 그 작업을 읽어야 합니다.

넓은 요청은 단계적으로 진행

"이커머스 API 구축해줘" 같은 큰 요청에서 어시스턴트는 한 번에 모든 것을 쏟아내지 않습니다.

먼저 핵심 결정에 대한 명확화 질문을 낸다.
답변 후 한 번에 하나의 집중 패치를 제안한다. 각 카드는 2~5 작업.
가장 최근 요청이 여전히 그 목표 범위 내에 있을 때만 계속한다.

범위가 명확해지면 어시스턴트는 구축하려는 작업의 plan도 생성해 패치가 오기 전 작업의 형태를 볼 수 있습니다.

흐트러짐 방지

호스트는 작업 정렬을 유지하기 위해 몇 가지 규칙을 강제합니다.

현재 문서가 권위 상태. 문서가 그렇지 않다고 보이면 모델이 더 이른 패치가 존재한다고 가정하지 않는다.
집중 모드에서는 활성 목표(와 명시적으로 참조되는 컴포넌트 스키마)만 변경. 형제 작업에 대한 기회주의적 변경 없음.
다른 METHOD /path를 명시하면 의도적인 작업 전환으로 처리된다.
적용·거부된 제안은 이력에서 추적돼 기존 패치를 반복하지 않는다.

필요한 세부 사항이 보이지 않으면 어시스턴트는 날조하지 않고 집중된 질문을 냅니다.

다른 카드

모든 응답이 패치는 아닙니다.

질문 카드는 선택지 중 고르도록 요청.
검증 카드는 품질 검사를 보고. 통과, 경고, 오류 상태 포함.
액션 카드는 시나리오 실행이나 워크스페이스 열기 같은 구체적 다음 단계 제공.
데이터 테이블 카드는 작업이나 스키마의 구체적 샘플/테스트 데이터 제시.

관련: 요청 워크스페이스、시나리오 테스트、AI와 모델.

승인 루프​

패치 카드​

기존 작업에 대한 세밀한 편집​

읽기 도구가 각 제안에 근거 제공​

넓은 요청은 단계적으로 진행​

흐트러짐 방지​

다른 카드​