AI는 왜 자꾸 Root에 파일을 만들까: AI 시대의 시니어 개발자가 가져야 할 새로운 철학

지난 며칠 동안 AI와 함께 몰입해서 개발하며 뼈아픈 깨달음을 하나 얻었습니다. AI는 코드를 작성하는 데에는 천재적이지만, 프로젝트를 관리하는 데에는 아직 미숙하다는 사실입니다.

처음 AI 도구들을 도입했을 때는 생산성이 폭발할 것이라는 기대에 부풀어 있었습니다. 실제로 초기 속도는 놀라웠습니다. 기능을 구현하는 속도가 기존 대비 몇 배는 빨라졌으니까요. 하지만 프로젝트의 규모가 일정 수준을 넘어서자, 마치 잘 닦인 고속도로에서 갑자기 비포장도로로 진입한 것처럼 프로젝트가 삐걱거리기 시작했습니다.

처음에는 사소한 문제처럼 보였습니다

가장 먼저 맞닥뜨린 문제는 AI가 자꾸만 Root 디렉토리에 파일을 생성한다는 점이었습니다. 분명히 src/components/, src/utils/와 같이 제가 정해둔 프로젝트 구조가 있음에도 말이죠.

repository-root/
├── App.jsx
├── Hero.jsx        // 왜 여기에?
├── Services.jsx    // 왜 여기에?
├── utils.js        // 끔찍한 혼종의 시작
├── data.js
├── config.js
└── something.js

시간이 지날수록 문제는 심화되었습니다. 어제는 pages 폴더를 기준으로 구조를 잡던 AI가, 오늘은 components를 고집하고, 내일은 features라는 생소한 개념을 가져와 구조를 흩뜨려 놓았습니다. 모델(Claude, GPT-4, Codex)을 바꿔봐도 상황은 비슷했습니다. 처음엔 AI가 멍청해서 그런 줄 알았습니다.

하지만 고민 끝에 내린 결론은 정반대였습니다.

문제는 AI가 아니라, 내가 프로젝트의 규칙을 단 한 번도 명확하게 정의해주지 않았다는 사실이었습니다.

AI는 ‘주니어’가 아니라 ‘초고속 외주 개발자’입니다

많은 이들이 AI를 주니어 개발자처럼 가르치려 듭니다. 하지만 제가 경험한 AI는 주니어보다는 ‘엄청나게 빠르지만, 프로젝트의 맥락은 전혀 모르는 외주 개발자’에 가깝습니다. 그들은 주어진 지시를 완벽하게 수행하지만, 프로젝트 전체를 관통하는 철학이나 아키텍처까지 스스로 추론하지는 않습니다.

예를 들어, 제가 운영 중인 ETERNOps 프로젝트는 Vite와 React 기반의 웹사이트입니다. AI에게 “서비스 소개 페이지를 만들어줘”라고 지시하면 훌륭한 결과물을 내놓습니다. 하지만 다음 작업에서 AI는 이전과는 전혀 다른 구조를 제안합니다. AI 입장에서는 ‘효율적이고 합리적인’ 선택일지 몰라도, 프로젝트 전체의 일관성 관점에서는 재앙입니다.

아키텍처를 정의하는 힘: ARCHITECTURE.md

결국 저는 ARCHITECTURE.md와 AGENTS.md라는 문서를 만들기 시작했습니다. 처음에는 단순한 지침이었지만, 점차 프로젝트를 지탱하는 헌법이 되었습니다.

AI는 수천 개의 학습 데이터 속에 있는 수많은 패턴을 가지고 있습니다. 지시가 없으면 자신의 학습 데이터 중 가장 보편적인 구조를 선택해버리죠. 저는 다음과 같이 금지 사항을 명시했습니다.

# FORBIDDEN_DIRECTORIES
- features (사용 금지)
- shared (사용 금지)
- services (사용 금지)
- api (사용 금지)
- state (사용 금지)

신기하게도 이 제약사항을 적용한 이후, AI는 더 이상 제 프로젝트 구조를 오염시키지 않았습니다. 이때 깨달았습니다. AI가 코드를 잘 짜게 만드는 법은 더 좋은 모델을 쓰는 것이 아니라, 제약 조건을 명확히 주는 것이라는 점을요.

