Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
작성자는 AI 에이전트가 제작한 업무 시스템을 인계받았으나, 문서 가독성 저하, 설계 원칙 미준수, 테스트 코드 부재 등 심각한 품질 문제에 직면했다. 이 경험은 AI의 빠른 코딩 능력과 별개로, 구조적 결함 및 유지보수 비용 관리가 후속 공정을 통해 반드시 검증되어야 함을 보여준다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기저는 평소 자체 개발용 신규 업무 시스템을 개발하고 있습니다. 그러던 중, 급하게 발생한 프로젝트로 인해 AI 에이전트만으로 제작된 시스템을 인계받는 기회가 있었습니다.
결론부터 말씀드리자면, 작동은 하지만 품질이 낮았고, 수정하는 데 상당한 어려움을 겪었습니다.
평소 저 역시 구현의 거의 모든 부분을 AI 에이전트에 맡기고 있기 때문에, AI 에이전트를 사용하는 것에 대해서는 긍정적입니다. 따라서 'AI로는 고품질의 결과물을 만들 수 없다'고 말하고 싶은 것은 아닙니다. 오히려 AI를 제대로 제어하지 못했을 때 어떤 일이 벌어지는지에 대한 사례로 보고 있습니다.
본문에서는 단순히 불평으로 끝내지 않고, 무엇이 문제였는지, 그리고 거기서 무엇을 배웠는지를 정리했습니다.
인계받은 시스템은 업무상 갑자기 필요해져 AI 에이전트를 중심으로 만들어진 것이었습니다. 이후 사정상 제가 수정 작업을 담당하게 되었습니다.
인계받은 PowerPoint 자료는 정리가 잘 되어 있었고, 진행 과정도 시간표대로였습니다. 솔직히 약간의 기대를 했습니다. 하지만 문서나 코드를 열어보니 그 기대가 무너졌습니다.
확인하고 발견한 문제점들은 다음과 같습니다.
문서는 모든 기능이 5,000줄 정도의 단일 파일에 몰려 있었습니다. 상세 사양이 없었기 때문에, 각각의 코드가 어떤 기능을 나타내는지 한눈에 이해하기 어려웠습니다.
함수명이나 변수명도 그대로 사용되어, PM 계층이나 사용자가 읽는 문서로서 기능하지 못했습니다. 어느 정도 코드를 읽을 수 있는 저조차 해독하는 데 고생했습니다...
동일한 로직 처리가 반복되는 등 설계 원칙이 지켜지지 않은 부분이 무수히 많았습니다.
모듈 분할이 부적절하여 의존 관계가 복잡하게 얽혀 있었습니다. 게다가 수정해야 할 부분이 예상보다 많이 늘어났습니다.
그 결과, 기능을 추가하기 전에 먼저 전체적인 리팩토링(Refactoring)이 필요한 상태였습니다.
테스트 코드가 단 한 줄도 없었습니다. 유닛 테스트나 E2E 테스트는 AI에게 맡기면 비교적 짧은 시간 안에 준비할 수 있기 때문에, 이 부분은 처음부터 갖춰야 했던 부분이었습니다.
테스트가 없었기 때문에, 하나를 고치면 다른 곳에 버그가 발생하는 상황이었습니다. 약간만 조작해도 오류가 발생하기도 했습니다.
자동 테스트가 없으니 당연히 완전 수동 인수 테스트(Acceptance Test)의 비중이 커지는데, 버전이 거듭될수록 확인 항목이 늘어나 검증 부담이 너무 커졌습니다.
UI에 AI 느낌이 남아있었고, 기호나 시각적인 요소로 충분한 안내도 긴 문장으로 작성되어 있었습니다. 예를 들어 편집할 수 없는 입력란은, 비록 입력 자체가 무효화되었지만 배경은 일반 상태 그대로였고, 대신 '여기서는 편집할 수 없습니다'와 같은 긴 설명문이 표시되고 있었습니다.
저는 설명서를 읽기 전에 일단 시도해 보는 타입이라, 입력이 가능하다고 착각하는 함정에 빠졌습니다.
PR(Pull Request) 리뷰가 존재하지 않아, 푸시하고 끝내는 운영 방식이었습니다. 또한 라이브러리가 오래된 상태로 업데이트나 취약점 진단 같은 흔적이 없었습니다. 지원 중인 최신 메이저 버전보다 10개 이상 뒤처진 것도 있었습니다.
단순히 대충 만든 것이 아니라, 구조적인 문제라고 느꼈습니다.
물론 저는 개발의 당사자로서 현장에 함께 있었던 것은 아닙니다. 아래 내용은 남아있는 코드, 문서, 이력에서 읽어낼 수 있는 범위 내에서의 추측입니다.
AI는 작동하는 코드를 빠르게 생성합니다. 하지만 테스트가 없는 리스크나 밀접하게 결합된 구조(Tight Coupling)가 초래하는 유지보수 비용은, 후속 공정을 경험하지 않으면 눈에 보이지 않습니다. 출력물의 결함에 알아차리지 못하기 때문에, 일단 작동하면 완성으로 착각해 버립니다.
게다가 AI 에이전트는 요청받은 태스크의 실행에 충실합니다. 개발자가 구현이 어떤 메커니즘으로 이루어졌는지 이해하지 못해도, 태스크를 계속 진행시켜 버립니다. 저희가 되물어보지 않는 한, AI 측에서 멈춰서 이해를 촉구해 주는 일도 없습니다. 따라서 스스로 강하게 의식하며 코드를 읽으러 가지 않으면 전체 그림을 파악할 수 없고, 어느새 블랙박스화되어 버립니다.
더 나아가, 'AI니까 빠를 거야', '작동만 하면 돼'라는 분위기가 있으면, 검증은 실제 기기 동작 확인이 통과하는 것으로 끝나기 쉽습니다. 품질 기준을 제시할 사람이 없다면, '테스트를 작성해 달라'고 부탁해도 커버리지나 설계의 기준까지 지시하기 어렵고, 완성된 결과물을 내용물로 평가하는 것도 힘들어집니다.
이러한 요인들이 겹치면서, 겉보기에는 완벽하지만 속은 빈 시스템이 만들어진 것이라고 생각합니다. 다만, 나쁜 점만 있었던 것은 아니었습니다.
특히 가독성이 나쁘더라도 지식이 축적되어 있어 사전에 결함이 발생할 만한 부분을 회피했던 사례가 있었고, 그러한 면에서는 매우 배울 점이 많았습니다.
제가 의식하는 것은 프롬프트의 기교에만 의존하지 않고, 개발 환경 자체에 가드레일(Guardrail)을 설치하는 것입니다. AI 에이전트 기반에서 도입하고 있는 몇 가지 시스템을 소개합니다.
문서 교정 스킬 사용하기: 가독성을 향상시키는 데 효과적인 문서 교정 스킬을 사용하도록 합니다.
설계 원칙 주입(Inputting Design Principles)시키기: 설계, 구현, 리뷰 시 기능 단위 분할이나 느슨한 결합(Loose Coupling)과 같은 설계 원칙을 사전에 제공하여 적절한 설계가 되도록 유도합니다.
구현 및 테스트 규칙을 스킬에 담아 구현하게 하기: 코딩 규약(Coding Convention)과 테스트 작성 방법을 스킬에 통합하고, 테스트를 먼저 작성한 후 구현하는 흐름으로 진행하도록 합니다.
코드 리뷰 규칙을 스킬에 담아 리뷰하게 하기: 리뷰 관점이나 기준을 스킬에 포함시키고, 구현한 것과는 별도의 에이전트가 리뷰하도록 합니다.
UI 규칙 주입(Inputting UI Rules)시키기: '문자보다 기호를 우선한다'와 같은 UI 개념을 사전에 제공하여 AI 느낌의 화면이 되는 것을 방지합니다.
개발 흐름 규칙 정의하기: PR 포맷이나 커밋 메시지의 형식을 정해 변경 경위를 나중에 추적할 수 있도록 합니다. 또한, 브랜치 전략(Branching Strategy)도 규칙으로 기재하고 있습니다.
AI 덕분에 작동하는 것은 누구나 만들 수 있는 시대가 되었고, '작동한다'는 것 자체의 가치는 하락했다고 느낍니다.
하지만 품질을 높이는 것의 가치는 아직 요구되고 있다고 생각합니다. 유지보수성(Maintainability), 보안(Security), UI/UX, 테스트, 아키텍처는 AI에게 맡긴다고 해서 보장되지 않습니다. 사람이 내용을 이해하고 판단해야 합니다.
AI를 방치하지 않고, 지식이 있는 사람이 자신의 지식을 축적한 AI 에이전트 기반을 구축하여 팀에서 사용할 수 있도록 하는 것. 이것이 품질을 유지하는 비결이라고 느낍니다.