P6-18.2 응답보다 근거·상태·회고를 먼저 남기는 최소 구현¶

Section ID: P6-18.2 Version: v2026.07.23

P6-18.1에서 작은 생성형 AI 기능을 요청 해석 -> 검색 또는 도구 선택 -> 응답 생성 -> 상태 판단 -> 기록의 흐름으로 묶었다면, 여기서는 그 흐름을 아주 작은 코드로 다시 그려 보면 됩니다.

최소 구현의 초점은 성능 좋은 서비스를 완성하는 데 있지 않고, 어떤 입력이 어떤 경로를 거쳐 어떤 출력과 기록으로 남는가를 눈으로 확인하는 데 있습니다. 더 정확히는 무엇이 돌아갔는가와 다음에 어디를 먼저 고쳐야 하는가가 같은 요청 기록에서 함께 보이게 만드는 데 있습니다.

요청 실행 기록이 남기는 것¶

핵심 질문은 다음과 같습니다.

실제 상용 API를 붙이기 전에도 어떤 최소 구현을 만들어 볼 수 있는가?
검색, 응답 생성, 검토 필요 여부를 어떤 실행 기록으로 함께 남겨야 하는가?
남은 기록을 보고 다음 개선 지점을 어떻게 읽을 수 있는가?

이 구현은 축약된 기준선 구현입니다. RAG 흐름, 도구 사용 구조, 평가와 기록 관점을 작은 코드로 묶어, 요청이 어떤 출력과 실행 기록으로 남는지 확인합니다. 제품 수준 자동화나 배포 절차를 완성하는 것이 아니라, 같은 기록에서 검색을 먼저 고쳐야 하는가, 근거 부족 게이트를 먼저 고쳐야 하는가, 사람 검토 경계를 다시 잡아야 하는가 같은 패치 우선순위가 읽히게 하는 것이 목표입니다.

중요한 전환은 요청 흐름을 설계한다에서 그 흐름을 실제 요청 실행 기록으로 남긴다로 관점이 바뀌는 데 있습니다. 돌아간다와 기록 가능하게 설계되었다를 구분하는 기준도 여기서 눈에 보이게 만듭니다. 이 기록은 단순 결과 저장이 아니라, 검색 품질, 상태 분류, 사람 검토 handoff 중 무엇을 먼저 손볼지 고르게 하는 입력이어야 합니다.

같은 질문이 코드 흐름 안에서 언제 답변 초안 생성, 근거 부족, 문서 미회수, 사람 검토 필요 같은 상태로 바뀌는지 같이 보는 편이 더 안전합니다. 최소 구현의 핵심은 단순히 문자열을 출력하는 데 있지 않고, 요청 하나가 어떤 운영 상태로 끝났는지를 같은 기록 안에 남기는 데 있습니다.

코드 흐름 안에서 먼저 갈리는 상태	언제 자주 생기는가	왜 이 상태를 따로 남겨야 하는가
답변 초안 생성 가능	관련 근거가 둘 이상 잡히고 충돌이 크지 않을 때	`일단 답을 만들 수 있다`와 `바로 배포 가능하다`를 구분한 채 다음 평가로 넘기기 위해서입니다.
근거 부족	관련 문서는 잡혔지만 직접 근거가 약하거나 하나뿐일 때	검색 성공과 답변 확정 가능을 같은 뜻으로 읽지 않기 위해서입니다.
문서 미회수	질문을 닫을 문서를 아예 찾지 못했을 때	일반론으로 덮지 않고 검색 확장 문제를 분리해 남기기 위해서입니다.
사람 검토 필요	예외 조항이나 승인 경계가 걸려 자동 확답이 위험할 때	최소 구현도 운영 경계와 handoff 지점을 남겨야 다음 개선이 가능하기 때문입니다.

응답 생성과 실행 기록의 구분¶

작은 생성형 AI 기능의 최소 구현 흐름을 읽을 수 있습니다.
검색 결과, 응답, 근거, 실패 기록이 왜 함께 출력되어야 하는지 설명할 수 있습니다.
기능이 돌아간다는 사실과 기능이 잘 설계되었다는 판단이 다르다는 점을 구분할 수 있습니다.
다음 개선 전에 먼저 확인해야 할 최소 기록 구조를 설명할 수 있습니다.

최소 구현의 다섯 실행 단계¶

이 절의 최소 구현은 다음 다섯 단계를 가집니다.

질문을 받는다.
간단한 규칙으로 관련 문서를 찾는다.
찾은 문서를 바탕으로 답변을 만든다.
답을 바로 확정할지, 근거 부족이나 사람 검토가 필요한지 상태를 정한다.
어떤 문서를 썼는지와 답변 품질 메모를 남긴다.

실제 LLM API 호출을 붙이지 않아도 이 다섯 단계를 먼저 확인해 두면, 이후 어디에 모델 호출이 들어가고 어디에 검색 품질 문제가 생기는지 구조를 읽기 쉬워집니다.

정책 문서와 질문으로 남길 실행 상태¶

입력:

정책 문서 CSV에 담긴 정책 조각 12개
서로 다른 실패 유형을 유도하는 사용자 질문 36개

출력:

문서별 검색 점수
선택된 근거 문서
생성된 답변 초안
사람 검토 필요 여부와 평가 메모

이 예제의 목표는 정답률이 아니라 운영 상태 구분을 포함한 흐름 확인입니다. 같은 최소 기능이라도 여러 근거가 맞물린 경우, 근거가 부족한 경우, 검색 자체가 실패한 경우를 구분해 읽어야 다음 개선 우선순위를 정할 수 있습니다. 질문 CSV의 requires_review는 정답표가 아니라, 질문 자체가 승인, 예외, 보안처럼 사람 검토 경계를 건드리는지 표시하는 관찰 신호입니다.

사례 및 예시¶

최소 구현 절이 실제로 필요한 이유는 한 번 돌았다와 운영 판단까지 남겼다를 분리해 보여 주기 위해서입니다. 아래 세 장면은 같은 정책 안내 도우미처럼 보여도, 요청 실행 기록을 남기지 않으면 어디서 실패했는지 다시 읽을 수 없다는 점을 보여 줍니다.

사례 1. 답은 나왔는데 왜 나왔는지 남기지 않으면¶

사람은 답변 문자열만 자연스럽게 보이면 기능이 일단 됐다고 느끼기 쉽습니다. 예를 들어 이번 달에 입사한 직원도 여름휴가를 바로 쓸 수 있나요?라는 질문에, 답변이 그럴듯하게 한 문장으로 나오면 바로 통과시키고 싶어집니다.

하지만 이 경우 실제로 필요한 것은 입사 후 1개월 규정과 여름휴가 승인 규정을 함께 읽었는지, 두 근거가 충돌하지 않았는지, 답변이 어떤 문서를 바탕으로 만들어졌는지 남기는 일입니다. 답만 남기고 근거 문서와 실행 상태를 안 남기면, 나중에 답이 어긋났을 때 검색을 잘못한 것인지 해석을 잘못한 것인지 구분할 수 없습니다.

그래서 최소 구현이라도 답변 문자열 옆에 문서별 점수, 선택 문서, 실행 상태를 함께 남겨야 합니다. 이 사례에서 확인해야 할 결과는 답이 나왔다가 아니라 왜 그 답이 나왔는지를 같은 요청 실행 기록에서 다시 읽을 수 있는가입니다.

이 장면이 중요한 이유는 운영에서 문제가 생겼을 때 사람이 가장 먼저 묻는 질문이 무슨 답을 했나보다 왜 그렇게 답했나이기 때문입니다. 근거 문서와 실행 상태가 빠져 있으면, 다음 날 같은 실패가 나와도 검색 품질 문제인지 프롬프트 해석 문제인지 바로 분리할 수 없습니다. 결국 수정도 감으로 하게 됩니다. 반대로 최소 구현에서도 요청 실행 기록이 남아 있으면, 어떤 문서가 과하게 높은 점수를 받았는지, 어떤 규정이 함께 선택되지 않았는지, 어디서부터 판단이 비틀렸는지를 다시 추적할 수 있습니다.

같은 질문이라도 기록 유무에 따라 운영자가 볼 수 있는 정보는 크게 달라집니다.

요청 실행 결과	겉으로는 어떻게 보이나	운영자가 실제로 다시 읽을 수 있는 것
답변 문자열만 남음	일단 응답은 완성된 것처럼 보임	거의 없음. 검색 실패인지 해석 실패인지 구분 어려움
답변 + 선택 문서 목록이 남음	근거가 있는 것처럼 보임	어떤 문서를 봤는지는 알 수 있지만 왜 그 문서를 골랐는지는 불분명
답변 + 문서 점수 + 선택 문서 + 실행 상태가 남음	작은 기준선 구현처럼 보임	검색, 선택, 해석 중 어디를 먼저 고쳐야 하는지 추적 가능

이 표에서 꼭 붙잡아야 할 기준은 기록이 많으면 복잡하다가 아니라 기록이 없으면 다음 개선이 막힌다는 점입니다. 최소 구현의 초점은 화려한 대시보드를 만드는 일이 아니라, 실패를 다시 읽을 최소 단서를 남기는 일입니다.

사례 2. 근거가 부족한데도 답을 확정해 버리면¶

신규 복지포인트는 이번 주부터 바로 쓸 수 있나요? 같은 질문은 더 위험합니다. 검색 결과가 한 문서만 잡혔다고 해서 바로 답을 확정하면, 실제로는 복지포인트 직접 규정이 아니라 신규 복지 제도는 공지 전까지 인사팀 확인이 필요하다는 일반 문장만 보고 답했을 가능성이 있습니다.

이 장면에서는 관련 문서가 하나라도 나왔으니 일단 답은 가능하다고 느끼기 쉽지만, 더 중요한 것은 근거가 하나뿐인가, 예외 조항 누락 가능성이 있는가, 사람 검토가 필요한가를 함께 남기는 일입니다. 즉 검색 성공과 답변 확정 가능은 같은 단계가 아닙니다.

