들어가며

테스트는 모두 통과되었습니다.
그런데 나중에서야 알았습니다. 테스트한 건 ‘현재’가 아니라 기획서 속의 ‘과거’였다는 사실을요.

QA의 테스트 설계는 보통 추측에서 시작합니다. 기획서와 경험을 바탕으로 "지금은 이렇게 동작하겠지"라며 테스트 케이스(TC)를 작성합니다. 하지만 기획서에 적힌 현재 동작이 틀렸다면, 그 기획서로 만든 TC 역시 잘못된 기준을 검증하게 됩니다. 테스트가 통과해도 무엇이 틀렸는지 알아차리기는 쉽지 않습니다.

원래는 과제를 하나씩 순서대로 진행했습니다. 그러다 혼자서 8개 팀의 과제를 한꺼번에 맡게 되면서 감당하기 어려워졌습니다. "이거 지금도 진짜 이렇게 동작하나?" 싶어도 확인할 시간이 없었습니다. QA라면 다들 비슷한 경험을 해보셨을 거예요.

AI를 도입해 봤습니다. 하지만 AI 역시 똑같은 문서를 보고 똑같이 추측할 뿐이었습니다. 오래된 문서를 근거로, 사람보다 더 빠르고 더 그럴듯하게 틀렸습니다. 결국 AI의 판단이 맞는지 검증할 방법이 필요했습니다.

이 글은 3월부터 10월까지 추측을 확신으로 바꾸기 위해 시도한 과정입니다. 잘된 부분과 생각보다 효과가 없었던 시행착오도 함께 적었습니다.

1. 문제의 정의

기존 방식에서 테스트 설계의 출발점은 기획서와 API 명세였습니다. 기획서가 확정되고 리뷰가 끝나야 테스트를 설계할 수 있었고, 문서에 적힌 현재 동작을 의심할 근거도 부족했습니다.

하지만 코드에서 직접 현재 동작을 확인할 수 있다면, 기획서가 바꾸려는 내용과 실제 코드를 비교해, 기획 리뷰 전에 확인할 항목을 추려 낼 수 있습니다.

병목은 주로 테스트 설계 기간에서 생겼는데, 2025년 상반기에는 과제의 절반 이상(52%)이 테스트 설계에만 4일 넘게 걸렸습니다. 문서만 보고 분석해서는 설계 기간을 줄이기 어려웠습니다.

그래서 두 가지 가설을 세웠습니다. 아래는 그 가설을 검증하며 방법을 발전시켜 온 과정입니다.

• 가설 1. 현재 동작의 기준을 코드로 고정하고 판정마다 근거를 남기면, 추측이 확신으로 바뀌고 판단이 빨라질 것이다.
• 가설 2. 분석 결과와 확인할 질문을 기획 리뷰 전에 정리하면 테스트 설계 기간을 줄일 수 있을 것이다.

2. 시행착오 과정

위 가설을 검증하기 위해 한 번에 완성하지 않고, 각 단계에서 드러난 한계를 다음 단계에서 순차적으로 고쳐 나갔습니다.

2.1 1단계 단순 문서 기반 분석(AI 도입 초기)

초기에는 기획서와 API 명세서만 AI에 붙여 넣어 리포트와 TC를 빠르게 얻어내는 방식을 썼습니다. 하지만 실제 코드를 대조하는 기준선이 없다 보니, 질문 방식에 따라 결과물의 형식과 내용이 매번 달라졌습니다.

처음에는 기획서와 API 명세를 AI에 입력하고, 불일치 항목과 테스트 시나리오를 추출했습니다. 사람이 문서를 읽고 TC를 작성하던 작업 일부를 AI가 대신하도록 한 것입니다.

초기 결과는 나쁘지 않았습니다. 시나리오를 빠르게 정리하고 문서 사이의 차이를 찾을 수 있었습니다. 하지만 이 방식에는 명확한 한계가 있었습니다.

1. 기획서의 현재 동작이 틀렸는지 확인할 기준이 없었습니다.
2. 작업 조건이 세션마다 달라 매번 프롬프트로 분석 순서와 결과 형식을 설명해야 했습니다. 같은 과제의 리포트를 여러 번 다시 요청하는 일도 잦았습니다.
3. 산출물 형식이 통일되지 않아 사람이 다시 대조하고 손보는 시간이 매번 들었습니다.

