AI가 이해하기 쉬운 구조가 가장 좋은 아키텍처다

개발의 기준은 계속 바뀌어 왔다

소프트웨어 개발은 지금까지 수많은 변화를 거쳤다.

절차지향에서 객체지향으로, 객체지향에서 프레임워크 중심 개발로, 그리고 클라우드와 DevOps를 지나 지금은 AI가 개발 과정에 자연스럽게 참여하는 시대가 되었다.

과거에는 생산성을 높이기 위해 온갖 프레임워크와 설계 패턴이 등장했다. 프레임워크를 얼마나 깊이 이해하고 다루는지가 곧 개발자의 경쟁력이었다.

이제 질문이 달라졌다

AI가 개발의 핵심 도구가 된 지금은 다른 질문을 해야 한다.

AI는 이 프로젝트를 얼마나 쉽게 이해할 수 있는가.

앞으로의 생산성은 사람이 코드를 얼마나 잘 쓰는지가 아니라, AI가 얼마나 빠르고 정확하게 프로젝트를 파악하고 고칠 수 있는지에 따라 갈릴 가능성이 크다.

AI는 큰 그림보다 좁은 맥락에서 판단한다

사람은 프로젝트 전체를 훑어보면서 구조를 이해한다.

AI는 다르다. 지금 작업하는 코드와 그 주변 맥락을 기준으로 판단한다.

기능 하나를 고치기 위해 수십 개의 파일을 뒤져야 하거나 여러 계층을 계속 오가야 한다면, AI는 그만큼 많은 토큰을 쓰고 그만큼 많은 문맥을 기억해야 한다. 수정 정확도는 떨어지고, 예상하지 못한 부작용이 생길 확률은 올라간다.

반대로 하나의 기능이 독립적으로 서 있으면 AI는 필요한 부분만 이해하면 된다.

AI에게 좋은 구조는 정교한 구조가 아니라 명확한 구조다.

하나의 단위는 하나의 역할만 한다

객체지향에는 오래전부터 단일 책임 원칙이라는 개념이 있었다. AI 시대에는 이 원칙을 좀 더 실용적으로 적용해야 한다.

여기서 말하는 단위는 파일일 수도 있고, 클래스일 수도 있고, 함수나 모듈, API Endpoint일 수도 있다.

중요한 건 형태가 아니라 책임이다. 하나의 단위가 하나의 일만 할수록 AI는 빠르고 정확하게 이해한다.

Endpoint 하나가 기능 하나를 담당해야 한다

주문 시스템을 예로 들어보자.

좋지 않은 구조는 Endpoint 하나에서 주문 생성, 재고 차감, 포인트 지급, 문자 발송, 이메일 발송, 로그 저장까지 전부 처리하는 것이다. 이러면 AI는 그 안에 얽힌 비즈니스 흐름 전체를 이해해야 한다.

반면 역할이 이렇게 나뉘어 있다면 이야기가 달라진다.

POST /order/create
POST /stock/decrease
POST /point/reward
POST /notification/send
POST /log/write

각 Endpoint는 책임이 하나뿐이다. AI는 필요한 Endpoint만 손대면 되고, 다른 기능을 건드릴 위험도 크게 줄어든다.

이름 자체가 문서가 된다

AI는 프로젝트의 역사나 개발자의 의도를 추측하지 않는다. 대신 이름에서 많은 정보를 얻는다.

/api/member/login
/api/member/register
/api/order/create
/api/order/cancel
/api/shipping/request
/api/shipping/complete

설명이 없어도 무엇을 하는지 바로 읽힌다.

좋은 이름은 사람에게도 좋지만 AI에게는 더 중요하다. 이름이 곧 문서이기 때문이다.

함수 하나도 행동 하나만 해야 한다

긴 함수는 사람도 읽기 어렵지만 AI에게는 더 어렵다.

