Aider + Qwen 로컬 구축 및 활용

    Aider와 Qwen 오픈 소스 LLM을 활용하여 로컬에 코딩 에이전트를 구축하는 방법을 공유하고자 글을 작성합니다.

    (MacOS를 기준으로 작성되었음을 알려드립니다.)

     

     

    ■ Aider 란?

    터미널(CLI)에서 실행되는 오픈소스 AI 페어 프로그래머 도구로 단순한 챗봇을 넘어 실제 프로젝트의 소스 코드를 직접 수정하고 Git과 연동하여 변경 사항을 자동으로 커밋해주는 강력한 툴입니다.

    • 코드 직접 수정: AI가 요청 사항에 대해 코드를 제안하고 파일에 즉시 적용합니다.
      - Default 설정 값이 즉시 적용으로 되어있기 때문에 원하지 않을 경우 실행 옵션 적용 필요
    • Git 통합: 작업이 완료되면 자동으로 적절한 커밋 메시지와 함께 커밋을 생성합니다.
    • 멀티 파일 지원: 여러 파일을 동시에 분석하고 수정 범위를 파악합니다.

     

    ■ LLM 이란?

    알리바바 클라우드에서 개발한 오픈소스 LLM 시리즈입니다. 굳이 Qwen을 사용하지 않아도 되고 구축하는 시점에 가장 높은 성능을 내는 모델을 다운받으시면 됩니다.

     

     

    ■ 로컬 구축의 장점

    1. 데이터 프라이버시: 코드가 외부 서버로 전송되지 않아 기업 기밀이나 개인 프로젝트 보안에 완벽합니다.

    2. 비용 제로: 구독료나 토큰 사용료 없이 하드웨어 성능만큼 무제한 사용 가능합니다.

    3. 오프라인 작업: 인터넷 연결 없이도 언제 어디서나 개발 보조를 받을 수 있습니다.

     

     

    ■ Aider 설치 전 사전 작업

    1. git 설치

    brew install git

     

    2. Universal Ctags 설치 (Aider 성능 최적화)

    brew install universal-ctags

     

     

    ■ Aider 설치 방법

    pip install aider-chat

     

     

    ■ LLM 설치 방법

    ollama run qwen3-coder:30b-a3b-q8_0

     

    • LM Studio 앱 이용
      1) 앱 설치 후 실행
      https://lmstudio.ai/download

      2) 좌측 사이드바에 'Model Search' 탭에서 모델 다운로드

    • Hugging Face (주로 ollama에 원하는 양자화 모델이 없을 경우 모델을 직접 다운로드 하는 용도로 많이 사용)
      https://huggingface.co/ 에 들어가서 모델 검색하고 원하는 양자화 모델 선택해서 GGUF 파일로 다운로드
      - gguf 파일로 직접 다운로드 할 경우, Ollama에 모델로 생성하거나 LM Studio에 모델을 등록할 수 있다.
    • 1) Ollama에 모델 생성 방법
      Modelfile을 이용하여 시스템 프롬프트를 주입하여 생성하면 좀 더 좋은 성능을 내는 모델을 생성할 수 있다.
    ollama create {원하는 모델명} -f {Modelfile 명}

     

    • Modelfile 예시
    # 1. 기반 모델 설정
FROM /모델이/설치되어/있는/경로/모델명.gguf

# 2. 파라미터 최적화
# 문맥 창 크기를 24k로 확장 (코드 분석 및 긴 대화에 유리)
PARAMETER num_ctx 32768
# MoE 모델의 창의성과 논리 균형을 위한 온도 설정 (0.4 ~ 0.5 권장)
PARAMETER temperature 0.35
# 답변의 일관성을 위한 상위 확률 필터링
PARAMETER top_p 0.9
PARAMETER top_k 40
# 한국어 문장의 자연스러운 마무리를 위한 반복 패널티
PARAMETER repeat_penalty 1.12
# 추론 시 사용하는 CPU/GPU 스레드 최적화 (자동 설정)
PARAMETER num_thread 11
# 답변이 중간에 잘리지 않도록 최대 토큰 설정 (-1은 무제한)
PARAMETER num_predict 8192
# stop sequence
PARAMETER stop "</analysis>"
PARAMETER stop "<|endoftext|>"

