Aider 완전 가이드 — Git에 사는 AI 페어프로그래머, 모든 변경이 자동 커밋

Claude Code는 Claude에만 묶이고, Cursor는 IDE에 묶입니다. Aider는 어디에도 묶이지 않습니다. 터미널에서 돌고, 어떤 모델이든 붙고, 모든 변경이 자동으로 Git에 커밋됩니다. 코드 히스토리가 곧 AI 작업 로그입니다.

[핵심 요약]
→ Aider: 터미널 기반 AI 페어프로그래밍 도구 — Apache 2.0 오픈소스
→ Git-Native: 모든 변경 자동 원자 커밋 + 설명 메시지 — /undo 한 방에 롤백
→ 모델 무관: 100개+ 모델 지원 (Claude, GPT, Gemini, DeepSeek, Ollama)
→ 편집기 무관: VS Code, Vim, Emacs, SSH 터미널 — 어디서든 동일한 워크플로우
→ Repo Map: tree-sitter로 전체 코드베이스 구조 자동 분석
→ Architect 모드: 계획(고성능 모델) + 구현(저렴한 모델) 분리로 비용 최적화
→ Watch 모드: 코드에 AI! 주석 달면 자동 실행
→ GitHub 25,000+ 스타, SWE-bench 상위권

---

Claude Code vs Cursor vs Aider — 포지션

Claude Code:
→ Anthropic 모델 전용
→ 최고 코드 품질
→ 유료 구독

Cursor:
→ VS Code 기반 IDE
→ 빠른 자동완성 특화
→ 시각적 diff, 멀티파일 편집

Aider:
→ 터미널 전용, IDE 무관
→ 어떤 모델이든 — Claude, GPT, DeepSeek, Ollama
→ 모든 변경 자동 Git 커밋 + 롤백
→ 도구 자체는 무료 (API 비용만)
→ SSH 서버, iPad 터미널, CI/CD에서도 동일하게 동작
→ 레거시 코드베이스 대규모 리팩토링에 특히 강함

---

실전 1 — 설치 및 첫 실행

# 설치
pip install aider-install
aider-install

# 또는
pip install aider-chat

# Claude로 시작
export ANTHROPIC_API_KEY=your-key
aider --model sonnet  # claude-sonnet-4-6

# GPT로 시작
export OPENAI_API_KEY=your-key
aider --model gpt-5.4

# DeepSeek (저렴)
aider --model deepseek/deepseek-chat \
      --api-key deepseek=your-key

# 로컬 모델 — 완전 무료
aider --model ollama/qwen3-coder:7b

# 첫 실행 시
# → .gitignore에 .aider.* 추가 여부 확인 → 승인
# → git init 없는 디렉토리면 자동 생성 제안

# 파일과 함께 시작
aider src/auth.py src/middleware.py tests/test_auth.py

# 또는 실행 후 채팅에서 추가
aider
> /add src/auth.py src/middleware.py
> /read docs/api-spec.md  # 읽기 전용 컨텍스트 (편집 안 됨)

---

실전 2 — Git-Native 워크플로우

Aider의 핵심 차별점입니다. 모든 변경이 자동으로 원자 커밋됩니다.

# 기능 개발 예시
git checkout -b feature/jwt-auth
aider src/auth.py src/models/user.py tests/test_auth.py

> JWT 기반 인증 구현해줘:
> 1. 로그인 엔드포인트 → JWT 토큰 반환
> 2. 토큰 검증 미들웨어
> 3. 리프레시 토큰 처리
> 테스트도 같이 작성해줘

# Aider가 실행하는 것:
# 1. 파일 수정
# 2. 자동 커밋: "feat: implement JWT auth with login endpoint and middleware"
# 3. 자동 커밋: "test: add JWT auth test coverage"

# git log 확인
git log --oneline
# a3f1b2c feat: implement JWT auth with login endpoint and middleware
# 8d2e4f1 test: add JWT auth test coverage
# (이전 커밋들...)

# 결과가 마음에 안 들면
/undo          # 마지막 커밋 즉시 롤백
/undo          # 한 번 더 — 그 전 커밋도 롤백

# diff 확인
/diff          # 현재 변경사항 확인

# 수동 커밋
/commit        # 현재 변경사항 커밋

# 아무 git 명령
/git log --oneline -5
/git diff HEAD~2
/git stash

---

실전 3 — 채팅 모드 4가지

# code 모드 (기본) — 바로 코드 수정
> JWT 토큰 만료 시간을 15분으로 변경해줘

# ask 모드 — 코드 수정 없이 질문
/ask
> 현재 인증 구조에서 refresh token을 어떻게 구현하는 게 좋을까?

# architect 모드 — 계획 먼저, 승인 후 구현
/architect
> 전체 인증 시스템을 OAuth2.0으로 마이그레이션하는 계획 세워줘

# help 모드 — Aider 사용법 질문
/help
> watch 모드는 어떻게 써?

Architect 모드 — 비용 최적화 핵심

# 강력한 모델로 계획, 저렴한 모델로 구현
aider \
  --model claude-opus-4-6 \        # architect: 복잡한 계획 수립
  --editor-model claude-sonnet-4-6  # editor: 실제 코드 작성 (더 저렴)

# 또는
aider \
  --model gpt-5.4 \                # architect
  --editor-model deepseek/deepseek-chat  # editor (훨씬 저렴)

/architect
> 현재 모놀리스를 마이크로서비스로 분리하는 단계별 계획 세워줘

# Architect 모델이 계획 수립 → 사용자 검토 → 승인
# Editor 모델이 실제 파일 수정 → 자동 커밋