주문 생성과 재고 수정, 포인트 지급, 문자 발송, 이메일 발송, 로그 저장이 한 함수 안에 다 들어 있으면 AI는 그 함수 전체를 이해해야 한다.

createOrder(), decreaseStock(), rewardPoint(), sendSMS(), writeLog()처럼 나뉘어 있으면 필요한 함수 하나만 고치면 된다. 수정 범위가 줄고 정확도가 올라간다.

숨겨진 상태가 가장 어렵다

AI가 특히 어려워하는 건 숨겨진 상태다.

어디선가 바뀌는 전역 변수, 여러 계층을 거쳐 흘러오는 값, 눈에 보이지 않는 부수효과. 이런 것들이 AI의 추론을 무너뜨린다.

입력은 명확하게, 출력은 명확하게, 상태는 최소한으로.

이런 구조는 사람도 이해하기 쉽고 AI도 안정적으로 고칠 수 있다.

작은 모듈의 조합이 강하다

큰 서비스 하나를 만드는 게 아니라 작은 기능을 조립해 서비스를 만드는 방식이 AI와 가장 잘 맞는다.

/member    login, logout, register, profile
/order     create, update, cancel, complete
/product   create, update, delete, search
/shipping  request, tracking, complete

각 기능은 독립적으로 존재한다. 필요한 것만 호출하고 필요한 것만 고치면 된다. AI가 프로젝트 전체를 다시 이해할 필요가 없다.

이 기준으로 보면 무거운 프레임워크는 불리하다

여기까지의 기준을 그대로 들고 요즘의 프론트엔드 스택을 들여다보면 불편한 결론이 나온다.

리액트로 대표되는 무거운 프레임워크는 사람의 생산성을 올리기 위해 만들어졌지만, AI가 이해하기 좋은 구조와는 방향이 어긋나는 지점이 많다.

기능 하나를 고치는 데 파일 여섯 개를 연다

버튼 하나의 동작을 바꾸려고 컴포넌트 파일을 열고, 훅을 열고, 전역 스토어를 열고, 타입 정의를 열고, 라우터 설정을 열고, 빌드 설정까지 확인하는 일이 드물지 않다.

사람은 그 구조에 익숙해지면 머릿속 지도로 따라간다. AI에게는 그 지도가 없다. 매번 파일을 뒤져서 맥락을 다시 쌓아야 한다.

기능 하나가 파일 하나에 담기지 않는 구조는, 그 자체로 AI에게 비용이다.

프레임워크의 관례는 코드에 적혀 있지 않다

무거운 프레임워크일수록 코드에 안 적혀 있는 규칙이 많다.

이 파일이 왜 이 위치에 있어야 하는지, 이 이름이 왜 이렇게 붙어야 하는지, 어떤 함수가 언제 자동으로 호출되는지가 코드가 아니라 프레임워크의 약속에 들어 있다.

이건 결국 앞에서 말한 숨겨진 상태와 같은 문제다. 눈에 보이는 코드만으로 동작을 설명할 수 없는 구조다.

상태가 코드가 아니라 생명주기에 숨는다

값이 언제 바뀌는지가 함수 호출 순서가 아니라 렌더링 주기와 의존성 배열에 달려 있으면, 코드를 읽는 것만으로 흐름을 따라가기 어렵다.

사람도 여기서 자주 헷갈린다. 무한 렌더링이나 한 박자 늦은 값 같은 문제는 다들 한 번씩 겪는다.

AI는 그 헷갈림을 그대로 물려받는다. 그리고 사람과 달리 실행해보면서 감으로 눈치채지 못한다.

버전이 바뀌면 아는 것과 실제가 어긋난다

무거운 프레임워크는 관례가 자주 바뀐다.

AI가 학습한 시점의 관례와 지금 프로젝트의 관례가 다르면, 그럴듯한데 동작하지 않는 코드가 나온다. 문법 오류라면 차라리 낫다. 예전 방식으로 멀쩡히 돌아가는 코드가 섞이는 쪽이 더 골치 아프다.