그래서 최소 구현에서도 근거 부족 상태와 사람 검토 필요 상태를 따로 남겨야, 다음 회고에서 검색 확장 문제인지 승인 게이트 문제인지 분리할 수 있습니다. 이 사례에서 확인해야 할 결과는 답을 생성했다가 아니라 근거 부족 상태를 숨기지 않고 운영 경로로 남겼는가입니다.

실무에서 더 위험한 이유는 문서가 하나 잡혔다는 사실이 사람에게 과도한 안도감을 주기 때문입니다. 검색 화면에 관련 문서 제목이 하나 보이면, 그것을 근거 확보와 거의 같은 뜻으로 받아들이기 쉽습니다. 하지만 운영 판단에서는 관련 문서가 존재한다와 질문을 닫기에 충분한 근거가 있다를 분리해야 합니다. 특히 예외 조항이 따로 있거나 승인 절차가 얽혀 있는 질문에서는 단일 근거 문서만으로 자동 응답을 확정하는 순간 오답이 더 자신 있게 배포될 수 있습니다.

이 차이를 운영 메모처럼 다시 적으면 다음과 같습니다.

상태	먼저 떠올리기 쉬운 해석	실제로 남겨야 할 운영 판단
관련 문서 1건 회수	`찾았으니 답할 수 있다`	직접 근거인지, 주변 설명 문서인지 구분
예외 조항 미확인	`일단 답하고 나중에 보강해도 된다`	사람 검토 필요 상태로 올려야 한다
단일 근거로 자동 응답 완료	`최소 기능은 동작했다`	근거 부족을 숨겼으므로 오히려 운영 위험이 커졌다

이 사례에서 넘어가야 할 오해는 검색 성공 = 자동 응답 허용이라는 등식입니다. 최소 구현이 보여 줘야 하는 것은 자동화의 화려함이 아니라, 지금은 아직 사람 검토로 넘겨야 한다는 경계선을 상태값으로 남길 수 있는가입니다.

사례 3. 아예 문서를 못 찾았는데도 그럴듯한 일반론으로 덮으면¶

야간 근무 수당은 이번 달부터 얼마인가요? 같은 질문을 생각해 보겠습니다. 현재 문서 세트에 야간 수당 규정이 없는데도, 모델이 일반적인 인사 안내 문구를 조합해 사내 규정에 따라 지급됩니다처럼 그럴듯한 답을 만들 수는 있습니다. 검색이 비어도 답변 문장이 자연스러우면 일단 응답은 했으니 나중에 보강하면 되지 않을까라고 생각하기 쉽습니다. 하지만 운영 관점에서는 이런 경우가 가장 위험합니다. 관련 문서를 찾지 못했다는 사실 자체가 핵심 신호인데, 이를 숨기고 일반론으로 덮어 버리면 사람 검토가 필요한 질문과 검색 인덱스를 확장해야 하는 질문이 함께 묻혀 버립니다.

그래서 최소 구현에서는 문서를 찾지 못한 상태를 단순 예외가 아니라 명시적 상태로 남겨야 합니다. 이 상태가 있어야 다음 회고에서 검색 대상 문서가 없었던 것인가, 문서는 있었는데 키워드/임베딩이 못 찾은 것인가, 질문 표현을 더 잘 풀어야 하는가를 분리해서 볼 수 있습니다. 여기서 넘어가야 할 오해는 답을 못 찾았으면 조용히 일반론으로 메우자는 태도입니다. 이 사례에서 확인해야 할 결과는 빈칸을 자연스럽게 덮었는가가 아니라 문서를 못 찾았다는 실패를 운영 상태로 분명히 남겼는가입니다.

세 사례를 요청 실행 기록 관점으로 다시 줄이면 다음과 같습니다.

장면	답만 남기면 놓치는 것	함께 남겨야 할 기록
다중 근거가 필요한 질문	어떤 문서를 같이 읽었는지, 충돌 가능성이 있었는지	문서 점수, 선택 문서, 실행 상태, 답변 초안
근거가 하나뿐인 질문	답을 확정해도 되는지, 사람 검토가 필요한지	근거 부족 상태, 사람 검토 필요 여부, 회고 메모
문서를 전혀 못 찾은 질문	검색 실패인지 해석 실패인지, 일반론으로 덮어 버렸는지	문서 미회수 상태, 실패 메모, 다음 조치

기록으로 다시 읽는 실패¶

최소 구현을 처음 읽을 때 자주 생기는 오판은 일단 답이 나온다는 사실만으로도 구현이 충분하다고 느끼는 점입니다. 하지만 먼저 봐야 하는 것은 답이 나왔는가보다 다음 개선을 위해 무엇이 남았는가를 같은 요청 기록에서 다시 읽을 수 있는가입니다.

이런 장면이 보이면	먼저 확인할 것	왜 그 확인이 먼저 필요한가
답변은 나왔지만 왜 그렇게 답했는지 설명이 안 됨	문서 점수와 선택 근거가 함께 남아 있는가	검색 실패인지 해석 실패인지 분리하려면 답변 뒤의 선택 경로가 보여야 하기 때문입니다.
근거가 약한데도 자동 응답으로 끝남	사람 검토 필요 상태가 따로 남아 있는가	검색 성공과 답변 확정 가능은 같은 뜻이 아니기 때문입니다.
문서를 못 찾았는데도 일반론 답으로 덮음	문서 미회수와 다음 조치가 명시돼 있는가	실패를 숨기면 다음 회고에서 검색 확장 문제와 답변 정책 문제를 구분할 수 없기 때문입니다.

