표현이 다른 문장은 의미로 찾되, 제품명·고유 용어·수치는 정확히 놓치지 않아야 했습니다.

사용 기술

PostgreSQL · pgvector · FTS/RRF

선택 이유

벡터 검색의 의미 유사도와 전문 검색의 정확한 토큰 일치를 함께 사용하고, 팀 문서와 검색 근거를 같은 데이터 경계 안에 두기 위해 선택했습니다.

검증 근거

팀 범위로 후보를 제한한 뒤 vector·lexical 결과를 RRF로 합치고, 선택된 chunk를 초안의 인용 근거로 유지합니다.

트레이드오프

두 검색 결과의 가중치와 인덱스를 함께 튜닝해야 하며, 검색 경로를 추적하는 코드가 늘어납니다.

여러 단계의 AI 실행은 중단 후 재개해야 하지만, 공급자 런타임을 제품 상태의 원본으로 사용할 수는 없었습니다.

사용 기술

OpenAI Agents SDK · PostgreSQL · Prisma

선택 이유

Agents SDK에는 실행 오케스트레이션을 맡기고, 팀·문서·실행·검수 상태는 제품 DB에 영속화해 책임을 분리했습니다.

검증 근거

Agent 실행 ID와 단계 상태를 Prisma 레코드에 연결하고, 재개 시에도 저장된 제품 상태와 권한을 기준으로 다음 작업을 결정합니다.

트레이드오프

런타임 상태와 제품 상태 사이의 멱등성, 재시도, 동기화 규칙을 별도로 관리해야 합니다.

최종 결과만 저장하면 어느 단계에서 오류가 시작됐는지 찾거나 같은 조건으로 다시 실행할 수 없었습니다.

사용 기술

TypeScript · Zod · Prisma · revisioned checkpoints

선택 이유

작성 과정을 명시적 상태 전이로 만들고 단계별 입력·출력과 revision을 보존해 부분 재실행과 비교가 가능하도록 했습니다.

검증 근거

attempt UUID, 단계 transition, checkpoint snapshot을 스키마로 검증하고 presstuner-debug-run/v3 형태의 변경 불가능한 실행 근거를 발행합니다.

트레이드오프

단계와 스키마가 바뀔 때 버전 호환성을 유지해야 하고, 저장량과 전이 관리 코드가 증가합니다.

프롬프트 변경이 좋아 보이더라도 유용한 내용을 지우거나 비용·지연을 악화시키는 회귀를 놓칠 수 있었습니다.

사용 기술

버전 평가셋 · baseline/candidate · human gate

선택 이유

같은 사례와 기준으로 변경 전후를 비교하고, 자동 점수만으로 배포하지 않기 위해 선택했습니다.

검증 근거

실제 문서 기반 평가 사례, 독립적으로 계산한 품질·비용·지연 결과, 케이스별 regression 기록을 함께 남기고 사람이 최종 승인합니다.

트레이드오프

평가셋을 계속 관리해야 하고, 검수 단계를 거치는 만큼 실험에서 배포까지 시간이 더 걸립니다.

LangSmith trace와 PostHog·GA4 이벤트의 식별자가 달라 같은 AI 작업의 원인과 제품 결과를 연결할 수 없었습니다.

사용 기술

service-issued operation ID · versioned workflow contract

선택 이유

공급자 ID가 아닌 제품 서비스의 안정적인 작업 ID를 모든 관측 도구에 전파해 공통 join key로 사용했습니다.

검증 근거

워크플로 시작 시 발급한 operation ID를 LangSmith metadata, PostHog·GA4 이벤트, brieFFlow checkpoint snapshot에 기록하고 수집 시 동일성을 검증합니다.

트레이드오프

모든 producer가 계약과 버전을 따라야 하며, 누락되거나 오래된 계약을 별도로 처리해야 합니다.

운영 콘솔이 여러 분석 도구에 접근하면서 과도한 권한, 개인정보 수집, 끝없는 재시도 위험을 만들 수 있었습니다.

사용 기술

Read-only connectors · allowlist normalization · bounded collection

선택 이유

수집을 읽기 전용·프로젝트 범위로 제한하고 허용된 필드만 정규화해 중앙 콘솔의 보안 반경을 줄였습니다.

검증 근거

LangSmith·PostHog·GA4 수집기는 page·record·retry 한도를 가지며, 정규화된 행이 저장된 뒤에만 cursor를 이동하고 불완전한 수집은 partial로 표시합니다.

트레이드오프

원본 payload의 세부 정보 일부를 포기하고, 공급자별 allowlist와 adapter를 유지해야 합니다.

대시보드와 보고서가 지표를 따로 계산하면 같은 기간에도 서로 다른 숫자를 보여줄 수 있었습니다.

사용 기술

PostgreSQL · strict schemas · canonical hash · deterministic aggregation

선택 이유

정규화된 근거와 지표 계산을 하나의 계약으로 고정해 모든 화면과 보고서가 같은 결과를 재사용하도록 했습니다.

검증 근거

Zod 스키마가 알 수 없거나 안전하지 않은 필드를 거부하고, canonical hash와 provider-neutral metric engine이 동일 입력에서 동일 집계를 만듭니다.

트레이드오프

계약 변경에는 schema migration이 필요하고, 새 공급자는 canonical model에 맞추는 adapter를 구현해야 합니다.

자연어 보고서가 원본 로그를 임의로 해석하거나 저장된 지표와 다른 숫자를 만들어서는 안 됐습니다.

사용 기술

RAG reporting · numeric citation verifier

선택 이유

LLM의 역할을 검증된 집계를 설명하는 데 한정하고, 모든 수치 주장을 저장된 fact와 source로 역추적하도록 했습니다.

검증 근거

보고서 생성 전에 프로젝트·기간별 canonical fact를 검색하고, 생성 뒤 숫자 citation이 실제 근거와 일치하지 않으면 검증 단계에서 거부합니다.

트레이드오프

검증 가능한 fact가 없는 질문에는 답변 범위를 제한해야 하며, 자유로운 분석보다 보수적으로 동작합니다.