반면 요청을 받고 응답을 돌려주는 단순한 구조는 몇 년이 지나도 크게 변하지 않는다.

빌드가 두꺼우면 확인 주기가 길어진다

고치고 확인하는 데 걸리는 시간은 AI와 함께 일할 때 특히 중요하다.

AI가 코드를 만들고 사람이 확인하고 다시 고치는 사이클이 짧을수록 결과가 좋아진다. 빌드 체인이 두꺼워서 한 번 확인하는 데 시간이 걸리면 그 사이클 자체가 느려진다.

리액트가 나쁘다는 말은 아니다

정말 복잡한 화면 상태를 다뤄야 하는 서비스라면 그만한 도구가 필요하다. 그런 자리에서는 리액트가 여전히 최선이다.

문제는 필요하지 않은데 기본값으로 고르는 태도다.

관리자 화면 몇 개, 목록과 상세, 폼 몇 개면 끝나는 서비스에 프레임워크 한 벌을 통째로 얹고 시작하는 경우가 많다. 그렇게 얹은 무게는 개발 내내 같이 다닌다.

기술을 고를 때 이 질문 하나를 더 붙여보면 된다. 이 선택이 나중에 코드를 고칠 사람과 AI에게 맥락을 몇 개나 더 요구하는가.

코드는 설명보다 명확해야 한다

좋은 코드는 긴 주석으로 설명하는 코드가 아니다. 주석 없이도 읽히는 코드다.

AI 역시 주석보다 실제 코드 구조를 더 신뢰한다.

조건문이 단순하고, 역할이 나뉘어 있고, 이름만 봐도 의도가 보이는 구조가 가장 좋은 구조다.

이제 코드의 독자는 사람만이 아니다

우리는 지금까지 사람을 위한 코드를 써왔다.

하지만 앞으로의 개발은 사람 혼자 하지 않는다. AI가 초안을 만들고, 리팩터링하고, 테스트를 쓰고, 버그를 고치는 시대가 이미 시작됐다.

그렇다면 좋은 코드의 기준도 달라져야 한다. 사람이 이해하기 쉬운 것만으로는 부족하다.

언어나 프레임워크의 문제가 아니다

정리하면 원칙은 단순하다.

하나의 단위는 하나의 책임만 가진다. Endpoint 하나는 기능 하나만, 함수 하나는 행동 하나만 한다. 이름만 봐도 역할이 보여야 하고, 모듈 사이의 의존성과 숨겨진 상태는 최소로 줄인다. 필요한 부분만 읽어도 고칠 수 있게 설계한다.

이 원칙은 특정 언어나 프레임워크에 묶이지 않는다. Java든 C#이든 Go, Python, Rust, JavaScript, PHP든 똑같이 적용된다.

결국 남는 건 단순함이다

AI는 앞으로 더 똑똑해질 것이다. 그래도 복잡한 구조를 좋아하지는 않을 것이다.

사람도 마찬가지다. 복잡한 시스템보다 단순하고 명확한 시스템이 유지보수가 쉽고 오류가 적고 확장도 빠르다.

무거운 프레임워크를 기본값으로 고르던 습관도 결국 여기서 다시 검토하게 된다. 도구가 주는 편의보다, 그 도구가 감춰버리는 맥락의 값이 더 커졌기 때문이다.

앞으로의 소프트웨어 개발은 코드를 쓰는 일이 아니라, 사람과 AI가 함께 개발할 환경을 설계하는 일이 될 것이다.

좋은 아키텍처는 더 이상 사람만을 위한 구조가 아니다. 둘 다 이해하기 쉬운 구조가 가장 좋은 아키텍처다.

AI 시대의 개발자는 코드를 많이 쓰는 사람이 아니라, AI가 제 성능을 낼 수 있는 환경을 만들어두는 사람이다.