테스트 설계 기간도 크게 달라지지 않았습니다.

AI는 문서를 읽는 속도를 바꿨지만 판단은 여전히 사람 몫이었고, 매번 다른 결과물을 같은 품질로 맞추는 데 시간을 쓰고 있었습니다. 먼저 AI가 매번 같은 조건에서 일하게 만들었습니다.

2.2 2단계 하네스 엔지니어링(절차 구체화)

Claude 채팅으로 설명하던 규칙과 작업 순서를 파일로 고정하고, 세션이 열릴 때마다 자동으로 불러와 일관된 결과물을 내도록 만든 하네스(harness) 구조입니다.

7월부터 하네스(harness) 구조를 정리했습니다. 목표는 매번 말로 설명하던 규칙과 작업 순서를 파일로 고정하고 세션이 시작될 때 주어지는 조건과 산출물의 틀을 정하는 것이었습니다.

구조는 네 가지 요소로 나눴습니다.

매번 다르게 표현되던 판정도 네 가지로 정리했습니다.

마지막 판정을 따로 둔 이유는 근거를 찾지 못한 항목을 AI가 그럴듯한 설명으로 채우면 안 되기 때문입니다. 확인되지 않은 사실은 미확인 상태로 남겨야 사람이 추가로 확인할 수 있습니다.

산출물은 하나의 형식으로 통일됐지만, 작업 규칙을 고정하는 것만으로는 핵심 문제가 풀리지 않았습니다. 실제 동작을 확인할 코드를 찾는 방법이 여전히 없었기 때문입니다. 판정의 근거를 얻으려면 무엇을 기준으로 판단할지부터 바꿔야 했습니다.

2.3 3단계 코드랙(Code Rack → RAG) 정착

하네스를 정리하던 즈음 코드 분석도 함께 붙였습니다. 처음에는 저장소를 직접 내려받고 grep으로 코드를 찾았고, 이렇게 코드를 보는 방법에 코드랙(Code Rack)이라는 이름을 붙였습니다.

이름은 RAG(Retrieval-Augmented Generation, 검색 증강 생성)에서 착안한 말장난이었습니다. 동시에 저장소에 있는 코드를 보관대(Rack)에서 필요한 만큼 꺼내 쓰듯, 관련 코드를 찾아 분석에 활용한다는 의미도 담았습니다.

처음에는 이름만 RAG를 닮았을 뿐, 실제 구현은 clone + grep이었습니다. 이후 시스템 맵으로 탐색 범위를 넓혔고, 결국 RAG를 도입하면서 이름과 구현 방식을 일치시켰습니다.

검색 방식이 발전하는 동안에도 변하지 않은 원칙이 하나 있습니다. 코드랙에서 검색은 분석할 대상을 찾는 수단이고, 판단의 기준이 되는 단일 출처(SoT, Source of Truth)는 코드입니다.

어느 코드를 현재 동작으로 볼 것인가

코드를 찾는 것만큼 어려웠던 건, 어느 코드를 현재 동작으로 볼지였습니다. 사내 코드 검색은 develop 브랜치만 색인하고 있었습니다. 배포가 main이나 master로 이루어지는 저장소라면 develop에는 아직 배포되지 않은 코드가 섞일 수 있습니다. 이 코드를 현재 동작으로 오해하면 기획서의 오류를 찾으려다 다른 오류를 만들 수 있습니다.

각 서비스 저장소의 운영 기준 브랜치를 내려받아 분석에 사용했습니다. 리포트에는 어느 저장소의 어느 커밋을 확인했는지 저장소@커밋 형식으로 기록했습니다.

이제 기획서 설명과 실제 코드가 다르면 그 차이를 변경점(델타)으로 적습니다. 변경점마다 코드를 인용해 동작과 enum 값까지 바로 확인할 수 있습니다.

초기 모델: clone + grep, 그리고 시스템 맵

