모든 Aider 세션에 컨벤션 파일 고정하는 방법 (2026년 가이드)

Aider의 컨벤션 문서는 이 메커니즘을 명확하게 설명합니다. 작은 마크다운 파일을 작성한 다음:

"컨벤션 파일은 /read CONVENTIONS.md 또는 aider --read CONVENTIONS.md로 로드하는 것이 가장 좋습니다. 이렇게 하면 읽기 전용으로 표시되며, 프롬프트 캐싱이 활성화된 경우 캐싱됩니다."

이 문장에는 두 가지 속성이 담겨 있으며, 둘 다 의도된 것입니다. 파일을 읽기 전용으로 표시하면 에이전트가 이를 수정하려고 시도하지 않습니다. 컨벤션 파일은 작업 결과물이 아니라 입력값입니다. 캐싱을 한다는 것은 프롬프트 캐싱을 사용할 수 있을 때 매 턴마다 토큰 비용을 다시 지불하지 않는다는 것을 의미합니다.

문제는 동사에 있습니다. 여러분이 직접 로드해야 합니다. Aider의 문서화된 컨벤션 메커니즘은 명시적으로 읽어들이는 파일이지, 알아서 찾아내는 파일명이 아닙니다. 파일이 존재한다고 해서 자동으로 실행되는 CONVENTIONS.md 탐색 단계는 없습니다.

이 점을 정확히 짚고 넘어갈 필요가 있습니다. 오해하기 쉽기 때문입니다. 또한 이는 도구가 파일을 찾아내고도 무시하는 오류와는 다른 종류의 실패입니다. Why agents ignore your instruction files에서 해당 사례를 다루고 있으며, 이번 사례는 무시할 파일조차 로드되지 않았기 때문에 훨씬 더 단순합니다.

Aider가 여러분의 코드베이스에 무관심한 것은 아닙니다. Aider는 매 요청마다 리포지토리 맵을 자동으로 빌드하여 전송합니다:

"Aider는 가장 중요한 클래스와 함수, 그리고 이들의 타입 및 호출 시그니처를 포함하는 전체 git 리포지토리의 간결한 맵을 사용합니다."

"Aider는 사용자의 각 변경 요청과 함께 LLM에 레포 맵을 전송합니다."

따라서 모델은 코드 구조의 실제 그림을 가지고 작업을 시작합니다. 하지만 컨벤션은 가지고 시작하지 못하며, 그 이유는 실수라기보다는 구조적인 한계 때문입니다. 레포 맵은 코드에서 파생됩니다. 특정 모듈이 존재하고 그 호출 시그니처가 무엇인지는 보여줄 수 있습니다. 하지만 8개월 전에 대안 라이브러리를 거부했다는 사실은 보여줄 수 없습니다. 거부된 라이브러리는 매핑할 리포지토리에 존재하지 않기 때문입니다. 바로 이 차이점이 컨벤션 파일이 존재하는 이유입니다.

공식 문서에는 그 효과를 구체적으로 보여주는 비교 예시가 포함되어 있습니다. 컨벤션 파일을 읽어들인 상태에서는 생성된 함수가 선호하는 HTTP 클라이언트를 사용하고 타입 힌트를 포함했습니다. 반면 컨벤션 파일이 없었을 때는 동일한 요청에 대해 다른 라이브러리를 사용하고 타입이 없는 코드가 생성되었습니다. 문서에서는 이를 "아마도 작은 파이썬 스크립트에서 더 일반적인 형태"라고 설명합니다. 동일한 모델, 동일한 프롬프트이지만 단 하나의 파일 때문에 완전히 다른 결과가 나온 것입니다.

매 세션 시작 시 /read CONVENTIONS.md 입력하기. 이 방법은 작동하며 올바른 첫 단계입니다. 하지만 이는 습관에 의존해야 하며, 바쁜 날에는 습관을 잊어버리기 마련입니다. 그리고 바로 그 바쁜 날에 컨벤션이 위반된 코드가 머지됩니다.

프롬프트에 컨벤션 붙여넣기. 한 번은 작동합니다. 하지만 읽기 전용이 아니므로 에이전트가 파일을 수정할 수 있고, 캐싱되지 않으므로 비용을 반복해서 지불해야 하며, 다음 주에는 또 다른 내용을 붙여넣게 될 것입니다.

