AI 에이전트에게 전체 저장소를 먹이지 마세요: 필요한 것만 검색하는 프로젝트 브레인 구축하기

2026년 6월 26일 게시.

많은 개발자가 현재 AI 에이전트를 사용하고 있지만, 여전히 많은 이들이 에이전트를 거대한 채팅창처럼 다루고 있습니다. 모든 것을 붙여넣고, 에이전트가 프로젝트를 이해하기를 바라며, 실제 지식이 어디에 있는지 알지 못해 에이전트가 무작위 파일을 반복해서 읽는 것을 지켜보는 식입니다.

이것은 스마트한 에이전트 워크플로우 (workflow)가 아닙니다. 그것은 비용이 많이 드는 추측 루프 (guessing loop)일 뿐입니다.

더 나은 패턴은 AI 에이전트에게 **프로젝트 브레인 (project brain)**을 제공하는 것입니다. 즉, 프로젝트가 무엇인지, 어떻게 작업해야 하는지, 그리고 현재 작업에 필요한 정확한 문서 (docs), 파일, 명령 (commands), 의사결정 사항을 어디에서 검색해야 하는지를 에이전트에게 알려주는 작고 신뢰할 수 있는 지식 시스템을 구축하는 것입니다.

목표는 전체 저장소 (repository)를 모델 컨텍스트 (model context)에 집어넣는 것이 아닙니다. 목표는 에이전트가 적절한 시점에 적절한 컨텍스트를 가져오도록 (pull) 만드는 것입니다.

문제점: 더 많은 컨텍스트가 항상 더 나은 것은 아니다

Anthropic은 컨텍스트 (context)를 유한한 자원으로 설명합니다. 그들의 컨텍스트 엔지니어링 (context engineering) 가이드는 에이전트 작업이 더 이상 단순히 좋은 프롬프트 (prompt)를 작성하는 것에 그치지 않는다고 설명합니다. 그것은 지침 (instructions), 도구 (tools), MCP 서버, 외부 데이터, 히스토리 (history), 그리고 검색된 문서 등 모델이 사용할 수 있는 전체 상태 (state)를 큐레이션 (curating)하는 것에 관한 것입니다. 또한 그들은 컨텍스트가 커짐에 따라 모델이 집중력을 잃거나 정보를 올바르게 사용하지 못하는 컨텍스트 저하 (context degradation) 현상에 대해 경고합니다.

이것이 바로 코딩 에이전트 (coding agents)에서 발생하는 현상입니다. 에이전트에게 프로젝트 브레인이 없다면, 에이전트는 모든 것을 처음부터 발견하려고 시도합니다:

파일을 하나씩 계속 읽습니다.
패키지 파일들을 반복해서 엽니다.
이전 세션의 아키텍처 결정 사항을 잊어버립니다.
프로젝트의 컨벤션 (conventions) 대신 일반적인 프레임워크 조언을 사용합니다.
프로젝트가 어떻게 테스트되거나 배포되는지 이해하기 전에 코드를 수정합니다.

좋은 AI 에이전트 설정은 작업이 시작되기 전에 다음과 같은 질문에 답할 수 있어야 합니다:

이 프로젝트는 무엇인가?
가장 중요한 디렉토리는 무엇인가?
어떻게 실행(run), 테스트(test), 린트(lint), 빌드(build) 및 배포(deploy)하는가?
어떤 컨벤션(conventions)을 따라야 하는가?
더 상세한 문서는 어디에 있는가?
이 작업과 관련된 파일만 어떻게 검색(retrieve)하는가?
허가 없이 절대 건드려서는 안 되는 것은 무엇인가?

프로젝트 브레인 패턴 (The project brain pattern)

저는 에이전트의 브레인을 다섯 가지 계층으로 나누는 것을 선호합니다:

