Aider 설정 가이드 2026: 코드베이스를 위한 구성 방법

이 기사는 원래 aifoss.dev에 게시되었습니다.

title: 'Aider 설정 가이드 2026: 코드베이스를 위한 구성 방법'
description: '단계별 Aider 설정 가이드: 설치, Ollama 또는 Claude 연결, .aider.conf.yml 구성, 그리고 명령줄(command line)에서 실제 커밋(commit) 시작하기.'
pubDate: '2026년 5월 22일'

tags: ["ai", "coding", "productivity", "llm", "opensource"]

Aider는 실제 파일을 편집하고 변경 사항을 git에 커밋(commit)하는 CLI 코딩 에이전트(coding agent)입니다. 채팅창이 아닙니다. 제안 사이드바도 아닙니다. Aider는 코드베이스(codebase)를 읽고, 지침을 받아 코드를 작성한 다음, 적절한 메시지와 함께 커밋합니다. 이것이 핵심 설명이며, 대부분의 경우 기대에 부응합니다. (설정을 결정하기 전 전체적인 역량 평가를 원하신다면 Aider 리뷰를 읽어보세요.)

이 가이드는 설치, 모델 구성, 코드베이스 설정, 그리고 실제로 시간을 절약해 주는 워크플로(workflow) 패턴을 통해 30분 이내에 여러분을 생산적인 상태로 만들어 드립니다.

사전 요구 사항 (Prerequisites)

Aider를 설치하기 전에 다음이 필요합니다:

Python 3.10 이상 — python --version 또는 python3 --version으로 확인하세요.
git — Aider의 커밋(commit) 통합을 위해 필요합니다. Aider를 실행하기 전에 저장소(repo)를 초기화하세요.
모델 엔드포인트 (model endpoint) — API 키(OpenAI, Anthropic, Gemini) 또는 로컬 Ollama 인스턴스

Aider 자체는 가볍습니다. 리소스 요구 사항은 모델에 달려 있습니다. GPT-4o와 Claude Sonnet은 클라우드에서 실행되므로 로컬 GPU가 필요하지 않습니다. Ollama를 통한 로컬 모델의 경우, 7B 모델(GGUF Q4)에는 8GB 이상의 RAM이, 13B 모델에는 16GB 이상의 RAM이 필요할 것으로 예상됩니다.

설치 (Installation)

pip를 통해 설치합니다. 가상 환경(virtual environment) 사용을 권장하지만 반드시 필수적인 것은 아닙:

pip install aider-chat

확인:

aider --version

Python 2와 3이 모두 있는 시스템을 사용 중이라면 pip3를 사용하세요. Linux의 경우 PATH에 ~/.local/bin을 추가해야 할 수도 있습니다. 설치 후 aider를 찾을 수 없다면 셸 프로필(shell profile)에 export PATH="$HOME/.local/bin:$PATH"를 추가하세요.

나중에 업데이트하려면:

pip install --upgrade aider-chat

각 버전에서 무엇이 변경되었는지는 Aider GitHub releases page를 확인하세요. 이 프로젝트는 매우 빠르게 업데이트되며, 때로는 매주 업데이트되기도 합니다.

라이선스 (License): Apache 2.0. 자유롭게 사용, 포크(fork) 및 수정이 가능합니다.

모델 연결하기

Aider의 유용성은 연결하는 모델에 따라 직접적으로 결정됩니다. 가장 일반적인 세 가지 구성 방법은 다음과 같습니다.

옵션 A: OpenAI (GPT-4o)

export OPENAI_API_KEY=sk-...
aider --model gpt-4o

OPENAI_API_KEY가 설정되어 있고 --model 플래그가 지정되지 않은 경우 GPT-4o가 기본값으로 사용됩니다. 코드 작업에 있어 유능하고 빠릅니다. 다만, 대규모 코드베이스에서 여러 차례 대화(back-and-forth turns)가 오갈 경우 비용이 발생하므로, aider --show-token-count를 통해 토큰 사용량을 주시하세요.

옵션 B: Anthropic Claude