같은 기준을 더 짧은 실무 질문으로 바꾸면 다음처럼 읽을 수 있습니다.

이런 의심이 들면	먼저 던질 질문
`답은 있는데 왜 고쳐야 할지 모르겠다`	어떤 문서가 어떤 점수로 선택됐는가?
`이건 사람이 다시 봐야 하는 답 아닌가?`	사람 검토 필요 여부가 상태로 남았는가?
`검색이 안 됐는데 왜 그냥 답했지?`	문서 미회수와 다음 조치를 숨기지 않고 기록했는가?

먼저 익혀야 하는 기준은 단순합니다. 최소 구현은 응답이 나온다에서 끝나는 장난감이 아니라, 근거 문서, 실행 상태, 사람 검토 필요 여부, 다음 조치를 함께 남겨 다음 개선을 읽을 수 있게 만드는 기준선 구현입니다.

연습 및 예제¶

예제는 질문 -> 검색 -> 답변 초안 -> 평가 -> 기록을 한 번에 확인하는 데 목적이 있습니다. 질문 두 개만 보는 대신 다중 근거가 잡히는 경우, 근거가 하나만 잡히는 경우, 아예 검색 실패가 나는 경우를 함께 넣어, 작은 기준선 구현도 여러 실패 유형으로 갈라진다는 점을 확인합니다. 특히 각 질문이 끝난 뒤 요청 실행 기록 하나로 남도록 만들어, 회고나 운영 판단에서 무엇을 고쳐야 하는지 바로 다시 읽을 수 있게 합니다.

예제 입력은 정책 문서 CSV와 사용자 질문 CSV입니다. 결과에서는 문서별 검색 점수, 선택된 근거 문서, 답변 초안, 사람 검토 필요 여부와 회고 메모, 질문별 요청 실행 기록, 전체 질문 묶음에 대한 요약 통계를 함께 확인합니다.

확인할 핵심은 최소 구현도 검색, 답변, 평가, 기록이 한 흐름으로 묶여야 한다는 점입니다. 질문별 요청 실행 기록을 남겨야 어떤 실패 유형이 반복되는지 다시 읽을 수 있고, 운영 관점에서는 정답률보다 근거 부족과 검색 실패를 어떻게 구분했는지가 더 중요합니다.

코드를 보기 전에, 먼저 아래 대표 질문에 대해 어떤 실행 상태가 남아야 하는지 스스로 적어 보는 편이 좋습니다.

질문	먼저 예상해 볼 실행 상태	왜 이렇게 예상하는가
`이번 달에 입사한 직원도 여름휴가를 바로 쓸 수 있나요?`	다중 근거 확인 상태	입사 규정과 휴가 규정을 함께 읽어야 닫히기 때문
`신규 복지포인트는 이번 주부터 바로 쓸 수 있나요?`	근거 부족 + 사람 검토 상태	직접 근거가 약할 가능성이 커서 예외 조항 누락 위험이 있기 때문
`야간 근무 수당은 이번 달부터 얼마인가요?`	문서 미회수 + 사람 검토 상태	현재 문서 세트로는 관련 규정을 못 찾을 가능성이 크기 때문

답을 미리 적어 두고 코드 결과와 비교하면, 이 예제가 단순 출력 확인이 아니라 질문별 운영 상태 분류를 검증하는 실습이라는 점이 더 분명해집니다.

먼저 이 예제에서 함께 볼 통합 기록 기준은 다음과 같습니다.

점검 항목	왜 필요한가
근거 문서 목록	어떤 근거를 실제로 썼는지 남겨야 해서
사람 검토 필요 여부	답을 바로 써도 되는지, 사람 확인이 필요한지 나눠야 해서
실행 상태	다중 근거 확보, 근거 부족, 검색 실패를 한눈에 구분해야 해서
전체 요약	한 질문씩만 보지 않고 전체 흐름에서 어떤 실패가 많은지 읽어야 해서

아래 예제는 정책 문서 CSV p6_18_2_policy_documents.csv와 질문 CSV p6_18_2_policy_questions.csv를 사용합니다. 문서 파일의 한 행은 정책 조각 하나이고, 질문 파일의 한 행은 사용자 질문과 질문을 해석해 만든 키워드 묶음, 사람 검토 필요 신호를 담습니다. requires_review는 모델이 맞혔는지 확인하는 정답 열이 아니라, 자동 확답이 위험한 질문 유형을 관찰하기 위한 입력 신호입니다. 이 예제는 실제 LLM이나 실제 검색 엔진을 붙인 것이 아니라, 요청 실행 기록에 어떤 근거와 상태가 남아야 하는지 확인하는 기준선 구현입니다.

검색도 자연어 질문을 직접 이해하는 방식이 아닙니다. 질문 CSV의 query_groups와 문서 CSV의 keyword_groups가 겹치는 정도를 점수로 삼는 단순 검색입니다. 그래서 이 예제에서 중요한 것은 검색 품질을 과장하는 것이 아니라, 느슨한 검색이 어떤 문서를 같이 끌고 왔는지와 그 한계를 실행 기록에 남기는 것입니다.

