진단: AI는 팀 코드베이스를 소리 없이 죽인다
5명의 개발자, 하나의 Git 레포, 공유 규칙 없이 자유롭게 쓰는 Cursor·Copilot·Cline. 한 달 뒤에 뭐가 남을까? dev.to에 올라온 'Context-as-Code' 아티클의 첫 문장이 정확하게 찌른다. "아키텍처에 영혼이 남아 있지 않을 것이다." 나는 이걸 '조용한 발산(Silent Divergence)'이라 부르기로 했다.
생성형 AI는 공개 GitHub 레포지토리에서 가장 많이 본 것을 뽑아낸다. 팀의 고유한 선택—성능 최적화 방식, 의존성 관리 원칙, 의도적으로 수용한 기술 부채—을 AI는 처음부터 모른다. 그래서 공백이 생기면 자동으로 "평균적인 GitHub"로 채운다. 커밋마다 팀의 전문성이 제네릭 코드로 교체되는 것이다.
맥락 해석: LLM 전쟁과 아키텍처 분열
더 심각한 문제는 LLM 전쟁이다. 개발자 A가 ChatGPT에 물어보면 패턴 X가 최선이라 하고, 개발자 B가 Copilot에 물어보면 패턴 Y가 표준이라 한다. 둘 다 "AI가 이렇게 하라고 했다"며 머지한다. PR 리뷰는 논쟁으로 끝나고, 아키텍처는 조현병적 상태가 된다.
AI는 세 가지 모순된 현실 사이에서 맹목적으로 항법한다. 글로벌 "베스트 프랙티스"(과잉 엔지니어링된 이론), 프롬프트를 입력한 개발자의 개인 습관(AI의 아첨 본능), 그리고 프로젝트의 실제 현실(팀의 아키텍처 결정, 비즈니스 제약). AI는 세 번째 현실을 전혀 모르기 때문에 자연스럽게 무시한다. 이게 문제의 구조다.
2026년 AI 개발 워크플로우 트렌드를 분석한 또 다른 글에서도 같은 흐름이 잡힌다. AI 에이전트는 이미 "다음 줄 제안"을 넘어 브랜치를 분석하고 서브태스크를 자율 구현하는 단계로 진입했다. 에이전트가 강력해질수록 "무엇을 만들지 아는 것"과 "어떻게 만들지 아는 것" 사이의 간극을 누가 채우느냐가 팀 품질의 핵심 변수가 된다.
시사점 ①: 코드 짜기 전에 비전을 문서화하라
Context-as-Code 방법론의 출발점은 도구가 아니다. 첫 git init 이전에 팀이 세 가지 질문에 솔직하게 답하는 문서를 만드는 것이다.
- 실제 제약은 무엇인가? (성능 목표, 예산, 규정 준수 요건)
- 의도적 선택과 그 이유는? ("Redux를 쓰지 않는다. 상태가 단순하고 가독성이 더 중요하기 때문에.")
- 이 프로젝트에서 명시적으로 금지된 것은? ("검토되지 않은 외부 의존성 없음. 우리는 3명짜리 팀이다.")
Confluence에 박힌 UML 다이어그램 말고, 짧고 솔직하고 살아있는 문서. AI는 빈 공간을 발견하면 통계로 채운다. 비전이 문서화되어 있으면 그걸 실행한다. 이 원칙 하나가 이후 모든 설계의 전제다.
시사점 ②: Context-as-Code—규칙을 버전 관리하라
비전 문서를 만들었다면 다음은 그것을 AI가 읽을 수 있는 형태로 레포에 박아 넣는 것이다. .cursorrules 파일은 많이들 알고 있지만, 이건 특정 에디터의 비표준 관행이다. 더 견고한 표준은 .agents/ 폴더와 AGENTS.md 파일이다. Google DeepMind의 Antigravity 같은 자율 에이전트 SDK들이 이 패턴을 채택하면서 사실상 표준이 되고 있다.
핵심은 파일 형식이 아니라 규칙을 Git으로 버전 관리하는 것이다. 이러면 두 가지가 해결된다.
첫째, 시간 여행(Context Time-Travel). 2년 전 브랜치를 체크아웃해서 v1 패치를 할 때, AI 에이전트도 그 시점의 아키텍처 규칙을 읽는다. 현재의 v3 패턴을 레거시 코드에 주입하지 않는다.
둘째, 주니어 온보딩 자동화. 공유 컨텍스트 파일이 없는 환경에서 주니어 개발자는 AI의 환각을 이해 없이 복붙한다. 엄격한 컨텍스트 파일이 있는 IDE에서는 AI가 실시간으로 "이 프로젝트에서는 이 구조와 네이밍 컨벤션을 써야 하는 이유"를 설명한다. 시니어 개발자의 시간을 독점하지 않고 팀 문화가 전파된다.
시사점 ③: AI-Ready 코드베이스—문서의 독자를 바꿔라
기술 문서의 주 독자가 바뀌었다. 인간만을 위해 쓰는 시대는 끝났다. AI가 자율적으로 인덱싱하고 이해할 수 있도록 문서를 설계해야 한다.
/docs/patterns 폴더에 이론 설명 대신 "Gold Standard" 코드 예시를 넣어라. AI는 긴 이론 설명보다 Few-Shot 예제에서 훨씬 잘 학습한다. 모놀리식 10,000토큰 시스템 프롬프트 대신, 접근성 감사가 필요할 때만 로드하는 .agents/skills/a11y-debugging/SKILL.md 같은 모듈형 스킬 파일로 쪼개라. MCP(Model Context Protocol) 생태계가 성숙해지면서 에이전트가 Figma 서버를 직접 쿼리해 디자인 토큰을 읽어오는 것도 이미 실현 가능한 수준이다.
그리고 AI를 코드 저자로만 쓰지 말고 Pre-Reviewer로 써라. ESLint가 형식을 잡는다면, AI Pre-Reviewer는 실질을 잡는다. "이 컴포넌트가 존재해야 하는 이유가 있나? 어제 동료가 만든 것과 중복되지 않나? 비즈니스 제약을 지키고 있나?" PR이 열리기 전에 이 질문들을 AI가 먼저 돌린다.
전망: 설계가 없으면 AI는 팀의 가장 빠른 적이다
2026년의 AI 에이전트는 강력하다. 브랜치를 만들면 Jira 티켓을 읽고, 구현 초안을 짜고, 테스트를 붙이고, PR을 올린다. 개발자는 리뷰하고 승인하는 역할로 이동한다. 이 흐름 자체는 막을 수도, 막을 필요도 없다.
하지만 Context-as-Code 없이 강력한 에이전트를 팀에 풀면, 빠르게 잘못된 방향으로 달리는 팀이 된다. 속도는 빨라지는데 아키텍처의 일관성은 빠르게 무너진다. AI가 "침묵 속에서" 팀의 코드베이스를 죽이는 가장 효율적인 시나리오다.
테크 리드로서 내일 당장 할 수 있는 일은 하나다. 첫 PR 전에, 첫 AI 프롬프트 전에, 팀의 실제 현실을 문서로 만들고 레포에 버전 관리하라. 도구를 도입하는 것과 그 도구에 팀의 DNA를 심는 것은 전혀 다른 작업이다. AI-First 워크플로우의 진짜 전제 조건은 더 좋은 AI 도구가 아니라, AI가 읽을 수 있는 팀의 설계 언어다.