5명의 개발자가 있다고 가정해 봅시다. 이들을 동일한 Git 저장소에 배치합니다. 그리고 공유된 규칙 없이 Cursor, Copilot 또는 Cline을 자유롭게 사용하게 둡니다. 한 달 뒤, 여러분의 아키텍처에는 영혼이 남아있지 않을 것입니다. **조용한 발산 (Silent Divergence)**에 오신 것을 환영합니다.

생성형 AI (Generative AI)는 정의상 공개된 GitHub 저장소에서 가장 자주 본 것을 생성합니다. 기술 팀에게 이는 엄청난 위험입니다. 바로 코드의 정체성을 완전히 상실하는 것입니다. 만약 여러분의 스튜디오 DNA가 (저희 _Vibrisse_처럼) 에코 디자인, 하드코어 접근성, 또는 React Three Fiber에서 60fps를 짜내는 것이라면, "바닐라 (vanilla)" AI는 일반적인 솔루션을 제안할 것이며, 이는 종종 비대해지고 과하게 설계(over-engineered)되어 있습니다. AI는 커밋이 쌓일 때마다 여러분 팀의 전문성을 조용히 지워버리고, 그 자리를 보이지 않는 기술 부채 (technical debt)로 대체합니다.
코드는 거짓말을 하지 않습니다. 일반적인 AI는 거짓말을 합니다.

"베스트 프랙티스 (Best Practices)" 전쟁과 권위의 환상

통계적 평균보다 더 나쁜 것은, 제가 정기적으로 관찰하는 이른바 **LLM 전쟁 (LLM War)**입니다. 개발자 A가 ChatGPT에 솔루션을 묻습니다. ChatGPT는 그것이 최신 기술(state of the art)이라고 장담하며 패턴 X를 제안합니다. 개발자 B가 Copilot에 묻습니다. Copilot은 패턴 Y를 절대적인 표준이라며 밀어붙입니다. 각 개발자는 "자신의" AI를 맹목적으로 신뢰하며 코드를 병합합니다. 그 결과는 무엇일까요? 팀은 스스로를 기생시키고, 아키텍처는 조현병적인 상태가 되며, PR(Pull Request) 논쟁은 영원히 길어집니다 ("하지만 Claude는 이게 베스트 프랙티스라고 말했어요!").

AI의 위험성은 AI가 다음의 세 가지 모순된 현실 사이에서 끊임없이 눈먼 항해를 한다는 점에 있습니다:

1. 글로벌 "베스트 프랙티스" (이론적인 최신 기술이며, 실제 사용 사례에 비해 과하게 설계되는 경우가 많음).
2. 프롬프팅을 하는 개발자의 개인적 습관 (AI는 사용자를 기쁘게 하기 위해 개인의 스타일에 맞춥니다 — 순전한 아첨입니다).
3. 프로젝트의 실제 현실 (여러분의 구체적인 아키텍처 결정, 비즈니스 제약 조건, 또는 심지어 여러분이 의식적으로 수용한 기술 부채).

제약이 없다면, AI는 1번을 강요하거나 2번에 아부하기 위해 (자신이 전혀 알지 못하는) 3번의 현실을 자연스럽게 무시할 것입니다.

사실, 단 한 줄의 코드를 작성하거나 단 하나의 프롬프트(prompt)를 실행하기 전에, 팀은 그 어떤 AI도 대신해 줄 수 없는 일을 반드시 수행해야 합니다. 바로 멈춰 서서 프로젝트의 현실을 기록하는 것입니다. 그 근본적인 비전 — 즉, 여러분의 실제 베스트 프랙티스(best practices)와 의도적인 선택들 — 이 코드로 인코딩되어야만, 팀의 AI가 학습 통계(training statistics)가 아닌 코드베이스(codebase)에 정렬되도록 강제할 수 있습니다. 이것이 바로 Context-as-Code의 본질입니다.

0. 첫 번째 git init 이전의 비전