첫 구현에서 필요했던 것은 실제로 존재하는 코드와 그 위치였습니다. 의미 기반 검색 결과는 이름이나 맥락만 비슷할 뿐 실제 호출 경로와 무관할 수 있어서, 그것만으로 해당 동작의 구현이라고 판단할 수는 없습니다.

임베딩이나 별도의 검색 인덱스 없이 시작했습니다. 저장소를 직접 내려받아 grep으로 관련 문자열을 찾고, 호출 흐름을 따라가며 구현을 확인했습니다.

남은 문제는 범위였습니다. 검색어를 잘못 고르거나 서비스 간 호출을 놓치면 분석 범위 자체가 빠집니다. QA가 확인할 동작은 여러 서비스와 API를 거치는 경우가 많아서, 처음 찾은 결과만으로는 영향 범위를 파악하기 어렵습니다.

이를 보완하기 위해 서비스 간 관계를 시스템 아키텍처 맵으로 정리했습니다. AI는 과제의 진입점을 찾은 뒤 맵을 따라 연결된 서비스와 의존성까지 분석 범위를 넓힙니다. 시스템 맵은 어디까지 볼지를 정하고, 코드 검색과 추적은 실제로 무엇이 구현되어 있는지 확인합니다. 검색 인덱스 없이도 RAG와 비슷하게 동작하는 구조였습니다.

정착 모델: Rack을 RAG로

시스템 맵을 활용한 방식은 초기 검색의 한계를 보완했지만, 과제를 진행할수록 새로운 문제가 드러났습니다.

• 한계 1. 기획서와 코드의 용어가 다릅니다. 기획서의 ‘한그릇’과 코드의 mfo처럼 사내 줄임말과 도메인 용어가 다르면, 관련 심볼을 미리 알지 못하는 한 grep으로는 찾을 수 없습니다.
• 한계 2. 시스템 맵을 사람이 관리해야 합니다. 코드는 계속 바뀌는데 맵이 뒤처지면, 맵에 없는 연결은 분석 범위에서 빠질 수 있습니다.
• 한계 3. 탐색 범위가 넓을수록 비용이 커집니다. 과제마다 진입점을 찾고 관련 파일을 읽으며 호출 흐름을 확인하는 작업이 반복됩니다.

이 한계를 메우려고 코드랙에 RAG를 도입하되, 검색과 판정의 역할은 나눴습니다. RAG는 관련 코드의 후보를 찾고, 최종 판정은 코드로 합니다.

코드랙의 전체 흐름

코드랙은 운영 코드에서 분석 대상을 찾는 데서 끝나지 않습니다. 기획서와 코드의 차이를 변경점으로 정리하고, 그 차이에서 테스트 범위를 정한 뒤, 실제 환경에서 검증하는 데까지 이어집니다.

아래는 코드 확보부터 변경점 분석, 테스트 범위 도출, beta 환경 검증까지의 흐름입니다.

배달권역 전환에서의 코드랙 검증

배달권역 전환 과제는 코드랙을 시험하기에 딱 맞는 과제였습니다. 배달권역은 한 곳의 설정이 여러 서비스에 걸쳐 영향을 주는 구조여서, 일부만 이전 방식으로 되돌리더라도 어디까지 영향이 가는지를 코드에서 넓게 찾아내야 했기 때문입니다.

화면을 그리는 서비스에는 코드 변경이 없는데, 그 서비스가 호출하는 API 쪽 변경이 여러 곳에 영향을 주는 구조였습니다. 기획서만 봐서는 영향 범위가 드러나지 않고, 코드를 따라가야 보이는 과제였습니다.

AI가 만든 리포트를 개발자에게 공유하고, 리포트 전체를 읽은 뒤 의견을 받았습니다. 개발자 의견을 바탕으로 리포트의 판정을 네 가지로 나눴습니다.

개발자가 수정이나 추가가 필요하다고 판단한 비중은 19%였습니다. 나머지 8%는 틀렸다기보다, 외부 응답에 달려 있거나 근거를 찾지 못해 AI가 단정하지 않고 남겨 둔 부분이었습니다. 물론 이 방식을 정량 평가라고 하기엔 한계가 있습니다. 그래도 판정마다 코드 위치가 붙어 있어서, 개발자가 맞는지 확인하는 데 시간이 오래 걸리지 않았다는 점은 분명했습니다.

