AI 에이전트 라이브러리에는 시맨틱 버전 관리만으로는 충분하지 않다

라이브러리 릴리스는 모든 내보낸 TypeScript 타입을 보존하면서도 사용자가 관찰하는 바를 변경할 수 있습니다.

어댑터(adapter)는 다른 필드를 포착할 수 있습니다. 트레이스 검사(trace check)는 반복되는 도구들을 다르게 해석할 수 있습니다. CLI 명령어는 새로운 종료 코드를 반환할 수 있습니다. 마스킹 프로파일(redaction profile)은 더 많은 데이터를 제거할 수 있습니다. 영속화된 트레이스(persisted trace)는 여전히 파싱 가능하지만 다른 실행 트리로 재구성될 수 있습니다.

시맨틱 버전 관리(Semantic Versioning, SemVer)는 여전히 필요합니다. 하지만 AI 에이전트 도구링(tooling)의 경우, 그것만이 전체 호환성 스토리를 결정하지는 않습니다.

저는 TypeScript 우선의 로컬 증거 디버거이자 궤적 테스트 키트인 AgentInspect를 유지 관리하고 있습니다. 이를 유지하면서 저는 호환성을 하나의 패키지 API가 아닌 여러 표면(surface)으로 생각하게 되었습니다.

여기 예시는 [email protected], 영속화된 스키마 1.0, 그리고 Node.js 20 이상을 참조합니다.

모든 호환성 표면 매핑하기

에이전트 라이브러리의 경우, 적어도 다음 계약(contract)들을 검토해야 합니다:

“타입은 여전히 컴파일된다”는 약한 테스트이다

어댑터 옵션을 고려해 봅시다:

type CaptureMode = "metadata-only" | "preview";

두 어댑터가 preview를 허용한다고 가정합시다. 하지만 한 어댑터는 메타데이터만 조용히 기록합니다. 나중에 릴리스에서 preview 동작이 일관되게 되고 경계가 지정되고 마스킹된 미리보기가 추가됩니다. 공개 유니온(public union)은 변하지 않았습니다. 그러나 설정의 의미가 변했습니다.

그러한 개선은 바람직하지만, 여전히 다음을 받을 자격이 있습니다:

• 행동 변화를 설명하는 릴리스 노트;
• 명시적인 개인정보 보호 지침;
• 이전 및 이후에 대한 어댑터별 고정값(fixture);
• 메타데이터만 기본값으로 유지됨을 증명하는 테스트;
• 예상치 못한 네트워크 전송이 발생하지 않음을 증명하는 테스트.

AgentInspect의 6.18.0 버전에서 구현된 바운디드 프리뷰 패리티(bounded preview parity)는 API 시그니처 외에 런타임 의미론(runtime semantics)이 자체적인 변경 기록을 가져야 하는 이유를 보여주는 실제 예시입니다.

영속화된 아티팩트는 리더 계약(reader contracts)이 필요합니다

로컬 트레이스(local trace)는 그것을 생성한 코드보다 더 오래 지속될 수 있습니다. 따라서 리더는 다음 중 하나를 수행해야 합니다:

1. 스키마를 올바르게 열거나;
2. 명시적으로 마이그레이션하거나;
3. 실행 가능한 오류와 함께 거부해야 합니다.

알 수 없는 필드를 그럴듯하지만 잘못된 트리(tree)로 '최선 노력(best effort)'으로 채우지 마십시오.

골든 픽스처(Golden fixtures)가 이를 테스트 가능하게 만듭니다:

fixtures/
  v0.1/minimal-success.jsonl
  v1.0/parallel-tools.jsonl
...

각 릴리스는 현재 리더, 검사(checks), 보고서(reports), 그리고 내보내기 도구(exporters)를 지원되는 역사적 픽스처에 대해 실행해야 합니다. 사용자 정의 수집(custom ingestion)의 경우, 픽스처 계약은 외부 이벤트에서 표준 읽기 모델(canonical read model)로 매핑하는 것을 다루어야 합니다.

