창업자 저널 #8 — AI가 소프트웨어를 이해하기 전에 문서를 먼저 읽는 이유

"수십 년 동안 소스 코드(Source code)는 궁극적인 진실의 원천이었습니다. AI 엔지니어링(AI Engineering) 시대에는 문서화(Documentation)가 소스 코드에 의미를 부여하는 운영 매뉴얼이 되고 있습니다."

우리는 코드가 진실이라고 배웠다

소프트웨어 엔지니어링(Software engineering)의 가장 오래된 원칙 중 하나는 다음과 같습니다:

"소스 코드(Source code)는 궁극적인 진실의 원천이다."

이는 일리가 있습니다.

코드는 소프트웨어가 실제로 무엇을 하는지를 정의합니다.

문서화(Documentation)는 시대에 뒤처질 수 있습니다.

다이어그램(Diagrams)은 부정확할 수 있습니다.

사양(Specifications)은 구현(Implementation)에서 벗어날 수 있습니다.

충돌이 발생하면 엔지니어들은 코드를 신뢰합니다.

그 원칙은 우리 산업에 큰 도움이 되어 왔습니다.

하지만 AI는 새로운 관점을 도입합니다.

소스 코드가 덜 중요해졌기 때문이 아닙니다.

소스 코드만으로는 더 이상 충분하지 않기 때문입니다.

AI는 코드를 읽을 수 있다. 하지만 의도를 이해할 수 있는가?

현대의 AI 모델들은 소스 코드를 읽는 데 놀라울 정도로 뛰어납니다.

함수(Functions)를 설명할 수 있습니다.

모듈(Modules)을 리팩터링(Refactor)할 수 있습니다.

버그(Bugs)를 찾을 수 있습니다.

테스트(Tests)를 생성할 수 있습니다.

최적화(Optimizations)를 제안할 수 있습니다.

하지만 그들은 종종 훨씬 더 어려운 질문 앞에서 어려움을 겪습니다:

이 시스템은 왜 존재하는가?

소스 코드는 AI에게 소프트웨어가 **무엇(what)**을 하는지 알려줍니다.

하지만 다음과 같은 사항은 거의 설명하지 않습니다:

• 왜 이 아키텍처(Architecture)가 선택되었는가.
• 왜 다른 데이터베이스 대신 특정 데이터베이스가 선택되었는가.
• 왜 특정 트레이드오프(Trade-off)가 수용되었는가.
• 왜 특정 모듈이 다른 모듈에 절대 의존해서는 안 되는가.
• 왜 겉보기에 비효율적인 구현이 의도적으로 유지되고 있는가.

의도(Intent)는 코드에 인코딩되는 경우가 드뭅니다.

의도는 다른 곳에 존재합니다.

문서화는 엔지니어링 의도를 포착한다

좋은 문서화(Documentation)는 단순한 지침 그 이상입니다.

그것은 엔지니어링 지식(Engineering knowledge)을 포착합니다.

성숙한 엔지니어링 팀이 유지 관리하는 문서의 종류를 생각해 보십시오:

• 아키텍처 결정 기록 (Architecture Decision Records, ADRs)
• 시스템 아키텍처 (System architecture)
• 도메인 모델 (Domain models)
• API 사양 (API specifications)
• 보안 가이드라인 (Security guidelines)
• 코딩 표준 (Coding standards)
• 배포 절차 (Deployment procedures)
• 운영 런북 (Operational runbooks)
• 설계 원칙 (Design principles)
• 엔지니어링 헌법 (Engineering constitutions)

이러한 문서들은 종합적으로 엔지니어가 무엇을 만드는지 (what engineers build) 뿐만 아니라, **어떻게 생각하는지 (how engineers think)**를 설명합니다.

AI가 소프트웨어 개발에 참여할 때, 이러한 차이는 점점 더 중요해집니다.

AI는 더 많은 토큰이 필요한 것이 아니라, 더 나은 지식이 필요합니다.

복잡한 프로젝트에 대한 흔한 대응 방식은 더 긴 프롬프트 (prompts)를 제공하는 것입니다.

결국, 프롬프트에는 다음과 같은 내용들이 포함되기 시작합니다:

• 아키텍처 요약 (Architecture summaries)
• 코딩 컨벤션 (Coding conventions)
• 배포 지침 (Deployment instructions)
• 보안 규칙 (Security rules)
• 테스트 요구사항 (Testing requirements)

이 시점에 흥미로운 일이 발생합니다.

프롬프트가 문서화 (documentation)를 모방하기 시작한 것입니다.

더 큰 프롬프트를 작성하는 대신, AI가 일관되게 참조할 수 있는 엔지니어링 문서를 개선해야 할지도 모릅니다.

잘 구조화된 문서화는 끊임없이 길어지는 대화보다 훨씬 더 잘 확장(scale)됩니다.

문서화는 실행 가능한 지식이 되고 있습니다

전통적으로 문서화는 인간을 위해 작성되었습니다.

엔지니어들은 가끔 이를 읽었습니다.

새로운 팀원들은 온보딩 (onboarding) 과정 중에 이를 참고했습니다.

몇 달이 지나면, 그 내용의 상당수는 잊혀지곤 했습니다.

AI는 이러한 역학 관계를 변화시킵니다.

AI 에이전트 (AI agent)는 엔지니어링 문서를 지속적으로 참조할 수 있습니다.

모든 작업에서.

모든 리뷰에서.

모든 설계 제안에서.

모든 구현에서.

문서화는 더 이상 수동적이지 않습니다.

