이 기사는 2026년 6월 시점에서의 자신의 생각을 정리한 것입니다.

세상의 개발 방법론이나 설계서 작성법을 부정하고 싶은 것은 아닙니다.

워터폴(Waterfall) 개발, 애자일(Agile) 개발, 수탁 개발, 사내 개발 등 현장에 따라 필요한 문서는 다르다고 생각합니다.

어디까지나 AI 에이전트나 생성형 AI (Generative AI)를 사용하며 개발하는 과정에서, 지금의 나에게는 이렇게 보인다는 이야기입니다.

최근 AI에게 코드를 읽게 하여 설계 자료를 만드는 것을 시도하고 있습니다.

계기는 Codex에 앱의 구성을 읽게 하여, HTML 한 장으로 된 설계 자료를 만들게 해본 것이었습니다.

처음에는,

AI로 설계 자료를 만드는 것이 편해지겠구나

정도로 생각했습니다.

실제로 상당히 편리했습니다.

코드를 바탕으로 아키텍처 (Architecture), 화면 구성, 데이터의 흐름, 주요 기능을 정리해 줍니다.

Markdown으로 길게 작성된 자료보다, HTML 한 장으로 볼 수 있는 자료가 전체상을 파악하기 쉬운 경우도 있었습니다.

하지만 조금 생각하다 보니, 이것은 단순히 '설계 자료를 편하게 만들 수 있다'는 이야기만은 아니라는 느낌이 들었습니다.

AI로 구현 후의 코드로부터 설계 자료를 만들 수 있다면, 애초에 지금까지와 같은 상세 설계서 (Detailed Design Document)는 무엇을 위해 필요한 것인가.

구현 전에 자세히 쓰는 설계서와, 구현 후에 코드로부터 만들 수 있는 이해용 자료는 같은 것으로 생각하지 않아도 되지 않을까.

그런 생각을 하게 되었습니다.

이 기사에서는 AI 시대의 설계서는, '상세 내용을 쓰는 것'에서 '합의를 남기는 것'으로 조금씩 역할이 변해가는 것이 아닐까 하는 이야기를 정리해 보겠습니다.

지금까지 설계서라고 하면, 하나로 묶어 '설계서'라고 불렀던 것 같습니다.

하지만 최근에는 조금 나누어 생각하는 것이 좋지 않을까 생각합니다.

크게 나누면 설계서에는 적어도 두 가지 역할이 있습니다.

하나는, 합의를 위한 설계서입니다.

다른 하나는, 이해를 위한 설계서입니다.

이 두 가지는 비슷하지만 목적이 다릅니다.

합의를 위한 설계서는 앞으로 무엇을 만들 것인지, 무엇을 만들지 않을 것인지, 어디까지를 이번 범위로 할 것인지를 관계자와 확인하기 위한 것입니다.

반면, 이해를 위한 설계서는 이미 존재하는 시스템이 어떤 구성으로 되어 있는지, 코드를 읽기 전에 전체상을 파악하기 위한 것입니다.

이 두 가지를 같은 형식, 같은 입도 (Granularity), 같은 갱신 방법으로 다루려고 하면 조금 무리가 생기지 않을까 생각합니다.

둘 다 중요합니다.

다만 역할이 다르다면 만드는 방법도 달라도 될 것입니다.

AI로 설계 자료를 만들 수 있게 되어도, 합의를 위한 설계서는 없어지지 않을 것이라고 생각합니다.

왜냐하면 AI가 코드로부터 자료를 만들 수 있는 것은 기본적으로 '이미 무언가가 있는' 경우이기 때문입니다.

하지만 개발에서는 구현 전에 결정해야 하는 것들이 있습니다.

• 무엇을 만들 것인가
• 무엇을 만들지 않을 것인가
• 누가 사용하는가
• 어디까지를 이번 범위로 할 것인가
• 어떤 사양을 뒤로 미룰 것인가
• 어떤 제약을 받아들일 것인가
• 어디에서 고객이나 관계자의 확인을 받을 것인가

이런 것들은 코드로부터 역생성할 수 없습니다.

