소스 코드에서 화면 사양서를 자동 생성하여 브라우저에서 바로 확인할 수 있도록 만든 이야기

업무 시스템 개발에 있어, 「화면 사양서 유지보수」는 항상 골치 아픈 문제입니다.

• 텍스트 기반의 사양서로는,
  화면상의 어떤 요소를 가리키는지 연결하기가 어렵다 - 그렇다고
  화면 캡처를 붙여넣는 운용은 UI 변경 시마다 교체가 필요하여 관리 비용이 크다 - 화면마다 사양서를 만들면
  수가 방대해져 유지보수를 따라갈 수 없다 - 처리 내용을 상세하게 적을수록
  기술량이 늘어나 유지보수 부하와 누락이 증가한다

이 과제에 대해, 「AI를 사용하여 소스 코드로부터 화면 사양서를 자동 생성하고, 화면과 일체화하여 참조할 수 있도록 하는」 수법을 구축했습니다. 본 기사에서는 그 전체 모습과 현재 구상 중인 MCP 서버 연동까지 소개합니다.

사양서 작성의 시작점으로 준비한 것이 AI 에이전트용 재사용 가능한 프롬프트 (Skill) 입니다. 화면 사양서를 정의한 JSON 파일을 생성하는 Skill을 정의해 둠으로써,

"화면 사양서를 작성해줘"

xxx 화면

의 사양서 JSON을 만들어줘

라고 지시하는 것만으로, 대상 화면의 소스를 재귀적으로 해석하여 화면 사양이 정의된 JSON 파일이 출력됩니다.

Skill의 프롬프트에서는 "페이지 → 자식 컴포넌트 → 손자 컴포넌트 → 증손자..."와 같이 말단까지 재귀적으로 추적할 것을 명시하고 있습니다. AI가 얕은 계층에서 중단하는 것을 방지하기 위해 체크리스트도 심어 두었습니다.

[ ] 페이지 내에 탭 전환으로 표시되는 자식 컴포넌트가 있는 경우,
각 탭 컴포넌트의 소스를 읽어 들여,
내부의 모든 폼 요소·표시 요소를 elements로 정의한
...

AI가 처리 플로우를 단계별로 구성해 나가는 과정에서, "이 분기는 의도대로인가?", "이 에러 핸들링은 정말 필요한가?"와 같은 리뷰 관점이 떠오릅니다. 문서 생성과 동시에 코드 리뷰가 돌아간다는 것은 예상치 못한 수확이었습니다.

JSON을 생성하는 것만으로는 결국 PDF가 늘어나는 것과 다를 바 없습니다. 그래서 실제 화면과 사양서를 1대 1로 연결하여 표시하는 사양서 Viewer를 화면에 통합했습니다.

개발 환경에서 특정 키 입력을 하면 드로어(Drawer) 형태로 Viewer가 나타납니다. 표시 내용은 4개의 탭으로 구성되어 있습니다.

화면 설명·화면 ID·파일 경로·관련 API 목록을 참조할 수 있습니다.

초기 표시 시 실행 중인 처리를 참조할 수 있습니다.

관련 API의 개요·URI·요청/응답(Request/Response) 사양을 참조할 수 있습니다. 이러한 사양 내용은 API를 통해 취득합니다.

화면상의 폼 요소·버튼 요소·동적 표시값의 사양을 참조할 수 있습니다.

폼 요소: 유효성 검사(Validation) 정보 -
동적 표시값: 어떤 API의 어떤 필드가 표시되고 있는지 -
버튼 요소: 비활성화 조건이나 클릭 이벤트 처리

Viewer의 핵심은 화면의 요소를 클릭하면 대응하는 사양이 즉시 열리는 조작감입니다. 이를 실현하고 있는 것이 Skill이 자동으로 부여하는 data-spec-id 속성입니다.

<!-- 페이지의 루트 -->
<div data-spec-id="spec:screen1-elementA">
<!-- 폼 요소 -->
...

