AI 에이전트와 120만 줄 코드베이스를 8개월간 만들며 정착시킨 방법 (그누보드7)
안녕하세요. 저는 그누보드7 개발팀에서 일하고 있습니다.
최근 저희가 8개월간 개발한 결과물을 오픈소스로 공개했습니다. 결과물 소개도 겸하지만, 그보다는 "AI 에이전트와 함께 큰 코드베이스를 만들 때 기존 설계가 깨지지 않게 하는 방법"에 대해 저희가 정착시킨 방식을 공유하고, 개발자분들의 피드백을 듣고 싶어 글을 씁니다.
저희가 부딪힌 문제
AI 에이전트를 붙이면 기능을 만들어내는 속도 자체는 더 이상 문제가 아닙니다. 문제는 코드량이 많아질수록 에이전트가 기존 설계와 컨벤션을 조금씩 깨뜨린다는 것이었습니다. 사람이 매번 전부 리뷰하기에는 생산되는 코드량이 많았고, 그대로 두면 설계와 컨벤션이 조금씩 어긋나기 시작했습니다.
정착시킨 방식 두 가지
첫째는 규정집입니다. 언어/프레임워크 관례와 기능별 모범사례를 AGENTS.md에 문서화했고, 작업할 때마다 규정집도 함께 최신화하는 것을 원칙으로 했습니다. 지금은 약 60KB 분량입니다.
둘째는 그 규정집을 기준으로 작업 전후에 자동으로 도는 검증 절차입니다. 에이전트가 작업을 시작하기 전과 끝낸 후에 규정집 기준의 검증이 강제로 돌게 해서, 누가 에이전트를 붙여 작업해도 기존 설계를 깨뜨리기 어렵게 만들었습니다.
이 두 가지를 강제한 결과, 개발자 3명이 8개월(2025.11 ~ 2026.06) 동안 제품 코드 약 73만 줄, 테스트 코드 약 44만 줄 규모를 유지보수 가능한 상태로 끌고 갈 수 있었습니다.
다만, 코드 라인 수는 자랑이 아니라 저희가 감당해야 했던 부담을 수치로 표현한 것입니다. AI 시대에 코드량이 품질을 보장하지 않는다는 것도 잘 압니다. 이 코드가 슬롭인지 아닌지는 아래 저장소를 직접 확인해주시는 것이 정확할 것 같습니다.
https://github.com/gnuboard/g7
결과물 (그누보드7)
이 방식으로 만든 결과물이 그누보드7입니다. 네, 그 그누보드 맞습니다. 23년 된 CMS이고, 솔직히 이미지가 좋지 않다는 것도 압니다. include, require, extract()로 얽힌 레거시 코드들이 만든 이미지니까요.
그래서 레거시 코드를 한 줄도 가져가지 않고 처음부터 다시 만들었습니다. 스택은 Laravel + React이고, 백엔드는 MVC 위에 서비스, 레포지토리, 폼리퀘스트, 프로바이더 계층을 뒀습니다. 문제는 PHP가 아니라 PHP를 쓰던 방식이었다는 평소 갖고 있던 생각에 대한 검증이기도 했습니다.
라이선스는 MIT이고, AI 에이전트용 규정집(AGENTS.md)도 저장소에 있습니다.
논쟁이 있는 부분
솔직하게 말씀드리자면, 호불호가 갈리는 설계가 있습니다. 레이아웃을 JSON으로 정의하는 렌더링 방식입니다. HTML과 템플릿에 익숙한 분들께는 진입장벽이라는 지적이 있었고, HTML과 유사한 문법을 추가로 지원하는 방안을 두고 그누보드 커뮤니티에서 논의를 진행하기도 했습니다. 관련 스레드도 함께 남깁니다.
https://sir.kr/boards/free/1736774
설치 난이도와 매뉴얼 부족에 대한 지적도 받고 있습니다. 모두 인지하고 있고, 우선순위를 고민하며 개선해 가려고 합니다.
듣고 싶은 피드백
AGENTS.md와 작업 전후 검증 방식에 대해: 비슷한 방식을 쓰고 계신 분들의 경험이나, 더 나은 구조에 대한 의견
저장소를 보신 분들의 아키텍처/코드 품질 관점 피드백
JSON 레이아웃 방식에 대한 솔직한 의견
읽어주셔서 감사합니다. 어떤 이야기든 댓글로 편하게 남겨주시면 감사히 읽겠습니다.