2.4 리포트 구조 개편

코드 근거가 붙자 리포트는 정확해졌습니다. 대신 너무 길어져서 끝까지 읽기 어려웠고, AI가 분석을 대신해 줘도 그 결과를 읽는 데 다시 시간이 들었습니다.

리포트를 읽는 사람은 기획자, 개발자, QA입니다. 이들이 알고 싶은 건 무엇이 바뀌는지, 자기가 무엇을 확인하거나 답해야 하는지입니다.

코드 경로는 신뢰도를 확인할 때 주로 쓰는 도구이므로 부록으로 옮겼습니다. 본문에서는 핵심 변경점을 먼저 확인하고, 판단이 필요할 때 부록에서 코드 근거를 찾아보도록 순서를 맞췄습니다.

리포트의 구조는 스킬에, 정책 요약을 쓰는 자세한 방법은 스킬이 참고하는 레퍼런스 템플릿에 나눠 적었습니다.

<skill>  SKILL.md — 리포트 구조
  ① 리포트 맨 위(생성일 줄 바로 아래) §0에 정책 요약을 먼저 쓴다. 별도 파일로 만들지 않는다.

  <reference>  references/policy-brief-template.md — 정책 요약 쓰는 법
    ② 코드 인용은 부록에 있으므로 §0에서는 파일 경로를 쓰지 않는다.
    ③ 먼저 배경 한 줄. AS-IS 서술은 반드시 코드에서 확인한 동작으로 쓴다.
    ④ 1. 무엇이 생기나 — 기획서 예시를 표로, "바뀌지 않는 것:" 1문장
    ⑤ 2. 운영 케이스 — 코드 흐름 2~3문장 + "코드에서 확인한 전제:" (Δ번호 병기)
    ⑥ 3. 어드민·화면 수정사항 — 화면 경로를 따라 불릿으로, 한 줄에 한 동작
    ⑦ 4. 여기에 맞춘 API 변경점 — | API | 지금(AS-IS) | 바뀌어야 하는 것 |, "변경 없음"도 행으로
    ⑧ 표 아래에 기획서 밖 영향(타 시스템·타 팀·로그)이 있으면 2~3문장
    ⑨ 아직 확정되지 않아 물어봐야 하는 것 — (Q1)…(Q5) 번호와 함께. 번호는 §7과 같게
  </reference>

  ⑩ 확인 기준(코드 브랜치·커밋, 기획서·스펙 버전)은 부록 A에 둔다.
  ⑪ 본문 §3은 지금 동작 / 기획서 / 개발 코드(또는 스펙) / 판정 열을 사람이 읽는 동작 문장으로 쓴다.
  ⑫ 파일·라인 인용은 부록 B에 모은다. 부록은 없애지 않고 숨긴다.
  ⑬ §0 안의 Δ·Q 번호는 같은 리포트 §3·§7(질의 모음)과 맞춘다.
  ⑭ 질의는 §7 질의 모음(열린/닫힌)으로 따로 모은다.
  ⑮ Q 번호는 구조화 문서 §7·TC 비고와 같게 유지하고, 닫혀도 번호를 재사용하지 않는다.
  ⑯ 질의마다 관련 Δ·TC 번호를 적는다.
</skill>

이 규칙으로 리포트를 생성하면, 이런 결과가 나옵니다.

리포트 맨 위의 정책 요약입니다. 자리는 스킬이, 안의 순서는 레퍼런스 템플릿이 정합니다.

본문의 변경점 표입니다. 지금 동작과 바뀌는 동작을 나란히 놓고, 항목마다 판정을 붙이고, 코드 근거는 부록으로 보냅니다.

코드만으로는 답할 수 없는 것은 질의로 남깁니다.

3. QA의 변화

1장에서 세운 가설 1은 프로세스 변화에서, 가설 2는 설계 기간 변화에서 확인합니다.

3.1 프로세스 변화

기획서 분석부터 테스트 설계, 실행, 회고까지 AI와 코드를 활용해 달라진 프로세스 변화입니다.

