Aider 가이드

소개

Aider는 Git 워크플로우에 최적화된 AI 코딩 CLI 도구입니다. 모든 변경사항을 자동으로 커밋하고, diff를 생성하며, 다양한 LLM을 지원합니다. 2023년 Paul Gauthier가 오픈소스로 공개한 이후 빠르게 성장하여, 터미널 기반 AI 코딩 도구 중 가장 활발한 커뮤니티를 형성하고 있습니다.

왜 Aider인가?

Edit-Test-Commit 워크플로우

Aider의 핵심 동작 방식은 편집 → 테스트 → 커밋의 자동화된 사이클입니다. 사용자가 요청을 입력하면, LLM이 코드를 편집하고 린트/테스트를 실행한 뒤 통과하면 자동으로 Git 커밋을 생성합니다. 실패 시 자동으로 재시도합니다.

설치

Python으로 설치

# pip로 설치
pip install aider-chat

# 또는 pipx로 설치 (권장)
pipx install aider-chat

# 설치 확인
aider --version

다른 설치 방법

# Docker로 실행
docker run -it --rm \
  -v $(pwd):/app \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  paulgauthier/aider

# Homebrew (macOS)
brew install aider

API 키 설정 (선택사항)

# Claude 사용
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"
aider --model claude-

# OpenAI 사용
export OPENAI_API_KEY="sk-xxx"
aider --model gpt-4

# Ollama 사용 (무료, API 키 불필요)
aider --model ollama/llama3.2

# .env 파일로 관리 (권장)
# .aider.env 파일 생성
ANTHROPIC_API_KEY=sk-ant-api03-xxx
OPENAI_API_KEY=sk-xxx

기본 사용법

Aider 시작

# 프로젝트 디렉토리에서
cd my-project

# Git 저장소 초기화 (필수)
git init

# Aider 실행
aider

# 특정 파일만 포함
aider src/app.js src/utils.js

# 특정 모델 지정
aider --model claude-

첫 번째 요청

You> "Python Flask 웹 서버 만들어줘.
/hello 엔드포인트 추가하고, JSON 반환하게."

Aider> "Flask 서버를 생성하겠습니다."

# 파일 생성
Add app.py
Add requirements.txt

# Git 자동 커밋
Commit 3a7f2e1 Create Flask server with /hello endpoint

Aider> "2개 파일을 생성하고 커밋했습니다!"

주요 명령어

편집 모드 비교

Aider는 LLM이 코드 변경사항을 전달하는 방식을 여러 편집 포맷(edit format)으로 지원합니다. 모델의 능력과 작업 유형에 따라 최적의 포맷이 다릅니다.

whole (전체 파일)

파일 전체를 출력하는 가장 단순한 방식입니다. 소규모 파일이나 새 파일 생성에 적합하지만, 큰 파일에서는 토큰 낭비가 심합니다.

# whole 모드 사용
aider --edit-format whole

# LLM이 파일 전체를 다시 작성
# 장점: 단순, 오류 적음
# 단점: 토큰 사용량 높음, 큰 파일 비효율

diff (검색/치환)

변경할 부분만 검색/치환 블록으로 전달합니다. 대부분의 상용 모델(Claude, GPT-4)에 기본으로 사용됩니다.

# diff 모드 (기본값)
aider --edit-format diff

# LLM 출력 형식 예시
# <<<<<<< SEARCH
# 원래 코드
# =======
# 변경된 코드
# >>>>>>> REPLACE

udiff (Unified Diff)

표준 unified diff 형식을 사용합니다. +/- 줄 표기로 변경사항을 표현하며, diff에 익숙한 개발자에게 가독성이 좋습니다.

# udiff 모드
aider --edit-format udiff

# LLM 출력 형식 예시
# --- a/src/app.js
# +++ b/src/app.js
# @@ -10,3 +10,5 @@
#  const app = express();
# +const auth = require('./auth');
# +app.use(auth.middleware);

architect (아키텍트)

두 단계로 나누어 작동합니다. 먼저 architect 모델이 변경 계획을 수립하고, editor 모델이 실제 코드 편집을 수행합니다. 복잡한 리팩토링이나 다중 파일 변경에 유용합니다.

# architect 모드
aider --edit-format architect

# architect + editor 모델 분리 (비용 최적화)
aider --architect --model claude- --editor-model claude-

편집 포맷 비교표

리포지토리 맵 (repo-map)

