artifact-transformer 작업 일지 #30

이 글은 2026-07-22 하루의 기록이다. #29가 화면을 지우고 도크 하나로 모은 날이었다면, 이날은 그 남은 표면 전체를 IntelliJ의 시각 언어로 끝까지 따라간 날이었다. 헤더·좌측·우측·하단 네 벽을 순서대로 손댔고, 그중 하나(정합성 검사)는 방향이 다섯 번 뒤집혔다.

배경 — 사소한 요청이 전수조사로 번지다

아침은 작은 요청으로 시작했다. “프로젝트 정보 보여주는 화면은 모달창으로 가자, 관리 화면도 마찬가지.” 모달 전환 자체는 금방 끝났지만, 뒤이은 세부 다듬기(닫기·새로고침 위치, 프로젝트명 중복, 정보 순서)를 처리하던 중 사용자가 질문을 하나 던졌다.

“전체 레이아웃 검토해줘. 중복되는 컨텐츠가 있고 IDE에 흐름에 맞는 레이아웃 구성으로 상세 검토.”

이 한 문장이 하루의 방향을 바꿨다. 모달 다듬기는 국지적 수정이었지만, 전수조사는 구조 전체를 다시 묻는 일이었다. 이후의 모든 결정은 사실 이 질문에 대한 답이었다.

문제

1. 헤더 밴드와 하단 상태 바가 왜 같은 지표를 위아래로 두 번 보여주나.
2. 활성 작업(칩) 하나를 화면 몇 군데에서 다뤄야 적당한가.
3. 좌우 패널을 IntelliJ처럼 접고 펴려면 어떤 골격이 필요한가.
4. 관리 화면은 왜 그냥 설정 목록이 아니라 IntelliJ Settings처럼 보여야 하나.
5. 정합성 검사와 식별자 발급, 이 둘을 하단 도크에서 어떻게 공존시키나.

결정 1 — 스크롤이 상단 바를 삼켰다

모달에 sticky 상단 바(제목+새로고침+닫기)를 붙이는 작업은 간단해 보였다. 그런데 스크롤을 700px쯤 내리자 콘텐츠가 바 위 18px 틈으로 새어 나왔다.

원인은 파일 뒤쪽에 있던 .modal { padding: 18px 20px } 단축 선언이 앞서 정의한 padding-top: 0을 되돌리고 있었던 것 — 전형적인 CSS 특정도(specificity) 문제였다. .modal.projmodalwrap으로 두 클래스를 묶어 특정도를 올려 해결했고, 같은 sticky 패턴을 관리 모달에도 공용 클래스(.modalbar/.modalwrap)로 일반화했다.

규칙은 순서를 모른다. CSS는 나중에 선언된 낮은 특정도가 먼저 선언된 높은 특정도를 이긴다고 착각하기 쉽지만, 실제로는 그 반대다 — 특정도가 같으면 순서가, 특정도가 다르면 특정도가 이긴다.

결정 2 — 지표가 네 곳에서 같은 말을 하고 있었다

전수조사는 목업 없이 텍스트 지도로 시작했다. 결과는 예상보다 심했다.

리뷰 대기 하나가 4중으로 중복 표출되고 있었다. 결론은 명확했다.

IDE 관례상 요약은 하단 상태 바 한 곳이 정본이고, 상단은 도구모음(검색·AI·실행)만 담는다.

헤더 밴드에서 지표 배지를 전부 걷어 검색·AI·오류 상태만 남기고, 하단 StatusBar를 유일한 요약으로 승격했다(발급 대기 세그 신규 추가). 활성 작업 ⛏ 세그도 헤더 위젯·우측 실행판과 겹쳐 제거했다. 이 결정 하나가 이후 하루 종일의 작업 방향(중복 제거 → IDE 언어 통일)을 정했다.

결정 3 — 작업 칩, 사라졌다가 다시 태어나다

헤더의 “활성 작업 칩”은 이날 가장 많이 왕복한 요소다. 네 번의 요청이 이어졌다.

1. Jira 바로가기가 팝오버·도크와 중복이라 헤더에서 제거. 팝오버가 리뷰인데도 “작업 중”으로 잘못 표기하던 버그를 “검토 중”으로 고쳤다.
2. Jira 이동 버튼을 이슈 키 옆으로, 대상 문서 열기 버튼을 대상 문서 옆으로 재배치. 우측 작업 도크에 접기 기능(26px 세로 스트립)을 추가했다.
3. “완료·해제 버튼은 헤더 우측으로.” 처음엔 칩 알약 안에 넣었다가, 다시 읽고 “헤더 우측”이 알약 밖을 뜻한다고 스스로 재해석해 옮겼다.
4. 마지막엔 헤더 칩 자체를 통째로 삭제했다(ActiveTaskBar 파일 제거). 대신 작업 도크 내부의 이슈 헤더를 에픽(위·작은 폰트)→키+이름(하나의 Jira 링크)→포인트 순서로 재구성했다.

