artifact-transformer 작업 일지 #26

뷰어를 편집기로 바꾸되, 모든 변경이 영향성 검토를 통과해야 반영되게 했다

이 글은 2026-07-14 하루의 기록이다. 어제(#25)까지 인증과 이슈 연동이라는 배관을 깔았다면, 이날은 그 배관에 처음으로 물을 흘려본 날이었다. 한쪽에선 실제 리뷰어 피드백을 만들어 둔 Jira 파이프라인으로 흘렸고, 다른 한쪽에선 지금까지 “보기만 하던” 웹 뷰어를 편집기로 바꿨다. 두 작업의 결론은 하나로 모였다 — 변경은 함부로 반영되지 않는다. 검토를 통과해야 반영된다.

배경 — 만든 파이프라인에 처음 실제 리뷰가 흘렀다

artifact-transformer는 31종 소프트웨어 산출물을 생성·검증하는 CLI에서, 인증과 이슈 추적을 갖춘 다중 사용자 협업 웹 서비스로 넘어가는 중이다. 어제까지 만든 것은 도구였다 — 산출물 피드백을 Jira 이슈로 다루는 CLI, Keycloak 기반 인증, SDLC 단계 게이트.

이날은 그 도구를 실제로 썼다. SUOMS 프로젝트(군집 무인기 운영 관리 시스템)의 리뷰 이슈 SUOMS-666~672와 PAIX-31이 실제 리뷰어(김희민) 피드백을 담고 들어왔고, 각각을 “처리” — 피드백을 산출물에 반영하고, 다이어그램·문서를 재생성해 올리고, 이슈에 변경 이력을 남기는 — 것이 오전의 과제였다.

동시에 다른 채널에선 웹 서비스가 한 단계 넘어갔다. 지금까지의 웹 UI는 산출물을 스키마 폼으로 편집하는 데까지는 왔지만, “편집하면 무엇이 깨지는가”를 사용자에게 보여주지 못했다. 이날 그 게이트를 붙였다.

문제

리뷰어 피드백을 산출물에 반영할 때, 문서·다이어그램·관리 시트가 서로 어긋나지 않게 어떻게 함께 고치나.
웹에서 산출물을 편집할 때, 변경이 무엇에 영향을 주는지 보여주고 반영 여부를 사용자가 결정하게 하려면.
그 영향성 검토를, 기계가 할 몫과 AI가 할 몫으로 어떻게 가르나.
로그인을 조직 계정(Google)으로 넘기려면 어디에 무엇을 붙이나.
시스템 설정·모니터링·토큰 사용량을 한곳에서 보려면.
편집 화면이 애초에 틀린 값을 못 넣게 하려면.

결정 1 — 만든 김에, 산출물 피드백을 실제로 흘려본다

어제 만든 feedback 사이클을 이날 처음 실전에 걸었다. SUOMS-666부터 672까지, 그리고 PAIX-31. 각 이슈는 리뷰어가 특정 산출물에 남긴 지적이고, 처리란 곧 지적을 산출물 원본(JSON)에 반영 → 다이어그램·문서 재생성 → Drive 업로드 → 이슈에 변경 내용·이력 댓글의 한 바퀴다.

실전에서 드러난 것은 “함께 고쳐야 하는 것”의 범위였다. 한 예로, 인수 시나리오의 “비행 계획 인수(SUOMS-ASC-PLN-001)” 인수 주체가 자산관리자로 되어 있었는데 리뷰어 정정은 비행총괄자였다. 이건 한 줄 수정이 아니다 — 같은 인수 주체가 시퀀스 다이어그램 라벨에도, 운영/인수 시나리오 정의서 서술에도, 이해관계자 매핑에도 박혀 있다. 그래서 표시명을 개별 문서에 하드코딩하는 대신 business.json에서 도출하도록 바꿨다(커밋 afe85a5 — 분류·상위모드·이해관계자 표시명을 데이터 원본에서 도출). 한 곳을 고치면 파생물이 따라오게.

관리 시트도 같은 결로 정리했다 — AN13-2 행 정리, AN24-1 기능↔요구사항 중복 제거, 운영 시나리오 서술 세부 정리, SUOMS C4 토폴로지 추가, BPDG 신설. 반영이 끝난 이슈에는 변경 내용·변경 이력·후속 처리 내역을 댓글로 남겨, 저장소와 Jira가 키로만 이어지되 이력은 이슈에 남게 했다.

배관은 만들 때가 아니라 처음 물을 흘릴 때 샌 곳이 보인다. 이날 흘려 보니, 진짜 일은 “무엇을 고치나”가 아니라 “그것과 함께 무엇이 어긋나나”였다.

결정 2 — 뷰어를 편집기로: 변경은 검토를 통과해야 반영된다

웹 서비스에 붙인 이날의 핵심 기능은 영향성 검토 게이트다. 요청은 명확했다 — “산출물 내용을 변경할 때, 변경 검토를 우선 수행해서 검토 후 반영 여부를 결정하는 흐름을 원한다.”

그래서 편집의 흐름을 바꿨다. 편집 → 곧바로 저장이 아니라, 편집 → 영향성 검토 → (검토 결과 확인) → 반영이다. 다이어그램 편집도 같은 게이트를 지난다 — 편집 후 영향성 검토를 거쳐야 저장된다.

여기에 AI 검토를 얹되, AI가 멋대로 고치게 두지 않았다. 흐름은 이렇게 짰다:

변경에 대해 AI가 영향받는 부분을 검토하고 제안 내용들을 선택지로 제시한다.
사용자가 제안을 수락하면, 그때 AI가 그 변경을 적용한다.
적용 뒤에도 검토 → 반영이 이어져, 한 번의 변경이 파생 변경을 끌고 가며 수렴한다.

즉 AI는 “무엇이 영향받는지 보여주고 고칠 안을 제시하는” 역할이고, 반영의 결정권은 사용자에게 있다. 이 제품의 오래된 원칙 — 자동화가 사람의 판단을 대체하지 않는다 — 을 편집 UX에 그대로 옮긴 셈이다.

결정 3 — 영향성 검토도 결정적 코어 + 최소 AI

영향성 검토를 붙이면서 다시 확인한 원칙은, 이 프로젝트 내내 반복된 그것이다 — 결정적으로 할 수 있는 것은 코드로, AI는 기계가 못 보는 것만.

영향성 검토의 뼈대는 결정적 분석이 진다. 무엇이 바뀌었는지(리프 diff), 그 항목을 누가 참조하는지(참조 영향), 바뀐 뒤에도 정합성 검사가 통과하는지(검증 시뮬레이션) — 이건 데이터와 규약으로 답이 딱 떨어지므로 코드가 계산한다.

AI에는 그 위에서 기계가 못 보는 것만 맡겼다. 실제로 이날 쓴 검토 프롬프트는 이렇게 못 박혀 있다:

결정적 분석 리포트(리프 diff·참조 영향·검증 시뮬레이션)가 이미 주어진다 — 그것을 반복하지 말고, 기계 분석이 못 보는 것만 보완한다.

AI가 볼 것은 세 가지로 좁혔다 — ① 의미적 파급: 바뀐 서술의 의미가 그것을 참조하는 산출물(요구사항↔기능↔유스케이스↔시험)의 서술과 어긋나는지. ② 누락 위험: 함께 고쳤어야 하는데 리포트에 안 잡힌 관례적 동반 수정(시험 항목의 기대결과·판정기준, 시나리오 단계 서술, 용어집, 다이어그램 라벨). ③ 반영 전 체크리스트: 검토자가 확인할 질문 3~5개. 과장을 금하고, 근거 없는 내용은 “추정”으로 표기하며, 문제가 없어 보이면 “특이 소견 없음”으로 끝내게 했다.

층	맡는 것	누가
결정적 코어	리프 diff, 참조 영향, 검증 시뮬레이션	코드
의미 계층	의미적 파급, 누락 위험, 반영 전 체크리스트	AI

결정 1의 “비행총괄자” 정정이 바로 이 검토가 잡아야 할 종류의 변경이다 — 값 하나가 바뀌면 라벨·서술·매핑이 함께 어긋난다. 결정적 분석은 참조를 세고, AI는 “이 서술이 저 시험 항목의 기대결과와 어긋나지 않나”를 본다.

결정 4 — 로그인은 조직 계정으로: Google을 Keycloak IdP로

어제 웹에 SSO의 자리를 마련해 뒀고, 이날 실제 로그인을 조직 계정으로 넘겼다. 방식은 서비스가 직접 소셜 로그인을 구현하는 게 아니라, Keycloak에 Google을 Identity Provider로 등록하는 것이다(Identity providers → Add Google provider). 서비스는 여전히 Keycloak이 발급한 토큰만 검증하고, 구글 인증의 실제는 Keycloak↔Google 사이에서 끝난다.

정리하다 헷갈렸던 지점 하나는 짚고 넘어갈 가치가 있다. client_secret.json을 시스템 설정에 한 계정으로 올려 두는 것(서버가 Drive에 접근하기 위한 서비스 계정)과, 로그인 시 SSO 연동은 다른 층의 문제였다. 앞은 서버가 파일 저장소에 접근하는 자격이고, 뒤는 사용자가 누구인지 증명하는 자격이다. 둘을 섞지 않기로 정리했다.

결정 5 — 관리자 콘솔, 그리고 전체 UX를 워크플로우 기준으로 재배치

운영에 필요한 것들을 한곳에 모은 관리자 페이지를 붙였다 — 시스템 설정, 모니터링, 그리고 AI 토큰 사용량. 토큰 사용량은 한 번 보고 마는 값이 아니라 비용·한도 관리의 근거이므로, 세션 메모리에 담지 않고 감사 로그처럼 영속화하기로 했다. 껐다 켜도 남는다.

핵심 기능 중 하나인 정합성 검사도 손봤다. 지금까지 너무 단촐하게 보였다 — 검사라기보다 통과/실패 표시에 가까웠다. 무엇이 왜 걸렸는지 보이도록 개선을 걸었다.

마지막으로 화면 전체를 워크플로우 기준으로 재배치했다. 원칙을 잡았다 — 프로젝트별 공통 정보는 상단에 고정, 그 외 기능은 흐름 순서로. 결과:

상단: 프로젝트 선택, 그 옆에 프로젝트 정보, 협업 현황은 상단 고정(프로젝트를 넘나들어도 늘 보이는 값).
우측: 관리·로그인 정보(자주 안 건드리는 것은 가장자리로).
생성 버튼을 “발행”으로 이름을 바꾸고 기능·워크플로우도 그에 맞게 다듬었다. “생성”은 무엇을 만드는지 모호했지만 “발행”은 이 화면이 무엇을 하는 곳인지 말해 준다.
“변경 검토” 탭을 따로 둘지 검토한 끝에, 별도 탭이 아니라 편집 흐름에 녹인 통합안으로 갔다. 검토는 별도 화면이 아니라 저장 직전의 관문이어야 한다는 결정 2의 연장이다.
구 UI 버튼과 레거시 코드는 걷어냈다.

결정 6 — 편집 화면이 애초에 틀린 값을 못 넣게

영향성 검토가 “반영 후” 방어라면, 입력 UX는 “입력 시점” 방어다. 애초에 규약을 어기는 값을 못 넣게 만드는 쪽이 나중에 검토로 걸러 내는 것보다 싸다. 그래서 편집 폼을 이렇게 손봤다:

식별자 잠금 시 해당 입력은 disabled 처리 — 잠긴 식별자는 눈에 잠겨 보인다.
시퀀스는 내부 order로 정렬하고, 화면의 1·2·3 번호는 그 order로 대체 표시. 순서 변경은 숫자를 고치는 게 아니라 드래그로 이동.
이해관계자(actor)처럼 다른 산출물에 매핑되는 값, 그리고 RACI 입력란은 자유 입력이 아니라 셀렉트 박스로. 오타로 존재하지 않는 actor를 만들어 낼 여지를 없앴다.

의도치 않은 함정 — 이미 어긋나 있던 것들

이날의 삽질은 새로 만든 것에서가 아니라, 이미 어긋나 있던 상태를 발견하는 데서 나왔다.

첫째, interface-data.json이 변경된 뒤 커밋이 안 되어 있었다. 데이터는 바뀌었는데 그 변경이 저장소에 박히지 않은 상태 — 리뷰어 정정을 반영하는 도중 인터페이스 정합을 확인하다 드러났다. 검토하고, 정정 내용을 SUOMS-670 댓글에도 함께 남겼다(설계 정합·인터페이스 정합 정정 각각).

둘째, 웹에서 새로 고침을 하면 왼쪽 메뉴에 설계(아키텍처·데이터 흐름도·상태 흐름도)만 표출되는 버그가 있었다. 초기 로드 시점에 다른 그룹이 빠지는 문제로, 편집기로 전환하는 김에 잡았다.

셋째, 구글 드라이브에 올린 파일(다이어그램 이미지 등)에 접근하면 {"detail":"Authorization 헤더가 없습니다."}가 났다. 인증을 붙이는 중이라 오히려 드러난 함정이다 — 정적 자산을 가져오는 요청에 토큰이 실리지 않았다.

인증과 검토를 붙이는 작업의 절반은, 그동안 아무도 안 보던 곳에서 조용히 어긋나 있던 상태를 드러내는 일이었다.

마무리

이날은 “만든 것을 처음 써 보고”, 동시에 “보기만 하던 것을 고칠 수 있게” 만든 날이었다. 두 작업이 같은 결론에 닿았다.

검토를 통과해야 반영된다 — 산출물 피드백은 재생성·정합성 검토를 거쳐 올라가고, 웹 편집은 영향성 검토 게이트를 지나 저장된다. 별도 탭이 아니라 저장 직전의 관문으로.
영향성 검토도 결정적 코어 + 최소 AI — 리프 diff·참조 영향·검증 시뮬레이션은 코드가, 의미적 파급·누락 위험·체크리스트는 AI가. 파이프라인의 원칙을 편집에 그대로.
표시명은 데이터 원본에서 도출 — “자산관리자→비행총괄자” 한 정정이 라벨·서술·매핑을 함께 끌고 가도록 business.json에서 도출로 바꿨다.
로그인은 조직 계정으로 — Google을 Keycloak IdP로. 서버가 소셜 로그인을 만들지 않고, Drive 서비스 계정과 사용자 인증을 층으로 갈랐다.
애초에 틀린 값을 못 넣게 — 잠금 disabled, order·드래그, actor/RACI 셀렉트. 입력 방어가 반영 후 방어보다 싸다.

다음에 남는 것:

SUOMS 리뷰 이슈 잔여분과, 반영 정합성(설계↔인터페이스↔시험) 최종 교차 검토.
영향성 검토 게이트의 AI 검토를 실사용 데이터로 튜닝 — 오탐(멀쩡한 변경을 붙잡는 것)이 자동화의 적이다.
관리자 콘솔의 토큰 사용량·감사 로그를 실제 운영 대시보드로.
Google SSO를 실계정으로 끝까지 확인(어제 남긴 웹 SSO 검증 항목의 연장).