Case 08 · Technical Retrospective
LLM이 TC를 잘 쓰게 만든 과정이 아니라, LLM이 틀려도 제품 범위·실행 차수·검증 결과·산출물이 망가지지 않도록 통제 구조를 만든 과정입니다.
Claude Code, 사용자 매뉴얼, 릴리즈 노트와 Excel만 있던 제로베이스에서 시작해 문서 evidence, 요구사항 분해, YAML TC, run/Jira, 제품별 웹 인스턴스, cache invalidation과 Excel 2013 최종 검증까지 발전한 과정을 실패 중심으로 정리했습니다.
실패할 때마다 문장을 다시 쓰는 대신, 그 실패를 더 앞 단계에서 잡는 schema, validator, 상태 모델 또는 운영 Gate로 바꿨습니다.
Claude Code가 문서와 Excel을 직접 읽고 쓰는 단일 흐름이었습니다. 문서 권위, TC schema, 실행 이력과 검증 자동화가 없었습니다.
정답을 더 잘 생성하는 문제를 떠나, 근거 분류, 제품 범위, 상태 전이, run snapshot과 재조회 검증을 설계했습니다.
YAML quality, 테스트, 웹 revision 재조회, Jira reread와 Excel 2013 실제 열기까지 통과해야 산출물이 완료됩니다.
| 단계 | 이전 방식 | 전환점 | 새 통제 장치 |
|---|---|---|---|
| 1. 문서 읽기 | 문단 중심 요약 | 화면과 초기 설정 절차 누락 | 렌더링 이미지 검토, 화면 단위 pre-chunk, coverage matrix |
| 2. TC 세분화 | 기능 하나를 TC 하나로 작성 | 열기·조회·재조회는 서로 다른 실패를 검출 | 상태 전이와 관찰 지점별 독립 TC |
| 3. 데이터 구조화 | Markdown/Excel이 원본 | 정의와 결과가 섞여 재생성 불가 | 정책 YAML, TC·dataset·suite·run 분리 |
| 4. 실행 차수 | 매 차수 Excel 복사 | 이전 FAIL과 변경 TC 의미 소실 | run snapshot, inheritance, PENDING, Not Run, retired |
| 5. Jira | 사람이 상태 재입력 | Closed 이슈 PASS 반영 누락 | Fix Version 전수 대조, ETag PUT, reread verify |
| 6. 웹 운영 | 읽기 전용 catalog | 파일 변경 후 프로세스 cache가 과거 TC 노출 | explicit invalidate, watcher, LKG, stale 가시성 |
| 7. 산출물 | 생성 성공을 완료로 간주 | office 앱별 색상·수식·레이아웃 차이 | 구조 검사 후 Excel 2013 final-open Gate |
| 8. 다제품 | 공통 기능과 제품 자산 혼재 | 존재하지 않는 제품 기능이 TC에 포함 | 제품별 branch/root/instance, 공통 runtime만 승격 |
| 9. Claude | 작성 결과를 바로 신뢰 | 근거 없는 귀인과 긴 중간 출력 | sanitized read-only review와 local disposition |
사람의 판단이 필요한 Evidence Gate를 가운데 두고, 정의·실행·운영·출력을 각각 별도 책임으로 나눴습니다.
flowchart LR
A["문서 / 기획서 / 화면 증거"] --> B["요구사항 분해<br/>Q&A Evidence Gate"]
B -->|confirmed| D["YAML TC<br/>정적 Validator"]
B -->|unresolved| H["사람 확인"]
H --> B
D --> F["Run Snapshot<br/>Jira 상태 동기화"]
F --> W["웹 실행 / 편집<br/>Cache consistency"]
W --> X["Excel 생성<br/>Excel 2013 검증"]
사용자의 정정이 어떤 즉시 수정으로 끝났고, 다시 같은 문제가 생기지 않도록 무엇을 자산화했는지 연결했습니다.
관찰: 4~6개 화면 묶음에 의미가 섞였고 초기 설정, 장비 등록과 모델 선택이 빠졌습니다.
조치: DOCX 100쪽을 렌더링하고 이미지와 본문을 함께 대조해 하위 화면별 pre-chunk로 재분할했습니다.
관찰: 단일 모델도 기본 열기, 올바른 조회, 조건 변경 후 데이터 혼입이 서로 다른 위험이었습니다.
조치: 모든 보고서의 단일 모델 baseline을 세 TC로 분리했습니다.
관찰: WPF 창을 유지한 연속 조회와 export가 사용자 경험에 치명적인 회귀 표면이었습니다.
조치: 비동기 완료 역전, 0건, 오류·취소, 반복 조회, 창 재오픈과 정렬·필터 export를 추가했습니다.
관찰: 정렬한 화면 대신 source를 재조회한 파일이 생성됐고, batch 누적 의미도 초기 해석과 달랐습니다.
조치: visible snapshot 계약, run 결과 모델, ETag, explicit invalidate, 직접 편집과 파일 기반 정적 token을 구현했습니다.
관찰: 같은 Fix Version의 새 차수에서 과거 결과와 변경 TC를 구별할 수 없었습니다.
조치: 결과 승계, PENDING, Not Run, retired 보존과 Jira 전수 대조, 불완전한 제안의 mutation 전 복구를 적용했습니다.
관찰: 11개 묶음 변경점이 실제 기능과 회귀 영향 경계를 숨겼습니다.
조치: 29개 기능 경계, 203 TC, 47 dataset과 한국어·영어·중국어·일본어 검색 별칭으로 보강했습니다.
관찰: 무응답처럼 보이는 긴 실행, 중간 JSON 소모와 잘못된 기준선 귀인이 있었습니다.
조치: 20~30분 wait, 최종 텍스트만 수집, sanitized read-only packet과 base/head 검증을 의무화했습니다.
관찰: Jira Closed FAIL의 PASS 후처리가 빠졌고 고객사 전용 제품에 비대상 모듈 TC가 섞였습니다.
조치: 공통 Jira 조회-판정-PUT-재조회 모듈, Excel 2013 Gate와 제품 scope lock을 도입했습니다.
실수의 영향, 실제 탐지 신호와 재발 방지 장치를 같은 행에 두었습니다. 수정 결과보다 탐지 가능성과 통제 위치가 중요했습니다.
| 실수 | 영향 | 탐지 방법 | 재발 방지 장치 |
|---|---|---|---|
| 화면 4~6개를 한 청크로 묶음 | 검색과 TC에 여러 기능 목적이 섞임 | heading과 렌더링 화면의 목적 대조 | 하위 화면 단위 pre-chunk boundary |
| 초기 설정·장비 등록·모델 선택 누락 | 신규 QA가 시작 상태를 만들 수 없음 | 원문 heading, image inventory, 생성 index 양방향 비교 | source-to-chunk coverage matrix |
| 단일 모델을 TC 하나로 처리 | 재조회 데이터 혼입을 놓침 | 창을 유지한 조건 변경 재조회 | open·query·reload-mix 독립 baseline |
| WPF 정상 경로만 검증 | 이전 async 응답이 최신 화면을 덮음 | 빠른 연속 조회, 0건, 오류, 취소, 재오픈 | latest-result-wins와 old-data non-mix 기대 결과 |
| export가 화면 대신 source 재조회 | 사용자 정렬과 파일 순서 불일치 | 같은 시점의 화면 행·순서와 파일 비교 | visible snapshot export와 source mutation TC |
| 누적 batch 의미 오해 | 차수별 기대 건수 오류 | 실제 업무 규칙과 batch별 파일 비교 | 명시적 기대식과 정정의 정책 승격 |
| 웹 process cache가 과거 TC 유지 | 오래된 목록으로 검증 수행 | file revision, loaded time, API count 비교 | explicit invalidate, watcher, stale와 LKG |
| Jira Closed인데 FAIL 유지 | 차수 결과와 결함 현황 불일치 | Fix Version key와 run key 합집합 대조 | 상태 정책, ETag PUT, 저장 후 reread |
| Excel 생성 성공만 확인 | 색상·수식·유효성 검사 파손 | 최종 앱으로 두 sheet 시각 검토 | 구조 검사 + Excel 2013 final-open Gate |
| 유사 제품에서 기능 범위 상속 | 비대상 모듈·장비 전제 혼입 | 제품 근거와 금지 용어 검색 | product/branch/root lock과 validator |
| 과거 package path/date 승계 | 잘못된 설치 파일과 차수 사용 | 재귀 탐색 결과와 파일명 날짜 비교 | release별 source declaration |
| 계정 체계를 먼저 과설계 | Excel보다 불편한 도구가 됨 | 사용자 수와 기존 업무 흐름 검토 | 파일 기반 정적 token, HR 연동 연기 |
| Claude finding을 즉시 사실화 | 기존 문제를 새 회귀로 오판 | 정확한 base/head semantic diff | local validation과 disposition 기록 |
| 중간 JSON·추론 stream 수집 | 컨텍스트 소진과 판단 흐림 | 출력량과 timeout 관찰 | 20~30분 wait, 최종 텍스트만 수집 |
프롬프트를 반복 수정하는 대신 입력, 상태, 저장, 실행, 출력의 책임 경계를 세분화했습니다.
이미지가 많은 DOCX는 텍스트만 읽어서 화면 순서와 초기 상태를 복원할 수 없었습니다. 여러 화면을 한 덩어리로 요약하면 검색에는 편해 보여도 실제 TC의 사전 조건과 성공 기준이 섞였습니다.
원본을 보존한 채 전체 문서를 렌더링하고 heading, page screenshot, embedded image inventory를 대조했습니다. 자동화의 첫 schema는 TC가 아니라 “무엇을 근거로 읽었는가”였습니다.
보고서가 열린다는 사실, 올바른 데이터가 조회된다는 사실, 조건을 바꿔도 이전 데이터가 남지 않는다는 사실은 서로 다른 품질 주장입니다. TC 수를 줄이는 것보다 한 TC가 한 가지 실패를 설명하게 하는 편이 실행과 결함 분류에 유리했습니다.
미조회 -> 조회 성공 -> 다른 조건 조회 조회 성공 -> 0건 조회 성공 -> 오류 -> 재시도 성공 요청 A 시작 -> 요청 B 시작 -> B 완료 -> A 늦은 완료 정렬/필터 -> export -> 화면과 파일 비교 창 유지 -> 닫기 -> 재오픈
Excel 셀에 정의, 결과, Jira와 코멘트를 모두 넣으면 익숙하지만 재사용과 변경 추적이 어렵습니다. 정의를 YAML로 옮기고 precondition, dataset, change, suite, run을 분리했습니다.
가장 위험한 문제는 파일 저장 성공 뒤 프로세스 메모리가 과거 catalog를 계속 제공하는 것이었습니다. 공통 runtime은 write 뒤 명시적으로 invalidate하고 watcher도 같은 coordinator를 호출합니다.
후보 catalog 검증이 실패하면 last-known-good를 유지하고 stale 여부와 revision을 노출합니다. “저장했다”가 아니라 “새 revision을 다시 읽었고 사용자 화면도 같은 값을 본다”가 완료입니다.
새 release와 새 run의 경계를 분리하고, run 생성 시점의 active TC를 snapshot합니다. Jira 상태는 TC 정의가 아니라 실행 증거입니다.
공통 후처리는 Fix Version 전체 issue를 대조하고 상태를 판정한 뒤, 각 write 직전 ETag를 확인하고 저장 후 재조회합니다. 이 단계가 빠지면 Closed 이슈가 계속 FAIL로 남거나 미실행 TC가 자동 PASS가 될 수 있습니다.
공통화 대상은 schema, validator, web runtime, Jira reconciliation과 Excel 규칙입니다. 제품별 release note, TC, dataset, run과 장비 전제는 공통화하지 않습니다.
제품 UI가 비슷하다는 사실은 기능 존재의 증거가 아닙니다. 비대상 모듈이 섞인 실제 오류 뒤에는 작업 시작 시 제품 범위를 잠그고 금지 용어를 검사하도록 바꿨습니다.
Claude Code는 빠르게 구조를 만드는 데 유용했지만, 긴 실행에서 무응답처럼 보이거나 중간 JSON이 컨텍스트를 소진했고 기존 기준선 문제를 현재 변경 탓으로 잘못 귀인하기도 했습니다.
이후 제품·브랜치 경계, acceptance criteria, sanitized diff, 권위 문서와 검증 결과만 전달합니다. 최종 finding은 로컬에서 재확인하고 accepted, rejected, deferred disposition을 기록합니다.
상세 근거는 중앙 공개 정책에 따라 기본으로 접었습니다. 내부 추적에 필요한 범위만 익명화해 제공합니다.
| 사용자 정정 요지 | 즉시 수정 | 제도화된 장치 |
|---|---|---|
| 하위 화면 단위로 청킹 | 청크를 화면별 재분할 | pre-chunk boundary 규칙 |
| 초기 설정·장비 등록·모델 선택 누락 | 누락 chapter 추가 | source coverage matrix |
| 단일 모델도 열기·조회·갱신 혼입 분리 | 기본 TC 3분할 | report baseline pattern |
| 다중 모델·월별·barcode·조건 변경 재조회 | variant와 WPF 예외 TC 추가 | state-transition checklist |
| 내보내기는 현재 화면과 동일 | 정렬·필터·batch snapshot 검증 | screen-to-file Gate |
| 과거 TC 수는 process cache 문제 | instance reload와 수동 확인 | explicit invalidation과 stale/LKG |
| Closed Jira FAIL의 PASS 변경 누락 | 결과 후처리 | 공통 reconciliation과 reread verify |
| 최종 XLSX는 Excel 2013으로 확인 | 검증 앱 변경 | Excel 2013 final-open Gate |
| 고객사 전용 제품의 비대상 모듈 제거 | 잘못된 TC 삭제가 아닌 retire/정정 | product scope lock과 용어 검사 |
짧은 SHA는 비공개 업무 저장소의 감사용 식별자입니다. 공개 GitHub에서 링크되지는 않으며 고객명과 Jira 키를 제거한 의미만 기록합니다.
| SHA | 날짜 | 공개 가능한 의미 |
|---|---|---|
7c44e15 | 2026-07-13 | 회사 TC 표기 규칙을 policy와 validator로 고정 |
eea3c0a | 2026-07-14 | 공통 TC 편집·추가·복제와 transactional write |
3f9e243 | 2026-07-23 | 같은 릴리즈의 실행 결과 승계와 미확인 FAIL 가시화 |
7c58b00 | 2026-07-25 | 불완전한 LLM 제안을 mutation 전에 복구·차단 |
c5568e8 | 2026-07-27 | 기능 경계 재분할 뒤 203 TC와 다국어 검색 별칭 보강 |
5780674, 195ba1c | 2026-08-13 | 제품 공통 Jira 상태 동기화와 재조회 검증 |
6d968b0, 23e4c58 | 2026-08-14 | Claude read-only review 정책과 권위 문서 진입점 |
d432cc5 | 2026-08-18 | 고객사 전용 제품에서 비대상 모듈 TC 제거 |
pnpm tc:quality pnpm test pnpm test:e2e pnpm assets:instances:audit pnpm runs:jira:sync -- --project <PROJECT> --release <RELEASE> --run <RUN>
stale=false를 함께 확인합니다.마지막 산출물은 설명문이 아니라 다음 에이전트가 제품 범위를 잠그고 Evidence Gate부터 검증까지 그대로 실행할 수 있는 운영 절차입니다.
제품, 저장소, branch, release, Fix Version, patch와 run을 잠근 뒤 ActiveDocs와 관련 권위 문서를 읽습니다.
주장을 confirmed/inference/recommendation/unresolved로 분류하고 상태 전이, 예외와 경계 TC를 구성합니다.
quality, tests, desktop E2E, cache revision reread, Jira reread와 최종 Excel 앱 검증을 증거로 남깁니다.