코드는 이미 결정된 결과를 나타냅니다.

하지만 왜 그렇게 결정했는지까지는 코드만으로는 알 수 없는 경우가 많습니다.

예를 들어, 어떤 기능이 구현되어 있지 않다고 가정해 봅시다.

그것이 누락된 것인가.

이번 스코프 (Scope) 외로 합의한 것인가.

장래 대응으로 미룬 것인가.

비용 문제로 삭감한 것인가.

운영으로 커버하기로 한 것인가.

이것은 코드만 봐서는 알 수 없습니다.

그래서 합의의 이력은 필요합니다.

내가 앞으로도 남겨야 한다고 생각하는 것은, 모든 세세한 처리를 미리 다 써 내려가는 상세 설계서라기보다, 관계자와 무엇을 합의했는지를 나중에 추적할 수 있는 자료입니다.

여기서 말하는 '합의를 남긴다'는 것은 단순히 승인 도장을 받는다거나 설계서에 서명을 받는다는 의미가 아닙니다.

내 안에서는 다음과 같은 것들을 남기는 이미지입니다.

특히 중요한 것은, '결정한 것'뿐만 아니라, 결정하지 않은 것이나 스코프 외(Scope out)로 둔 것도 남기는 것이라고 생각합니다.

나중에 문제가 되는 것은 구현의 세부 사항보다는, 오히려 "이것이 이번에 하기로 했던 이야기였나", "왜 이 사양(Specification)이 되었나", "누가 확인했나"를 알 수 없게 되는 상황이기도 합니다.

코드에서 구현 내용을 읽어내는 것은 AI에 의해 상당히 편해질지도 모릅니다.

하지만 무엇을 합의했는지, 왜 그렇게 판단했는지는 코드만으로는 복원하기 어렵습니다.

한편으로, 구현 후의 이해를 위한 자료는 AI에 의해 만드는 방식이 상당히 바뀔 것이라는 느낌이 듭니다.

지금까지 구현 후의 설계서를 수동으로 계속 업데이트하는 것은 힘들었습니다.

처음에 깔끔한 설계서를 작성해도 구현이 진행되면 코드가 변합니다.

사양 변경(Specification change)이 들어옵니다.

예외 처리(Exception handling)가 늘어납니다.

화면이나 데이터의 흐름도 변합니다.

그리고 정신을 차려보면 설계서가 낡아 있습니다.

이것은 상당히 흔히 있는 일이라고 생각합니다.

하지만 AI에게 코드를 읽게 하여 자료를 만들 수 있게 되면 상황이 조금 달라집니다.

구현된 코드를 바탕으로,

• 애플리케이션의 구성
• 주요 화면
• 모듈(Module) 간의 관계
• 데이터의 흐름
• API 및 DB와의 접속
• 처리의 입구와 출구
• 영향 범위의 개요

와 같은 것들을 정리해 줍니다.

이것은 기존 의미에서의 '먼저 쓰는 설계서'와는 반대입니다.

코드를 쓰기 전에 설계서를 만드는 것이 아니라, 구현된 코드로부터 이해를 위한 설계 자료를 역생성(Reverse generation)하는 것.

이 사고방식은 AI 시대에는 상당히 현실적이 되었다는 느낌이 듭니다.

물론 AI가 생성한 자료를 그대로 믿는 것은 위험합니다.

실제 코드와 대조해 볼 필요가 있으며, 보안이나 사양 판단의 배경까지 스스로 이해할 수는 없습니다.

그럼에도 불구하고 코드를 읽기 전의 입구로서는 충분히 도움이 됩니다.

적어도 구현 후의 이해를 위한 자료를 인간이 전부 손으로 쓰고 계속 유지보수(Maintenance)하는 것보다는, AI에게 코드를 읽게 하여 다시 만드는 것이 현실에 더 가까운 상황이 많아질 것 같습니다.

여기서 생각해 보고 싶은 것이 이른바 상세 설계서(Detailed design document)의 역할입니다.

물론 상세 설계서가 필요한 현장은 있습니다.