Aider의 가장 차별화된 기능 중 하나는 리포지토리 맵입니다. 프로젝트의 전체 파일 구조와 심볼(함수, 클래스, 변수)을 tree-sitter로 파싱하여 LLM에 압축된 코드맵을 제공합니다.

작동 원리

1. 파싱: tree-sitter로 모든 소스 파일의 심볼(함수, 클래스, 메서드) 추출
2. 그래프 구축: 파일 간 참조 관계를 그래프로 구성
3. 순위 산정: PageRank 유사 알고리즘으로 현재 작업과 관련된 파일에 가중치 부여
4. 토큰 예산 내 맵 생성: --map-tokens 한도 내에서 가장 관련성 높은 심볼만 포함

맵 토큰 설정

# 기본값: 컨텍스트 윈도우의 25%
aider --map-tokens 2048

# 큰 프로젝트에서 더 넓은 맵
aider --map-tokens 4096

# 맵 비활성화 (토큰 절약)
aider --map-tokens 0

# 전체 맵 새로고침
aider --map-refresh always

Git 통합

자동 커밋

Aider는 모든 변경사항을 자동으로 커밋합니다. 각 커밋 메시지는 AI가 생성합니다.

You> "사용자 인증 기능 추가해줘."

# AI가 코드 생성
Add src/auth.js
Modify src/app.js

# 자동 커밋
Commit 8b3c9a2 Add user authentication with JWT

자동 커밋 비활성화

자동 커밋을 끄고 수동으로 변경사항을 검토한 뒤 커밋할 수 있습니다. 코드 리뷰를 꼼꼼히 하고 싶을 때 유용합니다.

# 자동 커밋 비활성화
aider --no-auto-commits

# 변경 후 직접 확인
You> "/diff"
# 변경사항 확인 후 수동 커밋
You> "/commit"

# 또는 Aider 밖에서 직접 git commit
git add -A && git commit -m "내 커밋 메시지"

커밋 메시지 커스터마이징

# 커밋 메시지 앞에 접두사 추가
aider --commit-prompt "conventional commits 형식 사용"

# .aider.conf.yml에서 설정
commit-prompt: "conventional commits 형식 사용. 한국어로 작성."

Diff 검토

# 변경사항 확인
You> "/diff"

# Git diff 표시
diff --git a/src/app.js b/src/app.js
@@ -10,6 +10,8 @@
 const app = express();
+const auth = require('./auth');
+app.use(auth.middleware);

변경 취소

You> "/undo"

Aider> "마지막 커밋을 되돌렸습니다."
Reverted commit 8b3c9a2

더티 커밋 (Dirty Commits)

Aider 시작 시 스테이지되지 않은 변경사항이 있으면, Aider가 자동으로 이를 별도 커밋합니다. 이 동작을 제어할 수 있습니다.

# 더티 커밋 비활성화
aider --no-dirty-commits

# 기존 변경사항을 Aider가 건드리지 않음

다중 LLM 지원

지원 모델

# Claude
aider --model claude-
aider --model claude-

# OpenAI
aider --model gpt-4
aider --model gpt-4-turbo

# Gemini
aider --model gemini/gemini-pro

# Ollama (로컬)
aider --model ollama/llama3.2
aider --model ollama/codellama

# DeepSeek
aider --model deepseek/deepseek-coder

# OpenRouter (다중 프로바이더)
aider --model openrouter/anthropic/claude-

모델 선택 가이드

세션 중 모델 전환

# 세션 중에 모델 변경
You> "/model claude-"

# Architect 모드에서 모델 분리
# 계획: 고급 모델 / 실행: 경량 모델
aider --architect --model claude- --editor-model claude-

대규모 코드베이스 전략

수백~수천 개의 파일로 구성된 대규모 프로젝트에서는 LLM의 컨텍스트 윈도우를 효율적으로 관리하는 것이 핵심입니다.

컨텍스트 관리

# 필요한 파일만 정확히 추가
You> "/add src/auth/login.js"
You> "/add src/auth/middleware.js"

# 참조만 필요한 파일은 read-only로
You> "/read-only src/types/user.ts"

# 작업 완료 후 불필요한 파일 제거
You> "/drop src/auth/login.js"

# 현재 추가된 파일 목록 확인
You> "/ls"

# 토큰 사용량 확인
You> "/tokens"

컨텍스트 관리 전략

.aiderignore 파일

# .aiderignore - repo-map에서 제외할 파일
node_modules/
dist/
build/
*.min.js
*.bundle.js
package-lock.json
*.log
__pycache__/
.pytest_cache/
vendor/