핵심 정체성 (Core identity): 짧은 프로젝트 개요, 제품 목적, 기술 스택 (tech stack), 그리고 안전 경계 (safety boundaries).
운영 지침 (Operating instructions): 명령어 (commands), 테스트 규칙, 코드 스타일, PR 규칙, 그리고 일반적인 워크플로우 (workflows).
지식 인덱스 (Knowledge index): 문서, 아키텍처 노트, API 계약 (API contracts), 데이터베이스 스키마 (database schemas), 그리고 결정 기록 (decision records)의 지도.
검색 시스템 (Retrieval system): 검색 (search), 임베딩 (embeddings), BM25, 저장소 지도 (repo maps), MCP 도구, 또는 필요할 때 관련 청크 (chunks)를 가져오는 로컬 RAG 서비스.
피드백 메모리 (Feedback memory): 에이전트가 실수를 저지른 후 얻은 수정 사항과 교훈이며, 문서처럼 짧게 유지하고 관리됩니다.

새로운 개발자를 온보딩(onboarding)하는 과정이라고 생각해보세요. 그들에게 저장소 전체를 던져주며 "전부 다 읽어봐"라고 말하지는 않을 것입니다. 대신 README, 아키텍처 가이드, 테스트 명령어, 주요 문서, 그리고 필요한 것을 검색할 수 있는 방법을 제공할 것입니다.

항상 로드되는 컨텍스트(always-loaded context)에는 무엇이 포함되어야 하는가?

항상 로드되는 지침은 작게 유지하세요. 에이전트가 거의 모든 작업에서 필요로 하는 고신호 (high-signal) 세부 사항만 넣으세요:

프로젝트 목적 및 현재 앱/제품의 경계.
기술 스택 (tech stack) 및 패키지 매니저 (package manager).
설치 (install), 개발 (dev), 테스트 (test), 린트 (lint), 타입 체크 (typecheck), 빌드 (build)를 위한 명령어.
핵심 디렉토리와 그 안에 포함된 내용.
타협 불가능한 규칙: 보안, 마이그레이션 (migrations), 생성된 파일, 비밀 값 (secrets), 배포 규칙.
더 상세한 문서를 찾는 방법.

대규모 API 레퍼런스 (API references), 전체 스키마, 오래된 논의 내용, 또는 전체 아키텍처 문서를 최상위 지침 파일에 직접 넣지 마세요. 대신 그것들을 연결(link)하세요. 검색 가능하게 만드세요.

검색(retrieval)에는 무엇이 포함되어야 하는가?

검색(retrieval)은 매 턴마다 필요하지는 않지만 중요할 수 있는 정보를 위한 것입니다:

긴 아키텍처 문서 (Long architecture documents)
데이터베이스 스키마 상세 정보 (Database schema details)
API 엔드포인트 참조 (API endpoint references)
기능 명세서 (Feature specs)
에러 카탈로그 (Error catalogs)
디자인 시스템 문서 (Design-system docs)
과거의 결정 사항 (Historical decisions)
유사한 구현 사례 (Examples of similar implementations)

Anthropic의 컨텍스트 검색(contextual retrieval) 기사는 전형적인 RAG 흐름을 설명합니다: 문서를 청크(chunk)로 나누고, 청크를 임베딩(embed)하며, 이를 벡터 데이터베이스(vector database)에 저장한 뒤, 실행 시점에 가장 관련성이 높은 청크를 검색하여 모델 프롬프트(prompt)에 추가하는 방식입니다. 또한, 특히 정확한 식별자(identifiers)와 기술 용어의 경우, 의미론적 임베딩(semantic embeddings)을 BM25와 같은 어휘 검색(lexical search)과 결합하는 일반적인 개선 방법도 강조합니다.

Codex: AGENTS.md를 입구로 사용하기

OpenAI Codex의 경우, 첫 번째 해결책은 AGENTS.md입니다. OpenAI의 Codex 문서에 따르면, Codex는 작업을 수행하기 전에 AGENTS.md를 읽으며, 계층화된 가이드(layered guidance)를 지원합니다: Codex 홈 디렉토리의 전역 지침(global instructions), 저장소 루트(repository root)의 프로젝트 지침(project instructions), 그리고 현재 디렉토리에 더 가까운 중첩된 지침(nested instructions)이 그것입니다. 또한 문서에서는 기본 프로젝트 지침 크기 제한이 32 KiB라고 언급하는데, 이는 이 파일이 간결해야 한다는 중요한 점을 상기시켜 줍니다.