‘괴물’이 된 App.jsx와 리팩토링의 덫

프로젝트가 커질수록 또 다른 난관이 찾아왔습니다. AI는 기능을 추가할 때마다 습관적으로 App.jsx에 코드를 덧붙였습니다. 100줄이 500줄이 되고, App.jsx가 프로젝트 전체를 삼키는 괴물이 되어갔습니다.

다급해진 제가 “App.jsx를 작게 분리해줘”라고 명령하자, AI는 프로젝트 전체를 뒤흔드는 대대적인 리팩토링을 감행했습니다. 그 결과는 참담했습니다. 사이트는 하얀 화면만 출력되었고, 테스트는 전멸했습니다.

AI에게 리팩토링은 기능 구현보다 훨씬 위험한 작업입니다. AI는 현재 동작하는 시스템보다 자신의 기준에서 ‘이상적인 구조’를 구현하는 것을 더 좋아하기 때문입니다. 이제 저는 프롬프트를 이렇게 바꿨습니다.

Root cause를 분석하라. 가장 작은 수정만 수행하라.

추가적인 구조 변경 및 리팩토링은 절대 금지한다.

TASKS.md: AI를 위한 기억 장치

마지막으로 도입한 TASKS.md는 단순한 TODO 리스트가 아닙니다. 이는 AI가 기억하지 못하는 ‘프로젝트의 역사’를 담은 기억장치입니다.

[x] complete ETERNOps rebranding
[x] implement SEO
[x] add analytics service
[ ] create service detail pages

AI는 대화가 길어지면 이전의 합의를 잊습니다. 이미 구현된 기능을 다시 구현하려 하거나, 어제 결정한 규칙을 깨기도 하죠. TASKS.md를 통해 프로젝트의 상태를 명확히 고정함으로써, 우리는 비로소 AI와의 끊임없는 ‘반복 학습’에서 해방될 수 있었습니다.

결론: AI 시대, 개발자의 본질

며칠간의 시행착오 끝에 내린 결론은 명확합니다.

많은 개발자들이 어떤 모델이 가장 뛰어난지 토론합니다. 하지만 실제 프로젝트를 운영해 본 결과, 모델의 성능보다 훨씬 중요한 것은 프로젝트의 규칙(Rule)입니다. 규칙이 명확한 프로젝트에서는 어떤 AI를 사용해도 준수한 결과가 나오지만, 규칙이 없는 프로젝트에서는 아무리 똑똑한 모델도 일관성을 잃은 쓰레기 코드를 양산할 뿐입니다.

예전에는 코드를 가장 잘 짜는 사람이 좋은 개발자라고 생각했습니다. 하지만 지금은 생각이 완전히 바뀌었습니다.

AI 시대의 좋은 개발자는 코드를 가장 잘 작성하는 사람이 아니라, AI가 흔들리지 않도록 프로젝트의 설계와 규칙을 견고하게 만드는 사람입니다.

AGENTS.md, ARCHITECTURE.md, TASKS.md. 이 문서들은 AI를 위한 가이드처럼 보이지만, 사실은 미래의 나를 위한 안전장치입니다.

향후 이 문제를 해결하기 위해서 프레임워크 별로 필요한 AI 문서를 Github에 정리해서 프로젝트 별로 복사해서 사용하고 있습니다.

이 문서의 이름은 FRAMEWORK.md 라고 AI는 이름을 지어주었고, 아래 프레임워크 별로 미리 제작해 두었습니다.

• ASTRO.md
• FASTAPI.md
• GOLANG.md
• NEXTJS.md
• REACT_VITE.md
• VANILLA.md

프로젝트가 시작되면 해당 문서를 FRAMEWORK.md로 바꾸어서 root 폴더에 복사합니다.

AI 모델은 매달 바뀌고 도구는 변하겠지만, 우리가 정의한 프로젝트의 규칙은 영원히 남습니다. 결국 그 규칙이 내 프로젝트를 지킵니다. 여러분의 프로젝트에는 지금 어떤 규칙이 적혀 있나요?