이것은 아무도 듣고 싶어 하지 않는 지점입니다. 왜냐하면 돈을 주고 살 수도, 설치할 수도 없기 때문입니다. IDE를 열기 전, 리포지토리(repo)를 만들기 전, 심지어 프레임워크(framework)를 선택하기 전에도: 프로젝트의 비전을 문서화하십시오.

아무도 읽지 않을 UML 다이어그램으로 가득 찬 Confluence 페이지를 말하는 것이 아닙니다. 다음 세 가지 질문에 답하는, 살아있고 짧으며 잔인할 정도로 솔직한 문서여야 합니다:

• 우리의 실제 제약 사항은 무엇인가? (예산, 성능 목표, GDPR, 필수 접근성 요구사항 등...)
• 우리의 의도적인 선택은 무엇이며 그 이유는 무엇인가? ("우리는 상태 관리가 단순하고 이론적인 확장성보다 가독성을 중시하기 때문에 Redux를 사용하지 않습니다.")
• 이 프로젝트에서 명시적으로 금지된 것은 무엇이며 그 이유는 무엇인가? ("검증되지 않은 외부 의존성(external dependencies)은 절대 금지합니다. 우리는 3명 규모의 팀이기에 모든 것을 유지 관리할 수 없습니다.")

이 문서는 단지 인간만을 위한 것이 아닙니다. 이것은 **여러분의 AI를 위한 기초 브리핑(founding brief)**입니다. 이것이 없다면, 에이전트(agent)는 그 공백을 자신의 학습 통계로 채워버릴 것입니다. 그리고 그 통계는 여러분의 프로젝트가 아닌, GitHub의 평균값일 뿐입니다.

AI는 자신이 발견한 것을 증폭시킵니다. 공백을 발견하면, AI는 발명(invent)합니다. 문서화된 비전을 발견하면, AI는 실행(execute)합니다.

1. 공유된 프로젝트 프롬프트 (.cursorrules의 신화)

AI가 리포지토리의 규칙을 추측하게 두거나, 모든 개발자가 매 세션 시작 시마다 수동으로 어시스턴트(assistant)에게 브리핑하기를 기대하는 일을 멈추십시오. AI는 팀의 일관성을 지키는 타협 없는 수호자가 되어야 합니다.

오늘날 모두가 .cursorrules 파일을 신봉합니다. 하지만 뉘앙스가 중요합니다: 이 파일은 마법이 아니며 표준화된 적도 없습니다. 오랫동안 이는 특정 에디터(Cursor, Cline, Windsurf)에 의해 하드코딩된 독점적인 관례(proprietary convention)였습니다.

하지만 그 기저에 깔린 아키텍처 개념은 보편화되었습니다. 더 강력한 표준들이 그 자리를 대신하고 있습니다. 특히 Antigravity (Google DeepMind)와 같은 자율 에이전트 SDK에 의해 대중화된, 로컬 AGENTS.md 파일을 포함하는 .agents/ 폴더가 대표적입니다. IDE의 네이티브 메커니즘을 사용하든 에이전트 오케스트레이터(agent orchestrator)를 사용하든 원칙은 동일합니다: 바로 Context-as-Code입니다. 프로젝트 루트에서 규칙을 버전 관리함으로써, 팀의 모든 구성원에게 일관된 AI 동작을 강제할 수 있습니다.

다음은 실제 운영 환경에서 공유된 컨텍스트(shared context)가 어떤 모습인지 보여주는 구체적인 예시입니다:

# Project Rules
<stack>
React, TailwindCSS. 외부 컴포넌트 라이브러리 사용 금지. 성능 보장을 위해 모든 것을 자체 제작(in-house)합니다.
...

컨텍스트 "타임 트래블" (버전 관리)