규제가 강한 시스템.

대규모 수탁 개발.

외부 위탁이 많은 개발.

엄격한 리뷰(Review)나 승인이 필요한 현장.

구현 담당과 설계 담당이 나누어져 있는 현장.

이런 상황에서는 상세한 설계서가 필요해지는 경우도 있을 것이라고 생각합니다.

다만, 모든 개발에서 지금까지와 같은 상세 설계서를 먼저 만들 필요가 있는가라고 묻는다면 조금 의문이 생깁니다.

AI 에이전트(AI Agent)를 사용하면 구현의 시행착오가 빨라집니다.

프로토타입(Prototype)도 만들기 쉬워집니다.

수정도 빨라집니다.

코드에서 자료를 만드는 것도 가능합니다.

그렇게 되면 구현 전에 모든 것을 세세하게 다 써 내려가기보다, 우선 합의해야 할 것을 명확히 하고 구현 후의 이해를 위한 자료는 코드로부터 생성하는 편이 더 적합한 상황도 많아지지 않을까 생각합니다.

처음에는,

AI로 상세 설계서를 편하게 만들 수 있다

라고 생각했습니다.

하지만 조금 생각해보면, 이것은 상세 설계서를 효율화하는 이야기가 아니라, 기존의 상세 설계서의 역할을 재검토하는 이야기일지도 모릅니다.

AI로 설계서를 편하게 쓸 수 있으니까 지금까지와 같은 설계서를 대량으로 만든다.

그것도 하나의 사용법입니다.

하지만 저로서는 그것보다,

애초에 무엇을 위해 그 설계서를 쓰는 것인가

를 재검토하는 것이 좋다는 느낌이 듭니다.

제가 지금 가장 납득하고 있는 것은 설계서를 '상세 내용을 쓰는 것'이 아니라, 합의를 남기는 것으로 보는 사고방식입니다.

물론 상세 내용이 불필요하다는 의미는 아닙니다.

다만 구현의 세세한 부분은 최종적으로 코드에 나타납니다.

그리고 구현 후의 이해를 위한 자료는 AI로 코드로부터 만들기 쉬워지고 있습니다.

한편으로 합의는 코드만으로는 남지 않습니다.

• 왜 이 사양으로 했는가
• 왜 이 기능을 만들지 않기로 했는가
• 왜 이 화면 전환으로 했는가
• 어떤 제약 사항을 받아들였는가
• 어떤 리스크를 허용했는가
• 누구와, 언제, 무엇을 확인했는가

이런 정보는 코드에는 남기 어렵습니다.

하지만 나중에 굉장히 중요해집니다.

사양 변경이 일어났을 때.

트러블이 발생했을 때.

담당자가 바뀌었을 때.

"왜 이렇게 되어 있는가"를 설명할 때.

필요한 것은 세세한 처리의 설명뿐만 아니라, 당시 판단의 이력(History)입니다.

그렇기에, AI 시대의 설계서에서는 구현의 상세 내용을 모두 써 내려가는 것보다, 합의의 이력(History)을 남기는 것의 중요성이 높아지는 것이 아닐까 생각합니다.

이는 애자일 개발 (Agile Development)과도 연결되는 이야기라고 생각합니다.

애자일 개발에서는 처음부터 모든 것을 고정하는 것이 어렵습니다.

만들면서 알게 되는 것이 있습니다.

사용자에게 보여주고 나서야 비로소 알게 되는 것이 있습니다.

우선순위가 바뀌는 일도 있습니다.

구현해 보니 생각보다 어렵다는 것을 깨닫기도 합니다.

그렇기 때문에, 처음에 상세 설계서 (Detailed Design Document)를 완벽하게 만들고 그것을 끝까지 지킨다는 사고방식은 현실과 맞지 않는 상황이 있습니다.

하지만 그렇다고 해서 아무것도 남기지 않아도 된다는 뜻은 아닙니다.

오히려 애자일이기 때문에 더욱, 무엇을 합의했는지를 남기는 것이 중요하다고 생각합니다.