# 3. 시스템 프롬프트 (한국어 페르소나 및 코딩 능력 극대화)
SYSTEM """
너는 '큐웬 코더(Qwen Coder)'라는 이름의 고도로 지능화된 한국어 전문 AI 코딩 어시스턴트야.
하드웨어에 최적화된 상태로, 사용자에게 최상의 답변을 제공해야 해.

[한국어 커뮤니케이션 원칙]
- 모든 대화는 친절하고 전문적인 한국어 구어체로 진행한다.
- 기계적인 번역투를 지양하고, 한국의 기술 문화와 맥락에 맞는 자연스러운 문장을 구사한다.
- 복잡한 기술 용어는 한국어로 먼저 설명하고, 필요한 경우 괄호 안에 영문 원어를 표기한다.

[코딩 및 엔지니어링 지침]
- 너는 Qwen3-coder의 능력을 계승한 시니어 엔지니어다.
- 코드를 제안할 때는 항상 최신 안정 버전(Stable)의 라이브러리를 기준으로 한다.
- 가독성, 성능, 보안성 세 가지 측면에서 코드를 검토하고 최적의 솔루션을 제공한다.
- 긴 코드를 작성할 경우, 핵심 로직에 대한 주석을 한국어로 상세히 작성한다.

[사고 체계]
- 사용자의 질문이 모호할 경우, 의도를 명확히 파악하기 위한 질문을 먼저 던진다.
- 문제 해결 시 '단계별 사고(Chain of Thought)'를 적용하여 논리적 비약을 없앤다.
- 답변의 마지막에는 항상 사용자가 다음에 할 수 있는 행동이나 관련 팁을 한 줄로 요약한다.
"""

     

    • 2) LM Studio에 모델 생성 방법
    # LM Studio 모델 저장소에 복제
lms import /경로/모델명.gguf

# 심볼링 링크 생성
lms import /경로/모델명.gguf --symbolic-link

     

     

    ■ Aider 실행 옵션

    • --architect: 설계(Plan)와 구현(Write)을 분리하여 복잡한 로직 수정 시 더 정교한 결과물을 만들어내는 모드입니다.
    • --no-auto-accept-architect: Architect 모드가 제안한 수정 계획을 실제 파일에 적용하기 전에 사용자의 최종 승인을 대기합니다.
    • --no-auto-commits: AI가 코드를 수정할 때마다 자동으로 생성하던 Git 커밋 기능을 비활성화하여 사용자가 직접 커밋을 관리하게 합니다.
    • --auto-lint: 코드 수정 직후 문법 에러나 스타일 위반을 자동 검사하며, 오류 발견 시 AI가 스스로 다시 고치도록 유도합니다.
    • --auto-test: 코드가 바뀔 때마다 사전에 설정된 테스트 명령어를 자동으로 실행하여 기존 로직이 깨지지 않았는지 즉시 확인합니다.
    • --chat-mode <mode>: ask(질문만), code(수정 포함) 등 모드 설정.
    • --dark-mode / --light-mode: 터미널 테마에 맞게 UI 색상 조절.

     

    ■ Aider 실행 방법

    1. 모델 구동

    • Ollama 이용할 경우
    ollama run {모델명}

     

    • LM Studio 이용할 경우
      1) 앱 실행
      2) 좌측 사이드바 'Developer 탭' 이동
      3) 가운데 상단 'Load Model' 버튼 클릭
      4) 가운데 상단 'Status: Running' 토글 버튼 확인

     

    2. 터미널에서 작업할 프로젝트 루트 폴더로 이동

     

    3. 실행 구문 입력

    # Ollama 전용 실행 구문
aider --model ollama_chat/qwen3-coder --architect --auto-lint

# LM Studio 전용 실행 구문 (자유도가 높은 실행 옵션 적용)
aider --model custom_openai/qwen --openai-api-base http://localhost:1234/v1 --openai-api-key not-needed --architect --auto-lint