이제는 기획서가 완성될 때까지 기다릴 필요가 없습니다. 예전에는 기획서가 완성돼야 읽고, 현재 동작을 추측해 바로 TC를 작성했습니다.

지금은 코드로 현재 동작을 확인하고 초안 기획서, 명세와 다른 점을 정리한 뒤 테스트 범위부터 설계합니다.

실제로 만들어진 TC는 이렇습니다. TC마다 확인할 필드와 사전조건, 예상결과를 작성했습니다.

3.2 설계 기간 변화

이 변화가 테스트 설계 기간에 어떻게 나타났는지도 확인했습니다.

그래프를 보면, AI를 사용한다는 사실만으로 설계 기간이 줄지는 않았습니다. 문서 기반 분석과 하네스, 코드랙 단계에서도 설계 기간은 2일 안팎이었습니다. 현재 동작을 확인할 기준을 코드에 두고 분석 결과를 리뷰 전에 읽을 수 있게 정리하면서, 일하는 순서가 달라졌습니다. 본격적으로 리포트를 발행한 10월에는 평균 1.4일까지 줄일 수 있었습니다.

4. 기준을 만드는 사람, 확인하는 AI

AI 덕분에 결과물은 빠르게 나옵니다. 문제는 사람이 그 속도를 따라가기 어렵다는 점이었습니다. AI가 만든 리포트를 사람이 처음부터 다시 읽고 하나하나 맞는지 따져 봐야 한다면, 결과적으로 사람이 들여야 하는 시간은 줄지 않습니다.

필요한 건 무엇을 믿고 무엇을 의심할지 정하는 규칙이었고, 이에 맞춰 할 일을 다시 나눴습니다.

사람은 여러 과제를 겪으면서 기준을 만듭니다. 코드를 어디까지 따라가야 하는지, 무엇을 근거로 볼지, AI가 틀렸을 때 어떤 규칙을 하나 더 넣어야 하는지를 정합니다.

AI는 그 기준과 실제 코드를 보고 무엇이 바뀌는지 찾아냅니다. 그 결과는 다시 사람이 확인합니다.

물론 코드가 모든 답을 알려주지는 않습니다. 코드는 지금 어떻게 동작하는지를 보여줄 뿐, 그게 맞는 동작인지까지 알려 주지는 못합니다. 외부 시스템처럼 코드 밖에 있는 것도 있고, AI도 여전히 틀립니다.

따라서 AI의 결과를 정답으로 믿지 않고 근거를 보여 달라고 합니다. 모르는 건 미확인으로 남겨두고, 틀린 부분은 다음 규칙으로 보완해 나갑니다.

지금도 과제는 여러 개가 한꺼번에 들어옵니다. 하지만 이제는 "이거 지금도 진짜 이렇게 동작하나?"라는 질문에 답을 찾을 수 있습니다. 더는 추측으로 넘어가지 않아도 됩니다.

적어도 QA에 AI를 써보며 찾은 역할 분담은 그랬습니다.

5. 마치며

처음 AI를 도입했을 때 줄이고 싶었던 건 설계 시간이었습니다. 그런데 지난 7개월 동안 실제로 바뀐 건 작업 속도가 아니라 판단의 기준과 업무의 순서였습니다. 추측 대신 코드로 직접 확인하고, 근거가 없는 부분은 질문으로 남기기 시작했습니다. 설계 시간이 줄어든 건 그 결과였습니다.

지금도 테스트는 통과합니다. 달라진 게 있다면, 이제는 어떤 근거로 통과했는지 설명할 수 있다는 점입니다.

다만 아직은 이 규칙들을 사람이 기억해서 지키고 있습니다. 다음 목표는 리포트 규칙과 판정 기준을 팀이 함께 쓰는 QA 시스템으로 옮겨, 규칙을 시스템이 지키게 만드는 것입니다. 코드가 없는 신규 기능이나 외부 시스템과 연동된 동작처럼 여전히 사람이 직접 확인해야 하는 영역도 남아 있습니다. 그 영역을 어디까지 줄일 수 있을지는 앞으로 더 고민해야 할 문제입니다.