관리자 매뉴얼 자동화로 수동 작업 반나절을 수분으로 단축

매뉴얼 엔진을 손으로 짜기로 한 이유

관리자 화면이 계속 늘어나면서 운영팀에서 "이 버튼 뭐예요"라는 질문이 매주 쌓였음. 외부 문서툴에 정리하던 매뉴얼이 화면 변경 속도를 못 따라잡아서, 빌드 시점에 화면 메타데이터를 긁어 자동으로 매뉴얼 HTML을 뽑는 스크립트를 직접 만들기로 함.

처음엔 외부 문서 도구를 붙일까 고민했는데, 이커머스 도메인 특성상 화면 구조가 들쭉날쭉이라 우리 도메인을 아는 스크립트가 결국 빠를 거라 판단함.

manual-engine.js가 하는 일

대충 이런 흐름임.

// 메뉴 트리 → 화면 메타 → 스크린샷 → 마크다운 합성
const menus = readMenuTree();
for (const m of menus) {
  const meta = parseScreenMeta(m.path);
  await captureShot(m.url, m.id);
  writeManualSection(m, meta);
}

• 메뉴 트리에서 화면 ID를 읽어옴
• 각 화면의 입력 필드/버튼/권한 정보를 정적 분석으로 긁음
• 헤드리스 브라우저로 스크린샷 찍고 마크다운 섹션을 조립함
• 마지막에 단일 HTML로 합쳐서 운영팀 공유 채널로 떨굼

수동으로 갱신할 때 반나절 걸리던 게, 스크립트 돌리면 몇 분 안에 끝남.

.gitignore를 같이 손댄 이유

스크립트가 만들어내는 산출물이 꽤 묵직했음. 정리하면 이런 것들.

처음엔 결과물도 같이 커밋하다가 PR diff가 만 줄을 넘어서 리뷰 자체가 불가능해졌음. 그래서 산출물 디렉터리를 통째로 ignore하고, 매뉴얼 배포는 별도 채널로 분리함.

짠 뒤에 깨달은 것

• 산출물 vs 스크립트: 자동 생성물은 절대 저장소에 안 올림. 한 번 올리면 diff가 노이즈가 되고, blame도 망가짐
• 운영팀 피드백 루프: 자동화는 1차 초안일 뿐, 운영팀이 손으로 보강할 여지를 남겨야 실제로 쓰임
• 스크린샷 캐시 키: URL만으로 캐시하면 권한별 화면 차이를 놓침. 권한+URL 조합으로 키 잡는 게 맞았음
• 메타 표준의 부재: 화면마다 메타가 제각각이라 파서 분기가 계속 늘어남. 이게 다음 숙제

매뉴얼 자동화는 "한 번 짜두면 끝"이 아니라 화면 바뀔 때마다 스크립트도 같이 무거워지는 구조라, 다음엔 메타데이터 표준을 먼저 정하고 엔진은 그걸 소비만 하도록 분리할 계획임.

다음