실용적인 AGENTS.md에는 다음이 포함되어야 합니다:

# AGENTS.md

## 프로젝트 개요 (Project overview)
...

그 다음 더 깊은 인덱스(index)를 생성합니다:

docs/ai/index.md
- 제품 개요: docs/product/overview.md
- 아키텍처: docs/architecture/system.md
...

이렇게 하면 Codex에게 산더미가 아닌 지도를 제공하게 됩니다.

Claude Code: CLAUDE.md, 규칙, 임포트(imports), 그리고 MCP 사용하기

Claude Code의 문서는 Claude가 CLAUDE.md 파일과 자동 메모리(auto memory)를 통해 프로젝트를 기억한다고 설명합니다. CLAUDE.md는 사용자가 직접 작성하는 영구적인 지침(persistent instructions)을 위한 것이며, 자동 메모리는 Claude가 수정 사항과 선호도를 통해 축적하는 메모를 위한 것입니다. 문서에서는 Claude가 같은 실수를 두 번 반복할 때, 코드 리뷰에서 Claude가 알고 있었어야 할 사항이 발견될 때, 또는 팀원이 생산성을 높이기 위해 동일한 컨텍스트가 필요할 때 정보를 추가할 것을 권장합니다.

Claude Code는 또한 @ 참조를 사용하여 추가 파일을 가져올 수 있습니다. 이는 CLAUDE.md를 짧게 유지하면서도 더 깊은 문서들을 가리킬 수 있음을 의미합니다:

# CLAUDE.md

## Project instructions
...

Claude Code는 또한 MCP (Model Context Protocol)를 지원하는데, 이는 가장 좋은 프로젝트 브레인(project brain)이 종종 정적인 파일이 아니기 때문에 중요합니다. MCP는 에이전트를 이슈 트래커 (issue trackers), 데이터베이스 (databases), 디자인 도구 (design tools), 문서 시스템 (documentation systems), 검색 도구 (search tools) 또는 커스텀 코드베이스 검색기 (custom codebase retriever)에 연결할 수 있습니다.

Codex + Claude Code 함께 사용하기: 단일 진실 공급원(single source of truth) 만들기

Codex와 Claude Code를 모두 사용한다면, 서로 동떨어지는 두 개의 별개 브레인을 유지하지 마세요. 공유된 진실 공급원 (source of truth)과 각 에이전트를 위한 얇은 래퍼 (thin wrappers)를 사용하십시오.

권장 구조:

AGENTS.md
CLAUDE.md
docs/ai/index.md
...

AGENTS.md는 요약 내용을 담고 Codex가 docs/ai/index.md를 가리키도록 해야 합니다. CLAUDE.md는 지원되는 경우 동일한 문서를 요약하고 가져와야 합니다. 표준 지식 (canonical knowledge)은 docs/ai/에 존재합니다.

이렇게 하면 Codex는 하나의 워크플로우 (workflow)를 따르고, Claude Code는 다른 워크플로우를 따라 개발자가 혼란을 정리해야 하는 흔한 문제를 방지할 수 있습니다.

Ollama와 로컬 코딩 에이전트: 로컬 RAG를 주의해서 사용하기

Ollama, Continue 스타일의 설정, Open WebUI, Aider 또는 커스텀 스크립트를 사용하는 로컬 에이전트의 경우, 검색 (retrieval)이 훨씬 더 중요합니다. 로컬 모델은 종종 컨텍스트 윈도우 (context windows)가 더 작고 긴 컨텍스트 처리 능력 (long-context behavior)이 더 약하기 때문입니다.

Open WebUI의 RAG 문서는 특히 Ollama가 기본적으로 2048 토큰 컨텍스트 길이로 설정될 수 있으며, 이는 RAG 성능을 심각하게 제한할 수 있다고 경고합니다. 해당 문서에서는 웹 또는 문서 검색을 사용할 때 Ollama 모델의 컨텍스트 길이를 늘릴 것을 권장합니다.

