Aider 사용법：터미널에서 AI로 코드 짜는 법
설치부터 아키텍트 모드, 깃 커밋까지 한 번에 정리했습니다
- Aider는 터미널에서 직접 코드를 수정하는 오픈소스 AI 페어 프로그래밍 도구입니다.
- pip 한 줄로 설치하고, API 키만 넣으면 바로 코딩을 시작할 수 있습니다.
- 모든 수정 사항이 자동으로 git 커밋되어 언제든 되돌릴 수 있습니다.
- Claude, GPT, Gemini, 로컬 모델까지 100개 이상의 LLM을 골라 쓸 수 있습니다.
- 복잡한 작업은 아키텍트 모드로 계획과 구현을 분리해 처리합니다.
새 프로젝트에서 파일 열 몇 개를 고치는데 매번 IDE 창을 켜고, 마우스로 파일을 찾고, AI 확장 프로그램이 로딩되는 걸 기다린 적 있으신가요? Aider 사용법을 알면 이 과정을 통째로 건너뛸 수 있습니다.
Aider는 터미널 한 줄로 실행해서, 명령어로 파일을 지정하고 원하는 걸 말로 설명하면 AI가 실제 코드를 고쳐줍니다. 수정된 내용은 자동으로 git에 커밋되니 마음에 안 들면 바로 되돌릴 수 있습니다.
이 글에서는 Aider 사용법을 설치부터 실전 명령어, 아키텍트 모드, 자주 하는 실수까지 순서대로 다룹니다. 터미널이 낯설어도 따라올 수 있게 예시 위주로 설명하겠습니다.
Aider가 뭔가요? 터미널에서 돌아가는 AI 페어 프로그래머
Aider는 Paul Gauthier가 만든 오픈소스 AI 코딩 도구입니다. 커서나 윈드서프처럼 별도 에디터가 아니라, 기존에 쓰던 VS Code나 Vim, JetBrains 위에서 터미널로만 동작합니다.
동작 방식은 단순합니다. 작업할 파일을 채팅창에 추가하고, “로그인 함수에 입력값 검증 추가해줘”처럼 자연어로 요청하면 됩니다. Aider가 코드를 직접 수정하고, diff를 보여준 뒤 git에 커밋까지 마칩니다.
Apache 2.0 라이선스로 완전 무료이고, LLM 비용만 각 제공사에 직접 지불하는 구조입니다. GitHub 스타는 수만 개, PyPI 설치 수는 수백만 건에 달할 만큼 개발자 커뮤니티에서 자리를 잡았습니다.
Aider는 코드를 파일 단위로 통째로 다시 쓰지 않고, 필요한 부분만 diff 형태로 바꿉니다. 그래서 큰 파일도 처리 속도가 비교적 빠르고, git 히스토리도 깔끔하게 남습니다.
Aider 설치하고 첫 세션 시작하는 법
Aider 사용법의 첫 단계는 설치입니다. 파이썬 3.9~3.12가 깔려 있다면 pip 한 줄이면 끝납니다.
설치 명령어
가장 간단한 방법은 아래 명령어입니다. 가상환경을 쓰는 걸 권장하지만, 처음이라면 시스템 파이썬에 바로 설치해도 무방합니다.
uv나 pipx로 격리해서 설치하고 싶다면 pipx install aider-chat도 지원합니다. 설치 후 “aider command not found” 오류가 나오면 PATH 설정 문제이니 공식 문서의 설치 페이지를 참고하는 게 빠릅니다.
API 키 등록하고 실행하기
Aider는 자체 AI 모델이 없습니다. Claude나 GPT 같은 LLM에 API 키로 연결해서 씁니다. 터미널에 환경 변수로 키를 등록하면 됩니다.
cd /작업할/git저장소
aider –model sonnet
git 저장소 안에서 실행하는 게 핵심입니다. Aider는 git이 있어야 자동 커밋 기능을 쓸 수 있고, 저장소가 없으면 새로 초기화할지 물어봅니다.
API 키를 코드에 직접 적지 마세요. 터미널 히스토리나 공개 저장소에 실수로 노출되는 사고가 실제로 자주 일어납니다.
.env 파일이나 셸 프로필에 등록하는 방식을 권장합니다.Aider 사용법 기본기: 파일 추가부터 diff 확인까지
설치가 끝났다면 이제 실전입니다. Aider 사용법의 핵심은 세 가지 흐름입니다. 파일 추가, 요청 입력, diff 확인입니다.
먼저 수정할 파일을 명령줄 인자로 넘기거나, 세션 안에서 /add app.py처럼 추가합니다. 파일을 넣지 않아도 Aider가 저장소 맵을 보고 관련 파일을 찾아주지만, 명시적으로 지정하는 편이 정확도가 높습니다.
> 로그인 함수에 이메일 형식 검증 추가해줘
> validate_email 함수에 대한 단위 테스트 작성해줘
> 데이터베이스 연결을 컨텍스트 매니저 방식으로 리팩터링해줘
요청을 입력하면 Aider가 변경할 코드를 diff로 먼저 보여줍니다. 승인하면 파일에 반영되고, 동시에 의미 있는 커밋 메시지와 함께 git 커밋이 자동으로 생성됩니다.
Aider가 자동 커밋을 남기는 이유는 “AI가 뭘 고쳤는지” 항상 추적 가능하게 하려는 설계 철학 때문입니다. 마음에 안 드는 결과는
git revert 한 줄로 되돌릴 수 있어서, 실험적인 요청도 부담 없이 던져볼 수 있습니다.큰 저장소에서는 관련 없는 파일까지 컨텍스트에 다 넣으면 LLM이 오히려 헷갈릴 수 있습니다. 한 번에 한 기능 모듈만 집중해서 작업하는 게 정확도가 훨씬 높습니다.
아키텍트 모드와 모델 선택, 언제 어떤 조합이 좋을까
파일 하나 고치는 수준을 넘어 여러 파일에 걸친 리팩터링을 시킬 때는 기본 모드만으로 버거울 수 있습니다. 이럴 때 아키텍트 모드를 씁니다.
아키텍트 모드는 모델을 두 개로 나눠 씁니다. 하나는 계획을 세우는 역할(architect), 다른 하나는 실제 코드를 작성하는 역할(editor)입니다. 비싼 추론 모델로 설계만 시키고, 저렴한 모델로 구현을 맡기면 비용과 품질 균형을 잡을 수 있습니다.
모델 선택도 Aider 사용법에서 중요한 부분입니다. Aider는 특정 회사에 묶여 있지 않아서, 작업 성격에 따라 골라 쓸 수 있습니다.
작업별 모델 조합 예시
복잡한 아키텍처 변경이나 어려운 버그는 추론 강도가 높은 모델이 유리합니다. 반대로 단순 반복 수정이나 테스트 코드 생성은 빠르고 저렴한 모델로도 충분합니다.
세션 도중에도
/model 모델명 한 줄이면 바로 다른 모델로 갈아탈 수 있습니다. 어려운 부분만 강한 모델로 풀고, 나머지는 저렴한 모델로 마무리하는 식으로 비용을 아낄 수 있습니다.Aider vs 커서·코파일럿, 뭐가 다를까
같은 AI 코딩 도구라도 접근 방식이 다릅니다. 커서는 에디터 자체가 AI 중심으로 새로 만들어졌고, 코파일럿은 기존 에디터에 확장 프로그램으로 얹는 방식입니다.
Aider는 둘 다 아닙니다. 에디터를 바꾸지 않고, 지금 쓰던 VS Code나 Vim 옆에서 터미널로만 작동합니다. 파일 변경은 디스크에 직접 반영되니 에디터가 자동으로 감지합니다.
Aider의 강점은 “리뷰 가능한 변경 이력”입니다. AI가 만든 수정이 전부 커밋 단위로 남아서, 팀 코드 리뷰나 롤백이 표준 git 도구만으로 깔끔하게 됩니다. 반면 GUI가 없어서 터미널이 낯선 사람에게는 진입장벽이 있습니다.
Aider 자주 하는 실수와 해결법
Aider 사용법을 익히는 과정에서 초반에 자주 걸리는 함정들이 있습니다. 미리 알아두면 시행착오를 줄일 수 있습니다.
첫 번째는 파일을 추가하지 않고 요청하는 경우입니다. Aider가 관련 파일이 더 필요하다고 물어보면, 그건 애초에 그 파일을 세션에 넣었어야 했다는 신호입니다.
두 번째는 저장소 맵이 꺼진 채로 큰 프로젝트를 돌리는 경우입니다. 약한 모델은 저장소 맵 정보량에 오히려 압도당해서 엉뚱한 코드를 건드리기도 합니다. 이럴 땐 --map-tokens 옵션으로 맵 크기를 줄이는 게 낫습니다.
git이 없는 폴더에서 실행하면 자동 커밋 기능을 쓸 수 없습니다. 작업 전에 반드시
git init이나 기존 저장소 안으로 이동했는지 확인하세요.세 번째는 한 번에 너무 많은 걸 요청하는 경우입니다. “전체 코드 다 리팩터링해줘”보다 “데이터베이스 연결 부분만 컨텍스트 매니저로 바꿔줘”처럼 범위를 좁힐수록 결과 품질이 올라갑니다.
📘 Aider FAQ 공식 문서 보기❓ 자주 묻는 질문
git과 터미널 기본 명령어(cd, git status 정도)에 익숙하면 시작할 수 있습니다. 다만 결과 코드를 검증하려면 어느 정도 프로그래밍 지식이 있는 편이 안전합니다.
도구 자체는 Apache 2.0 라이선스로 무료입니다. 다만 Claude나 GPT 같은 LLM을 쓰려면 해당 API 비용은 별도로 지불해야 합니다. 로컬 모델을 쓰면 API 비용 없이 완전 무료로도 가능합니다.
네, pip로 설치하면 Windows·macOS·Linux 모두 동일하게 동작합니다. 음성 입력 기능(PortAudio)만 운영체제별로 설치 방식이 조금 다릅니다.
아닙니다. 파일 하나짜리 간단한 수정은 기본 모드가 더 빠릅니다. 여러 파일에 걸친 설계 변경이 필요할 때만 아키텍트 모드를 쓰는 게 효율적입니다.
모든 변경이 git 커밋으로 남기 때문에 /undo 명령어나 git revert로 바로 직전 상태로 되돌릴 수 있습니다.
📚 함께 보면 좋은 글
Aider 말고 다른 AI 코딩 도구가 궁금하다면 아래 글도 함께 보세요.
🔗 공식 자료
📖 출처
- Aider 공식 문서 — Installation, Usage, FAQ (aider.chat)
- Aider GitHub 저장소 (Aider-AI/aider)
- PyPI aider-chat 패키지 페이지
- Codegen, “Aider Review: Terminal AI Coding Agent” (2026)
- DeployHQ, “How to Use Aider in 2026: Setup, Architect Mode & Git Workflow”
Aider 사용법의 핵심은 파일 추가, 자연어 요청, diff 확인 세 가지뿐입니다. 에디터를 바꾸지 않고도 터미널에서 git 커밋까지 자동으로 관리되니, 지금 쓰는 워크플로에 그대로 얹어보세요.