사양서 모드를 활성화하면 호버(Hover) 시 요소가 하이라이트되며, 클릭하면 Viewer의 해당 부분으로 점프합니다. 예를 들어 목록 테이블의 셀을 클릭하면,

"이 셀은 getUserList API의 users[].name을 표시하고 있다"

라고 즉시 확인할 수 있습니다. "이 값은 어디서 오는 거지?"를 grep 하는 시간이 거의 제로가 되었습니다.

여기까지는 하나의 프로덕트 내에서 완결되는 이야기이지만, 더 나아가 사양서 JSON의 내용을 공통 DB에 저장했습니다.

당사에서는 업무 SaaS인 "Hirameki 7"의 개발에 있어, 이용 중인 API·테이블 구조·시스템 코드를 "SEVEN'S DOOR"라는 자체 개발 관리 도구로 일원 관리하고 있습니다. 여기에 화면 사양도 추가로 갖게 하는 형태로 만들었습니다. 사양 데이터의 중복 관리를 피하기 위해 공통 DB를 유일한 참조 원천(Single Source of Truth)으로 삼고, SEVEN'S DOOR와 Hirameki 7 모두에서 동일한 내용을 가져오는 구성으로 하고 있습니다.

Skill 측에서도 이 연동을 고려하여, 생성하는 사양서에는 공통 DB 측의 API 정보와 연결하기 위한 식별자를 반드시 포함합니다. 공통 DB의 API 목록과 요청 URI를 대조하여 자동으로 연결하는 절차를 Skill 내에 명문화하고 있습니다.

이를 통해 「Hirameki 7 화면에 표시되고 있는 API의 정규 사양은 SEVEN'S DOOR에서 관리하는 마스터와 항상 일치한다」는 상태를 실현할 수 있었습니다. 사양 변경 시 발생하는 이중 관리 비용도 없습니다.

여기서부터가 현재 진행 중인 시도입니다. 사양 정보가 DB에 집약된 이상, 이를 MCP (Model Context Protocol) 서버로 공개하면 AI 에이전트가 직접 쿼리할 수 있게 됩니다.

구상 중인 유스케이스 (Use Case):

개발자의 질문	MCP 서버가 반환하는 것
「사용자 목록 조회 API를 사용 중인 화면 목록을 알려줘」	API → 화면 역조회 리스트
「사용자 관리 화면에서 필수 항목으로 지정된 폼을 전부 알려줘」	화면 사양 요소 목록에서 필수 항목 추출
「POST /api/xxx를 변경했을 때의 영향 범위는?」	API 변경 시의 회귀 테스트 (Regression Test) 범위
「이 화면의 처리 흐름을 시퀀스 다이어그램으로 만들어줘」	processFlow를 mermaid로 변환

문서는 단순히 「읽는 것」뿐만 아니라 **「기계 판독 가능한 (Machine-readable) API로 제공하는 것」**을 통해, AI 지원 개발의 레버리지를 단번에 높일 수 있습니다. MCP화된 후에는 각종 AI 에이전트가 「코드를 읽는 것」과 동일한 감각으로 「사양을 읽는 것」이 가능해질 것으로 전망합니다.

과제	해결 접근 방식
사양서 유지보수 비용	AI 에이전트용 스킬 (Skill)로 자동 생성
「이 값은 어디서 오는 거야?」	data-spec-id를 통한 화면 ↔ 사양의 양방향 연결
개발 관리 도구와 화면 사양의 이중 관리	공통 DB에 집약하여 SEVEN'S DOOR (개발 관리)와 Hirameki 7 (프로덕트)에서 공유
AI 지원 개발의 정밀도 향상	사양 DB의 MCP 서버화 (구상)

사양서를 「인간이 쓰고 인간이 읽기만 하는 문서」에서, **「AI가 생성하고, 화면과 연결되며, DB에서 공유되고, AI가 호출할 수 있는 기계 판독 가능 데이터」**로 전환함으로써, 개발 흐름 전체가 한 단계 가벼워지는 것을 체감하고 있습니다.

비슷한 고민을 하고 계신 분들께 참고가 된다면 기쁘겠습니다.