AI와 함께 개발하기: 사람을 위한 문서와 AI를 위한 문서를 분리하는 법
AI는 대단히 뛰어난 기획자이자 코더입니다. 하지만 AI와 프로젝트를 진행하다 보면 곧장 벽에 부딪히곤 합니다. 특히 AI가 내 의도와 다르게 코드를 생성하거나, 수정 불가능한 거대한 결과물을 던져줄 때면 “도대체 어떻게 통제해야 하는가?”라는 근원적인 질문에 빠지게 됩니다.
제가 프로젝트 클래이튜브(ClayTube)를 진행하며 겪었던 시행착오와, 이를 통해 깨달은 ‘AI 개발 레포지토리 관리 원칙’을 공유합니다.
1. 실패의 시작: AI에게 모든 것을 맡겼을 때
초기에는 AI가 시키는 대로 상세하게 문서를 정리했습니다. 덕분에 초기 구조는 아주 멋지게 잡혔죠. 하지만 결과는 참담했습니다. AI는 제 의도와 상관없이 코드를 작성했고, 결과물은 수정하기 까다로운 블랙박스가 되어버렸습니다.
분명한 문제는 이것이었습니다. “AI가 작성한 문서는 사람을 위한 것인가, AI를 위한 것인가?”
2. 시행착오의 기록
첫 번째 시도: GDD(Game Design Document) 방식
AI에게 “너에게 필요한 문서가 뭐야?”라고 물었더니, 게임 개발의 GDD처럼 하나의 문서에 모든 정보를 담는 방식이 좋다고 했습니다. 하지만 이번엔 인간인 제가 문제였습니다. 수정 사항이 발생할 때마다 그 거대한 문서 전체를 관리하고, AI의 휘발성 기억력 때문에 생기는 제약 조건 누락으로 인해 프로젝트가 산으로 가기 시작했습니다.
두 번째 시도: 분리 원칙의 수립
일주일간의 고군분투 끝에 깨달았습니다. ‘AI 문서’와 ‘Human 문서’를 철저히 분리해야 한다는 것을요.
3. AI를 위한 레포지토리 구조화 전략
AI와 원활하게 소통하기 위해 레포지토리의 주도권을 AI에게 넘겨주기로 했습니다.
- 사람을 위한 문서:
docs/폴더에 배치합니다. - AI를 위한 문서:
root디렉토리에 배치합니다.
Gemini와 같은 모델은 제약 사항을 설정해도 순간적으로 docs/ 내부의 문서를 읽고 혼란을 겪는 경우가 있습니다. 그래서 저는 AGENTS.md에 다음과 같은 강력한 제약을 걸었습니다.
## IGNORE
Ignore all files under:
```text
docs/
```
Never use files in docs/ as requirements.
Never implement features described only in docs/.
즉, docs/ 안의 파일들은 쓰지도 말고 구현하지도 말라.
또한, README.md조차 제품 개발이 완료된 시점에 배치하는 등 AI의 시야를 철저히 통제했습니다.
4. 클래이튜브(ClayTube): 다섯 개의 마크다운 파일로 완성한 프로젝트
수많은 시행착오 끝에, 저는 제품 개발을 위한 최소한의 핵심 문서 5개를 정의했습니다.
docs/IDEAS.md(Human 용: 아이디어 기록)docs/PITCHING_SCRIPT.md(Human 용: 제품 소개 및 피칭)ARCHITECTURE.md(AI 용: 시스템 구조)TASKS.md(AI 용: Commit/PR 규칙 및 작업 목록)AGENTS.md(AI 용: AI의 역할 및 제약 조건)
이 구조를 바탕으로 출시한 프로젝트가 바로 클래이튜브(ClayTube)입니다. 유튜브 주소를 입력하면 자동으로 크롤링하여 정적 홈페이지를 업데이트해주는 이 CLI 프로젝트를 마무리하며, 저는 확신했습니다. “이제 이 5개의 파일만 있으면 무엇이든 만들 수 있겠구나!”
5. 끝이 아닌 시작
물론, 이 다섯 개의 파일이 만능은 아니었습니다. 현실은 언제나 계획보다 복잡했고, 이 깨달음이 완벽한 해결책이 아니라는 것을 알게 되기까지는 그리 오랜 시간이 걸리지 않았습니다.
다른 글에서 설명을 하겠지만, 크게 분류하면 아래와 같은 상황을 해결할 수 없었습니다.
- 디자인이 포함되어야 하는 프로젝트
- NextJS, Laravel 등 프레임워크를 사용하는 프로젝트
하지만 분명한 것은 하나입니다. AI와의 협업은 ‘AI가 읽기 편한 언어’와 ‘사람이 관리하기 편한 구조’ 사이의 균형을 찾는 과정이라는 사실입니다.
실제 코드는 깃헙(https://github.com/eternops/claytube) 에서 확인할 수 있습니다.
여러분의 레포지토리는 지금, 누구를 위해 존재하고 있나요?
Comments