설정 상세 (.aider.conf.yml)

프로젝트 루트에 .aider.conf.yml 파일을 생성하면 Aider 실행 시 자동으로 설정이 적용됩니다. 글로벌 설정은 ~/.aider.conf.yml에 배치합니다.

전체 설정 예시

# .aider.conf.yml - 프로젝트별 설정

# 모델 설정
model: claude-
editor-model: claude-
edit-format: diff

# Git 설정
auto-commits: true
dirty-commits: true
commit-prompt: "conventional commits 형식 사용"

# 컨텍스트 설정
map-tokens: 2048
map-refresh: auto
cache-prompts: true

# 테스트/린트 통합
auto-test: true
test-cmd: "npm test"
auto-lint: true
lint-cmd: "npm run lint"

# UI 설정
dark-mode: true
stream: true
pretty: true

# 파일 필터
subtree-only: false

린트/테스트 자동화

--auto-lint와 --auto-test를 활성화하면 Aider가 코드 편집 후 자동으로 린트와 테스트를 실행합니다. 실패 시 오류 메시지를 LLM에 전달하여 자동으로 수정을 시도합니다.

# 린트 + 테스트 자동화
aider --auto-lint --lint-cmd "eslint src/" \
      --auto-test --test-cmd "pytest tests/"

# 편집 -> 린트 실행 -> 실패 시 자동 수정 -> 테스트 실행 -> 실패 시 자동 수정 -> 커밋

설정 파일 Git 관리

# .aider.conf.yml은 팀과 공유 (커밋)
# .aider.env는 개인 키 포함 (gitignore)

# .gitignore에 추가
.aider.env
.aider.tags.cache
.aider.chat.history.md
.aider.input.history

실전 워크플로우

기능 브랜치 개발

# 새 브랜치 생성
git checkout -b feature/user-auth

# Aider 시작
aider

You> "사용자 인증 시스템 구현해줘.
JWT 토큰 사용, 회원가입/로그인 API."

# AI가 코드 생성 및 커밋
Commit a3f89d Implement JWT authentication system

# 브랜치 푸시
git push origin feature/user-auth

버그 수정

# 버그가 있는 파일 열기
aider src/buggy-file.js

You> "이 파일에서 TypeError 발생해.
users.map()에서 users가 undefined일 때 에러나.
수정해줘."

Modify src/buggy-file.js
Commit f2e8b3a Fix TypeError: Add null check before map()

테스트 주도 워크플로우

# 테스트 자동 실행 설정
aider --auto-test --test-cmd "pytest tests/ -x"

You> "UserService 클래스에 이메일 유효성 검사 추가해줘.
테스트도 같이 작성해줘."

# Aider가 코드 + 테스트 작성
Modify src/user_service.py
Add tests/test_user_service.py

# 자동으로 pytest 실행
Running: pytest tests/ -x
Tests passed!

# 테스트 통과 후 자동 커밋
Commit 4e7a1b2 Add email validation with tests

리팩토링

You> "src/utils.js를 읽어봐.
이 파일을 더 작은 모듈로 분리하고,
TypeScript로 변환해줘.
테스트 코드도 작성해줘."

Add src/utils/string.ts
Add src/utils/array.ts
Add src/utils/__tests__/string.test.ts
Add src/utils/__tests__/array.test.ts
Delete src/utils.js

Commit 9d4c2f1 Refactor utils to TypeScript modules with tests

고급 기능

쉘 명령어 실행

# Aider 내부에서 명령어 실행
You> "/run npm test"

# 테스트 실패 시 자동 수정
You> "테스트가 실패했어. 수정해줘."

# /run vs /test 차이
# /run: 명령어 실행 후 출력을 대화에 추가
# /test: 명령어 실행 후 실패 시 자동으로 수정 시도

Architect 모드

복잡한 변경사항을 계획하고 단계별로 실행:

aider --architect

You> "전체 인증 시스템을 재설계해줘.
OAuth 2.0 지원, refresh token, 역할 기반 권한."

Aider> "계획을 수립하겠습니다..."
# 1단계: Architect 모델이 변경 계획 수립
# - 수정할 파일 목록
# - 각 파일의 변경 내용 설명
# - 의존성 순서

# 2단계: Editor 모델이 실제 코드 편집
# - 계획에 따라 순차적으로 파일 수정
# - diff 생성 및 적용

음성 모드

# 음성으로 코딩 요청
aider --voice