export ANTHROPIC_API_KEY=sk-ant-...
aider --model claude-3-5-sonnet-20241022

Claude Sonnet은 Aider의 유지 관리자가 aider.chat/docs/leaderboards/에 게시하는 벤치마크에서 다중 파일 리팩토링(multi-file refactors) 및 아키텍처 수준의 변경 작업에 대해 지속적으로 가장 강력한 성능을 보여줍니다. 고립된 함수 이상의 작업을 수행하는 경우, Claude가 편집 충돌(edit conflicts)이 적은 경향이 있습니다.

최신 Claude 4.x 모델의 경우 리더보드(leaderboards) 페이지를 확인하세요. Aider는 새로운 모델을 빠르게 추적합니다.

옵션 C: 로컬 Ollama (오프라인, API 비용 없음)

Ollama가 실행 중이라면, Aider는 OpenAI 호환 API를 통해 Ollama와 통신할 수 있습니다:

aider --model ollama/qwen2.5-coder:7b

먼저 Ollama가 실행 중인지 확인하세요 (ollama serve 또는 데스크톱 앱). qwen2.5-coder:7b 부분은 사용자가 다운로드(pull)한 모델명으로 교체하세요. 코딩 작업의 경우, 코드 특화 모델(Qwen2.5-Coder, DeepSeek-Coder, CodeLlama)이 동일한 크기의 범용 모델보다 더 뛰어난 성능을 발휘합니다.

로컬 모델(Local models) 사용 시 현실적인 기대치: 7B 모델은 단일 파일 변경 및 간단한 리팩터링(Refactor)은 잘 수행합니다. 하지만 여러 파일에 걸친 아키텍처 작업은 성공 여부가 불확실합니다. 32B 이상의 모델은 그 격차를 줄여주지만 24GB 이상의 VRAM이 필요합니다. 로컬 GPU 투자 없이 해당 성능이 필요하다면, RunPod를 통해 대여한 A100을 시간당 비용을 지불하며 대규모 모델을 실행할 수 있습니다. 이는 일괄 리팩터링(Batch refactor) 세션에 유용합니다.

로컬 실행기(Runner) 옵션에 대한 비교는 Ollama vs LM Studio vs llama.cpp 2026을 참조하세요.

.aider.conf.yml을 통한 지속적인 설정

매 세션마다 플래그(Flag)를 전달하는 대신, 프로젝트 루트에 .aider.conf.yml 파일을 생성하세요:

model: claude-3-5-sonnet-20241022
auto-commits: true
gitignore: true
...

주요 설정 설명:

auto-commits — true로 설정하면 Aider가 각 편집이 성공할 때마다 커밋(Commit)을 수행합니다. 커밋 전 디프(Diff)를 검토하고 싶다면 false로 설정하세요.
gitignore: true — 어떤 파일을 읽을지 결정할 때 .gitignore를 준수합니다. 거의 항상 이 설정을 권장합니다.
lint-cmd / test-cmd — Aider는 편집 후 이 명령들을 실행하고, 실패 내용을 모델에 자동으로 다시 전달합니다. 이것이 다단계 수정(Multi-step fixes)을 가능하게 하는 "아키텍트(Architect)" 피드백 루프입니다.
dark-mode — 시각적인 설정이지만, 다크 터미널에서 디프(Diff) 렌더링을 훨씬 읽기 쉽게 만들어 줍니다.

설정 파일은 프로젝트별로 적용되며 커밋해도 안전합니다. API 키는 커밋하지 마세요. 환경 변수(Environment variables)나 .gitignore에 포함된 .env 파일을 사용하세요.

.aiderignore를 사용한 파일 제외

기본적으로 Aider는 사용자가 컨텍스트(Context)에 명시적으로 추가한 파일(아래 참조)과 관련이 있다고 판단되는 모든 파일을 포함합니다. 절대 읽어서는 안 되는 디렉토리를 제외하려면 다음과 같이 작성하세요:

# .aiderignore
node_modules/
.next/
...