칩을 검증하려고 서버 상태에 활성 작업을 직접 세팅했는데 브라우저에 반영되지 않는 일이 있었다. 원인은 두 겹이었다 — localStorage에 남은 이전 리뷰 상태가 서버 상태를 가리고 있었고, PUT 요청의 작성자 식별자가 브라우저 세션과 달라 애초에 다른 사용자의 상태를 세팅하고 있었다. 두 레이어를 맞춘 뒤에야 재현이 됐다.

헤더에서 지웠던 칩은 §10에서 조작 버튼 없는 순수 요약 인디케이터로 다시 돌아온다. 지운 것과 다시 놓은 것의 차이는 “무엇을 담느냐”였다 — 처음엔 동작(완료·해제·Jira 이동)까지 다 얹었고, 나중엔 상태만 보여주고 클릭하면 도크로 보냈다.

결정 4 — 좌우 패널을 세 벽으로 두르다

“IntelliJ처럼 양쪽에 아이콘 패널을 두고, 클릭하면 패널이 열리는 형태로.” 좌(📁 산출물)·우(🗂 작업) 30px 상시 아이콘 스트라이프를 신설하고 Alt+1/Alt+2 단축키를 걸었다. 흩어져 있던 개별 접기 버튼들을 스트라이프 하나로 흡수했다.

여기서 지시 대상을 잘못 짚은 일이 있었다. “산출물 탭의 세로스크롤바를 없애고 펼치기 메뉴 형태로”라는 요청을 좌측 산출물 트리(PhaseNav) 이야기로 읽고 그쪽을 고쳤는데, 돌아온 답은 짧았다.

“edtabstrip의 탭을 말한거였어.”

사용자가 가리킨 건 상단 편집기 탭 스트립(EditorTabs)이었다. “산출물”이 트리의 이름이자 탭 콘텐츠의 이름이기도 해서 생긴 중의성이었다. 좌측 트리 변경을 git revert로 되돌리고, 편집기 탭 쪽에 스크롤바 숨김과 오버플로 드롭다운(▾, 열린 탭 전체 나열, 활성 탭 자동 스크롤)을 새로 만들었다.

짧은 지시일수록 명사 하나가 두 곳을 가리킬 수 있다는 걸 먼저 의심해야 했다. 되돌리는 데는 커밋 하나면 됐지만, 그 사이 엉뚱한 화면을 만졌다는 사실은 남는다.

이후 편집기 탭을 .center 컬럼에 격리해 좌우 툴윈도우를 덮지 않게 하고, 좌우 패널에 고정 헤더(제목+숨기기)와 스크롤 가능한 본문 구조를 넣고, 하단에 ⚠ 문제 (N) 스트라이프를 더해 좌·우·하 3면 툴윈도우 프레임을 완성했다.

결정 5 — 관리 화면이 세팅스가 되다

“라이트/나이트 모드를 관리 화면으로 이동. Intellij의 settings처럼 구현.” 다섯 커밋에 걸쳐 좌측 카테고리(외관·AI설정·시스템진단·모니터링·프로젝트·작업큐) + 우측 콘텐츠 구조로 재편됐다.

컴팩트화 과정에서 특이한 버그를 하나 잡았다. 진단 카드가 CSS로 패딩을 줄여도 반영이 안 됐는데, 원인은 ConfCard 컴포넌트의 인라인 style 패딩이 외부 CSS를 이기고 있었기 때문이었다. 인라인 스타일은 특정도 계산에서 클래스보다 항상 위라, 결정 1의 CSS 특정도 문제와 다른 얼굴을 한 같은 종류의 함정이었다.

후반엔 좌측 메뉴 이모티콘을 텍스트 라벨로 바꾸고, 2단계 항목(모니터링 하위의 요청메트릭/AI토큰사용량 등)을 들여쓰기 + 세로 안내선으로 구분했다. 마지막엔 아바타 드롭다운(§7 참고)에 테마 토글이 옮겨가면서 설정의 “외관” 섹션 자체가 중복이 되어 제거됐다 — 하루 안에서 같은 기능이 두 번 자리를 옮긴 셈이다.

결정 6 — 정합성 검사, 다섯 번 뒤집힌 방향

이날 가장 길게 왕복한 작업이다. “화면을 없애고 하단 패널 하나로 일원화한다”는 방향이 다섯 번의 시행착오 끝에 굳어졌다.

1. 식별자 발급을 하단 도크에 신설(IdentifiersDock, 문제 도크와 상호배타).

2. 정합성도 하단에 얹었는데, 처음엔 요약 배지만 옮긴 축약판이었다. “기능 전체를 녹여달라”는 재지시에 CheckView에 embed prop을 추가해 전용 화면과 완전히 같은 컴포넌트를 그대로 임베드했다 — 오히려 코드가 95줄 줄었다.