from collections import Counter
from csv import DictReader
from pathlib import Path
from pprint import pprint

OUT_DIR = Path(__file__).resolve().parent
DOCUMENTS_CSV = OUT_DIR / "p6_18_2_policy_documents.csv"
QUESTIONS_CSV = OUT_DIR / "p6_18_2_policy_questions.csv"

SELECTED_QUERIES = {
    "query_001",
    "query_002",
    "query_003",
    "query_007",
    "query_026",
    "query_030",
}
DETAILED_QUERY = "query_001"


def split_groups(value):
    return [item for item in value.split("|") if item]


def parse_bool(value):
    return value == "yes"


def read_documents():
    with DOCUMENTS_CSV.open(newline="", encoding="utf-8") as file:
        return [
            {
                "doc_id": row["doc_id"],
                "title": row["title"],
                "policy_text": row["policy_text"],
                "keyword_groups": split_groups(row["keyword_groups"]),
            }
            for row in DictReader(file)
        ]


def read_questions():
    with QUESTIONS_CSV.open(newline="", encoding="utf-8") as file:
        return [
            {
                "query_id": row["query_id"],
                "question": row["question"],
                "query_groups": split_groups(row["query_groups"]),
                "requires_review": parse_bool(row["requires_review"]),
                "scenario": row["scenario"],
            }
            for row in DictReader(file)
        ]


def score_document(question, document):
    matched_groups = sorted(
        set(question["query_groups"]).intersection(document["keyword_groups"])
    )
    return {
        "doc_id": document["doc_id"],
        "title": document["title"],
        "policy_text": document["policy_text"],
        "score": len(matched_groups),
        "matched_groups": matched_groups,
    }


def retrieve_documents(question, documents, top_k=3):
    scored = [score_document(question, document) for document in documents]
    scored.sort(key=lambda item: (-item["score"], item["doc_id"]))
    return scored[:top_k], scored


def draft_answer(question, retrieved):
    positive_docs = [doc for doc in retrieved if doc["score"] > 0]
    if not positive_docs:
        return "관련 규정을 찾지 못했습니다. 답변을 확정하지 말고 사람 검토로 넘깁니다."

    evidence_lines = [
        f"- {doc['doc_id']}: {doc['policy_text']}" for doc in positive_docs
    ]
    if len(positive_docs) == 1:
        summary_line = "초안 판단: 근거가 하나뿐이므로 예외 조항과 최신 공지를 다시 확인해야 합니다."
    else:
        summary_line = "초안 판단: 여러 근거를 함께 읽어 조건 충돌과 적용 순서를 확인해야 합니다."
    return "\n".join(
        [
            f"질문: {question['question']}",
            "확인된 근거:",
            *evidence_lines,
            summary_line,
        ]
    )


def evaluate_run(question, retrieved):
    positive_docs = [doc for doc in retrieved if doc["score"] > 0]
    notes = []
    if not positive_docs:
        run_status = "retrieval_failed"
        notes.append("검색 실패: 관련 문서를 찾지 못했으므로 사람 검토가 필요함")
        next_patch = "expand_index_or_add_policy_documents"
    elif len(positive_docs) == 1:
        run_status = "single_evidence"
        notes.append("근거 부족 가능성: 한 문서만 잡혔으므로 예외 조항 누락을 점검")
        next_patch = "expand_retrieval_or_add_review_gate"
    else:
        run_status = "multi_evidence"
        notes.append("다중 근거 확인: 여러 문서를 함께 읽어 조건 충돌 여부를 점검")
        next_patch = "improve_grounded_answer_rules"

    if question["requires_review"]:
        notes.append("질문 특성상 자동 확답보다 사람 검토 상태를 남김")

    needs_human_review = (
        run_status != "multi_evidence" or question["requires_review"]
    )
    return {
        "run_status": run_status,
        "needs_human_review": needs_human_review,
        "notes": notes,
        "next_patch": next_patch,
    }


def build_run_record(question, documents):
    top_docs, full_scores = retrieve_documents(question, documents)
    positive_top_docs = [doc for doc in top_docs if doc["score"] > 0]
    evaluation = evaluate_run(question, top_docs)
    return {
        "query_id": question["query_id"],
        "question": question["question"],
        "document_scores": [
            {
                "doc_id": item["doc_id"],
                "score": item["score"],
                "matched_groups": item["matched_groups"],
            }
            for item in full_scores
        ],
        "retrieved_doc_ids": [doc["doc_id"] for doc in positive_top_docs],
        "draft_answer": draft_answer(question, top_docs),
        "evaluation": evaluation,
    }


def load_run_records():
    documents = read_documents()
    return [build_run_record(question, documents) for question in read_questions()]