[비용 비교 — Architect 모드]
일반: Claude Opus로 전체 실행 → 비쌈
Architect 모드: Opus로 계획(짧음) + Sonnet으로 구현(저렴)
→ 동일 품질, 비용 40~60% 절감

---

실전 4 — Watch 모드: IDE에서 AI! 주석으로 제어

터미널 열기 귀찮을 때, 에디터 안에서 바로 Aider 호출합니다.

# 백그라운드에서 Watch 모드 실행
aider --watch-files

# 에디터에서 코드에 주석 추가 → 저장하면 자동 실행

def calculate_tax(price, rate):
    # AI! 입력값 검증 추가해줘. 음수면 ValueError 발생시켜
    return price * rate

# → 파일 저장 → Aider 감지 → 자동 수정 → 커밋
# → 에디터가 변경된 파일 자동 반영

// JavaScript / TypeScript
async function fetchUser(id) {
    // AI! 에러 핸들링 추가하고 타입 안전하게 만들어줘
    const res = await fetch(`/api/users/${id}`);
    return res.json();
}

-- SQL도 지원
-- AI! 이 쿼리에 인덱스 힌트 추가하고 성능 최적화해줘
SELECT * FROM orders WHERE user_id = 123;

[AI 주석 문법]
# AI!   → 즉시 실행 (코드 수정)
# AI?   → 질문 (코드 수정 없이 답변)
# AI    → 여러 줄 지시 (! 없으면 즉시 실행 안 함)

장점:
→ 터미널 전환 없이 에디터에서 바로
→ 주석이 작업 로그로 남음
→ /undo로 롤백 가능

---

실전 5 — 실전 커맨드 모음

# ── 파일 관리 ─────────────────────────────────────
/add src/auth.py tests/test_auth.py  # 파일 추가
/add src/**/*.ts                     # glob 패턴
/drop src/auth.py                    # 파일 제거
/read docs/spec.md                   # 읽기 전용 컨텍스트
/ls                                  # 현재 추가된 파일 목록

# ── 모델 전환 ─────────────────────────────────────
/model claude-sonnet-4-6             # 세션 중 모델 교체
/model deepseek/deepseek-chat        # 저렴한 모델로 전환
/model ollama/qwen3-coder:7b         # 로컬 모델로

# ── Git ───────────────────────────────────────────
/undo                                # 마지막 커밋 롤백
/diff                                # 변경사항 확인
/commit                              # 수동 커밋
/git log --oneline -5                # git 명령 직접 실행

# ── 테스트 + 린트 ─────────────────────────────────
/test pytest tests/                  # 테스트 실행 + 실패 시 자동 수정
/run npm run lint                    # 린터 실행
/lint                                # 감지된 린터 자동 실행

# ── 컨텍스트 ─────────────────────────────────────
/web https://docs.stripe.com/api     # 웹 페이지 컨텍스트 추가
/map                                 # 현재 Repo Map 보기
/map-refresh                         # 대규모 리팩토링 후 맵 갱신
/tokens                              # 현재 토큰 사용량 확인

# ── 기타 ─────────────────────────────────────────
/ask 이 코드 어떻게 동작해?           # 수정 없이 질문
/voice                               # 음성으로 지시 (마이크 필요)
/paste                               # 클립보드 내용 붙여넣기
/clear                               # 채팅 히스토리 초기화

---

실전 6 — .aider.conf.yml 설정

매번 옵션 타이핑 없이 기본값 저장합니다.

# ~/.aider.conf.yml — 글로벌 설정

# 기본 모델
model: claude-sonnet-4-6
editor-model: deepseek/deepseek-chat

# 자동 기능
auto-lint: true          # 매 편집 후 린트 자동 실행
auto-test: true          # 매 편집 후 테스트 자동 실행
test-cmd: pytest         # 테스트 명령

# Repo Map
map-tokens: 2048         # 큰 코드베이스면 늘림 (기본 1024)

# 출력
dark-mode: true
pretty: true
stream: true             # 스트리밍 응답

# 비용 절감
cache-prompts: true      # 프롬프트 캐싱 (Claude, GPT 지원)

# 프로젝트별 — 프로젝트 루트/.aider.conf.yml

# 팀 공통 모델
model: claude-sonnet-4-6

# 프로젝트별 린트/테스트
lint-cmd: "npm run lint"
test-cmd: "npm test"
auto-lint: true
auto-test: true

# 컨벤션 파일 자동 로드
read:
  - docs/CONVENTIONS.md
  - docs/API_SPEC.md

---

마무리

✅ Aider가 빛나는 경우
→ 어떤 LLM이든 쓰고 싶을 때 (모델 벤더 락인 거부)
→ Git 히스토리를 AI 작업 로그로 쓰고 싶을 때
→ SSH 서버, 원격 환경에서 AI 코딩 필요할 때
→ 대규모 레거시 코드 리팩토링 (Repo Map 강점)
→ IDE 없는 환경 (Vim, Emacs, 서버 터미널)
→ 저렴하게 쓰고 싶을 때 (DeepSeek + Aider 조합)

❌ Aider가 안 맞는 경우
→ GUI, 시각적 diff가 필요한 경우 (Cursor가 더 적합)
→ 터미널 불편한 사람 (Claude Code, Cursor 권장)
→ 자동완성 + 인라인 제안이 주요 워크플로우인 경우
→ 팀 표준 툴이 IDE 기반인 경우

---

관련 글

• OpenCode 완전 가이드 — 오픈소스 터미널 AI 에이전트
• Claude Code 한도 자꾸 걸리는 이유와 요금제 선택 가이드
• Goose 완전 가이드 — Block이 만든 오픈소스 AI 에이전트