Context-as-Code의 가장 큰 장점은 순수하고 강력한 버전 관리(versioning)입니다. 파일이 Git에 존재하기 때문에, AI는 시간을 여행할 수 있습니다. v1을 패치하기 위해 2년 전 브랜치로 git checkout을 하나요? 에이전트는 그 시대의 아키텍처 규칙을 읽습니다. 에이전트는 당신의 번쩍이는 새로운 v3 패턴을 레거시 코드(legacy code)에 주입하려고 시도하지 않을 것입니다. AI는 브랜치의 시간적 현실에 맞춥니다. 그리고 이러한 규칙을 마찰 없이 여러 저장소(repo)에 걸쳐 유지 관리하고 배포하는 "업데이트" 측면을 처리하기 위해, 이제 팀 규모에서 이러한 지식을 동기화하는 Context7과 같은 전용 플랫폼들이 등장하고 있습니다.

주니어 개발자 멘토 효과

이 컨텍스트 파일은 기술 관리 측면에서 환상적인 부수 효과를 가집니다. 일반적인 AI와 단둘이 남겨진 주니어 개발자는 종약 이해도 없이 환각(hallucination)을 복사하여 붙여넣는 경우가 많습니다. 반대로, 엄격한 컨텍스트 파일에 의해 제약된 IDE에서 작업하는 주니어는 실시간으로 "교정"을 받게 됩니다.

AI는 코드를 무분별하게 대량으로 찍어내는 것을 멈춥니다. 대신, 왜 이 특정 프로젝트에서 특정 구조나 명명 규칙 (Naming Convention)을 사용해야 하는지 설명합니다. 에이전트(Agent)는 시니어 개발자의 시간을 독점하지 않으면서도 팀 문화를 전달하는 진정한 온보딩 (Onboarding) 매개체가 됩니다.

2. AI-Ready 코드베이스와 "골드 스탠다드 (Gold Standards)"

또 다른 패러다임의 전환은 기술 문서 (Technical Documentation, 여러분의 README 및 Wiki)의 대상 독자가 바뀌어야 한다는 점입니다. 이제 여러분은 인간만을 위해 글을 쓰는 것이 아닙니다. AI가 자율적으로 컨텍스트 (Context)를 인덱싱하고 이해할 수 있도록 글을 써야 합니다.

• /docs/patterns 폴더: 이론을 설명하는 대신, 완벽한 코드 예시 ("골드 스탠다드 (Gold Standards)")를 제공하세요. AI는 긴 이론적 설명보다 모방 (Few-Shot Prompting)을 통해 훨씬 더 잘 학습합니다. 이것이 바로 모델을 실제로 파인튜닝 (Fine-tuning)하지 않고도 컨텍스트를 "파인튜닝"하는 방법입니다.
• 모듈형 기술 (Modular Skills): 메모리(및 예산)를 포화시키는 10,000 토큰 규모의 거대한 단일 시스템 프롬프트(Monolithic System Prompt)의 시대는 끝났습니다. 2026년에는 AI가 타겟팅된 "기술 (Skills)" (예: .agents/skills/a11y-debugging/SKILL.md)를 스스로 갖춥니다. 접근성(Accessibility) 감사를 요청하면, 에이전트는 해당 전문가 기술만을 로드하여 적용한 뒤 컨텍스트 메모리를 비웁니다. 소프트웨어 엔지니어링 원칙이 AI에 적용된 사례입니다.
• 실행 가능한 문서와 MCP 생태계: AI-Ready 코드베이스는 로컬 마크다운 (Markdown) 파일을 넘어섭니다. AI는 살아있는 문서(Living Documentation)를 읽음으로써 _"이 프로젝트에서 fetch 에러는 보통 어떻게 처리하나요?"_라는 질문에 답할 수 있어야 합니다. 그리고 오늘날, MCP (Model Context Protocol) 표준 덕분에 에이전트는 실제 세계에 쿼리(Query)를 보낼 수 있습니다. AI가 디자인 스타일을 환각(Hallucination)하게 두거나 개발자가 색상 코드(Hex Code)를 찾아 헤매게 만드는 대신, 에이전트는 @modelcontextprotocol/server-figma 서버에 쿼리하여 소스에서 디자인 토큰 (Design Tokens)을 직접 읽어올 수 있습니다. 근사치 없음. 복사-붙여넣기 없음. 완전한 통제.