• 이번에는 무엇을 만드는가
• 무엇은 만들지 않는가
• 어디까지 되면 완료인가
• 어떤 사양 (Specification)은 나중에 재검토할 것인가
• 누가 무엇을 확인했는가
• 어떤 판단을 언제 바꾸었는가

이런 것들이 남아 있지 않으면 나중에 경위를 알 수 없게 됩니다.

애자일에서의 설계서는 미래를 고정하기 위한 것이 아니라, 그 시점에서의 합의를 남기기 위한 것에 가까울지도 모릅니다.

그리고 구현 후의 구조 이해는 코드와 AI 생성 자료에 맡긴다.

이렇게 나누면 애자일 개발에서의 문서화 (Documentation)에 대한 생각도 조금 정리하기 쉬워지는 느낌이 듭니다.

AI 시대의 문서는 인간만이 읽는 것이 아니게 될 것이라는 느낌이 듭니다.

인간이 합의한 것을 남긴다.

AI가 코드를 읽을 때의 전제가 된다.

새롭게 참여한 사람이 시스템을 이해하는 입구가 된다.

리뷰를 할 때의 판단 재료가 된다.

과거의 경위를 추적하기 위한 로그 (Log)가 된다.

그렇게 생각하면, 문서는 단순한 납품물이 아니라 **합의와 이해를 잇는 컨텍스트 (Context)**가 되어가는 것일지도 모릅니다.

설계서도 마찬가지입니다.

지금까지처럼,

설계서를 작성한다

그대로 구현한다

구현이 바뀌면 설계서를 유지보수한다

라는 흐름으로만 생각하면 AI 시대에는 조금 힘들게 느껴집니다.

오히려,

합의는 인간이 남긴다

구현은 코드에 남는다

이해용 자료는 AI로 생성한다

판단의 배경은 합의 이력으로 남긴다

라는 구분이 저에게는 더 자연스럽게 보입니다.

즉, 설계서는 하나의 거대한 문서일 필요는 없을지도 모릅니다.

합의 메모.

회의록.

사양 결정 이력.

스코프 (Scope) 확인.

코드에서 생성한 구성 자료.

README.

화면 목록.

API 목록.

변경 이유.

그런 것들이 조합되어 설계의 문맥이 된다.

AI 시대의 설계서는 그런 형태에 가까워지는 것이 아닐까 생각합니다.

AI에게 HTML 한 장 분량의 설계 자료를 만들게 해 보았을 때, 처음에는 단순히 편리하다고 생각했습니다.

Markdown보다 보기 쉽다.

코드의 전체상을 파악하기 쉽다.

구현 후의 이해용 자료로서 상당히 쓸모가 있을 것 같다.

그런 감상이었습니다.

하지만 거기서 조금 더 생각해보니, 설계서의 역할 그 자체를 재검토하는 이야기로 이어졌습니다.

AI로 구현 후의 코드로부터 설계 자료를 역생성할 수 있다면, 기존의 상세 설계서를 모두 미리 만들 필요는 희박해질지도 모릅니다.

물론 합의는 필요합니다.

고객이나 관계자와 인식을 맞추기 위한 자료는 필요합니다.

무엇을 만드는가, 무엇을 만들지 않는가, 어디까지를 이번 범위로 할 것인가는 남겨두어야 합니다.

다만 그것은 구현의 세부 사항을 모두 미리 고정하는 상세 설계서라기보다, 합의의 이력에 가까운 것일지도 모릅니다.

구현 후의 이해용 자료는 코드로부터 AI가 생성하게 한다.

인간 사이의 판단이나 합의는 이력으로 남긴다.

그렇게 나누어 생각하면, 설계서는 '구현을 구속하는 것'이 아니라 합의와 이해를 잇는 것으로 재정의할 수 있다는 느낌이 듭니다.

아직 저 자신도 시행착오 중입니다.

다만 지금의 저에게 AI 시대의 설계서는,

상세를 쓰는 것에서 합의를 남기는 것으로

조금씩 역할이 바뀌어 가는 것으로 보입니다.