/read 대신 /add로 컨벤션 파일 추가하기. 보기보다 미묘하게 더 나쁜 방법입니다. /add는 파일을 편집 가능한 파일로 채팅에 추가합니다. 공식 문서의 조언은 읽기 전용 경로에 대해 구체적이며, 기억해 둘 만한 관련 팁이 있습니다. 시작 시 추가된 읽기 전용 파일을 /drop하지 마세요. 에이전트가 편집할 수 있는 컨벤션 파일은 결국 언젠가 수정되고 맙니다.

메인 소스 파일 상단의 주석 블록에 컨벤션 작성하기. 이제 규칙은 규칙이 적용되는 코드 내부에 존재하게 되며, 오직 그 하나의 파일과만 함께 이동합니다. 레포 맵은 기꺼이 그 주석을 포함하겠지만, 다른 12개의 모듈은 그 주석을 전혀 보지 못할 것입니다.

컨벤션 파일에 모든 것을 집어넣기. 반대 방향의 실패이며, 몇 달이 지난 후에 더 흔히 발생합니다. 모든 아키텍처 결정, 모든 장애 사후 분석, 모든 거부된 옵션을 담을 정도로 커진 컨벤션 파일은 매 세션마다 전체가 로드됩니다. 읽기 전용이고 캐싱되므로 비용은 감당할 수 있지만, 이제 요청의 아주 일부에만 적용되는 내용에 크고 고정된 컨텍스트 블록을 낭비하게 됩니다.

세 단계가 있습니다. 첫 번째는 두 줄짜리 변경 사항이며, 나머지 두 단계는 이 작업을 다시 반복하지 않도록 해줍니다.

Step 1: 프로젝트 설정 파일에 read 추가하기

Aider는 이를 자동화하는 방법을 문서로 제공합니다:

".aider.conf.yml 설정 파일에서 Aider가 항상 컨벤션 파일을 로드하도록 구성할 수도 있습니다."

필드명은 read이며, 단일 파일명 또는 파일명 목록을 받습니다. 단일 컨벤션 파일의 경우 하나의 항목을, 컨벤션 파일과 함께 항상 사용하고 싶은 스키마 참조 등이 있는 경우 목록을 작성합니다.

설정 파일을 어디에 두는지가 중요합니다. Aider는 다음 세 가지 위치를 검색하기 때문입니다:

"Aider는 다음 위치에서 이 파일을 찾습니다: 홈 디렉터리, git 리포지토리의 루트, 현재 디렉터리. 위의 파일들이 존재하면 해당 순서대로 로드됩니다. 가장 마지막에 로드된 파일이 우선순위를 가집니다."

read 항목을 홈 디렉터리가 아닌 git 리포지토리의 루트에 있는 설정 파일에 넣으세요. 두 가지 이유가 있습니다. 첫째, 프로젝트와 함께 이동하는 유일한 위치이므로 팀원들과 CI가 별도의 설정 없이도 동일하게 작동합니다. 둘째, 홈 디렉터리 설정의 read 항목은 여러분이 여는 모든 리포지토리에 존재하지 않을 수도 있는 파일명을 가리키게 됩니다. 프로젝트 로컬 파일을 참조하는 글로벌 설정은 다음 리포지토리를 클론할 때 문제를 일으키는 함정이 됩니다.

가장 마지막에 로드된 파일이 우선순위를 가지므로, 리포지토리 루트 설정은 전역적으로 설정한 모든 내용을 깔끔하게 덮어쓰며, 이는 대개 여러분이 원하는 방식입니다.

Step 2: 파일에 포함할 내용을 결정하고 나머지는 밖으로 이동하기

이제 파일이 매 세션마다 무조건 로드되므로, 파일 크기는 영구적인 비용이 됩니다. 이로 인해 파일에 포함되어야 할 내용이 달라집니다.

모든 요청에 적용되고 규칙으로 진술하기에 충분히 짧은 내용만 유지하세요. 선호하는 라이브러리, 타입 힌트 요구사항, 명명 규칙, 테스트 명령 등이 이에 해당합니다. 이것들은 명령이며, 컨벤션 파일은 명령을 담기에 좋은 그릇입니다.

