덕삼
블로그

설계서는 md·yaml·svg 만 고치고 docx·html 은 빌드한다 — 숫자는 한 곳에, 그림은 생성기로

문서 여러 종에 같은 숫자가 흩어지지 않고, 설명이 바뀔 때마다 그림을 다시 그리지 않으려면 어떻게 해야 할까?

답부터 적는다. 원본을 셋으로 나누고 나머지는 모두 빌드한다. 서술은 md, 반복되는 숫자와 표는 yaml, 그림은 svg 다. Word 와 HTML 은 산출물이라 손대지 않는다. 숫자는 yaml 한 곳에만 두고 본문은 자리표시로 센다. 흐름도는 yaml 에서 그리게 하고, 글자가 상자를 넘으면 빌드를 멈추게 한다.

글·표·그림 세 원본이 깔때기를 지나 빌드 기계로 들어가고, 컨베이어 위로 docx·html·md 문서가 나온다. 완성된 문서에는 수정 금지 딱지가 붙어 있고, 로봇은 깔때기 위의 원본에만 펜을 댄다

그림으로 줄이면 이렇다. 사람과 에이전트는 깔때기 위의 원본만 고친다. 기계에서 나온 문서에는 손대지 않는다.

근거는 은행 개발 조직의 3인 팀이 2026-10-23 에 에이전트와 함께 만든 문서 키트다. 2026-11-18 에 다시 돌려 보고 숫자를 셌다. 저장소가 비공개라 커밋 해시는 독자가 열어 볼 수 없다. 찾아갈 표시로만 남긴다.

원본은 세 가지, 문서는 여섯 종류다

키트 폴더 하나에 원본과 정의가 모두 들어 있다. 빌드 엔진과 Word·HTML 서식은 스킬 폴더에 따로 둔다. 키트 쪽 구조는 이렇다.

