개발 도중 AI 모델이나 에이전트를 바꿔도 품질을 유지하는 법: 리포지토리에 남겨야 할 3가지 원칙

AI 코딩 에이전트를 사용한 중대형 개발에서는 개발 과정 중에 모델이나 에이전트를 변경해야 하는 상황이 반드시 발생합니다.

대표적인 이유는 비용 재검토, 새로운 모델의 등장, 이용 가능한 프로바이더(provider) 변경, rate limit(사용량 제한) 도달, 또는 사내에서 사용하는 툴 변경(예: Claude Code에서 Cursor나 Cline으로 전환 등) 등이 있습니다.

하지만 막상 개발 도중에 모델을 전환하면 현장에서는 종종 아픈 트러블이 발생합니다. “방금까지의 일관된 설계 방침이 갑자기 무시된다”, “에러 처리 방식이나 테스트 작성법이 갑자기 제각각으로 바뀐다”와 같은 경우입니다. 저 자신도 모델을 변경한 직후, 이전 세션에서 2시간 동안 공들였던 설계 전제가 쉽게 뒤집히고 다른 방식으로 코드가 덮어씌워져서 난감했던 경험이 있습니다.

그렇다면 어떻게 해야 중간에 교체로 인한 품질 저하와 재작업을 막을 수 있을까요?

본 기사에서는 다음 세 가지 질문에 순차적으로 답해나갑니다.

중간에 바꾸면 왜/무엇이 발생하는가
품질과 효율을 유지하려면 사전에 무엇을 준비해야 하는가
실제로 바꿀 때는 어떤 절차로 진행해야 하는가

미리 결론부터 말씀드리자면, 판단과 상태를 모델의 머릿속이 아닌 리포지토리(repository)에 남겨두면 (컨텍스트 의존성이 낮아짐), 전환으로 인한 영향은 직후 몇 턴 정도만 지나도 해결됩니다.

1. 전환 시 무엇이 발생하는가

1.1 손실되는 것들

모델이나 에이전트를 변경할 때 발생하는 문제점 대부분은 “이전 모델의 머릿속에만 존재했던 것”이 사라지면서 생겨납니다.

┌─────────────────────────────────────────────────────────────┐
│ 이전 모델의 머릿속 (대화 컨텍스트・사고 과정) │
│ ・왜 이 설계를 했는지 (폐기된 안과 그 이유)
... 

여기에 더해, 모델 자체의 능력 차이 (하위 모델이나 경량 모델로 변경했을 경우, 복잡한 수정이 무너지기 쉬움)와, 상황을 파악하고 재정비하기 위한 토큰 소비 및 대기 시간이 발생합니다.

1.2 무엇을 바꾸느냐에 따라 영향의 크기가 달라진다

‘전환’이라고 해도, 같은 에이전트 내에서 모델만 변경하는 것인지, 아니면 에이전트(하우징) 자체를 변경하는지에 따라 인계되는 범위가 다릅니다.

| 비교 항목 | 모델만 변경할 때 | 에이전트 전체를 변경할 때 |
|---|---|
| 규약 파일・툴・권한 | 그대로 유지됨 | 에이전트 고유의 것 (훅, 권한, 규약 파일명)은 인계되지 않음 |
| 대화 기록 | 텍스트는 남아있지만, 사고 과정(reasoning)은 손실되는 경우가 많음 | 인계되지 않음 (새로운 세션 시작) |
| 작성 방식의 습관・툴 사용법 | 계통이 같은 모델끼리라면 차이가 작음 | 차이가 큼 |
| 일시적 비용 | 프롬프트 캐시가 무효화되어, 전환 직후에 비용과 대기 시간이 증가함 | 상황 재파악이 필요해짐 |
| 영향의 크기 | 작음 | 큼 |

그렇다고 해도, 어느 경우든 대응하는 생각 방식은 완전히 동일합니다. 차이는 에이전트 전체를 변경할 경우에 “에이전트 고유 설정을 옮기는 작업”이 추가될 뿐입니다 (구체적인 이전 절차는 3.2절에서 설명하겠습니다).

2. 대응 원칙: 머릿속이 아닌, 리포지토리에 남기기

전환으로 인해 손실되는 것들을 특정 모델에 의존하지 않는 세 가지 장소에 나누어 보관합니다.

| 남겨야 할 것 | 보관 위치 | 역할 |
|---|---|
| 컨텍스트 (방침・판단・진척도) | 파일 | 새로운 모델이 “무엇을, 왜” 알게 하는 기준 |
| 품질의 기준 | 툴 | 어떤 모델이 작성하든 같은 기준으로 판단하게 함 |
| 경위 (무엇을 언제 바꿨는지) | git | 작업 기록과 실패했을 때 복구 수단 |

2.1 컨텍스트를 파일에 남기기