역사적인 맥락은 모두 밖으로 이동시키세요. 특정 라이브러리를 선택하게 만든 장애에 대해 설명하는 단락은 가치 있고 규칙이 유지되는 이유이기도 하지만, 매 턴마다 프롬프트에 포함될 필요는 없습니다. 데이터 모델에 대한 긴 설명, 릴리스 체크리스트, 세 개의 모듈이 왜 이상하게 구성되었는지에 대한 메모도 마찬가지입니다.

테스트 방법은 간단합니다. 문장이 "내가 무엇을 해야 하는가"에 답한다면 컨벤션 파일에 속합니다. "왜"에 답한다면 에이전트가 요청받았을 때 찾아볼 수 있는 곳에 속합니다. What coding agents actually read는 항상 로드되는 지침 파일을 사용하는 모든 도구에 동일한 구분이 적용되므로 유용한 교차 검증 자료가 됩니다.

Aider 자체의 조언도 선호도에 대한 짧고 구체적인 진술이라는 점에서 동일한 맥락을 공유합니다.

Step 3: 에이전트가 쿼리할 수 있는 "왜"의 보금자리 마련하기

이 단계는 컨벤션 파일이 다시 커지는 것을 방지합니다. 기록된 이유가 없는 규칙은 아무도 삭제하지 않고 아무도 옹호하지 않으므로, 파일은 계속 길어지기만 할 뿐입니다.

의사결정 배경은 항상 로드되는 대신 검색 가능해야 하며, 다음 도구로 전환하더라도 유지되어야 합니다. Aider는 독특한 메커니즘을 가진 터미널 네이티브 도구이며, 많은 팀이 이를 IDE 어시스턴트와 함께 사용합니다. 만약 그 배경이 Aider만 읽어들이는 CONVENTIONS.md에만 존재한다면, 툴체인의 나머지 절반은 이를 전혀 보지 못할 것이며, 내년에 다른 도구를 사용할 때 여러분도 보지 못하게 될 것입니다. Turning project docs into AI memory에서는 기존에 작성된 문서를 처음부터 다시 쓰지 않고도 이러한 형태로 변환하는 방법을 다룹니다.

MemoryLake는 특정 도구에 종속되지 않고 컨벤션의 배경이 되는 논리를 보관하며, MCP나 API를 통해 요청하는 모든 에이전트에게 이를 제공합니다. CONVENTIONS.md는 원래 위치에 그대로 유지되고, Aider는 자체 문서에 설명된 대로 이를 계속 로드합니다. 공유 레이어는 파일 크기를 비대하게 만들 수 있는 내용만 보관합니다.

Step 1: API 키 생성하기

키를 생성하고 약 30초 만에 첫 번째 요청을 완료하세요. 위의 2단계를 진행하기 전에 이 작업을 수행하여, 파일을 정리하면서 각 규칙의 배경 이유를 저장할 공간을 마련해 두세요.

Step 2: 첫 번째 기억 업로드하기

컨벤션 파일을 한 줄씩 살펴보세요. 각 규칙에 대해 그것이 존재하는 이유(거부한 대안, 배경이 된 장애, 강제된 제약 조건 등)를 작성합니다. 이 단락들은 컨벤션 파일에서 제외되어 이곳으로 이동합니다. 관련 문서와 파일도 같은 위치에 저장됩니다.

Step 3: AI 및 에이전트 연결하기

Claude, Codex, OpenClaw 및 기타 에이전트에 MCP 또는 API를 통해 액세스 권한을 부여하세요. 누군가 컨벤션이 왜 그렇게 설정되었는지 물어보면, 단순히 규칙을 반복하는 대신 그 이유가 첨부된 답변이 제공됩니다.

첫 번째 변화는 월요일 아침의 실패가 멈춘다는 것입니다. 리포지토리가 있는 모든 컴퓨터에서, 누군가 기억해 내지 않아도 매 세션마다 첫 번째 메시지를 보내기 전에 컨벤션 파일이 로드됩니다.

두 번째는 읽기 전용 및 캐싱이 올바르게 입력해야 하는 옵션이 아니라 기본값으로 설정된다는 점입니다. 두 속성 모두 문서화된 read 경로에서 제공되며, 파일이 매번 로드될 때 그 중요성이 더욱 커집니다.