그것은 능동적인 엔지니어링 인프라 (engineering infrastructure)가 됩니다.

엔지니어링 스택의 새로운 레이어

두 개의 소프트웨어 프로젝트를 가정해 봅시다.

프로젝트 A

저장소(repository)에는 다음이 포함되어 있습니다:

• 소스 코드 (Source code)
• README
• 몇 개의 주석 (comments)

AI는 그 외의 모든 것을 추론해야 합니다.

프로젝트 B

저장소에는 다음이 포함되어 있습니다:

• 참조 아키텍처 (Reference Architecture)
• 엔지니어링 헌법 (Engineering Constitution)
• 문서화 표준 (Documentation Standards)
• 아키텍처 결정 기록 (Architecture Decision Records)
• 보안 정책 (Security Policies)
• 워크플로우 정의 (Workflow Definitions)
• 컨텍스트 레지스트리 (Context Registry)
• 도메인 용어집 (Domain Glossary)

이제 AI는 추측이 아닌 엔지니어링 컨텍스트 (engineering context)와 함께 모든 작업을 시작합니다.

그 차이는 엄청납니다.

지능은 동일할지 모릅니다.

하지만 엔지니어링 환경은 그렇지 않습니다.

소스 코드는 구현을 설명합니다

문서화는 결정을 설명합니다

다음과 같은 함수를 생각해 보세요:

func ProcessPayment() {}

구현 자체는 기술적으로 정확할 수 있습니다.

하지만 코드는 다음과 같은 질문에 답할 수 없습니다:

• 왜 결제는 비동기(asynchronously)로 처리되는가?
• 왜 멱등성 (idempotency)이 요구되는가?
• 왜 직접 실행보다 큐 (queue)를 선호하는가?
• 왜 재시도 (retry) 로직은 3회로 제한되는가?
• 왜 이 서비스는 고객 데이터에 직접 접근해서는 안 되는가?

이러한 결정들은 엔지니어링 지식입니다.

이러한 지식이 없다면, AI는 시스템의 설계 원칙을 의도치 않게 위반하면서 코드를 수정할 수 있습니다.

문서화는 살아있는 엔지니어링 자산이다

문서화는 한 번 작성하고 잊혀지는 프로젝트 산출물 (artifact)로 취급되어서는 안 됩니다.

대신, 소프트웨어와 함께 진화해야 합니다.

모든 아키텍처 결정 (architectural decision).

모든 새로운 정책 (policy).

모든 워크플로우 개선.

모든 엔지니어링 표준 (engineering standard).

이러한 변화들은 프로젝트의 공유 지식의 일부가 되어야 합니다.

AI는 인간 엔지니어에게 유익한 것과 동일한 '살아있는 문서화'로부터 이득을 얻습니다.

왜 문서화가 NAEOS의 중심에 있는가

NAEOS의 근간이 되는 아이디어 중 하나는 문서화가 사후 고려 사항이 아니라는 점입니다.

문서화는 런타임 환경 (runtime environment)의 일부입니다.

참조 아키텍처 (Reference Architectures)는 시스템의 경계를 정의합니다.

엔지니어링 헌법 (Engineering Constitutions)은 타협할 수 없는 원칙을 정의합니다.

정책 (Policies)은 조직의 규칙을 정의합니다.

표준 (Standards)은 일관성을 정의합니다.

의사결정 기록 (Decision Records)은 역사적 맥락을 보존합니다.

이들이 모여 AI가 추측이 아닌 명확성을 바탕으로 작동하는 엔지니어링 환경을 조성합니다.

목표는 인간의 판단을 대체하는 것이 아닙니다.

목표는 인간과 AI 모두가 동일한 엔지니어링 지식에 접근할 수 있도록 하는 것입니다.

문서화는 인프라가 되고 있다

인프라 (Infrastructure)는 모든 시스템이 의존하는 것입니다.

데이터베이스는 인프라입니다.

네트워킹은 인프라입니다.

ID 서비스 (Identity services)는 인프라입니다.

AI 시대에 문서화도 그 범주에 합류하고 있습니다.

문서가 코드를 실행하기 때문이 아니라,

하지만 문서가 코드가 설계되고, 리뷰되고, 생성되고, 유지보수되는 방식을 결정하기 때문입니다.

엔지니어링 지식(Engineering knowledge)이 운영 가능한(operational) 형태가 되고 있습니다.

향후 전망

문서화는 중요한 질문에 답합니다:

AI가 무엇을 알아야 하는가?

다음 질문 또한 그만큼 중요합니다:

어떤 지식이 가장 중요한가?

다음 기사에서는 왜 **컨텍스트 (context)**가 모델 크기, 벤치마크 점수, 또는 파라미터 수보다 AI의 품질에 종종 더 큰 영향을 미치는지 탐구할 것입니다.

소프트웨어 엔지니어링에서는 적절한 컨텍스트가 가공되지 않은 지능(raw intelligence)보다 일관되게 더 나은 성능을 발휘하기 때문입니다.

토론

현재 진행 중인 프로젝트를 위해 단 한 가지 유형의 엔지니어링 문서화를 개선할 수 있다면, 무엇을 선택하시겠습니까?

• 아키텍처 문서 (Architecture documentation)
• ADRs (Architecture Decision Records)
• 코딩 표준 (Coding standards)
• API 문서 (API documentation)
• 보안 정책 (Security policies)
• 배포 가이드 (Deployment guides)
• 그 외 다른 것?

여러분의 팀에 가장 큰 가치를 전달했던 것이 무엇인지 듣고 싶습니다.