채팅 대화만으로 방침을 결정하는 것을 멈추고, 다음 세 가지 종류의 파일로 리포지토리에 영속화해야 합니다.

특히 효과적인 것은 ADR(Architecture Decision Record)의 “왜 그 안을 채택하지 않았는지”에 대한 기록입니다. 이것이 없으면, 교체된 새로운 모델이 “이쪽 작성 방식이 더 일반적이에요”라며 과거에 검토하여 폐기했던 방식으로 임의로 리팩토링하는 사고가 빈번하게 발생합니다.

운영 포인트

• 규약의 본체는 : 에이전트 고유 파일(AGENTS.md)에 본체를 작성하지 않고, CLAUDE.md나 .cursorrules 등은 AGENTS.md를 참조하는 설정만 작성합니다. 이렇게 하면 에이전트를 교체해도 규약을 이중으로 관리할 필요가 없습니다.
• 명시적이고 구조화된 방식으로 작성 : 특정 모델의 ‘문맥을 읽는 능력’에 의존한 모호한 지시는 피하고, 절차와 조건을 목록 형태로 명확하게 정의합니다.

<!-- AGENTS.md (발췌) -->
## 세션 시작 시 반드시 수행할 것
1. `git status`로 커밋되지 않은 변경 사항이 없는지 확인한다
...

2.2 품질을 도구로 강제하기

왜 도구인가

규약 파일에 작성한 자연어 지시는 어디까지나 모델에 대한 ‘요청’입니다. 상위 모델이라면 정성껏 지켜주겠지만, 모델을 바꾼 순간 준수하는 방식이 제각각으로 달라집니다.

반면, 도구를 이용한 기계적인 체크는 ‘강제’입니다. 어떤 모델이 작성했든 코드에 대해 매번 오차 없이 동일한 기준을 적용할 수 있습니다.

무엇을 사용할까 (Python 예시)

운영 포인트

• 명령어는 : 훅(hook), pre-commit, CI 어느 곳에서든 이 두 가지만 호출하도록 합니다. 이렇게 하면 도구의 세부 옵션 설정이 에이전트로부터 숨겨지고, 에이전트에 의존하지 않게 됩니다. make fmt와 make check 두 가지로 통합합니다.

fmt:
ruff format . && ruff check --fix .
check:
...

• 자가 수정 루프를 돌리기 : make check의 결과를 에이전트에게 반환하고, 오류가 사라질 때까지 스스로 수정하게 합니다. 에이전트에 훅 기능(Post-tool-use hook 등)이 있다면, 파일 편집할 때마다 자동으로 make fmt를 실행하도록 만듭니다.
• “오류 제거의 허점”을 CI에서 막기 : 여기가 실무상의 급소입니다. 모델은 오류가 쉽게 사라지지 않을 때, 체크를 통과시키기 위해서 같은 ‘꼼수’를 부릴 수 있습니다. 이는 규약으로 금지하고, CI에서도 차이점을 이용해 기계적으로 감지하여 실패 처리합니다. # noqa를 붙이는 것, 테스트를 skip하는 것, 설정 파일을 느슨하게 만드는 것을 막습니다.

git diff --name-only origin/main | grep -E 'pyproject.toml|pre-commit|workflows' && exit 1
# noqa / type: ignore / skip 추가를 감지
...

• 중요한 테스트는 사람이 검토 : 테스트 코드 자체도 모델에게 작성하게 하면, 자신의 구현에 맞춘 ‘쉬운 테스트(느슨한 어설션)’가 되기 쉽습니다. 중요한 사양의 테스트는 반드시 인간이 리뷰해야 합니다.

2.3 경위를 git에 남기기

왜 git인가

Git 기록이 잘 정리되어 있다면, 새로운 모델은 '무엇을, 언제, 왜 변경했는지'를 스스로 추적할 수 있습니다. 작업 실패 시 안전하게 되돌릴 수도 있으며, pre-commit이나 CI에서의 차분 검사 역시 git이 전제됩니다.

운영 포인트

• 기록의 유무보다 커밋의 질이 전부: fix나 WIP 같은 잡다한 커밋들이 아무리 많이 쌓여 있어도, 새로운 모델은 문맥을 읽어낼 수 없습니다. 1개의 태스크를 1개의 커밋으로 하고, 커밋 메시지 본문에 '이유'와 '미처리 사항'을 작성하도록 합니다.

feat(alert): 알림 대장 대조 추가
- 알림 ID와 메시지 본문 모두로 대조 (ID만으로는 기기별 중복 발생)
- 미처리: 다른 제품의 알림 형식 (다음 태스크)

