기업 IT 현장에서 가장 많이 제기되는 불만은 문서화 부족, 특히 레거시 시스템의 자체 개발 코드에 문서가 거의 없어 운영이 불필요하게 복잡해지고 위험 부담이 커진다는 점이다.

심각한 문서화 부족 현상이 왜 발생했는지에 대해서는 잘 논의되지 않는다. 그러나 불편한 진실은 책임의 상당 부분이 IT 관리자에게 있다는 점이다. 코드 작성이 진행될 당시 문서화를 관리·강제하지 않았던 관리자의 책임이 크다. 그때나 지금이나 코드 작업을 관리하는 관리자는 현시점에서 진행되는 개발 업무에 대해 충분하고 정확한 문서화를 요구하고 있는지 자문해 볼 필요가 있다.

문서화 문제가 시작되는 지점은 단순하다. 개발자는 코드 문서화를 싫어한다는 사실이며, 그 이유는 여러 가지다.

첫째, 문서화는 재미와는 정반대에 있다. 개발자는 보통 코딩의 창의적인 요소에서 즐거움을 느끼지만, 작업이 끝난 뒤에도 이전 프로젝트에 매달려 모든 세부 사항을 기록하고 설계 의도를 설명하는 일은 지루한 잡무로 여긴다. 선택권이 주어진다면 개발자는 기꺼이 그 일을 피하려 한다.

둘째, 자기 보호다. 개발자는 실행 가능한 문서가 없으면 관리자가 언젠가 다시 자신을 필요로 할 수 있다는 이유로 쉽게 해고나 구조조정을 하지 못한다는 사실을 잘 안다. 더 나아가 개발자가 회사를 떠난 경우에도 미비한 문서 때문에 문제가 발생하면 이를 해결하기 위해 해당 개발자를 고액 컨설턴트로 다시 불러야 할 가능성이 커진다. 반대로 세밀하게 문서화를 해 두면 이런 부수입 기회가 줄어든다.

이 오래된 문서화 문제는 생성형 AI 테스트 문제와 테스트 문제와 닮은 점이 있다. 바로 고위 관리자가 직원에게 이런 문제를 제기하는 방식에서 드러나는 자기 인식 부족이다.

개발자와 관리자가 함께 만든 문서화 공백

많은 CEO가 생성형 AI 도구를 도입해 인력을 줄이겠다, 특히 개발자 수를 줄이겠다고 공언한다. 그런데 아이러니하게도, 그런 말을 하는 CEO는 정작 자사 개발자에게 그 생성형 AI 시스템 테스트를 맡긴다. 이런 CEO의 발언은 다음과 같이 들린다고 해도 과언이 아니다.

“이 생성형 AI 시스템이 제대로 작동한다는 것을 입증할 수만 있다면, 우리는 수천 명의 기술 인력을 해고할 것이다. (기술 인력을 향해) 이제 이 시스템을 테스트해 달라. 이 시스템이 충분히 신뢰할 수 있는지를 판단하는 건 너희들의 일이다. 그 결과에 따라 내가 너희 전원을 해고할지 결정하겠다. 우리는 너희의 보고를 신뢰하겠다.”

IT 관리자도 여러 면에서 비슷한 일을 하고 있다. 바로 프로그래머에게 자신이 작성한 모든 코드에 대해 세부적이고 완전한 문서화를 요구하는 것이다. 다행히도 개발자 입장에서는 관리자가 이런 요청을 하는 경우가 드물고, 설령 요청하더라도 반드시 지키라고 강하게 요구하지는 않는다. 그 이유는 몇 가지가 있다.

개발자가 새로운 프로젝트로 빨리 넘어가고 싶어 하는 것만큼이나 관리자는 그보다 더 다급하다. 하나의 애플리케이션이나 코드 수정이 완료돼 이를 요청한 업무 부서 관리자의 승인을 받으면, IT 부서는 곧바로 해야 할 1만 9,999건의 업무 목록 중 다음 항목으로 넘어가고 싶어 한다.

관리자는 프로그래머가 이미 끝난 프로젝트에 대해 하루 이상을 들여 세부 문서화를 하는 것을 원하지 않는다. 바로 여기서 인식의 괴리가 생긴다. IT 관리자는 개발자가 곧바로 다음 과제로 넘어가고 문서화를 건너뛰도록 묵인하거나 오히려 부추긴다. 그런데도 그 관리자는 18년 전에 작성된 레거시 코드에 문서가 없다고 목소리를 높인다.

문서화가 부족한 이유는 18년 전 그 자리에 있던 관리자가 지금의 관리자와 똑같은 선택을 했기 때문이다.

AI 활용 가능성과 현실적 대안

그렇다면 이 문제를 어떻게 해결할 수 있을까? 몇 가지 방안이 있다.

