이 글은 2026-06-23 하루 동안
artifact-transformer와 그 산하 문서 저장소들에서 도구를 실제로 풀어내고, 맞다고 믿어 온 창들을 실제와 맞춘 작업 기록이다. 오전엔 생성된 명세서 표지의 버전·일자를, 오후·저녁엔 ERD가 데이터 정의와 어긋난 자리를 — 두 종류의 “어긋남”을 같은 손으로 메웠다.
배경
artifact-transformer는 Jira 이슈와 PlantUML 다이어그램을 입력으로 받아 요구사항·유스케이스·기능·시퀀스 명세서와 데이터 정의서/명세서 등을 docx/xlsx로 자동 생성·역파싱하는 도구다 (#4 참조).
#17까지 도구는 .puml이라는 원천에서 갈라지는 세 길 — 렌더·시트 등록·작성 규약 — 을 같은 규약으로 묶었다. 그날 마무리에 남긴 빚이 둘 있었다. 문서 일괄 재생성, 그리고 6개 저장소 첫 실전 검수.
오늘은 그 빚을 갚으러 도구를 바깥으로 풀었다. 더 이상 도구 안쪽을 다듬는 날이 아니라, 만들어 둔 도구를 여러 도메인 저장소에 실제로 돌려 보는 날이었다. 그리고 늘 그렇듯, 풀어 보고서야 보이는 어긋남이 있었다.
문제
손대기 전, 두 결의 어긋남이 보였다.
- 생성된 표지가 최신 개정 이력을 따라가지 않았다 — 명세서 표지의 문서버전이
1.0으로 찍히는데 실제 규약은 3자리 semver(1.0.0)였고(#15에서 정한 규약), 일부 업무 명세서(an11-2)는 표지의 버전·일자가 최신으로 갱신되지 않았다. check가 보지 못하는 정합성이 있었다 — 다이어그램 ERD와 데이터 정의 JSON(logical-data.json·physical-data.json) 사이의 어긋남은 결정적 점검의 사각이었다.- 도구는 자랐는데 산출물은 안 내려와 있었다 —
iam·sdsp·fdsp·padx·sulas·sugcs6개 도메인 저장소에 생성·점검을 아직 돌리지 않았다(#17의 빚). - 풀어 보니 ERD 자체에 빚이 있었다 — 중복 엔티티, 논리와 어긋난 물리, 끊긴 관계, 의미가 어긋난 데이터 분류.
결정 1 — 표지 버전·일자를 최신 개정 이력으로 치환
가장 먼저, 산출물이 자기 표지에 대해 거짓말하지 않게 했다.
- 명세서 생성 시 표지의 문서버전은 개정 이력의 마지막 버전, 문서일자는 마지막 일자로 매핑하도록 전체를 검토하고 고쳤다. 표지는 그 문서가 “지금 몇 버전인지”를 가장 먼저 보는 자리인데, 거기가 옛 이력을 가리키면 첫 줄부터 틀린 걸 읽힌다.
1.0으로 찍히던 버그는 3자리 semver1.0.0규약(#15)에 맞춰 바로잡았다. 자릿수 규약을 한 곳에서 정했으면, 그걸 읽어 쓰는 표지도 같은 모양이어야 한다.- 업무 명세서(an11-2)에서 표지가 최신으로 갱신되지 않던 경로도 같이 메웠다.
산출물 관리 대장의 버전을 실제와 맞춘 게 #17이었다면, 오늘은 그 한 칸 더 안쪽 — 산출물 자신의 표지 — 을 실제와 맞췄다. 대장이 맞아도 문서 표지가 틀리면, 문서를 연 사람은 여전히 틀린 걸 본다.
fix(generate): 표지 문서버전/일자를 최신 개정 이력으로 치환으로 떼어 커밋했다.
결정 2 — check를 ERD↔데이터 JSON 정합까지 확장
정합성 점검은 도구가 사람 대신 봐 주는 눈이다. 그 눈에 사각이 있으면, 사각에 든 어긋남은 끝까지 사람 손에 남는다.
- 정합성 점검 명령어들을 다시 훑었다. 예를 들어 ERD와
logical-data.json·physical-data.json사이 — 같은 엔티티·속성을 가리키는데 한쪽엔 있고 한쪽엔 없거나, 값이 어긋난 경우. - ERD 파서를 추가하고,
check에 다이어그램 ↔ JSON 값 정합성을 포함시켰다. 이로써 다이어그램이 데이터 정의의 또 다른 표현인 한, 둘이 갈라지면check가 잡는다. - 이 점검은 어디까지나 결정적 CLI(
check) 가 한다. LLM이 “맞아 보인다”고 판단하는 게 아니라, 파서가 양쪽을 읽어 기계적으로 대조하는 자리다 — 결정적 검증을 도구에 맡긴다는 #13 결의의 연장이다.
ERD가 구조의 원천 중 하나로 격상되자, 다음 결정(저장소 전개)에서 ERD를 손볼 때마다 check가 곧장 영향 범위를 일러 줬다.
결정 3 — 산출물을 6개 도메인 저장소에 일괄 전개
도구를 다듬는 일과 도구로 일하는 일은 다르다. 오늘은 후자를 했다.
sdsp는/check-traceability로 추적성을 먼저 점검했고, 나머지 다섯(sugcs·iam·fdsp·padx·sulas)은/fill로 산출물을 채웠다.- 저장소마다 공통의 후속 작업을 한 바퀴 돌았다 — ERD와 논리/물리 데이터의 정합성 검토. 결정 2에서 새로 생긴 눈을 곧바로 여섯 곳에 들이댄 셈이다.
- 여러 저장소에 같은 도구·같은 점검을 동형으로 적용하면서, 도구가 저장소별로 다르게 동작하지 않는다는 걸 확인했다. 한 곳에서 통한 점검이 다른 곳에선 안 통하면, 그건 도구가 아니라 우연이다.
도구는 한 저장소에서 잘 도는 것만으로는 도구가 아니다. 여섯 곳에서 같은 모양으로 돌아야 비로소 “도구”라 부를 수 있다.
결정 4 — 도메인 ERD 정제: 중복 제거·논리 기준 정렬·관계 보강
전개하며 드러난 ERD의 빚을, 저장소별로 갚았다.
- 중복 제거 —
sdsp에서COM이OVERVIEW와 겹쳐 있었다.OVERVIEW로 일원화하고 중복 엔티티 정의를 제거한 뒤, 영향받는 산출물을 검토했다. 엔티티를 들어내면 그걸 가리키던 참조도 함께 정리해야 한다. - 논리 기준 정렬 — 물리와 ERD가 논리와 어긋난 곳은, 방향을 논리에 맞췄다(
물리/ERD → 논리). 셋 중 무엇을 기준 삼을지 흔들리면 정합성은 영원히 안 닫힌다. - 관계 보강 —
iam에선 사용자–조직 N:M 정션부터 메우고 나머지 관계를 차례로 보강했으며,fdsp에선 엔티티 재생성과 함께 관계선을 추가했다.sugcs는 ERD를 재생성하고 revise 커밋까지 돌렸다. - 도메인 의미 정정 —
DAT계열 데이터에 비행 영상을 포함시키고,COM계열의 API 인증 토큰·사용량 기록은 Keycloak이 검증을 전담하므로 불필요하다고 판단해 정리했다.IAMS의 Realm/Group 개념도 — 조직에 사용자가 추가·제거되는 정황으로 보아 Group을 의미한다고 — 바로잡았다. 더불어 RACI 설명 매트릭스를 산출물에 두자는 안을 세웠다.
의도치 않은 함정
- “빈 control은 의도적이다” — 정합성 점검이 비어 있는 control 항목을 어긋남으로 보고 채우거나 지우려 들었다. 하지만 그 공백은 버그가 아니라 사람이 의도적으로 비워 둔 결정이었다. 자동 점검은 “비어 있음”과 “비워 둠”을 구분하지 못한다. 그래서 앞으로 체크 시 빈 control을 어긋남으로 보고 삭제하지 않는다는 규약을 못박았다. 결정적 점검을 강화할수록, 의도적 공백을 점검의 예외로 명시해 두지 않으면 도구가 사람의 결정을 되돌려 버린다.
도구에 눈을 달수록, 그 눈이 보지 말아야 할 것도 함께 정해 줘야 한다. 모든 공백을 결함으로 읽는 점검은, 의도까지 결함으로 지운다.
마무리
오늘 관통한 결은 “맞다고 믿어 온 창을 실제와 맞추고, 도구를 실제 저장소에 풀어 본 것” 이었다.
- 표지를 실제와 맞추고 — 문서버전·일자를 최신 개정 이력 기준(3자리 semver)으로 치환했다.
- 점검의 사각을 메우고 — ERD 파서를 더해
check가 다이어그램↔데이터 JSON 정합까지 보게 했다. - 6개 저장소에 전개하고 —
/fill·/check-traceability로 산출물을 채우고 추적성을 점검했다. - ERD를 정제하고 — 중복 제거, 논리 기준 정렬, 관계 보강, 도메인 의미 정정까지.
#17이 .puml 원천에서 갈라지는 길을 깔아 둔 날이라면, 오늘은 그 도구를 실제로 여섯 저장소에 풀고, 산출물이 자기 자신(표지)과 자기 구조(ERD↔데이터)에 대해 거짓말하지 않게 맞춘 날이다.
다음에 할 것: