AI 에이전트의 성능을 높이는 것은 '더 많은 컨텍스트'가 아닌 '정확한 프로젝트 지식'이다

커뮤니티 반응

작성자의 경험과 도구에 대해 긍정적인 반응을 보이고 있으며, 특히 '더 적은 것이 더 낫다(Less is more)'는 컨텍스트 전략에 대해 많은 공감을 표하고 있습니다.

주요 논점

01찬성다수

컨텍스트의 양보다 질이 중요하며, 에이전트에게는 명확한 제약 사항과 규칙을 전달하는 것이 성능 향상의 핵심이다.

합의점 vs 논쟁점

합의점

무분별한 코드 덤프나 자동 생성된 컨텍스트는 에이전트의 성능을 저하시킬 수 있다.
에이전트에게는 단순한 코드 탐색 능력 이상의 프로젝트 지식(Knowledge Base)이 필요하다.

실용적 조언

에이전트용 지침 파일(예: AGENTS.md)을 작성할 때, 인증 방식이나 테스트 규칙처럼 코드만으로 파악하기 힘든 프로젝트 고유의 관습을 명시하라.
의존성이 높은 파일이나 수정 금지 파일 목록을 에이전트에게 미리 알려주어 위험한 수정을 방지하라.

섹션별 상세

AI 에이전트의 실패 원인이 코드 작성 능력이 아닌 프로젝트 구조에 대한 오해에서 비롯된다는 점을 확인했다. ETH Zurich의 연구에 따르면 자동 생성된 컨텍스트가 오히려 성능을 2-3% 저하시키며, 이는 에이전트에게 너무 많은 정보를 제공할 때 발생하는 '추측의 영역'이 넓어지기 때문이다. 따라서 에이전트에게는 코드에서 직접 읽어낼 수 없는 고유한 규칙과 제약 사항만 전달하는 전략이 필요하다.

프로젝트 지식을 전달하기 위해 컨벤션, 제약 사항, 구조적 신호, Git 이력 등 네 가지 핵심 요소를 추출하여 AGENTS.md 파일을 생성했다. 이 도구는 LLM이나 API 키 없이 로컬에서 정적 분석을 통해 수초 내에 약 70줄의 핵심 지침을 생성하며, 에이전트가 작업 중 스스로를 점검할 수 있는 런타임 도구도 포함한다. 이를 통해 에이전트는 수정해야 할 파일을 더 정확하게 식별하고 프로젝트의 일관성을 유지하며 코드를 수정할 수 있다.

Cal.com, Hono, Pydantic 등 실제 GitHub 이슈를 대상으로 벤치마크를 수행한 결과, 선별된 컨텍스트를 사용한 에이전트의 효율성이 크게 향상됐다. 특정 작업에서 처리 시간이 241초에서 136초로 단축되었으며, 패치의 완성도는 66% 더 높아진 것으로 나타났다. 이는 전체 코드베이스를 주입하는 것보다 70줄의 정제된 지침이 에이전트의 의사결정에 훨씬 더 유익함을 입증한다.

용어 해설

컨텍스트 윈도우(Context Window): — LLM이 한 번에 처리할 수 있는 텍스트 데이터의 총량입니다. 무조건 많은 정보를 넣는 것이 성능 향상으로 이어지지 않으며, 오히려 불필요한 정보가 섞일 경우 모델의 추론 능력이 저하되는 현상이 발생할 수 있습니다.
에이전트 지침 파일(AGENTS.md): — AI 에이전트가 프로젝트의 구조와 규칙을 이해하도록 돕는 메타데이터 파일입니다. 코드 자체에서 유추하기 힘든 컨벤션, 제약 사항, 구조적 중요도 등을 명시하여 에이전트의 오작동을 방지하는 역할을 합니다.
그래프 기반 검색(Graph-based Retrieval): — 코드 간의 의존 관계나 호출 구조를 그래프 형태로 파악하여 정보를 검색하는 방식입니다. 에이전트가 코드 베이스를 탐색하는 데는 유리하지만, 프로젝트의 고유한 의사결정 규칙을 파악하는 데는 한계가 있을 수 있습니다.

언급된 도구

sourcebook추천

프로젝트를 스캔하여 에이전트에게 필요한 핵심 지식(AGENTS.md)을 생성하는 CLI 도구