def summarize_records(records):
    status_counts = Counter(record["evaluation"]["run_status"] for record in records)
    patch_counts = Counter(record["evaluation"]["next_patch"] for record in records)
    return {
        "run_count": len(records),
        "multi_evidence_count": status_counts["multi_evidence"],
        "single_evidence_count": status_counts["single_evidence"],
        "retrieval_failed_count": status_counts["retrieval_failed"],
        "needs_human_review_count": sum(
            record["evaluation"]["needs_human_review"] for record in records
        ),
        "next_patch_counts": dict(sorted(patch_counts.items())),
    }


def compact_record(record):
    return {
        "query_id": record["query_id"],
        "question": record["question"],
        "retrieved_doc_ids": record["retrieved_doc_ids"],
        "run_status": record["evaluation"]["run_status"],
        "needs_human_review": record["evaluation"]["needs_human_review"],
        "next_patch": record["evaluation"]["next_patch"],
        "notes": record["evaluation"]["notes"],
    }


def detailed_record(record):
    return {
        "query_id": record["query_id"],
        "question": record["question"],
        "top_document_scores": record["document_scores"][:5],
        "retrieved_doc_ids": record["retrieved_doc_ids"],
        "draft_answer": record["draft_answer"],
        "evaluation": record["evaluation"],
    }


def main():
    records = load_run_records()
    selected_records = [
        compact_record(record)
        for record in records
        if record["query_id"] in SELECTED_QUERIES
    ]
    detail = next(record for record in records if record["query_id"] == DETAILED_QUERY)

    print("[summary]")
    pprint(summarize_records(records))
    print("[selected_records]")
    for record in selected_records:
        pprint(record)
    print("[detailed_record]")
    pprint(detailed_record(detail))


if __name__ == "__main__":
    main()

실행 결과 예시는 세 층으로 읽으면 됩니다. [summary]는 36개 질문의 상태 분포를 보고, [selected_records]는 대표 질문들이 서로 다른 실행 상태로 갈라지는지 보고, [detailed_record]는 한 요청 안에 문서 점수, 선택 근거, 답변 초안, 평가 상태가 함께 남는지 확인합니다.

[summary]
{'multi_evidence_count': 26,
 'needs_human_review_count': 24,
 'next_patch_counts': {'expand_index_or_add_policy_documents': 8,
                       'expand_retrieval_or_add_review_gate': 2,
                       'improve_grounded_answer_rules': 26},
 'retrieval_failed_count': 8,
 'run_count': 36,
 'single_evidence_count': 2}
[selected_records]
{'needs_human_review': False,
 'next_patch': 'improve_grounded_answer_rules',
 'notes': ['다중 근거 확인: 여러 문서를 함께 읽어 조건 충돌 여부를 점검'],
 'query_id': 'query_001',
 'question': '이번 달에 입사한 직원도 여름휴가를 바로 쓸 수 있나요',
 'retrieved_doc_ids': ['policy_001', 'policy_002', 'policy_003'],
 'run_status': 'multi_evidence'}
{'needs_human_review': True,
 'next_patch': 'expand_retrieval_or_add_review_gate',
 'notes': ['근거 부족 가능성: 한 문서만 잡혔으므로 예외 조항 누락을 점검',
           '질문 특성상 자동 확답보다 사람 검토 상태를 남김'],
 'query_id': 'query_002',
 'question': '신규 복지포인트는 이번 주부터 바로 쓸 수 있나요',
 'retrieved_doc_ids': ['policy_004'],
 'run_status': 'single_evidence'}
{'needs_human_review': True,
 'next_patch': 'expand_index_or_add_policy_documents',
 'notes': ['검색 실패: 관련 문서를 찾지 못했으므로 사람 검토가 필요함', '질문 특성상 자동 확답보다 사람 검토 상태를 남김'],
 'query_id': 'query_003',
 'question': '야간 근무 수당은 이번 달부터 얼마인가요',
 'retrieved_doc_ids': [],
 'run_status': 'retrieval_failed'}
{'needs_human_review': True,
 'next_patch': 'improve_grounded_answer_rules',
 'notes': ['다중 근거 확인: 여러 문서를 함께 읽어 조건 충돌 여부를 점검',
           '질문 특성상 자동 확답보다 사람 검토 상태를 남김'],
 'query_id': 'query_007',
 'question': '개인정보가 들어간 파일을 외부에 공유해도 되나요',
 'retrieved_doc_ids': ['policy_010', 'policy_002', 'policy_004'],
 'run_status': 'multi_evidence'}
{'needs_human_review': True,
 'next_patch': 'improve_grounded_answer_rules',
 'notes': ['다중 근거 확인: 여러 문서를 함께 읽어 조건 충돌 여부를 점검',
           '질문 특성상 자동 확답보다 사람 검토 상태를 남김'],
 'query_id': 'query_026',
 'question': '자산 관리 시스템에서 권한도 신청하나요',
 'retrieved_doc_ids': ['policy_006', 'policy_003', 'policy_007'],
 'run_status': 'multi_evidence'}
{'needs_human_review': True,
 'next_patch': 'expand_index_or_add_policy_documents',
 'notes': ['검색 실패: 관련 문서를 찾지 못했으므로 사람 검토가 필요함', '질문 특성상 자동 확답보다 사람 검토 상태를 남김'],
 'query_id': 'query_030',
 'question': '야간 근무 식대 기준은 어디에 있나요',
 'retrieved_doc_ids': [],
 'run_status': 'retrieval_failed'}