세 번째 변화는 컨벤션 파일이 커지는 대신 더 작아질 수 있다는 점입니다. 근거가 쿼리 가능한 저장소로 이동한 모든 규칙은 단 한 줄로 명시될 수 있습니다. 항상 로드되는 짧은 파일과 쿼리 가능한 배경 저장소의 조합은 항상 로드되는 긴 파일보다 확실히 더 나으며, 전체 정보량은 동일합니다.

네 번째 변화는 팀원 중 누군가 Aider를 사용하지 않을 때 나타납니다. 규칙은 Aider가 읽을 수 있도록 리포지토리에 유지됩니다. 배경 논리는 모든 에이전트가 접근할 수 있는 곳에 있습니다. 어느 쪽도 하나의 도구 형식에 갇히지 않습니다.

add 대신 read를 사용하세요. 읽기 전용은 입력 파일에 대한 올바른 자세이며, 공식 문서가 권장하는 방식입니다. 또한 에이전트가 규칙을 임의로 수정하지 못하도록 방지합니다.

설정을 git 루트에 두세요. 프로젝트와 함께 이동하며, 마지막에 로드된 파일이 우선하므로 홈 디렉터리 설정보다 우선순위를 가집니다.

항상 켜져 있는 입력값이 둘 이상인 경우 목록을 사용하세요. read 필드는 목록을 허용하므로, 컨벤션 파일과 스키마 참조를 하나의 거대한 파일로 병합하는 대신 각각 별도의 항목으로 지정할 수 있습니다.

시작 시 추가된 읽기 전용 파일을 /drop하지 마세요. Aider의 팁에서 이를 직접 언급하고 있으며, 긴 세션 동안 채팅에서 파일을 정리할 때 흔히 발생할 수 있는 실수입니다.

명령은 파일에 유지하고, 이유는 제외하세요. 이 파일은 매 요청마다 로드됩니다. "왜"에 답하는 모든 내용은 아무도 묻지 않은 턴에서도 비용을 지불하게 만듭니다.

리포지토리 맵이 컨벤션을 전달할 것이라 기대하지 마세요. 리포지토리 맵은 코드에서 빌드되어 매 요청마다 전송되므로 매우 유용하지만, 리포지토리에 포함된 내용만 반영할 수 있습니다. 거부된 라이브러리는 매핑할 흔적을 남기지 않습니다.

컨벤션 파일을 git에 체크인하세요. 당연한 이야기지만 여전히 강조할 가치가 있습니다. 단 하나의 노트북에만 존재하는 컨벤션 파일은 팀의 탈을 쓴 개인적 취향에 불과합니다.

사용하는 다른 모든 도구에서도 이 작업을 반복해야 할 것임을 예상하세요. 메커니즘은 다릅니다. making an agent stick to your coding style에서는 다른 도구에서 동일한 작업을 수행하는 버전을 다루며, memory solutions for autonomous coding agents는 이 모든 도구의 밑바탕이 되는 레이어를 다룹니다.

Aider의 컨벤션 메커니즘은 관례에 의해 발견되는 파일명이 아니라 명시적으로 로드되는 읽기 전용 파일이며, 이 단 하나의 차이 때문에 테스트 시 작동하던 파일이 일상적인 사용에서는 작동을 멈추게 됩니다. 해결책은 문서화되어 있으며 간단합니다. git 리포지토리 루트의 .aider.conf.yml에 read 항목을 추가하면 리포지토리를 가진 모든 사람에게 매 세션마다 파일이 읽기 전용 및 캐싱된 상태로 로드됩니다.

판단이 필요한 부분은 그 안에 무엇을 넣을 것인가입니다. 이제 파일이 무조건 로드되므로 모든 줄이 영구적인 비용이 되며, 이는 파일 내용을 상시 명령어로 제한하고 배경 논리는 에이전트가 필요할 때 쿼리할 수 있는 곳으로 이동시키도록 유도하는 좋은 압박이 됩니다. Aider의 레포 맵은 모델에게 코드가 무엇을 포함하고 있는지 계속 알려줄 것입니다. 코드가 의도적으로 포함하지 않는 것이 무엇인지 알려줄 수 있는 것은 오직 여러분뿐입니다.