Codex로 출력한 것입니다.

시스템 개발에서는 무언가를 만들기 전에 설계 자료를 만드는 경우가 많다고 생각합니다.

관계자의 요구사항이나 의견을 듣고, 인식을 맞추며, 합의를 이끌어냅니다.

그를 위한 자료라면, 지금도 Word, Excel, PDF와 같은 형식이 사용하기 쉬운 상황이 많습니다.

여러분은 코멘트를 적거나 수정 지시를 내릴 수 있고, 회의에서 설명하기에도 다루기 쉽습니다.

즉, 합의 형성을 위한 설계서로서는 기존 방식의 문서가 여전히 충분한 의미가 있다고 생각합니다.

반면, 계속 고민해 온 것은 구현이 끝난 후의 설계 자료입니다.

지금까지 저는 구현 후의 간단한 설계 자료를 Markdown으로 작성하곤 했습니다.

Git으로 관리하기 쉽고, 차이점(diff)도 보기 쉽습니다.

엔지니어에게 다루기 쉬운 형식임에는 틀림없습니다.

또한, AI에게 Markdown 형식으로 설계 자료를 작성하게 하는 경우도 있습니다.

하지만 솔직히 말해서, 설계 자료로서 읽기에는 조금 힘들다고 느낄 때가 있었습니다.

• 문장이 세로로 길어지기 쉽다
• 표나 그림을 넣는 것이 번거롭다
• 관련 정보를 오가며 확인하기 어렵다
• 시스템 전체를 조망하기 어렵다
• 어디서부터 읽어야 할지 알기 어렵다

Markdown은 편리합니다.

다만, 시스템의 내부 구조를 이해하기 위한 자료로서는 조금 단조롭게 느껴질 때가 있습니다.

특히 AI가 생성한 Markdown 설계 자료는 정보량은 많은데, 사람이 읽기에는 조금 무겁다고 느낄 때가 있었습니다.

그래서 시험 삼아, 최근 사용 중인 Codex에 다음과 같은 요청을 해보았습니다.

이 프로젝트의 아키텍처(Architecture)나 구성을 일람할 수 있는 자료를 만들어 주세요.
HTML 한 장으로, 인터랙티브(Interactive)하게 확인할 수 있는 것으로 만들어 주세요.

그러자 생각보다 훨씬 보기 좋은 자료가 나왔습니다.

HTML 한 장임에도 불구하고 화면이 정리되어 있어, 앱의 구성, 주요 기능, 데이터의 흐름, 화면 및 모듈 간의 관계를 시각적으로 확인할 수 있었습니다.

Markdown처럼 위에서부터 순서대로 읽는 것뿐만 아니라, 필요한 부분을 찾아볼 수 있습니다.

"이 시스템은 어떤 구성인가?"

"어디에 무엇이 있는가?"

"전체상을 대략적으로 파악하고 싶다"

그러한 목적이라면 상당히 실용적이라고 느꼈습니다.

물론 이것만으로 완전한 상세 설계가 되는 것은 아닙니다.

더 정확하게 확인하고 싶다면 최종적으로는 실제 코드를 볼 필요가 있습니다.

하지만 코드를 읽기 전의 입구로서는 충분합니다.

이번에 시도해 보면서, 설계 자료는 크게 두 종류로 나누어 생각하면 좋을 것 같다고 느꼈습니다.

이는 관계자와 인식을 맞추기 위한 자료입니다.

아직 구현 전이므로 내용도 확정되지 않았습니다.

수정이나 코멘트가 들어가기 쉽고, 회의에서 설명하기 쉬운 형식이 적합합니다.

이 용도에서는 Word, Excel, PDF와 같은 기존 방식의 자료가 좋다고 생각합니다.

이는 구현 후에 시스템의 내부를 파악하기 위한 자료입니다.

저는 구현 전에는 자료를 잘 만들지 않게 되었습니다...

코드를 읽기 전에 전체상을 파악하기 위한 입구가 됩니다.

이 용도라면 반드시 Markdown을 고집할 필요는 없을지도 모릅니다.

오히려 AI에게 HTML 한 장의 인터랙티브한 자료를 만들게 하는 것이 사람에게 더 읽기 쉬울 수 있습니다.

구현 후라면 AI는 실제 코드를 바탕으로 구성을 정리할 수 있습니다.

손으로 힘들게 설계서를 계속 업데이트하는 것보다, 실제 코드에 가까운 자료를 만들기 쉬울 가능성이 있습니다.

지금까지 설계서라고 하면 Word, Excel, Markdown 중 무엇으로 쓸 것인가라는 발상에 빠지기 쉬웠습니다.

하지만 AI가 코드를 읽어 들여 HTML 한 장의 보기 쉬운 자료를 만들 수 있게 되면, 생각이 조금 바뀝니다.

• 합의 형성을 위한 자료는 사람끼리 수정하기 쉬운 형태로 만든다
• 구현 후의 이해용 자료는 AI가 코드로부터 생성하게 한다
• 필요에 따라 HTML로 인터랙티브하게 볼 수 있도록 한다

이렇게 나누면 설계 자료의 작성과 유지보수가 상당히 편해질 것 같다는 느낌이 듭니다.

특히 구현 후의 설계 자료에 대해서는, 무리하게 긴 Markdown을 쓰는 것보다 AI에게 다음과 같이 부탁하는 것만으로도 상당히 실용적인 자료를 만들 수 있을지도 모릅니다.

이 프로젝트의 아키텍처(Architecture)나 구성을 일람할 수 있는 자료를 만들어 주세요.
HTML 한 장으로, 인터랙티브(Interactive)하게 확인할 수 있는 것으로 만들어 주세요.

설계서를 작성한다기보다,

AI에게 시스템을 읽히고, 사람이 이해하기 쉬운 형태로 변환하게 한다.

앞으로는 이런 방식의 문서 제작은 어떨까요?