[detailed_record]
{'draft_answer': '질문: 이번 달에 입사한 직원도 여름휴가를 바로 쓸 수 있나요\n'
                 '확인된 근거:\n'
                 '- policy_001: 신입 직원은 입사 후 1개월이 지나면 월차를 사용할 수 있습니다\n'
                 '- policy_002: 여름휴가는 공지된 기간 안에서 팀 승인 후 사용할 수 있습니다\n'
                 '- policy_003: 잔여 휴가 일수 조회는 인사 시스템에서 확인합니다\n'
                 '초안 판단: 여러 근거를 함께 읽어 조건 충돌과 적용 순서를 확인해야 합니다.',
 'evaluation': {'needs_human_review': False,
                'next_patch': 'improve_grounded_answer_rules',
                'notes': ['다중 근거 확인: 여러 문서를 함께 읽어 조건 충돌 여부를 점검'],
                'run_status': 'multi_evidence'},
 'query_id': 'query_001',
 'question': '이번 달에 입사한 직원도 여름휴가를 바로 쓸 수 있나요',
 'retrieved_doc_ids': ['policy_001', 'policy_002', 'policy_003'],
 'top_document_scores': [{'doc_id': 'policy_001',
                          'matched_groups': ['입사', '휴가'],
                          'score': 2},
                         {'doc_id': 'policy_002',
                          'matched_groups': ['휴가'],
                          'score': 1},
                         {'doc_id': 'policy_003',
                          'matched_groups': ['휴가'],
                          'score': 1},
                         {'doc_id': 'policy_004',
                          'matched_groups': [],
                          'score': 0},
                         {'doc_id': 'policy_005',
                          'matched_groups': [],
                          'score': 0}]}

요청 실행 상태와 사람 검토 필요 분포

검색 점수와 운영 상태를 함께 읽기¶

이 예제는 실제 LLM이나 실제 검색 엔진을 호출하지 않습니다. 여기서 먼저 보는 것은 성능이 아니라, 이후 LLM, RAG, tool use를 붙일 때도 유지해야 할 요청 실행 기록의 뼈대입니다. 하지만 이 작은 기준선만으로도 다음 다섯 가지를 분명히 드러낼 수 있습니다.

질문이 들어온다
검색 단계가 점수와 함께 따로 존재한다
답변은 하나의 문서가 아니라 선택된 근거 묶음에 기대어 만들어진다
다중 근거, 근거 부족, 검색 실패가 서로 다른 메모와 실행 상태로 기록된다
질문별 실행 결과가 마지막에 전체 요약으로 다시 묶인다

그래서 이 예제에서 확인해야 할 결과는 모델이 답했다는 한 줄이 아니라, 검색 점수, 근거 문서, 답변 초안, 사람 검토 플래그, 회고 메모, 질문별 요청 실행 기록이 실제로 따로 남는가입니다. 특히 같은 최소 기능 안에서도 다중 근거 확보, 근거 부족, 검색 실패가 서로 다른 운영 상태로 남는지가 중요합니다.

대표 상세 기록에서 잔여 휴가 일수 조회 문서가 함께 잡히는 것도 의도적으로 볼 지점입니다. 이 문서는 같은 휴가 키워드 그룹을 공유하지만, 입사 직후 여름휴가 사용 가능 여부를 닫는 직접 근거라고 보기는 어렵습니다. 따라서 이 결과를 완전한 검색 성공으로 읽으면 안 됩니다. 오히려 단순 키워드 그룹 검색은 주변 문서를 함께 끌고 올 수 있으므로, 실행 기록에 문서 점수와 선택 문서를 남겨야 다음 단계에서 재순위화, 근거 인용 규칙, groundedness 점검을 붙일 수 있다는 점을 확인해야 합니다.

같은 결과를 실무 검토 메모처럼 다시 적으면 다음과 같습니다.

질문	지금 바로 남길 검토 메모	다음 패치 우선순위
입사와 휴가 규정이 함께 걸린 질문	근거는 둘 이상 잡혔지만 조건 충돌 해석 규칙이 필요하다	해석 규칙과 groundedness 점검
복지포인트처럼 직접 근거가 약한 질문	답은 만들 수 있어도 바로 확정하면 위험하다	검색 확장 또는 승인 게이트
문서를 못 찾은 질문	답을 꾸미지 않고 실패를 드러낸 것은 맞지만, 검색 범위가 부족하다	색인 확장, 문서 추가, 사람 검토 흐름

요청 실행 기록에서 무엇을 회고하나¶

이 최소 구현은 코드가 한 번 돌아가는지 확인하는 데서 멈추지 않습니다. 질문마다 남은 요청 실행 기록을 다시 읽어, 실패가 검색 단계에 있었는지, 해석 단계에 있었는지, 사람 검토로 넘겨야 하는 상태였는지를 구분해야 합니다.

