AI가 자신 있게 틀리는 이유, 그리고 우리가 깔아야 할 '레일'
AI 코딩 어시스턴트한테 Next.js 16 프로젝트 코드를 맡겼는데 getServerSideProps를 추천받은 적 있으신가요? 두 메이저 버전 전에 사라진 API를요. Claude한테 물어보면 때때로 존재하지 않는 Tailwind 클래스를 자신만만하게 써 넣기도 합니다. 이건 모델이 멍청한 게 아니라, 데이터가 낡은 겁니다. 학습 데이터에 최신 문서가 없으니 빈 자리를 '그럴듯한 허구'로 메우는 거죠. AI-First 팀 리빌딩의 첫 번째 과제가 바로 여기 있습니다. AI를 팀원으로 쓰려면, 그 팀원이 읽는 교범부터 최신으로 바꿔줘야 합니다.
첫 번째 기둥: @neuledge/context로 '최신 문서'를 로컬에 깔다
@neuledge/context는 이 문제를 정면으로 해결합니다. dev.to에 공개된 튜토리얼에 따르면, 이 도구는 라이브러리의 GitHub 문서를 로컬 SQLite 파일로 인덱싱한 뒤 MCP(Model Context Protocol)를 통해 AI 어시스턴트에 제공합니다. 클라우드 없이, 속도 제한 없이, 쿼리 응답 10ms 이내. context add https://github.com/vercel/next.js --tag v16.0.0 한 줄이면 Next.js 16 공식 문서 전체가 FTS5 + BM25 랭킹으로 인덱싱됩니다.
이걸 팀 단위로 확장하면 진짜 강력해집니다. .db 파일 하나가 곧 '팀의 지식 패키지'이기 때문에, 사내 디자인 시스템 문서든 내부 API 런북이든 Git 저장소에 마크다운만 있으면 인덱싱해서 S3나 공유 드라이브에 올려놓을 수 있습니다. 신규 팀원이 합류하면 context add ./packages/design-system@3.1.db로 즉시 설치. 온보딩 과정에서 AI 어시스턴트가 우리 팀의 내부 문서까지 정확히 참조하는 환경이 세팅되는 겁니다. AI-First 온보딩을 설계한다면, 이 워크플로우를 빼놓을 수 없습니다.
두 번째 기둥: Claude Code 세션마다 '개발 규율'을 자동 주입하다
최신 문서를 먹였다고 끝이 아닙니다. AI가 '뭘 아느냐'만큼 중요한 건 '어떤 기준으로 코드를 쓰느냐'입니다. dev.to에 공개된 claude-core-values 플러그인은 YAML 파일에 정의한 개발 표준을 Claude Code 세션 시작 시 자동 주입합니다. 세션 시작 때 전체 가치 기준(~300-400 토큰)이, 매 프롬프트마다 모토 한 줄(~15 토큰)이 들어갑니다. 200K 컨텍스트 윈도우 대비 0.375%. 사실상 비용 제로입니다.
팀 리드 관점에서 흥미로운 건 프로젝트별 오버라이드와 팀 배포 구조입니다. .claude/core-values.yml을 저장소에 두면 프로젝트별 기준이 적용되고, 글로벌 설정과 분리됩니다. 사이드 프로젝트에는 'Startup' 템플릿(빠른 출시 우선), 메인 코드베이스에는 'Craftsman' 템플릿(품질 타협 불가)을 거는 식이죠. 팀원 전원에게 플러그인 세 줄로 배포하면, CLAUDE.md에 30줄씩 붙여넣으라고 슬랙 DM 돌리는 시대는 끝납니다. YAML이니까 PR 리뷰도 깔끔하고요.
세 번째 기둥: 프로덕션 RAG 안티패턴을 미리 차단하다
앞의 두 기둥이 아무리 탄탄해도, 실제 프로덕션에서 RAG 파이프라인이 무너지면 소용없습니다. dev.to의 RAG 안티패턴 분석 아티클은 이 지점을 날카롭게 짚습니다. 고정 크기 청킹이 의미 단위를 쪼개서 LLM을 혼란시키는 문제, 인사말까지 벡터 검색으로 보내는 쿼리 분류 부재, 대화 이력과 검색 결과를 한꺼번에 밀어넣어 '중간에서 잃어버리는' 컨텍스트 오버로드, 그리고 멀티테넌시 환경에서 검색 후 필터링이라는 보안 구멍까지. @neuledge/context가 BM25 랭킹과 토큰 버짓 캡핑으로 이 중 상당 부분을 자체 해결하고 있다는 점도 주목할 만합니다.
AI-First 워크플로우의 공식: 컨텍스트 × 표준 × 품질
이 세 가지를 엮으면 하나의 공식이 보입니다. AI-First 개발 환경 = 정확한 컨텍스트(@neuledge/context) × 일관된 표준(core-values 플러그인) × 프로덕션 품질(RAG 안티패턴 회피). 어느 하나라도 빠지면 AI 어시스턴트는 '자신 있게 틀리는 동료'로 전락합니다. 알리바바가 Qwen-3.5에서 100만 토큰 컨텍스트 윈도우를 밀고, Anthropic·OpenAI·Google이 MCP라는 오픈 표준으로 뭉친 건, 결국 '모델에게 더 정확하고 더 많은 맥락을 줄 수 있는 팀'이 이기는 구조로 가고 있다는 뜻입니다.
우리 팀에서는 이런 도구 도입을 '선택사항'이 아니라 온보딩 체크리스트 필수 항목으로 넣고 있습니다. AI는 도구일 뿐 아니라 동료니까요. 새 동료가 들어오면 사내 문서 읽히고, 코딩 컨벤션 숙지시키고, 코드 리뷰 기준 알려주잖아요. AI 어시스턴트한테도 똑같이 해줘야 합니다. 다만 사람과 다른 점은, 이 모든 걸 세 줄의 커맨드와 하나의 YAML 파일로 자동화할 수 있다는 것. 그게 AI-First 팀 리빌딩의 현실적인 출발선입니다.