AI 에이전트 문서가 개발팀을 혼란에 빠뜨리고 있다?

 

개발자들이 터미널에서 AI와 함께 코딩하는 시대가 왔어요. 하지만 모든 AI 에이전트가 서로 다른 설명서를 요구하면서 새로운 문제가 생겼어요. 똑같은 내용을 여러 번 써야 하는 '문서 중복의 늪'에 빠진 개발팀들의 이야기를 들어보세요.

AI 에이전트가 뭔가요?

AI 에이전트라고 하면 뭔가 복잡해 보이지만, 사실 생각보다 간단해요.

터미널에서 일하는 개발자들에게 "이 파일 좀 고쳐줘" 또는 "버그 찾아서 수정해줘"라고 말하면, AI가 알아서 파일을 읽고, 코드를 분석하고, 직접 수정까지 해주는 똑똑한 도우미예요.

예를 들어 이런 식으로 작동해요:

• 개발자: "searchtools.js 파일의 변경 이력을 정리해줘"
• AI 에이전트: Git 명령어를 실행하고, GitHub 이슈들을 찾아보고, 정보를 종합해서 요약 파일까지 만들어 줌

마치 옆에 앉은 숙련된 동료가 모든 걸 대신해주는 느낌이에요!

갑자기 왜 이렇게 인기가 많아졌나요?

2025년 현재, 세계 최대 AI 회사들이 모두 이 시장에 뛰어들었어요.

Anthropic의 Claude Code: 압도적 성장

Claude는 2025년 초 기준으로 전 세계 월 활성 사용자가 1,890만 명에 달하고, Anthropic는 연간 8억 5천만 달러의 수익을 기록하며 2025년에는 22억 달러를 목표로 하고 있다는 놀라운 성과를 보여주고 있어요.

Anthropic 내부 팀들은 디버깅부터 코드 지원까지 개발 워크플로우에서 Claude Code를 활용하고 있으며, 일반적으로 10~15분이 걸리던 수동 스캔 작업이 이제 3배 빠르게 해결된다는 실제 성과를 내고 있어요.

특히 Claude Code는 Pro 플랜에 포함되어 월 20달러(연간 결제 시)부터 시작해서, Max 플랜에서는 더 많은 기능을 제공하고 있어요.

Google의 Gemini CLI: 무료 전략으로 승부

Google은 완전히 다른 전략을 썼어요. Gemini CLI는 분당 60회 요청, 하루 1,000회 요청이라는 업계 최대 무료 사용량을 제공한다고 선언했어요.

Gemini CLI는 완전한 오픈소스(Apache 2.0)로 공개되어 개발자들이 코드를 검토하고 작동 방식을 이해할 수 있게 했고, 무료 라이선스로도 100만 토큰 컨텍스트 윈도우를 가진 강력한 Gemini 2.5 Pro에 접근할 수 있어요.

OpenAI의 Codex CLI: 후발 주자의 반격

OpenAI도 늦지 않게 합류했어요. 기본적으로 Codex는 빠른 추론을 위해 GPT-5를 타겟으로 하고, Plus, Pro, Team ChatGPT 계정 사용자들은 GPT-5를 포함한 최신 모델들을 플랜에 추가 비용 없이 접근할 수 있어요.

그런데 문제가 생겼어요

AI 에이전트들이 제대로 작동하려면 각자 특별한 설명서가 필요해요.

• Claude Code: 프로젝트 폴더에 "CLAUDE.md" 파일이 있어야 함
• Gemini CLI: "GEMINI.md" 파일을 찾음
• Codex CLI: "AGENTS.md" 파일을 원함

이 파일들에는 "우리 프로젝트는 이렇게 빌드해", "코딩할 때 이런 규칙 지켜", "문제 생기면 이렇게 해결해" 같은 내용을 적어야 해요.

문제는 이런 정보가 이미 팀 문서에 다 있다는 거예요! README 파일이나 기여자 가이드에 똑같은 내용이 이미 적혀 있는데, 또 다른 파일에 똑같은 걸 써야 한다니요.

실제 사례로 보면 이래요

CLAUDE.md는 Claude가 대화를 시작할 때 자동으로 컨텍스트에 가져오는 특별한 파일인데, 어떤 팀이 Sphinx라는 도구로 문서 사이트를 만든다고 해보세요.

Claude Code에게 "사이트 빌드해줘"라고 했더니, AI가 추측해서 bazel build //... 명령어를 실행했어요. 틀렸죠!

정확한 빌드 명령어를 CLAUDE.md 파일에 추가하니까, 그 다음부터는 제대로 빌드했어요.

하지만 생각해보세요. 이 정보는 이미 팀의 README나 개발자 가이드에 있을 가능성이 높아요. 같은 정보를 두 번 적어야 하는 거죠.

개발자들은 주로 어떻게 사용하고 있나요?

프로덕트 엔지니어링 팀은 Claude Code를 모든 프로그래밍 작업의 "첫 번째 정거장"이라고 부르고 있고, 실제 사용 패턴을 보면 흥미로운 결과가 나와요.

성장 마케팅 팀은 수백 개의 광고가 담긴 CSV 파일을 처리하고, 성과가 낮은 것들을 식별하며, 엄격한 글자 수 제한 내에서 새로운 변형을 생성하는 에이전트 워크플로우를 구축했어요. 또한 프레임을 식별하고 헤드라인과 설명을 바꿔가며 최대 100개의 광고 변형을 프로그래밍 방식으로 생성하는 Figma 플러그인도 개발했어요.

웹 개발 분야에서는 JavaScript와 TypeScript가 31%, HTML과 CSS까지 합치면 거의 60%가 웹 개발에 사용되고 있어요.

대부분 웹사이트나 앱의 사용자가 보는 부분을 만드는 데 사용하고 있어요.

그래서 어떻게 해야 하나요?

개발자들 사이에서 두 가지 의견이 나뉘고 있어요.

"따로 관리하자" 파의 주장

1. AI에게 말하는 방식이 달라요: AI 문서에서는 "중요함!!!"처럼 대문자로 강조하는 게 효과적이지만, 사람이 읽는 문서에서는 무례하게 느껴질 수 있어요.
2. 분량 조절이 필요해요: AI 에이전트 문서는 API 사용료를 아끼려면 짧고 핵심만 담아야 해요. 하지만 팀 문서는 모든 정보를 자세히 담아야 하죠.
3. 필요한 정보가 달라요: AI가 헷갈리는 부분과 사람이 헷갈리는 부분이 다를 수 있어요.

"합쳐서 관리하자" 파의 주장

1. 중복이 너무 많아요: 같은 내용을 두 곳에 적는 건 비효율적이고, 하나만 업데이트하고 다른 건 까먹기 쉬워요.
2. 관리가 복잡해져요: 문서가 늘어날수록 모든 걸 최신 상태로 유지하기 어려워요.

창의적인 해결책들

이 문제를 해결하려는 재미있는 아이디어들이 나오고 있어요.

1. AI로 AI 문제 해결하기

AI 에이전트를 써서 팀 문서와 AI 문서를 자동으로 맞춰주는 방법이에요. 아이러니하게도 AI 문제를 AI로 해결하는 거죠!

2. 아예 하나로 합치기

• 방법 A: AI 전용 문서를 포기하고, 필요할 때마다 기존 문서를 AI에게 보여주기
• 방법 B: 모든 팀 문서를 AI 형식으로만 작성하기

3. 숨겨진 주석 활용하기

팀 문서 안에 <!-- AI용: 빌드 명령어는 bazelisk build //... --> 같은 숨겨진 메모를 적고, 프로그램이 자동으로 이걸 찾아서 AI 문서를 만드는 방법이에요.

4. 참조 링크 사용하기

Claude에게는 프로젝트에서 페어 프로그래밍할 때 다른 엔지니어에게 묻는 것과 같은 종류의 질문을 할 수 있어서, AI 문서에 "자세한 내용은 @CONTRIBUTING.md 파일 봐줘"라고 적는 방법이에요. 대부분의 AI 에이전트가 이런 @ 문법을 지원해요.

실제로는 어떻게 하고 있나요?

팀마다 다른 선택을 하고 있어요.

Claude Code는 소프트웨어 개발에서 획기적인 순간을 의미하며, Intercom에서는 대역폭이 없어서 만들 수 없었을 애플리케이션들을 구축할 수 있게 해준다고 말하는 기업들은 AI 문서를 아주 꼼꼼하게 최적화해요.

반면 Google의 무료 Gemini CLI 사용자들은 좀 더 여유로워요. 무료 라이선스로도 100만 토큰 컨텍스트 윈도우를 가진 강력한 Gemini 2.5 Pro에 접근할 수 있어서 문서 길이에 대한 부담이 적어요.

앞으로는 어떻게 될까요?

AI가 점점 똑똑해지고 있어요. Claude Opus 4는 복잡하고 장기간 실행되는 작업과 에이전트 워크플로우에서 지속적인 성능을 자랑하는 세계 최고의 코딩 모델이고, Claude Sonnet 4는 Sonnet 3.7의 업계 선도적 능력을 크게 개선하여 SWE-bench에서 최첨단 72.7% 점수로 코딩 분야에서 우수한 성과를 보여주고 있어요.

미래에는 AI가 스스로 문서 구조를 파악하고 필요한 정보를 찾을 수 있을 것 같아요. 그럼 지금의 중복 문제는 자연스럽게 해결될 거예요.

하지만 지금 당장은 각 팀 상황에 맞는 선택이 필요해요.

어떤 선택이 좋을까요?

작은 팀이나 스타트업이라면

AI 전용 문서를 따로 만드는 게 나을 수 있어요. 빠르게 움직이는 게 더 중요하니까요.

큰 회사나 여러 팀이 함께 일한다면

문서를 통합 관리하는 게 좋을 수 있어요. 일관성이 더 중요하거든요.

무료 도구를 쓴다면

좀 더 여유롭게 접근할 수 있어요. 문서 길이나 최적화에 대한 압박이 적으니까요.

결론: 완벽한 답은 없어요

AI 에이전트 문서 관리에는 정답이 없어요. 팀 크기, 프로젝트 복잡도, 예산, 사용하는 도구 등을 모두 고려해서 결정해야 해요.

중요한 건 이런 문제가 있다는 걸 미리 알고 준비하는 거예요. 엔터프라이즈와 팀 고객들은 이제 더 많은 사용량과 Claude Code가 포함된 프리미엄 시트로 업그레이드할 수 있어서, AI 에이전트가 더욱 발전하면서 문서 관리 전략의 중요성도 더욱 커질 거거든요.

여러분의 팀은 어떤 방법을 선택하실 건가요? 각자 상황에 맞는 최고의 해답을 찾아가는 여정이 계속되고 있어요!