AI 코딩 에이전트는 소프트웨어 개발에서 점점 더 중요한 역할을 맡고 있다. 하지만 이를 제어하는 Agents.md나 Claude.md 같은 설정 파일에는 이른바 ‘악취(smell)’가 존재할 수 있다.
즉 설정 파일에 구조적 결함이나 중복 요소, 비효율적인 워크플로가 포함돼 있을 수 있다는 의미다. 이러한 문제는 컨텍스트를 불필요하게 비대하게 만들고 토큰을 낭비하며, 결과적으로 코딩 에이전트의 신뢰성을 떨어뜨릴 수 있다.
브라질 미나스제라이스 연방대학교(Federal University of Minas Gerais) 컴퓨터공학과 연구진은 이러한 문제를 조명하기 위해 코딩 에이전트 설정 파일을 위한 ‘최초의 악취 카탈로그(first catalog of smells)’를 제안했다. 연구진이 가장 심각한 문제로 지목한 항목은 린트 누출(lint leakage), 역량 누출(skill leakage), 컨텍스트 비대화(context bloat), 그리고 상충하는 지침(conflicting instructions)이다.
연구진은 논문에서 “분석 결과 이러한 악취는 실제 현장에서 광범위하게 발견되고 있다”라며 “프로젝트 규칙을 해석하는 방식, 지침의 우선순위를 정하는 과정, 그리고 개발 작업 수행에 직접적인 영향을 미칠 수 있다”라고 밝혔다.
설정 파일의 ‘악취’가 AI 모델의 오작동을 부른다
클로드 코드, 코덱스, 커서, 제미나이 같은 에이전트는 코드 생성과 리뷰, 테스트 작성, 버그 수정, 소프트웨어 마이그레이션, 문서 작성 등 다양한 소프트웨어 엔지니어링 업무를 점점 더 많이 수행하고 있다.
이들 에이전트는 기본적으로 LLM과 하니스(harness)의 결합체다. LLM이 두뇌 역할을 한다면, 하니스는 작업을 실행하는 루프를 제공하고 에이전트가 업무 수행에 필요한 도구를 호출할 수 있도록 지원한다. 여기에는 웹 검색 엔진, 이슈 추적 플랫폼, 테스트 실행기 등이 포함될 수 있다.
에이전트의 동작은 Agents.md, Claude.md 같은 설정 파일에 의해 제어된다. 이러한 파일에는 프로젝트 워크플로, 테스트 요구사항, 도메인별 지식 등에 관한 지침이 담겨 있으며, 이를 통해 여러 작업과 세션에 걸쳐 일관성을 유지할 수 있다. 일반적으로 설정 파일은 세션 시작 시 프롬프트의 일부로 로드되며 작업이 진행되는 동안 지속적으로 참조된다.
하지만 연구진은 이러한 설정 파일이 다양한 ‘악취’로 가득 차 있다는 사실을 발견했다. Agent.md 또는 Claude.md 파일을 포함한 인기 오픈소스 저장소 100개를 분석한 결과, 91개 저장소에서 최소 한 가지 이상의 악취가 확인됐다.
가장 빈번하게 발견된 6가지 문제는 다음과 같다.
- 린트 누출(Lint leakage): 62%
- 컨텍스트 비대화(Context bloat): 42%
- 역량 누출(Skill leakage): 35%
- 상충하는 지침(Conflicting instructions): 28%
- 초기화 화석화(Init fossilization): 24%
- 맥락 없는 참조(Blind reference): 16%
토큰 낭비를 부르는 설정 파일의 악취
린트 누출은 설정 파일에 코드 포매터나 린터 같은 정적 분석 도구가 이미 강제하는 규칙이 불필요하게 포함되는 현상을 말한다. 예를 들어 일반적인 스타일 가이드 권고사항, 코드 포맷 규칙, 줄 길이 제한, 네이밍 규칙, 임포트 순서 등을 설정 파일에 다시 명시하는 경우다. 린터는 이러한 규칙을 자동으로 적용해 버그, 보안 취약점, 불일치, 프로그래밍 오류 등을 걸러낸다.
연구진은 이러한 중복이 모델의 컨텍스트 크기를 늘리고 토큰을 낭비한다고 지적했다. 또한 “모델이 아키텍처 제약, 도메인 규칙, 보안 정책과 같은 프로젝트별 핵심 이슈보다 덜 중요한 규칙에 주의를 빼앗길 수 있다”라고 설명했다.
컨텍스트 비대화는 설정 파일이 지나치게 크고, 중요도가 낮거나 불필요한 규칙·예시·세부 정보로 과도하게 채워진 상태를 의미한다. 이로 인해 토큰 사용량이 증가하고 비용이 높아지며, 모델이 더 중요한 지침보다 부차적인 정보에 집중하게 될 수 있다.
역량 누출은 자주 사용되지 않거나 특정 작업에만 필요한 지침이 별도의 역량 또는 작업 파일이 아닌 메인 설정 파일에 포함되는 경우다. 이처럼 특수한 지식이 실제 필요 여부와 관계없이 모든 세션에 로드되면서 컨텍스트 창이 커지고 운영 비용이 증가하며 유지관리도 어려워진다.
연구진은 “이러한 규칙은 실제로 프로젝트에 중요한 규칙과 주의력을 놓고 경쟁할 수 있다”라고 지적했다.
상충하는 지침은 이름 그대로 파일 내 규칙들이 서로 모순되는 상황이다. 이 경우 모델은 어떤 지침을 따라야 할지 판단하기 어려워지고 사실상 임의로 선택하게 된다. 결과적으로 응답의 일관성이 떨어지고 결과가 불안정해질 수 있다.
초기화 화석화는 설정 파일이 한 번 생성된 이후 검토나 수정이 거의 이뤄지지 않는 현상을 의미한다. 코드베이스의 변화가 반영되지 않으면서 오래됐거나 관련성이 떨어지는 규칙이 그대로 남게 된다.
연구진은 “그 결과 설정 파일에 불필요한 정보가 축적되고 컨텍스트 소비량이 증가하며 시간이 지날수록 에이전트의 전반적인 효율성이 저하된다”라고 설명했다.
마지막으로 맥락 없는 참조는 특정 파일이나 문서를 가리키면서도 그 용도나 목적을 설명하지 않는 경우를 뜻한다. 이 경우 에이전트가 해당 자료를 무시할 수 있으며, 만약 그 자료가 작업에 중요하다면 문제가 발생할 수 있다. 반대로 맥락을 파악하기 위해 불필요한 자료를 불러와 토큰과 컨텍스트 공간을 낭비하거나, 중요한 정보를 제대로 우선순위화하지 못할 수도 있다.
연구진은 또한 여러 악취가 동일한 파일에서 동시에 나타나며 서로를 유발하는 경향도 발견했다. 예를 들어 역량 누출과 상충하는 지침은 불필요하거나 관련성이 낮은 정보를 추가하기 때문에 컨텍스트 비대화가 발생할 가능성을 83% 높이는 것으로 나타났다.
설정 파일의 악취를 줄이는 방법
연구진은 이러한 문제가 실제 현장에서 널리 발견되고 있지만 개선 방법도 존재한다고 설명했다.
우선 린트 누출을 줄이기 위해서는 코드 포맷이나 임포트 순서 같은 스타일 규칙을 프롬프트에서 제거해야 한다. 이러한 작업은 전용 도구에 맡기는 것이 바람직하며, 스타일 규칙에 토큰 예산을 사용하는 것은 비효율적이라는 설명이다.
컨텍스트 비대화를 줄이기 위해서는 Claude.md와 Agents.md 파일을 간결하게 유지하고 프로젝트별 핵심 지침만 담아야 한다. 실제로 앤트로픽은 Claude.md 파일을 200줄 이하로 유지할 것을 권장하고 있다.
역량 누출을 줄이기 위해서는 프로젝트 빌드 방식, 테스트 실행 방법, 코드 규약 등 핵심 정보만 설정 파일에 포함해야 한다. 특정 작업에만 필요한 지침은 설명적인 이름을 가진 별도의 마크다운 파일로 분리하는 것이 좋다고 연구진은 조언했다.
상충하는 지침을 방지하기 위해서는 설정 파일을 정기적으로 검토해 서로 모순되거나 오래된 규칙을 제거해야 한다. 초기화 화석화를 줄이기 위해서도 지속적인 업데이트가 필요하다.
특히 에이전트가 동일한 실수를 연속으로 반복하거나, 코드 리뷰 과정에서 이미 알고 있어야 할 정보를 놓치거나, 이전 세션에서 이미 해결된 내용을 다시 설명해야 하는 상황이 발생한다면 설정 파일을 점검해야 한다고 연구진은 설명했다.
맥락 없는 참조를 최소화하려면 에이전트에게 언제, 왜 특정 파일을 읽어야 하는지 명확히 알려줘야 한다. 또한 해당 문서의 역할과 포함된 정보, 활용해야 하는 상황을 간략히 설명하는 참조 정보를 함께 제공해야 한다.
예를 들어 외부 의존성을 언급할 때 깃허브 저장소 링크와 함께 해당 의존성의 목적을 설명하면, 에이전트는 외부 저장소를 직접 로드하거나 분석하지 않고도 해당 의존성의 역할을 이해할 수 있다.
연구진은 “설정 파일은 에이전트 기반 소프트웨어 개발에서 핵심적인 아티팩트”라며 “설정 파일에 악취가 발생하면 문제가 생길 수 있는 만큼 품질 향상을 위한 충분한 노력과 관심이 필요하다”라고 결론지었다.
dl-ciokorea@foundryco.com