# 마이크로 말하면 자동으로 텍스트 변환 후 실행

브라우저 모드

# 웹 브라우저 UI로 Aider 사용
aider --browser

# 브라우저에서 파일 트리, 대화, diff를 시각적으로 확인

Watch 모드

# 파일 변경 감지 모드
aider --watch

# 소스 코드에 AI 주석을 남기면 자동 실행
# 예: # AI: 이 함수에 에러 처리 추가해줘

비용 관리

Aider는 LLM API 호출 비용이 발생합니다. 효율적인 비용 관리를 위한 전략을 소개합니다.

비용 추적

# 세션 종료 시 비용 요약 표시
# Tokens: 12.5k sent, 3.2k received. Cost: $0.04

# 세션 중 토큰 사용량 확인
You> "/tokens"

비용 최적화 전략

# 비용 효율 극대화 설정 예시
aider \
  --model claude- \
  --cache-prompts \
  --map-tokens 1024

# Architect 모드 비용 최적화
aider --architect \
  --model claude- \
  --editor-model claude- \
  --cache-prompts

도구 비교

Aider vs Cursor vs Claude Code

터미널 기반의 Aider, IDE 통합의 Cursor, CLI 에이전트 Claude Code는 각각 다른 강점을 가지고 있습니다. 워크플로우에 맞는 도구를 선택하세요.

vs Codex

Aider는 Git 중심의 로컬 CLI 에이전트이고, Codex는 앱/웹/CLI에서 작업 단위로 실행되는 코딩 에이전트입니다. 팀의 워크플로우에 맞춰 선택하세요. 자세한 흐름은 Codex 가이드를 참고하세요.

모범 사례

활용 팁

• 작은 커밋: 한 번에 하나의 기능만 요청
• 명확한 요청: 구체적이고 명확하게 지시
• /add 활용: 관련 파일 모두 추가, 불필요한 파일은 /drop
• /diff 확인: 커밋 전 변경사항 검토
• Ollama 활용: 간단한 작업은 로컬 LLM으로 비용 절감
• read-only 활용: 참조만 필요한 파일은 /read-only로 추가
• 대화 초기화: 새로운 작업 시작 전 /clear
• 테스트 자동화: --auto-test로 품질 보증

피해야 할 패턴

• 너무 많은 파일 /add: 컨텍스트 초과로 품질 저하
• 모호한 요청: "코드 좋게 만들어줘" 대신 구체적 지시 필요
• 긴 대화 유지: 토큰 누적으로 비용 증가, 적절히 /clear
• /undo 없이 반복 수정: 불필요한 커밋 누적, 실패 시 /undo 후 재시도
• 린트/테스트 미설정: --auto-lint, --auto-test 미사용 시 오류 코드 커밋 가능

문제 해결

일반적인 문제

Not a git repository

해결: git init으로 Git 초기화

API 키 오류

해결: 환경 변수 확인 또는 .aider.env 파일 확인. Ollama 사용 시 API 키 불필요

파일이 수정되지 않음

해결: /add FILE로 파일 명시적 추가. /read-only로 추가된 파일은 편집 불가

diff 적용 실패

해결: --edit-format whole로 전환하거나, 파일이 외부에서 수정되지 않았는지 확인

컨텍스트 윈도우 초과

해결: /drop으로 불필요한 파일 제거, --map-tokens 값 축소, /clear로 대화 초기화

Ollama 연결 실패

# Ollama 서버 실행 확인
ollama serve

# 모델 다운로드 확인
ollama list
ollama pull llama3.2

# 디버깅 모드
aider --verbose

# 메시지 로그 파일 확인
# .aider.chat.history.md 에서 전체 대화 기록 확인 가능

핵심 정리

• Aider는 Git 네이티브 AI 코딩 도구로, 편집-테스트-커밋 사이클을 자동화합니다.
• 다양한 편집 포맷(whole, diff, udiff, architect)으로 모델과 작업에 최적화된 편집이 가능합니다.
• 리포지토리 맵(repo-map)이 프로젝트 구조를 자동 분석하여 LLM에 컨텍스트를 제공합니다.
• 다중 LLM 지원으로 비용과 품질을 유연하게 조절할 수 있습니다.
• .aider.conf.yml로 프로젝트별 설정을 체계적으로 관리합니다.
• 대규모 코드베이스에서는 /add, /drop, /read-only, .aiderignore로 컨텍스트를 효율적으로 관리하세요.
• --cache-prompts와 모델 계층화로 비용을 최적화하세요.