• 기록을 조사하는 절차를 : 관찰하고 있으면 알 수 있겠지만, 에이전트는 '현재 상태'(AGENTS.md에 명시된 git status 또는 최근 커밋 목록)는 스스로 찾아보지만, '변경의 이유'를 git log -p나 git blame으로 깊게 파고드는 것은 자발적으로 잘 하지 않습니다. 따라서 세션 시작 시 확인 절차로 AGENTS.md에 포함해 두는 것이 확실합니다(2.1절 예시 참조).
• 읽기 계열의 git 명령어는 승인 없이 허용 : status, log, diff, blame, show 같은 읽기 전용 명령어마다 매번 사람의 승인이 필요하다고 하면, 에이전트는 확인하는 과정을 귀찮아하며 생략하려 할 것입니다. 이들은 자동 실행을 허가해 둡니다.
• git에 남지 않는 것은 파일과 역할 분담 : git에 남는 것은 '커밋된 코드의 변경'뿐입니다. 아직 착수하지 않은 계획은 PROGRESS.md에, 채택하지 않은 안건은 ADR(Architecture Decision Record)에 남깁니다.

3. 실습: 전환의 구체적인 절차

실제로 개발 도중 모델이나 에이전트를 전환할 때는 '전환 전 - 전환 시 - 전환 후'의 3단계로 진행합니다.

[1. 전환 전] [2. 전환 시] [3. 전환 후]
・태스크 구분의 확인 ・규약 참조・훅・권한 등 상황과 계획을 요약하여 사람이 확인
・미커밋 변경 사항 해소, 이관 (에이전트 교체 시)・소태스크로 자가 수정 루프 검증
...

3.1 전환 전

• 작업이 태스크의 경계에 도달했는지 확인 : 파일 편집이나 툴 호출을 하는 도중에는 절대 바꾸지 않습니다.
• 미커밋된 변경 사항 해소 : 커밋하거나, 불필요하다면 폐기하여 워킹 트리를 깨끗하게 만듭니다.
• 이전 모델에게 : 현재 상태, 결정한 내용과 그 이유, 다음 작업을 작성하도록 합니다. PROGRESS.md와 인계 메모를 업데이트시킵니다.
  (예: make check가 통하는 상태에서 태그를 다는 git tag before-switch): 전환 후 오류가 발생했을 때, '원래부터 고장 났는지, 새로운 모델이 망가뜨린 것인지'를 즉시 구분할 수 있도록 하기 위함입니다.

3.2 전환 시 (에이전트별로 바꿀 경우만)

에이전트별로 교체하는 경우에는 에이전트 고유의 설정을 새로운 환경으로 이관합니다.

모델만 바꾸는 경우에는 이 작업이 필요 없습니다. 다만, 지금까지의 대화 기록이 길어진 경우라면, 그대로 이전 기록을 이어받기보다는 새로운 세션을 열고 AGENTS.md와 PROGRESS.md를 읽게 하여 시작하는 것이 컨텍스트 오염 없이 안정적입니다.

3.3 전환 후

• 상황과 작업 계획을 요약하여 사람이 확인 : 갑자기 코드를 작성하게 하지 말고, 먼저 AGENTS.md와 PROGRESS.md

ADR과 git 이력을 읽게 하고 현재 상황 인식과 향후 작업 계획을 요약하게 합니다. 불일치가 있으면 여기서 수정합니다.

작은 확인용 태스크로 '자가 수정 루프(Self-Correction Loop)'를 시도합니다. 처음부터 큰 변경을 맡기지 않고, 작은 태스크를 통해 "에러를 우회 경로(noqa 등)로 지우지 않고 정면으로 고칠 수 있는지"를 확인합니다.

초기 몇 개 태스크를 중점적으로 리뷰합니다: 궤도에 오르기 전까지의 몇 개 태스크는 설정 파일 변경, noqa나 skip 증가 여부, 테스트 어설션(assertion)이 약해지지 않았는지 사람이 중점적으로 확인합니다.

4. 요약 (Summary)

모델이나 에이전트를 전환할 때 손실되는 것은 '이전 모델의 머릿속에만 존재했던 것'입니다. 이를 다음 세 곳에 남겨두면, 도중에 모델이나 에이전트를 바꿔도 품질이 크게 무너지지 않습니다.

• 문맥은 파일에: AGENTS.md, ADR, PROGRESS.md
• 품질 기준은 툴에: make check를 완료 조건으로 삼고, pre-commit과 CI에서 강제합니다.
• 경위는 git에: 태스크당 하나의 커밋(commit)으로 하고, 변경 이유를 작성합니다.

그 위에, 태스크 경계에서 전환하고, 바꾼 직후에는 사람이 요약과 차이점(diff)을 확인합니다. 특정 모델에 의존하지 않는 이러한 진행 방식은 모델 교체에 대한 대비가 될 뿐만 아니라, 일상적인 AI 구동 개발의 품질 자체를 지탱하는 견고한 기반이 됩니다.

여러분의 현장에서는 모델이나 에이전트를 전환할 때 어떤 노하우를 가지고 계신가요? 댓글란에 지식을 공유해 주세요!

토론 (Discussion)