좋은 로컬 설정은 다음과 같습니다:

Ollama를 통해 성능이 뛰어난 로컬 모델 (local model)을 실행합니다.
임베딩 (embeddings)과 키워드 검색 (keyword search)을 사용하여 로컬 문서/코드 인덱스 (index)를 생성합니다.
코드를 단순히 고정된 크기의 텍스트로 나누지 말고, 심볼 (symbols), 클래스 (classes), 함수 (functions), 마크다운 섹션 (markdown sections), 그리고 설정 파일 (config files) 단위로 청킹 (chunk) 합니다.
메타데이터 (metadata)를 저장합니다: 파일 경로 (file path), 심볼 이름 (symbol name), 패키지/모듈 (package/module), 최종 수정 날짜 (last modified date), 문서 유형 (doc type).
하이브리드 검색 (hybrid search)을 통해 상위 결과를 검색합니다: 임베딩 (embeddings) + BM25 또는 정확한 일치 (exact match).
선택 사항으로, 컨텍스트 (context)에 추가하기 전에 결과의 순위를 재조정 (rerank) 합니다.
최종 컨텍스트 예산 (context budget)을 엄격하게 유지합니다: 작업에 필요한 내용만 포함합니다.

코드베이스 (codebases)의 경우, 검색 시 정확한 심볼 (symbols), 파일 경로 (file paths), 임포트 (imports), 패키지 이름 (package names), 그리고 에러 메시지 (error messages)를 우선시해야 합니다. 순수 벡터 검색 (pure vector search)은 정확한 기술적 식별자 (technical identifiers)를 놓칠 수 있습니다. 하이브리드 검색 (hybrid retrieval)이 일반적으로 더 효과적입니다.

Aider와 레포지토리 맵 (repo maps): 또 다른 유용한 패턴

Aider의 레포지토리 맵 (repository map)은 모델에게 전체 레포지토리 (repo)를 먹이지 않는 아주 좋은 사례입니다. Aider는 레포지토리 전반에 걸쳐 중요한 클래스 (classes), 함수 (functions), 타입 (types), 그리고 호출 시그니처 (call signatures)를 포함하는 간결한 맵을 구축합니다. Aider의 문서에 따르면, 이 맵은 모델이 코드베이스 전체에서 코드가 어떻게 연결되어 있는지 이해하도록 돕고, 대규모 레포지토리의 경우 Aider가 활성 토큰 예산 (active token budget)에 맞춰 가장 관련성이 높은 부분만을 선택합니다.

이것이 올바른 접근 방식입니다: 에이전트 (agent)에게 먼저 압축된 맵을 제공한 다음, 필요할 때 특정 파일을 요청하도록 하는 것입니다.

모든 로컬 AI 에이전트: 내가 권장하는 최소한의 브레인 (brain)

코딩 에이전트 (coding agent)를 구축하거나 설정하고 있다면, 다음과 같은 최소한의 설정부터 시작하세요:

docs/ai/index.md
AGENTS.md 또는 CLAUDE.md 또는 그에 상응하는 에이전트 지침 (agent instructions)
scripts/ai/context-search.sh 또는 MCP 검색 서버 (MCP search server)
...

docs/ai/index.md는 지루할 정도로 직설적이어야 합니다:

# AI 프로젝트 인덱스 (AI Project Index)

## 여기서 시작하세요
...

내가 더 많은 팀이 사용하기를 바라는 에이전트 워크플로우 (agent workflow)

AI 코딩 에이전트에게 작업을 할당할 때, 다음 루프 (loop)를 따르도록 지시하세요:

작업 분류 (Classify the task). 버그 수정 (bug fix), 기능 구현 (feature), 리팩터링 (refactor), 테스트 (test), 문서화 (documentation), 배포 (deployment), 또는 리서치 (research) 중 무엇인가요?
작은 브레인 로드 (Load the small brain). 최상위 지침 파일과 docs/ai/index.md를 읽습니다.
타겟팅된 컨텍스트 검색 (Retrieve targeted context). 문서 (docs), 심볼 검색 (symbol search), 레포 맵 (repo map), 또는 MCP 검색 (MCP retrieval)을 사용합니다.
파일 계획 명시 (State the file plan). 관련이 있다고 판단되는 파일들의 이름을 나열합니다.
최소한으로 수정 (Edit minimally). 작업에 필요한 부분만 변경합니다.
검증 (Verify). 적절한 테스트 (tests), 린트 (lint), 타입 체크 (typecheck), 또는 빌드 (build)를 실행합니다.
브레인 업데이트 (Update the brain). 에이전트가 지속 가능한 프로젝트 규칙을 학습했다면, 이를 적절한 문서에 추가합니다.

마지막 단계가 중요합니다. 여러분의 프로젝트 브레인 (project brain)은 시간이 지남에 따라 개선되어야 합니다. 만약 에이전트가 반복적으로 동일한 실수를 저지른다면, 채팅에서 계속 수정해주지 마세요. 그 교훈을 AGENTS.md, CLAUDE.md, 또는 관련 프로젝트 문서에 기록하세요.

에이전트 브레인이 제대로 작동하는지 확인하는 방법

다음과 같은 현상이 나타나면 설정이 개선되고 있다는 증거입니다:

에이전트가 매 세션마다 동일한 설정 파일들을 읽는 것을 멈춥니다.
에이전트가 수정을 시작하기 전에 프로젝트 구조를 설명할 수 있습니다.
무작위로 스캔하는 대신 특정 파일을 요청하거나 검색합니다.
별도의 지시 없이도 올바른 테스트를 실행합니다.
첫 시도부터 프로젝트 컨벤션 (project conventions)을 따릅니다.
아키텍처에 관한 주장을 할 때 문서나 코드 경로를 인용합니다.
새로운 팀원들이 동일한 문서를 사용하여 더 빠르게 생산성을 높일 수 있습니다.

흔한 실수들

AGENTS.md 또는 CLAUDE.md에 너무 많은 내용을 넣는 것. 이 파일들은 거대한 매뉴얼이 아니라 지도와 규칙이어야 합니다.
임베딩 (embeddings)만 사용하는 것. 코드 검색 (code retrieval)에는 정확한 검색 (exact search)도 필요합니다.
문서를 유지 관리하지 않는 것. 오래된 지침은 지침이 없는 것보다 더 해롭습니다.
각 에이전트가 서로 다른 진실을 갖게 하는 것. Codex, Claude Code, 그리고 로컬 에이전트들은 모두 동일한 표준 문서 (canonical docs)를 가리켜야 합니다.
검증 루프 (verification loop)의 부재. 지식이 풍부한 에이전트라도 여전히 테스트가 필요합니다.
경계 설정의 부재. 승인 없이 수정해서는 안 되는 항목을 에이전트에게 알려주세요.

최종 권장 사항

전체 프로젝트를 컨텍스트 (Context)에 쑤셔 넣어서 AI 에이전트를 똑똑하게 만들려고 하지 마세요. 대신 다음과 같은 '프로젝트 브레인 (Project Brain)'을 제공하여 똑똑하게 만드세요:

항상 로드되어 있는 작은 지침 파일 (Instruction file).
명확한 문서 인덱스 (Documentation index).
심층 지식을 위한 검색 레이어 (Retrieval layer).
코드 이해를 위한 저장소 맵 (Repo map) 또는 심볼 검색 (Symbol search).
실시간 외부 시스템을 위한 MCP 도구 (MCP tools).
에이전트가 중요한 것을 배웠을 때 지속 가능한 지식을 업데이트하는 습관.

최고의 AI 코딩 에이전트는 가장 큰 프롬프트 (Prompt)를 가진 에이전트가 아닙니다. 적절한 시점에 적절한 지식에 가장 잘 접근할 수 있는 에이전트입니다.