먼저 인식해야 할 점은 이 문제가 사실상 서로 겹쳐 있는 3가지 별개의 문제라는 사실이다. 첫 번째 문제는 오래전에 작성된 코드로, 원 개발자가 이미 회사를 떠나 더 이상 존재하지 않는 경우다. 두 번째 문제는 비교적 최근에 작성된 코드로, 원 개발자가 여전히 회사에 남아 있는 경우다. 마지막 문제는 현재 개발자가 작성하고 있는 코드다.

여기서 하나 물어볼 필요가 있다. 생성형 AI 코딩 어시스턴트가 이 문제 해결에 도움이 될 수 있을까? 만약 개발자의 문제의식이 단순히 “재미없다. 하고 싶지 않다”에 그친다면, AI 도구가 상당한 차이를 만들어낼 수도 있다. 하지만 이 문제에는 개발자의 자기 보호 요인이 있다. 문제는 개발자가 문서화를 하고 싶지 않다는 데 그치지 않는다. 누구에 의해서든 문서가 작성되는 것 자체를 원하지 않는다.

분명히 말하자면, IT 관리자는 AI가 문서화를 대신해 주는 것을 전혀 문제 삼지 않을 것이다. 그렇게 되면 오히려 관리자의 가장 큰 우려가 사라진다. 관리자의 바람은 언제나 똑같다. 개발자가 빨리 다음 프로젝트로 넘어가는 것이다.

하지만 프로젝트를 완료한 이후에 생성형 AI를 적용해서 알고리즘이 코드 한 줄 한 줄에서 개발자의 의도를 추측하도록 하는 방식은 오히려 더 많은 문제를 일으킬 가능성이 크다. 유일한 방법은 AI 에이전트가 코딩 과정의 매 단계마다 개발자와 함께 작업하며 전체 과정을 이해하는 것이다.

이론적으로는 이런 방식이 문제를 해결할 수 있다. 하지만 잊지 말아야 한다. 개발자의 경제적 목표는 자신이 회사에 계속 필요한 존재로 남는 것, 다시 말해 문서화를 통해 스스로 일자리를 없애지 않는 데 있다. 그렇기 때문에 협조는 그리 열정적이지 않을 가능성이 크다.

여기서 다시 생성형 AI 이야기가 나온다. 오늘날의 AI 에이전트는 레거시 코드에서 문제가 발생하는 원인을 더 잘 파악하고, 이를 해결하는 방법을 제시할 수 있을까? 그리고 만약 그것이 가능하다면, 문서화의 필요성이 줄어들게 될까?

IDC의 리서치 매니저 아담 레즈닉은 문서화 문제는 기업 IT에서 끊임없는 고민거리라고 지적하며 “부실한 문서화는 레거시 시스템의 현대화를 어렵게 만들고, 신규 인력 온보딩, 보안 감사, 버그 해결, 유지보수 같은 과정도 훨씬 더 복잡하게 만든다”라고 말했다.

레즈닉은 이 문제를 IT 우선순위의 문제로 봤다. “기업은 촉박한 일정 속에서 새로운 기능을 제공하거나 긴급한 버그를 해결하는 데 높은 우선순위를 둔다. 개발자 역시 이런 목표를 향해 동기부여된다. 승진이나 보상은 문서화가 아니라 산출물에 따라 결정되기 때문”이라는 이야기다.

그러나 문서화 저항에는 단순한 업무 기피를 넘어 심리적 요인이 깊게 작용한다.

레즈닉은 “많은 개발자가 문서화는 지루하고 불필요하다고 여긴다. 제대로 문서화하려면 시간이 많이 들고, 스스로 좋은 코드를 작성했다고 생각하는 개발자는 누구든 그 코드를 보면 큰 어려움 없이 이해할 수 있어야 한다고 믿는다. 문서화가 불필요하다는 주장이 정당하다고 말하는 건 아니다. 하지만 개발자가 문서화를 지루하다고 여긴다면, 그것은 지루한 일이다. 야심 있는 개발자 가운데 문서화를 우선순위에 올려두는 경우는 극히 드물다”라고 설명했다.

이 문제는 코드가 오래될수록 더욱 심각해진다.

레즈닉은 “시스템은 빠르게 진화하는 반면, 문서화는 거의 뒤처진다. 레거시 문서는 여러 사이클 동안 방치돼 구식이 된 경우가 많아 이를 최신 상태로 업데이트하려면 많은 시간이 걸린다. 하지만 기업이 이를 따라잡을 만큼 자원을 투입할 가능성은 낮다. 개발자는 새로운 기능을 제공하고 버그를 수정해야 한다는 압박을 받으며, 시간을 문서화에 많이 쓰도록 동기부여되는 경우는 거의 없다”라고 강조했다.

레즈닉은 “IT의 거의 모든 문제와 마찬가지로 돈을 투입하면 해결될 수 있다. 개발자가 문서화를 하도록 인센티브를 제공하라. 문서화에 두둑한 보너스를 연계하면 더 많은 문서화를 얻게 될 것”이라고 덧붙였다.
dl-itworldkorea@foundryco.com