예를 들어 문서는 찾았는데 입사 후 1개월 같은 조건을 끝까지 반영하지 못했다면, 이는 검색 성공 뒤의 해석 실패입니다. 이때는 키워드를 더 늘리는 것보다 근거 인용 방식과 답변 검토 규칙을 먼저 봐야 합니다. 반대로 관련 문서가 하나도 잡히지 않았다면 답을 꾸며내기보다 사람 검토 필요 상태를 남기고, 키워드 확장, 임베딩 검색, 색인 개선 쪽을 먼저 확인해야 합니다. 질문에 답은 했지만 실제 잔여 일수나 승인 상태가 빠졌다면 문서 검색 문제가 아니라 조회 API나 도구 호출 부재가 더 직접적인 원인일 수 있습니다.

이렇게 읽어야 같은 실패가 다시 나왔을 때 어디를 먼저 고쳐야 하는지 분명해집니다.

여기서 한 단계 더 가면, 최소 구현이 직접 보여 주는 것과 아직 다음 개선으로 남는 것을 분리해 두는 편이 좋습니다.

상황	이 최소 구현이 직접 보여 주는 것	아직 다음 개선으로 남는 것
질문마다 다른 결과가 나옴	다중 근거, 근거 부족, 검색 실패를 서로 다른 실행 상태로 남김	실제 임베딩 검색, 재순위화, 더 정교한 groundedness 판정
답은 나왔지만 검토가 필요함	사람 검토 필요 상태, 회고 메모, 요청 실행 기록	승인 게이트, 실제 사람 검토 큐, 재시도 정책
근거가 부족하거나 없음	검색 단계와 해석 단계를 구분해 회고함	더 나은 검색 인프라와 도구 호출 연결
코드가 한 번 돌아감	요청 경로와 기록 구조가 분리되어 보임	비용, 지연 시간, 운영 한도까지 포함한 서비스화

이 표의 핵심은 최소 구현이 작동 예시를 넘어서 어디를 다음에 고칠지 보여 주는 기준선이라는 점입니다. 실제 임베딩 검색, tool use, agent loop, 운영 통제는 이 기준선 위에 다음 단계로 얹힙니다.

회고 질문은 다음 정도면 충분합니다.

장면	바로 남겨야 하는 회고 질문	다음에 먼저 손볼 가능성이 큰 곳
문서를 찾았지만 답변이 어긋남	근거를 끝까지 읽었는가	해석 규칙, groundedness 점검
문서를 못 찾아 사람 검토로 넘김	근거 부재를 숨기지 않았는가	검색 확장, 사람 검토 흐름
다음 확장 지점을 고름	실패가 검색 문제인가 도구 부재인가	벡터 검색, tool use, agent 분기

이 최소 구현이 아직 하지 못하는 일¶

이 최소 구현은 분명히 한계가 있습니다.

검색 품질이 단순 키워드 규칙에 의존합니다.
답변 생성이 사실상 템플릿 수준입니다.
문서가 여러 개 충돌할 때 우선순위를 다루지 못합니다.
실제 도구 호출이나 권한 검사는 들어 있지 않습니다.

하지만 바로 이 한계를 적어야 코드가 한 번 실행된다는 사실과 실제 업무 조건에서 반복적으로 쓸 수 있다는 판단을 분리할 수 있습니다.

또 하나 중요한 점은, 이 한계 목록이 곧 설계 우선순위가 된다는 것입니다.

검색 실패가 많으면 검색 품질부터 고칩니다.
문서는 찾는데 답이 자주 어긋나면 답변 생성 규칙과 근거 표시를 먼저 고칩니다.
현재 상태 질문이 많아지면 tool use를 붙입니다.

즉, 최소 구현의 회고는 감상이 아니라 다음 패치 순서를 정하는 입력이어야 합니다.

언제 vector search와 tool use로 확장하나¶

다음 상황이 오면 이 미니 실습은 확장 대상이 됩니다.

문서 수가 많아져 키워드 규칙으로는 한계가 보일 때
비슷한 표현을 더 잘 찾고 싶을 때
현재 상태 조회나 실행이 필요할 때

즉, 이 절은 끝난 구현이 아니라 다음 개선을 위한 기준점입니다.

다음처럼 연결하면 충분합니다.

더 나은 근거 연결이 필요하면 P6-11의 RAG 흐름과 P6-12의 벡터 데이터베이스 구조로 돌아갑니다.
실제 상태 조회나 계산이 필요하면 P6-13의 tool use로 갑니다.
여러 단계 판단이 필요하면 P6-14의 agent 구조로 갑니다.
실패 기록과 안전 장치는 P6-16의 평가 관점과 P6-17의 운영 관점으로 다시 읽습니다.

체크리스트¶

최소 구현은 완성품이 아니라 구조 확인용 기준점이라는 점을 설명할 수 있는가?
검색, 응답, 기록은 따로가 아니라 함께 출력되어야 한다는 점을 설명할 수 있는가?
기능이 돌아간다는 사실과 실제로 쓸 만하다는 판단이 다르다는 점을 구분할 수 있는가?

출처와 참고 자료¶

OpenAI, Retrieval, OpenAI API Docs, 확인 날짜: 2026-07-19.
OpenAI, Working with evals, OpenAI API Docs, 확인 날짜: 2026-07-19.
OpenAI, Evaluate agent workflows, OpenAI API Docs, 확인 날짜: 2026-07-19.