파일하는 일지금 개수
kit.yaml프로젝트 정보, 표·그림 정의, 문서 종류(프로파일)표 11, 그림 3, 문서 6
data/*.yaml일정·지표·위험·기능 목록 같은 반복 데이터9
docs/*.md장별 본문. 자리표시로 표·숫자·그림을 끌어온다17
figures/*.svg손으로 그린 그림1
figures/_generated/yaml 에서 생성한 그림. 손으로 고치지 않는다2
out/산출물. git 에 올리지 않는다빌드할 때 생긴다

문서 종류는 장 목록과 출력 형식의 조합이다. 통합 설계서, 구성도, 기능명세서, 품의 요약, 보안 검토 자료, 완료보고서가 있다. 서로 다른 장 25개 가운데 10개는 두 문서 이상이 함께 쓴다. 한 장을 고치면 그 장을 쓰는 문서가 모두 바뀐다.

숫자는 yaml 한 곳에 두고 본문은 센다

본문에는 숫자를 직접 쓰지 않는다. 자리표시 두 가지로 yaml 에서 끌어온다.

기능은 모두 {{count:features}}개이고 그중 {{count:features|status=완료}}개를 마쳤다.

{{table:features}}

{{count:이름|조건}} 은 조건에 맞는 행 수로, {{table:이름|조건}} 은 그 행들의 표로 바뀐다. 기능 세 줄짜리 yaml 로 빌드하면 첫 줄은 “기능은 모두 3개이고 그중 2개를 마쳤다"가 된다. 범용 예제로 돌려 확인했다.

실제 키트의 본문에는 표 자리표시가 16개, 개수 자리표시가 9개 있다. 가장 많이 불리는 표 하나는 본문 12곳에서 쓰인다. 그 표의 행 하나를 바꾸면 12곳이 한 번에 바뀐다.

완료보고서가 이 구조의 덕을 가장 많이 본다. 완료보고서는 따로 쓰지 않는다. 지표 yaml 에는 실적과 판정을, 일정 yaml 에는 실제 날짜를 채운다. 기능 yaml 에 상태를 채우면 구현 현황표가 바뀐다. 결론과 이슈처럼 서술이 필요한 곳만 md 로 쓴다.

엔진을 옮길 때는 산출물을 바이트로 비교했다

처음 엔진은 Python 207줄이었다(c6eb615). 6분 뒤 커밋 c1ea56e 에서 Bun 과 TypeScript 로 옮겼다. Bun 에는 YAML 파서가 들어 있어 폐쇄망에 PyYAML 을 따로 반입하지 않아도 된다.

옮긴 근거는 커밋 메시지에 있다. 두 엔진이 만든 md·html·svg 16개가 바이트까지 같다는 것이다. 이번에 두 커밋을 각각 꺼내 다시 빌드했다. 산출물 폴더의 15개와 생성된 일정 그림 1개, 모두 16개가 같았다. SVG 를 PNG 로 바꾸는 rsvg-convert 는 PATH 에서 빼고 돌렸고, Word 파일은 비교하지 않았다.

리팩터링(동작은 두고 구조만 바꾸는 수정)의 완료 기준을 “산출물 바이트 동일"로 잡으면 리뷰가 짧아진다. 새 코드를 한 줄씩 읽기 전에, 같은 입력에서 같은 출력이 나왔다는 사실 하나로 먼저 판단한다.

그림은 34분 사이에 손 그림에서 생성기로 넘어갔다

흐름도 하나가 바뀐 순서를 커밋 시각으로 늘어놓으면 이렇다. 모두 2026-10-23 이다.

시각커밋바뀐 것
12:53bfd78d3다이어그램 도구로 만든 흐름도. HTML 한 파일이 13,790줄
13:0849b7d9e손으로 그린 SVG 51줄로 바꿔 문서 키트에 등록
13:17dd34395흐름 생성기 추가. 원본은 yaml 44줄, 손 그림은 지움
13:2198f86bc흐름을 10단계로 다시 정의. 사람 승인 관문 표시를 더함
13:26d39161c가로 배치와 줄바꿈, 영역 전체를 지켜보는 시스템 상자를 더함
13:27354ee1f설명 문구 수정. yaml 2줄

손 그림은 9분을 버텼다. 생성기가 생긴 뒤에는 흐름을 통째로 다시 정의해도 yaml 만 고쳤다. 마지막 수정은 yaml 2줄과 다시 생성한 그림 한 장이었다. 이 커밋들에는 모두 에이전트 공동 작성 표시가 있다.

해석은 이렇다. 흐름도는 이 키트에서 34분 동안 다섯 번 바뀌었다. 손 그림이었다면 바뀔 때마다 상자와 화살표를 다시 놓아야 한다. yaml 에서 그리면 단계 목록만 고치면 되고, 같은 yaml 에서 단계표도 나온다. 그림과 표가 서로 어긋날 수 없다.

그림 규칙은 문서가 아니라 생성기가 지킨다

그림 규칙은 36줄짜리 문서 하나에 있다. 요점은 다섯 가지다.

  • 색은 용도 여섯 가지로 묶는다. 강조만 테두리와 바탕 두 값을 쓴다.
  • 강조색은 그림당 한 곳에만 쓴다. 다섯 곳을 강조하면 아무것도 강조되지 않는다.
  • 글자는 이름 13, 설명 11.5 크기이고 10.5 미만은 쓰지 않는다.
  • SVG 에는 자동 줄바꿈이 없다. 상자 너비는 가장 긴 줄에 24를 더해 잡는다.
  • foreignObject, 외부 이미지·글꼴 링크, 스크립트는 넣지 않는다. 보안 점검과 Word 호환 때문이다.

손으로 그리는 사람은 이 규칙을 잊는다. 생성기는 잊지 않는다. 두 단계에 강조를 걸면 빌드가 멈추고, 세로 배치에서 글자가 상자 폭을 넘어도 멈춘다. 범용 예제로 일부러 넘치게 해 보았다.

error: data/flow.yaml: "바뀐 화면과 서비스를 모두 찾아 목록으로 만든다" 가 상자 폭(192)을 넘는다 — 줄이거나 나눈다

종료 코드는 1 이고 산출물 폴더는 비어 있었다. 빌드는 시작할 때 그 문서의 산출물 폴더를 지운다. 그래서 실패하면 낡은 문서도, 글자가 삐져나온 문서도 남지 않는다.

가로 배치에서는 멈추지 않고 상자를 넓힌다. 가장 긴 이름에 맞춰 상자 폭을 정하고, 한 줄에 wrap 개씩 놓은 뒤 다음 줄은 반대 방향으로 잇는다. ㄹ자 모양이다. 되돌림 화살표가 줄바꿈 화살표와 겹치면 그때는 빌드가 멈춘다.

말로 들은 흐름은 yaml 부터 만든다

스킬 문서에는 순서 규칙이 하나 있다. 사용자가 업무 흐름을 말로 설명하면, 에이전트는 먼저 흐름 yaml 로 정리한다. 단계, 담당, 넘기는 것, 되돌림, 옆 시스템을 적는다. 그 yaml 을 사용자에게 확인받은 뒤에 그림을 보여 준다.

direction: horizontal
wrap: 3
steps:
  - {id: a, name: 접수, desc: 요청 등록, output: 요청서}
  - {id: b, name: 분석, desc: 영향 범위 확인, output: 분석표}
  - {id: c, name: 승인, desc: 담당자 확인, gate: true, back: {to: b, label: 반려}}

이 규칙의 이유는 스킬 문서에 적혀 있지 않다. 내 해석은 이렇다. 그림을 먼저 보면 사람은 배치와 색을 본다. yaml 을 먼저 보면 단계와 순서가 맞는지를 본다. 확인할 것을 글자로 좁혀 주는 순서다.

이 판단이 틀리는 경우

  • 문서가 한 종류이고 한 번 쓰고 끝난다면 키트를 만드는 값이 더 크다. 같은 장을 여러 문서가 나눠 쓸 때 값을 한다.
  • 생성기는 일정 막대와 블록 흐름도 두 가지뿐이다. 구성도처럼 배치가 자유로운 그림은 여전히 손으로 그린다. 지금 그림 셋 가운데 하나가 손 그림이다.
  • 결재란처럼 칸 배치가 정해진 서식은 Pandoc 의 참조 서식만으로 맞추기 어렵다. 이 키트도 한글(HWP) 파일이 필요하면 docx 를 한컴오피스에서 변환한다.
  • 키트는 옮겨 넣은 만큼만 일한다. 통합 설계서 11장 가운데 8장은 아직 원본이 없어 빌드할 때마다 “없는 장” 경고가 나온다.
  • 바이트 비교는 엔진을 옮길 때 한 번 했다. 저장소에 CI 가 없어 그 뒤의 변경은 같은 방식으로 검증되지 않는다.

정리

같은 숫자가 흩어지지 않게 하려면 숫자를 한 곳에 두고 나머지는 세게 한다. 그림을 다시 그리지 않으려면 그림의 원본을 글로 두고 그림은 빌드한다. 산출물은 결과일 뿐이라 고치지 않는다.

지금 확인할 것은 하나다. 팀 설계서에 같은 숫자가 몇 군데 적혀 있는지 센다. 그리고 그 숫자를 yaml 파일 하나로 모을 수 있는지 본다.