버전 6.19.0에서는 사용자 정의 TraceReader 작성과 더 풍부한 실패 역할 상호 운용성(failure-role interoperability)이 추가되었습니다. 이러한 기능들은 통합의 수를 증가시키지만, 파일이 파싱되었는지 여부뿐만 아니라 아키텍처적 의도(architectural intent)를 테스트하는 것의 중요성 또한 높입니다.

CLI 종료 코드는 API입니다

사람은 CLI 문구를 읽습니다. CI는 종료 상태와 JSON을 읽습니다.

무해한 단어 변경은 괜찮을 수 있습니다. 실패 계약(failed contract)을 종료 코드 1에서 종료 코드 0으로 바꾸거나, JSON 키를 이름을 바꾸거나, 표준 오류 출력(stderr) 대신 표준 출력(stdout)에 진단 정보를 인쇄하는 것은 TypeScript 선언을 변경하지 않고도 자동화를 망가뜨릴 수 있습니다.

다음 항목들에 대한 픽스처를 유지하십시오:

• 성공 및 실패 검사;
• 잘못된 형식의 입력;
• 알 수 없는 스키마 버전;
• JSON 출력;
• 마스킹 경고;
• 무결성 확인 실패.

어떤 출력이 기계에 안정적인지, 어떤 것이 사람에게 보여주기 위한 것인지 문서화하십시오.

개인 정보 보호 변경은 더 높은 기준을 요구합니다

캡처 기본값(Capture defaults)과 마스킹 의미론(redaction semantics)은 보안 영향을 동반하는 호환성 문제입니다. 이전에 메타데이터만 존재했던 곳에 프롬프트 프리뷰를 기록하는 사소해 보이는 변경이 사용자의 데이터 경계를 위반할 수 있습니다.

모든 릴리스마다 부정적인 약속(negative promises)을 테스트하십시오:

metadata-only capture에는 프롬프트나 응답 미리보기가 포함되어 있지 않습니다.
redaction은 별도의 아티팩트를 생성합니다.
기본적으로 어댑터 업로드는 이루어지지 않습니다.
...

이러한 단언들은 “명령어가 성공하는지”만큼이나 중요합니다.

행동 호환성 노트 게시하기

저는 이제 변경 사항마다 “major인지 minor인지?”라는 질문보다 네 가지 질문을 더 유용하다고 생각합니다.

1. 어떤 표면(surface)이 변경되었는가?
2. 기존 사용자는 무엇을 관찰하게 될 것인가?
3. 어떤 이전 아티팩트와 설정들이 테스트되었는가?
4. 어떤 마이그레이션 또는 옵트인(opt-in)이 필요한가?

이 답변들을 기계가 비교할 수 있는 릴리스 아티팩트로 만드세요:

{
  "packageVersion": "6.19.0",
  "node": ">=20",
...

위 필드들은 호환성 매니페스트(compatibility manifest)의 형태를 보여주며, 수동으로 복사하기보다는 정확한 릴리스 계약으로부터 생성되어야 합니다. 이를 골든 트레이스(golden traces) 및 CLI 스냅샷 옆에 저장하여 업그레이드가 의도된 움직임과 우발적인 움직임을 모두 드러낼 수 있도록 하세요.

SemVer는 여전히 릴리스의 레이블로 남습니다. 하지만 행동 노트가 그 뒤에 숨겨진 엔지니어링 현실을 설명합니다.

AI 에이전트 라이브러리는 비결정론적 모델과 결정론적 소프트웨어 시스템 사이에 위치합니다. 이들의 역할은 종종 행동(behavior)을 증거, 정책 또는 제어(control)로 변환하는 것입니다. 따라서 사용자들은 단순히 함수 시그니처에 의존하지 않습니다. 그들은 무엇이 포착되는지, 그것이 어떻게 해석되는지, CI가 무엇을 보는지, 그리고 어떤 데이터가 제외되는지에 의존합니다.

이러한 더 광범위한 계약(contract) 역시 버전 관리가 필요합니다.

참고 자료

• Semantic Versioning 2.0.0
• AgentInspect changelog
• AgentInspect 6.19.0 source