artifact-transformer 작업 일지 #15

프로젝트마다 반복하던 규약을 도구·스킬로 굳히다 — init.py 그린필드 부트스트랩, Epic 명명 규약, 3자리 semver, 그리고 위험도 평가 AI 역량 기획

이 글은 2026-06-16 하루 동안 artifact-transformer를 여러 시스템에 반복 적용하며 드러난 규약들을 도구·스킬로 일반화한 작업 기록이다. 그린필드 프로젝트를 한 명령으로 부트스트랩하는 init.py 오케스트레이터를 세우고, Epic 명명을 행위명사로 통일했으며, 산출물 버전을 3자리 semver로 전환하고, 위험도 평가 AI 역량을 신규로 기획했다.

배경

artifact-transformer는 Jira 이슈와 PlantUML 다이어그램을 입력으로 받아 요구사항·유스케이스·기능·시퀀스 명세서와 데이터 정의서/명세서 등을 docx/xlsx로 자동 생성·역파싱하는 도구다 (#4 참조).

#14에서 도구를 LORAS·SUGCS·SUOMS을 비롯한 여러 시스템에 동시에 들이대며 빈틈을 찾았다. 그리고 그 빈틈이 거의 다 “정본(원천)이 어디냐”의 문제로 수렴한다는 걸 확인했다.

오늘은 그 다음 단계였다 — 시스템마다 손으로 반복하던 일을 도구·스킬·규약으로 굳히는 날. 어제는 같은 작업을 프로젝트별로 따로 했지만, 그건 지속 가능하지 않다. 새 시스템이 들어올 때마다 처음부터 다시 부딪힐 수는 없다. 그래서 한 프로젝트에서 내린 결정을 전 프로젝트가 상속하도록 끌어올리는 데 하루를 썼다.

문제

손대기 전, 프로젝트마다 반복되던 마찰들.

새 프로젝트 시작이 매번 수작업이었다 — 원천(Jira·다이어그램·상위 산출물)에서 입력 JSON 골격을 만드는 순서가 머릿속에만 있어, 시스템마다 같은 절차를 손으로 되풀이했다.
Epic 이름 규약이 프로젝트마다 달랐다 — 어떤 프로젝트는 명사구, 어떤 프로젝트는 행위명사. 통일된 기준이 없었다.
버전 체계가 2자리에 머물러 있었다 — 산출물 버전이 major.minor뿐이라, 의미 없는 패치 수정과 기능 추가를 같은 자리에서 다뤘다.
다이어그램에 버전·관계 표기가 빠져 있었다 — 어느 산출물이 어느 버전인지 그림만 봐서는 알 수 없었다.

그리고 도구 정비와 별개로, 도메인 쪽 숙제가 하나 들어왔다 — 위험도 평가 AI 역량을 새로 기획하는 것.

결정 1 — 그린필드 부트스트랩을 한 명령으로

원천에서 입력 JSON 골격을 도출하는 절차를 머리에서 꺼내 루트 CLI init.py로 강제했다. 순서와 원천 분류를 정본 NODES가 들고 있고, LLM은 원천 준비 확인과 골격 이후 보완(/fill) 안내만 한다.

init.py를 원천 데이터 정의(부트스트랩) 오케스트레이터로 세웠다. --list로 원천 맵과 준비 현황을, --dry-run으로 건너뜀 사유·선행 명령을, --check로 검증과 함께 도출을 본다.
의존 순서를 못 박았다 — requirement는 Jira(또는 --csv)에서, business/usecase는 parse.py bcdg/ucdg(다이어그램이 원천)에서, participant는 아키텍처 .puml에서. 상위 입력이 없는 노드는 오류 대신 건너뛰고 안내한다.
이미 성숙한 산출물을 덮어쓰지 않게 막았다. SQDG가 이미 있으면 sequence 도출을 건너뛴다 — 다이어그램이 원천인 노드를 부트스트랩이 다시 덮으면 안 되기 때문이다.

절차가 도구 안에 들어왔으니, 그 절차를 사람이 찾을 수 있는 곳마다 적어 두었다 — README의 그린필드 부트스트랩 절차, init-source 스킬의 그린필드 단계(+ 성숙 프로젝트 재실행 주의), /init 커맨드의 한 줄 요약까지.

절차가 머릿속에만 있으면 프로젝트마다 미묘하게 달라진다. 순서를 CLI가 강제하고 원천 분류를 정본이 들면, 새 시스템은 “이 명령을 이 순서로”가 전부가 된다.

결정 2 — Epic 명명을 행위명사로, 전 프로젝트 공통으로

Epic 이름을 두고 규약을 정했다. 출발점은 단순한 관찰이었다 — Epic은 스토리들의 집합이고 기간이 존재한다. 그렇다면 명사구보다 “개발”·“구현” 같은 행위명사가 그 성격에 맞다.

이 관점을 토대로 LORAS의 Epic을 “개발” 형태로 일괄 정규화하고, 메모리를 갱신했다. 그다음 그 결정을 한 프로젝트에 가두지 않고 init_requirement의 Epic 명명 규약을 전 프로젝트 공통(성격별 행위명사)으로 일반화했다. SUGCS·SUOMS처럼 명사형 라이프사이클로 남아 있던 Epic들도 같은 기준으로 점검했다.

AI 활용 캐퍼빌리티(1271)를 1315로 통합해 중복을 정리했다.
AIS 에픽(1316)을 군집 에픽(1317)과 같은 수준으로 가시성 있게 정리하고, 1317이 RSK 캐퍼빌리티 하위에서 제대로 보이는지 점검했다.

Epic의 이름은 그 Epic이 무엇인지를 드러내야 한다. 스토리들의 집합이자 기간을 가진 작업이라면, 이름은 명사가 아니라 행위여야 한다.

결정 3 — 산출물 버전을 3자리 semver로, 다이어그램에 버전 표기 자동화

버전 체계를 major.minor에서 3자리 semver(major.minor.patch)로 전환했다. 패치 수준의 보정과 기능 추가를 같은 자리에서 섞지 않도록, 자리마다 의미를 갈랐다. 동시에 버전 증감을 손으로 계산하지 않도록 semver를 도구화했다.

표기 쪽도 자동화했다 — 다이어그램 생성기가 버전 footer와 업무 관계선을 자동으로 찍도록 보강했다. 시퀀스·아키텍처를 비롯한 모든 다이어그램에 버전이 박히니, 그림만 봐도 어느 산출물의 어느 버전인지 드러난다.

규약과 도구가 함께 움직이도록, 빌드 스크립트 docstring과 init_requirement에도 같은 개발 규약을 반영하고, IAMS·SDSP 등 타 프로젝트에도 동일 규약을 적용했다(env 설정의 실 작성자·드라이브 갱신과 신규 4종 포함).

결정 4 — 위험도 평가 AI 역량을 신규로 기획

도메인 숙제였던 위험도 평가 AI 역량을 산출물·Jira에 얹었다. 두 갈래였다.

위험도 평가 RAG 개발 + 자사 AI 플랫폼 연동 — 기존 평가 흐름에 RAG 기반 검색·생성을 더하고, 사내 AI 플랫폼과 연동해 AI 서비스를 강화한다.
군집 비행 위험 평가 모델 연구 → 군집 위험도 평가 서비스 — 단건이 아니라 군집(swarm) 단위의 위험을 평가하는 모델을 연구하고, 그 결과를 서비스로 추가한다.

이 두 갈래를 관련 업무·요구사항과 연계된 작업까지 함께 끌어와 정리하고, Jira에 capability/epic/story로 생성했다. 어제 세운 “Jira Capability가 분류의 원천”이라는 원칙(#14 결정 1) 위에서, 신규 역량도 같은 계층으로 자리를 잡았다.

의도치 않은 함정

레거시가 발목을 잡았다 — models/ 아래 옛 산출물과, 초기화기가 만든 유령 데이터(논리·물리 데이터 각 3건)가 정합 검증을 흐렸다. 정리분을 산출물 단위로 커밋한 뒤, 결국 레거시는 모두 삭제하는 쪽으로 정했다. 정본이 분명해진 마당에 옛 사본을 남겨 두면 “둘 중 어느 게 맞냐”가 다시 살아난다.
issueKey가 중복됐다 — 요구사항·Jira를 오가며 같은 issueKey가 둘 붙은 경우가 생겨, 중복을 교정했다.
라이프사이클이 명사형으로 남아 있었다 — 결정 2의 행위명사 규약을 세우고 보니 SUGCS·SUOMS의 Epic 일부가 여전히 명사형이었다. 규약을 만든 그 자리에서 함께 점검해 끌어다 맞췄다.

마무리

오늘 관통한 결은 하나였다 — 반복을 규약으로, 규약을 도구로 끌어올린 것.

시작을 도구로 — 그린필드 부트스트랩을 init.py가 순서·원천 분류까지 강제하게 했다. 새 시스템은 “이 명령을 이 순서로”가 전부다.
이름을 규약으로 — Epic 명명을 행위명사로 통일하고 전 프로젝트 공통으로 일반화했다.
버전을 자리마다 의미 있게 — 3자리 semver로 전환하고, 다이어그램이 버전을 스스로 표기하게 했다.

어제가 “도구를 여러 시스템에 들이대며 빈틈을 찾은” 날이라면, 오늘은 그 빈틈을 메우는 방식을 한 시스템이 아니라 모든 시스템이 상속하도록 굳힌 날이다. 한 번 손으로 한 일을 도구·스킬·규약으로 올려 두면, 다음 시스템은 같은 자리에서 다시 부딪히지 않는다.

다음에 할 것:

위험도 평가 AI 역량 상세화 — 오늘 기획으로 얹은 RAG·군집 위험 역량을 요구사항·유스케이스·시퀀스까지 내려 구체화한다.
신규 4종 프로젝트 부트스트랩 실행 — env만 세운 프로젝트들을 init.py 그린필드 절차에 실제로 태운다.
문서 재생성(docx/xlsx) — 버전·규약 변경분이 쌓였으니 일괄 재생성으로 산출물을 맞춘다.