3. "퍼스트 리스폰더 (First-Responder)"로서의 AI (사전 리뷰어)

마지막으로, 팀의 맥락에서 AI는 단순한 작성자가 아니라 비평가입니다. 이를 여러분의 아키텍처를 위한 eslint라고 생각하십시오. ESLint가 세미콜론 누락이나 미사용 변수와 같은 형식을 검사한다면, AI 사전 리뷰어(Pre-Reviewer)는 실질적인 내용을 검사합니다. 이 컴포넌트가 존재해야 할 이유가 있는가? 어제 동료가 만든 무언가를 중복하고 있지는 않은가? 비즈니스 제약 조건(Business constraints)을 준수하고 있는가? 한 단계 더 높은 차원의 검사입니다. 그리고 ESLint처럼, 코드가 PR(Pull Request)에 도달하기 전에 실행됩니다.

• Pre-commit AI (LLMOps): LLM에게 조심해달라고 부탁하지 마십시오. 실행을 차단하십시오. 로컬 에이전트(Local agents)는 커밋이 전송되기도 전에 코드가 AGENTS.md를 준수하는지 검증할 수 있습니다. 여기 클라우드 데이터 유출 없이 로컬 SLM(Ollama를 통해)을 사용하여 diff를 검토하는 실용적인 pre-commit 훅(hook) 예시가 있습니다:

#!/bin/sh
# .git/hooks/pre-commit
DIFF=$(git diff --cached)
...

이러한 로컬 CI 장벽은 '조용한 분기(Silent Divergence)'가 메인 브랜치에 도달하는 것을 방지합니다.

• 의미론적 일관성 (Semantic Consistency): 에이전트는 저장소(Repository)를 스캔하여 새로운 컴포넌트나 서비스가 어제 동료가 작성한 함수를 중복하지 않는지 확인합니다. 전역적인 맥락(Global context)이 없다면, AI는 바퀴를 재발명하여 보이지 않는 기술 부채(Technical debt)를 생성하는 나쁜 습관을 가지고 있습니다.

결론: AI 시대의 장인 정신 (Craftsmanship)

설계도 없는 건설 현장은 빠르게 폐허가 됩니다. 문서화된 비전이 없는 프로젝트는 6개월 뒤 영혼 없는 코드베이스가 될 것이며, AI는 여러분이 상상했던 것보다 훨씬 빠르게 그 과정을 가속화할 것입니다.

팀 내에서 AI는 단순한 "코드 생성기"나 생산성 단축 도구로 간주되어서는 안 됩니다. AI는 **팀의 문화, 실제 제약 조건, 그리고 역사를 내재화한 타협 없는 페어 프로그래머 (Pair Programmer)**로 설정되어야 합니다. 이를 위해 AI는 여러분이 대신 해줄 수 없는 일, 즉 생각하고, 결정하고, 근간이 되는 비전을 작성하는 일을 여러분이 먼저 수행하기를 요구합니다.

코드는 거짓말을 하지 않습니다. 일반적인 AI는 거짓말을 합니다. 이 둘의 차이는 바로 여러분의 AGENTS.md입니다. 버전이 관리되고, 공유되며, 타협하지 않는 여러분의 아키텍처적 .eslintrc 말입니다.

여러분의 팀은 현실이 어떠한가요? 첫 번째 커밋이 이루어지기 전 문서화된 비전이 있나요, 아니면 진행하면서 아키텍처를 발견해 나가고 있나요?

Beauce, Québec 🇨🇦에서 자랑스럽게 개발되었습니다. 몰입형 웹 엔지니어링 (immersive web engineering)과 지역 AI 주권 (local AI sovereignty) 사이의 결합에 관심이 있으신가요? Vibrisse Studio를 통해 연결해 주세요!