# LM Studio 전용 실행 구문 (Strict한 실행 옵션 적용)
aider --model custom_openai/qwen --openai-api-base http://localhost:1234/v1 --openai-api-key not-needed --no-auto-accept-architect --no-auto-commits --auto-lint

     

     

    ■ Aider 명령어

    • /add <file>: 분석 및 수정에 포함할 파일을 컨텍스트에 추가합니다.
    • /drop <file>: 컨텍스트에서 파일을 제외합니다.
    • /ask <질문>: 코드를 수정하지 않고 로직에 대해 물어보기만 할 때 사용합니다.
    • /undo: 마지막으로 수행한 코드 수정 및 커밋을 취소합니다.
    • /diff: 수정된 사항을 커밋하기 전에 미리 봅니다.
    • /exit: Aider를 종료합니다.
    • /help: 사용 가능한 모든 명령어를 확인합니다.

     

    ■ Aider 활용 사례

    • 신규 기능 구현: "기존 user.py 모델에 이메일 중복 체크 로직을 추가하고 API 엔드포인트를 업데이트해줘."
    • 버그 수정: 오류 메시지를 복사해 붙여넣으며 "이 에러가 발생하는데 database.py에서 원인을 찾아서 고쳐줘."
    • 코드 리팩토링: "전체적인 코드 스타일을 PEP8에 맞게 수정하고, 함수들을 더 작은 단위로 쪼개줘."
    • 테스트 코드 생성: "현재 프로젝트 구조를 분석해서 tests/ 폴더에 유닛 테스트들을 만들어줘."

     

    ■ git 관련 명령어 정리

    Aider를 이용하여 개발을 할 때, 편의를 위해 Auto Commit 옵션을 적용하는 경우가 많을 겁니다.
    변경 사항을 확인하는 명령어와 커밋 내역이 마음에 들지 않을 경우 유용하게 사용할 수 있는 명령어들을 정리해봤습니다.

     

    1. 커밋 히스토리 파악하기 (git log)

    프로젝트의 흐름을 파악하는 가장 기본이 되는 명령어입니다.

    • git log: 전체 커밋 히스토리를 상세히 보여줍니다.
    • git log --oneline: 커밋 하나를 한 줄로 요약해서 보여줍니다. (전체 흐름을 빠르게 훑을 때 유용)
    • git log --graph: 브랜치와 병합(Merge) 내역을 시각적으로 선을 그려 보여줍니다.
    • git log --all: 현재 브랜치뿐만 아니라 모든 브랜치의 로그를 표시합니다.
    • 추천 조합: git log --oneline --graph --all (터미널에서 프로젝트 전체 지도를 그릴 때 가장 많이 쓰입니다.)

     

    2. 변경 사항 자세히 보기 (git show, git diff)

    단순한 로그를 넘어, 어떤 파일의 어떤 코드가 바뀌었는지 확인해야 할 때 사용합니다.

    • git show: 특정 커밋(기본값은 최신 커밋)에서 발생한 변경 사항과 상세 정보를 출력합니다.
    • git diff HEAD: 현재 작업 디렉토리의 수정 사항과 마지막 커밋(HEAD)을 비교합니다. (커밋 전 검토용)
    • git diff <이전 커밋ID> <이후 커밋ID>: 서로 다른 두 커밋 사이의 차이점을 비교합니다.
    • git diff --stat HEAD: 바뀐 코드의 상세 내용 대신, 어떤 파일이 몇 줄이나 바뀌었는지 통계 정보만 간결하게 보여줍니다.

     

    3. 잘못된 커밋 되돌리기 (git reset)

    Git에서 가장 강력하면서도 주의해서 사용해야 하는 명령어입니다. 특정 커밋 상태로 돌아가고 싶을 때 사용하며, 세 가지 모드가 있습니다.

    💡 Reset의 3가지 모드

    1. --soft: 커밋 내역만 삭제하고, 수정된 파일들은 Staging Area(add된 상태)에 그대로 둡니다. 바로 다시 커밋할 때 유용합니다.
    2. --mixed (기본값): 커밋 내역을 삭제하고, 수정된 파일들을 Working Directory(add 전 상태)로 돌립니다.
    3. --hard: 주의! 지정한 커밋 이후의 모든 변경 사항을 완전히 삭제하고 깨끗하게 되돌립니다. (복구 불가하므로 신중히 사용)

     

    4. HEAD와 기호 활용법

    Git에서 HEAD는 '현재 내가 위치한 지점(보통 최신 커밋)'을 의미합니다.

    • HEAD (또는 @): 현재 커밋 상태.
    • HEAD~1 (또는 HEAD~): 바로 이전 커밋.
    • HEAD~2: 2단계 전 커밋 (숫자를 바꿔가며 거슬러 올라갈 수 있습니다.)

     

    5. 활용 예시

    • 현재 작업 중인 코드가 엉망이 되어 다 버리고 싶을 때: git reset --hard HEAD
    • 방금 한 커밋에 오타가 있어서 커밋만 취소하고 다시 수정하고 싶을 때: git reset --soft HEAD~1
    • @ 기호 사용: HEAD 대신 간단하게 '@'를 써도 동일하게 작동합니다. (예: git show @~1)

     

    6. 요약 및 팁

    • 흐름 확인: git log --oneline --graph --all
    • 변경 확인: git diff HEAD
    • 커밋 수정: git reset --soft HEAD~1 후 다시 커밋
    • 완전 초기화: git reset --hard HEAD

     

    저작자표시 비영리 변경금지 (새창열림)

    'AI > Tools' 카테고리의 다른 글

    이미지 및 비디오 생성 워크플로우 로컬 구축  (1) 2026.02.28

    관련글

    댓글

    라이브러리 브랜드 그룹 | Hormone-like developer

    티스토리툴바