3. 정합성·식별자를 상단 탭으로 병합했다가, 곧바로 정정이 들어왔다.

   “정합성과 식별자를 병합하라는게 아니라, 정합성 내 여러 기능들을 내부 패널을 분할하고 개선해달라는거였어.”

   병합을 되돌리고 정합성 내부에 서브탭(추적성/스키마/다이어그램/개정영향)을 만들고, 식별자는 독립 창으로 되돌렸다.

4. IntelliJ Inspection Results의 3분할(액션 레일·이슈 트리·상세)을 적용했는데, 이 역시 방향이 틀렸다는 피드백을 받았다.

   “상세로 이동하는건 잘못된 방향이야. 상세 화면을 없애고 하단 패널에서 정합성 검토하는 모든 행위를 하고 싶어.”

   단계 화면의 정합성 탭·[상세] 버튼을 아예 제거하고, 모든 진입점(단계 개요·저장 후 재확인·발행 배지·명령 팔레트·프로젝트 모달)을 at:open-check 이벤트 하나로 통일해 하단 도크만 열리게 했다.

5. 마지막으로 상단 탭을 추적성/개정영향성 2개로 정리하고, 좌측 레일에 IntelliJ의 전 기능(다시검사·이전/다음 문제·모두펼치기/접기·소스로 이동)을 구현했다.

레일 구현 직후 아이콘이 안 보이는 버그가 났다. 레일 자체는 34px로 정상 렌더됐는데, 그 안의 SVG가 가로 0px로 찌부러져 있었다.

inline-flex 버튼 안에 viewBox 기반 스케일러블 SVG를 넣으면 flex 주축(가로)에서 min-content가 0으로 계산되며 붕괴하는 전형적인 flexbox-SVG 버그였다.

flex: none; width: 15px; height: 15px를 SVG에 직접 못 박아 해결했다. 이날 마지막 커밋은 개정 영향성 화면을 추적성과 같은 3분할 구조로 재작성한 것 — FDSP 프로젝트의 실제 개정 데이터(132개 리프)로 검증까지 마쳤다.

의도치 않은 함정

git add -A의 부수 사고. 같은 리포지토리에서 병렬로 돌아가던 다른 프로세스가 만든 파일(env 리네임, scratch 텍스트)이 커밋에 섞여 들어갈 뻔한 일이 하루에 여러 번 있었다. git reset --soft 후 자기 변경분만 다시 스테이징해 넘겼다. 여러 세션이 같은 워킹트리를 공유할 때는 git add -A가 항상 위험하다는 걸 다시 확인한 하루였다.

마무리

이날 손댄 네 벽(헤더·좌측·우측·하단)은 방향이 하나였다 — IntelliJ가 이미 풀어놓은 문법을 그대로 따라가는 것. 툴윈도우 스트라이프, 프로젝트 트리, Settings 다이얼로그, Inspection Results 3분할. 새로 발명한 패턴은 거의 없었고, 대신 기존 화면들이 그 언어에 맞게 몇 번이고 다시 배치됐다.

각각의 교훈:

• 중복은 전수조사로만 보인다 — 헤더와 상태 바가 같은 지표를 두 번 보여주는 건 개별 화면만 봐서는 안 보였다. “레이아웃 검토해줘” 한 문장이 하루의 방향을 정했다.
• CSS 특정도는 순서가 아니라 규칙이다 — .modal의 후행 단축 선언도, ConfCard의 인라인 스타일도 결국 같은 종류의 함정이었다. 낮은 특정도는 나중에 와도 이기지 못한다.
• 명사 하나가 두 화면을 가리킬 수 있다 — “산출물 탭”이 트리와 편집기 탭 둘 다를 가리키면서 엉뚱한 곳을 고쳤다. 되돌리는 데는 커밋 하나, 알아채는 데는 사용자의 짧은 정정 한 줄이면 충분했다.
• 참고 이미지는 “병합”과 “분할”을 혼동시킬 수 있다 — 같은 스크린샷을 보고도 “합쳐라”와 “내부를 나눠라”는 다르게 읽힐 수 있다. 방향이 틀렸다는 피드백이 오면 즉시 되돌리는 게 다음 시행착오보다 싸다.
• 레일이 보인다고 아이콘이 보이는 건 아니다 — flexbox 컨테이너와 그 안의 SVG는 각자 다른 붕괴 규칙을 따른다.

다음에 남는 것:

• 헤더 단계 스텝퍼와 PhaseView 내부 진행 표시가 겹치는 문제 — 오늘은 참고사항으로만 남기고 정리는 미뤘다.
• 정합성 도크의 좌측 레일 기능(다시검사·이전/다음 문제)이 실사용에서 얼마나 쓰이는지 관찰.
• 우측 도크의 “운영” 패널(작업큐+요청메트릭 병합)이 두 정보량 차이 때문에 다시 나뉘어야 하는지 지켜보기.
• 관리 화면에서 걷어낸 개별 설정 접근 경로들이 아바타 드롭다운 하나로 충분한지, 비관리자 사용성 재확인.