형식은 .gitignore와 동일합니다. Aider는 .gitignore와 .aiderignore를 모두 읽습니다.

Aider 실행: 세 가지 모드

프로젝트 루트에서 Aider를 실행하세요:

aider

이렇게 하면 대화형 프롬프트(Interactive prompt)가 열립니다. 여기서 세 가지 상호작용 모드를 사용할 수 있습니다:

/code (기본값)

메인 모드입니다. 사용자가 원하는 내용을 설명하면, Aider가 관련 파일을 수정하고 커밋(commit)합니다.

> 세션 대신 JWT를 사용하도록 인증 미들웨어(auth middleware)를 리팩터링(Refactor)해줘. 현재 구현은 src/middleware/auth.js에 있어.

Aider는 파일을 읽고, 변경 사항을 작성하며, 차이점(diff)을 보여준 뒤, refactor: migrate auth middleware to JWT와 같이 생성된 메시지와 함께 커밋합니다.

/ask

수정 없이 질문만 합니다. 코드를 건드리기 전 상황 파악(orientation)을 하는 데 유용합니다.

> /ask 결제 흐름(payment flow)이 어떻게 돼? Stripe 웹훅 핸들러(webhook handler)는 어디에 있어?

파일 수정이나 커밋은 발생하지 않습니다. 코드베이스에 대한 순수한 질의응답(Q&A) 모드입니다.

/architect

두 개의 모델을 사용하는 모드입니다. "설계자(planner)" 모델이 상위 수준의 설계를 제안하면, "편집자(editor)" 모델이 이를 실행합니다. 추론(reasoning)과 실행(execution)을 분리하고 싶은 대규모 변경 작업에 유용합니다.

aider --architect --model claude-opus-4-7 --editor-model claude-3-5-sonnet-20241022

설계자(architect) 모델은 비용이 더 많이 들지만(더 긴 사고 체인(chains)을 사용함), 대규모 차이점(diffs)에 대해 편집 충돌(edit conflicts)을 더 적게 발생시킵니다. 단일 파일 작업의 경우, 이러한 오버헤드를 감수할 가치는 없습니다.

컨텍스트(context)에 파일 추가하기

Aider는 코드베이스 전체를 맹목적으로 읽지 않습니다. 사용자가 컨텍스트에 포함될 내용을 직접 제어합니다. 시작할 때 파일을 추가하세요:

aider src/api/routes.py src/models/user.py

또는 세션 내부에서 추가할 수 있습니다:

> /add src/services/email.py

파일 제거:

> /drop src/models/user.py

현재 컨텍스트에 무엇이 있는지 확인:

> /ls

레포지토리 맵(repo map) 기능은 명시적으로 추가되지 않은 파일에 대해서도 Aider에게 코드베이스 전체의 압축된 뷰(함수 시그니처, 클래스 이름, 임포트(imports) 등)를 제공합니다. 덕분에 사용자가 모든 의존성(dependency)을 지정하지 않아도 Aider가 정확한 임포트 문을 작성하고 기존 함수를 호출할 수 있습니다. 이 기능은 전체 코드량이 약 10만(100k) 토큰(tokens)까지는 잘 작동하며, 그 이상이면 성능이 저하됩니다.

실제로 시간을 절약해주는 워크플로 패턴

패턴 1: 테스트 주도 수정(Test-driven fixes). 설정에서 test-cmd를 지정한 다음, 실패하는 테스트와 함께 Aider를 실행하세요:

> tests/test_auth.py의 실패하는 테스트를 수정해줘. 에러는 인증되어야 하는 요청에 대해 401이 발생하는 거야.

Aider는 테스트를 실행하고, 실패 출력(failure output)을 읽고, 코드를 수정하며, 테스트를 다시 실행합니다. 이 과정은 테스트가 통과하거나 포기할 때까지(보통 3번의 시도) 반복됩니다.

패턴 2: 범위 제한 리팩토링 (Scoped refactors). 작업 범위 내의 파일만 추가하고, 변경 사항을 정확하게 명시하세요:


> /add src/utils/date.py