dry-run이란? AI 코딩 도구에서 설정을 바꾸기 전 미리 확인하는 방법
AI 코딩 도구를 처음 사용하면 이런 안내를 볼 수 있습니다. “실행하면 설정 파일을 변경합니다. 먼저 dry-run으로 확인해 보세요.” 이 문장의 뜻이 궁금하신가요? dry-run(드라이런)은 명령을 실제로 적용하기 전에, 예상되는 작업이나 변경 내용을 미리 계산하고 보여주는 실행 방식을 말합니다. 쉽게 설명하면 집안 가구를 옮기기 전에 새 배치도를 미리 그려보는 것과 비슷합니다. 실제 가구를 옮기지 않은 상태에서 배치가 어떻게 달라질지 확인하는 것이죠. 하지만 처음부터 알아둘 중요한 차이가 있습니다. dry-run이 있다고 해서 모든 프로그램에서 부작용이 전혀 없다는 뜻은 아닙니다. 무엇을 미리 보여주고 무엇을 실행하지 않는지는 프로그램마다 다릅니다. 이 글에서는 AI 코딩 도구 FreeLLMAPI의 실제 공식 문서를 중심으로 의미·사용 방법·검수 포인트·안전상의 한계를 살펴봅니다.
이 글의 순서
- 1. dry-run을 가장 쉽게 이해하는 비유
- 2. 설정 파일 변경에서 dry-run을 쓰는 이유
- 3. FreeLLMAPI에서 실제 지원하는 dry-run은?
- 4. 실제 명령어는 어떻게 생겼나요?
- 5. diff란 무엇인가요?
- 6. dry-run 결과에서 무엇을 확인해야 하나요?
- 7. dry-run을 했으면 실제 설정도 자동 변경되나요?
- 8. dry-run이 모든 부작용을 방지하나요?
- 9. dry-run, 테스트, 시뮬레이션, 백업은 무엇이 다른가요?
- 10. 어떤 상황에서는 dry-run을 믿으면 안 되나요?
- 11. AI에게 안전하게 명령을 검토해 달라고 요청하는 방법
- 12. 자주 묻는 질문(FAQ)
1. dry-run을 가장 쉽게 이해하는 비유
워드 문서에서 ‘찾아 바꾸기’를 100번 실행하려고 한다고 생각해 보세요. 실제로 실행하면 잘못된 단어까지 바뀔 수 있습니다. 미리보기 기능이 있다면 먼저 어떤 단어가 어디에서 어떻게 바뀔 예정인지 확인할 수 있겠죠. dry-run이 지원되는 명령도 비슷합니다.
- 일반 실행: 프로그램이 실제 변경을 수행할 수 있습니다.
- dry-run 실행: 프로그램이 지원하는 범위 안에서 변경 계획이나 차이를 먼저 보여줍니다.
- 사람의 검토: 변경 대상과 결과를 보고 적용할지 결정합니다. 이때 핵심은 dry-run이 독립된 하나의 범용 프로그램이 아니라, 각 명령이 구현해 놓은 선택 기능 또는 실행 모드라는 점입니다. 그래서 어떤 도구의 dry-run은 파일 작성을 막고, 다른 도구의 dry-run은 배포 작업을 시뮬레이션하거나 서버에 보내려던 요청 내용을 보여줄 수 있습니다.
2. 설정 파일 변경에서 dry-run을 쓰는 이유
AI 코딩 도구를 다른 모델 서버와 연결할 때 설정 파일을 변경해야 하는 경우가 있습니다. 예를 들어 기존 Codex CLI 설정에 새로운 API 공급업체를 추가하고 싶다고 해보겠습니다. 설정을 바로 적용하면 다음과 같은 문제가 생길 수도 있습니다.
- 기존에 쓰던 제공업체의 설정이 덮어써짐
- API 주소를 잘못 지정해 연결이 끊김
- 의도하지 않은 모델이 기본값으로 선택됨
- 비밀번호나 API 키가 설정 파일에 불필요하게 들어감
- 여러 설정 항목이 한 번에 바뀌어 원인 파악이 어려워짐 dry-run은 실제 적용 전에 이러한 변경 예정 내용을 사람이 검토할 기회를 줍니다. 다만 dry-run이 보여주는 결과를 사람이 꼼꼼하게 읽지 않으면 이 장점은 사라집니다.
3. FreeLLMAPI에서 실제 지원하는 dry-run은?
FreeLLMAPI는 여러 AI 모델을 로컬 게이트웨이에 연결하는 프로젝트입니다. 개발자 공식 CLI 문서에서는 여러 AI 코딩 도구의 설정을 생성하는 명령에 --dry-run 옵션을 지원한다고 명시합니다. 특히 설정 생성기에서 이 옵션은 다음 의미입니다. “변경 예정 파일의 diff를 출력하고, 해당 설정 파일에는 쓰지 않는다.” 공식 CLI 구현도 파일의 새 내용을 먼저 계산하고, dry-run일 때 실제 쓰기 단계 대신 계산 결과를 반환하도록 구현돼 있습니다. 단, FreeLLMAPI의 모든 명령에 적용되는 것은 아닙니다. 예를 들어 개발자 문서에 따르면 제공업체 키를 관리하는 keys 명령은 --dry-run을 지원하지 않으며 요청하기 전에 거부합니다. 따라서 같은 프로그램에서도 명령 종류에 따라 지원 범위가 다르다는 점을 꼭 기억해야 합니다.
4. 실제 명령어는 어떻게 생겼나요?
원문에서 소개한 FreeLLMAPI 설정 확인 명령은 다음과 같습니다.
npx freellmapi setup-codex --url http://localhost:3001 --dry-run
이 명령은 설명용 예시이며, 이 글을 작성하면서 실제로 실행한 것은 아닙니다. 각 부분을 나눠 살펴볼까요?
| 부분 | 역할 |
|---|---|
| npx | npm 패키지 기반 명령을 실행하는 도구 |
| freellmapi | 실행하려는 CLI 패키지 |
| setup-codex | Codex CLI 설정 생성 명령 |
| --url | FreeLLMAPI 게이트웨이의 주소 |
| --dry-run | 해당 설정 파일의 변경 예정 내용만 보여주는 옵션 |
실제로 사용하려면 공식 문서에서 요구하는 Node.js 버전, 실행 중인 FreeLLMAPI 게이트웨이, 필요한 인증 설정 등을 갖춰야 합니다. 주소의 localhost는 이 명령을 실행하는 컴퓨터 또는 실행 환경 자신을 가리킵니다. 서버가 실제로 없다면 연결에 실패할 수 있습니다. 참고로 npx가 필요한 패키지를 내려받거나 로컬 캐시에 기록할 수 있다는 점도 중요합니다. FreeLLMAPI 설정 생성기가 설정 파일을 수정하지 않는다는 사실과 npx 실행 환경에 어떠한 파일 쓰기·네트워크 활동도 없다는 주장은 다릅니다.
5. diff란 무엇인가요?
dry-run 출력에서 자주 등장하는 단어가 diff입니다. diff는 기존 내용과 새 내용의 차이를 나타내는 표현입니다. 예를 들어 설정 파일에 다음과 같은 값이 있다고 가정해 보겠습니다.
기존 설정: model = "existing-model"
변경 예정: model = "new-model"
diff 형식에서는 흔히 이렇게 표현합니다.
- model = "existing-model"
+ model = "new-model"
마이너스 기호(-)가 있는 줄은 기존 내용이고, 플러스 기호(+)가 있는 줄은 새로 추가되거나 바뀔 예정인 내용을 가리킵니다. 위 출력은 교육용으로 만든 가상 예시입니다. 특정 FreeLLMAPI 버전에서 실제로 출력한 기록이 아닙니다. FreeLLMAPI 공식 CLI 소스는 기존 파일과 변경 계획을 비교해 diff를 출력하도록 구현되어 있습니다. 그러나 출력 스타일과 변경 파일은 설치한 도구·버전·설정에 따라 다릅니다. 핵심 질문은 하나입니다. “내가 의도한 변경만 표시되었는가?”
6. dry-run 결과에서 무엇을 확인해야 하나요?
다음 항목을 순서대로 확인해 보세요. ① 어떤 파일을 변경하려는가? 사용 중인 설정 파일인지, 프로젝트 내부 파일인지, 개인 환경 전체에 적용되는 파일인지 확인합니다. ② 기존 내용이 보존되는가? 바꾸려는 항목 외에 기존 모델과 공급업체 설정이 사라지지 않는지 살펴봅니다. ③ 새 주소가 정확한가? 로컬 게이트웨이 주소와 포트, API 경로가 현재 실행 환경에 맞는지 확인합니다. ④ 비밀정보가 노출되는가? 실제 API 키가 출력이나 설정 파일, 스크린샷에 포함되지 않았는지 살펴봅니다. ⑤ 변경 범위가 예상대로인가? 작은 설정 하나만 고치려 했는데 파일 전체가 바뀐다면 바로 적용하지 말고 원인을 조사합니다. ⑥ 실패·경고 메시지가 있는가? dry-run이 오류 없이 끝났더라도 실제 모델 호출의 성공이나 요금·성능을 보증하지 않습니다.
7. dry-run을 했으면 실제 설정도 자동 변경되나요?
FreeLLMAPI 설정 생성기의 --dry-run은 실제 설정 파일 쓰기를 수행하지 않습니다. 즉, 변경 결과를 보고 마음에 들더라도 실제로 적용하려면 나중에 별도 적용 절차가 필요합니다. FreeLLMAPI의 설정 생성기는 일반 실행 시 기존 설정에 병합하고, 기존 파일이 있을 때 시각이 포함된 백업 파일을 만든다고 설명합니다. 여기에서 역할을 구분해 주세요.
- dry-run: 적용 전에 계획을 검토
- 백업: 이미 있던 설정을 되돌릴 수 있도록 사본 확보
- 실제 적용: 현재 설정 파일 변경
- 연결 테스트: 새 설정으로 서버와 정상 통신하는지 검사 각각은 별개의 단계입니다. dry-run 성공 = 실제 변경 성공 = AI 모델 정상 동작이 아닙니다.
8. dry-run이 모든 부작용을 방지하나요?
가장 중요하게 알아둘 부분입니다. 그렇지 않습니다. FreeLLMAPI의 경우 공식 구현으로 확인할 수 있는 것은 설정 생성기가 목표 설정 파일의 쓰기 단계를 건너뛴다는 점입니다. 하지만 다음까지 전부 ‘하지 않는다’고 단정해서는 안 됩니다.
- npx의 npm 패키지 다운로드·실행 캐시 사용
- CLI가 현재 설정 파일을 읽는 작업
- 게이트웨이에서 모델 목록을 가져오기 위한 네트워크 통신
- 명령 실행과 오류 메시지의 터미널 출력·로그 기록
- 다른 프로그램에서 같은 --dry-run 이름을 다르게 구현한 경우 특히 실제 API 키를 --api-key 값으로 명령어에 직접 적으면 셸 기록이나 실행 환경에 흔적이 남을 수 있습니다. 공식 CLI는 환경변수 형태의 키 설정도 지원합니다. 실제 키를 공개 블로그 예시나 공유 채팅에 넣지 마세요. dry-run은 설정 변경 위험을 낮추는 도구이지, 위험을 완전히 제거하는 보안 격리 환경이 아닙니다.
9. dry-run, 테스트, 시뮬레이션, 백업은 무엇이 다른가요?
| 용어 | 주로 확인하는 것 | 주의할 점 |
|---|---|---|
| dry-run | 예상 작업이나 예정된 파일 변경 | 프로그램별 지원 범위가 다름 |
| 실제 테스트 | 설정을 사용했을 때 동작하는가 | 외부 요청·비용·파일 변경 가능 |
| 시뮬레이션 | 가정한 조건에서 어떻게 동작하는가 | 현실 환경과 다를 수 있음 |
| 백업 | 이전 상태를 복구할 사본이 있는가 | 복구 절차 검증 필요 |
일부 다른 개발 도구도 비슷한 개념을 사용합니다. 예를 들어 HashiCorp Terraform의 plan은 인프라 변경을 적용하기 전에 계획을 보여주고, Docker Compose는 일부 명령에서 dry-run으로 실행 순서를 보여줄 수 있습니다. 그렇다고 FreeLLMAPI와 Terraform, Docker의 dry-run이 같은 일을 하고 같은 안전성을 보장한다는 뜻은 아닙니다. 도구별 공식 문서를 확인해야 합니다.
10. 어떤 상황에서는 dry-run을 믿으면 안 되나요?
다음 상황에서는 dry-run 출력 하나만으로 작업을 승인하지 마세요. 보안·인증 설정: 새 키가 로그나 파일에 노출되지 않는지 추가 검토해야 합니다. 서버와 데이터베이스 변경: 프리뷰에서는 성공했더라도 실제 적용 시 권한이나 동시 실행 상태가 달라질 수 있습니다. 요금이 발생하는 API 호출: 설정 미리보기만으로 호출 비용과 무료 할당량을 실제 검증하지 못합니다. 배포·공개 게시: 설정 계획이 올바르더라도 웹사이트의 실제 배포 결과와 모바일 레이아웃은 별도입니다. 프로덕션의 중요한 데이터: 사전 검토 외에 백업, 승인, 영향 범위 및 복구 절차가 필요합니다. 초보자라면 dry-run → 결과 확인 → 백업 확인 → 실제 적용 승인 → 적용 후 검증의 흐름을 기억해 보세요.
11. AI에게 안전하게 명령을 검토해 달라고 요청하는 방법
AI 코딩 도구에게 다음처럼 지시할 수 있습니다.
현재 설정 파일을 수정하지 마.
먼저 공식 문서에서 dry-run 지원 여부를 확인해.
지원되는 경우 변경 대상과 예상 diff만 보여줘.
- 수정 예정 파일의 경로
- 추가·변경·삭제될 설정
- 기존 설정에 미치는 영향
- 키나 인증정보가 노출될 위험
- 실제로 수행한 명령과 실행하지 않은 명령
결과를 요약한 뒤 멈춰 줘.
내가 승인하기 전에는 실제 적용, 배포, 공개 게시를 하지 마.
단, AI에게 ‘수정하지 마’라고 요청한 사실만으로 기술적인 차단 장치가 만들어지는 것은 아닙니다. AI가 어떤 실행 권한을 갖고 있는지와 실제 명령·도구의 동작도 별도로 확인해야 합니다. 또 AI가 “dry-run 성공”이라고 보고했다면 명령의 실제 실행 증거와 출력 결과가 있는지 살펴보는 것이 좋습니다.
12. 자주 묻는 질문(FAQ)
Q1. dry-run을 한국어로 무엇이라고 하나요?
‘미리 실행해 보기’, ‘모의 실행’, ‘변경 미리보기’ 등으로 설명할 수 있습니다. 실제 기능 범위는 명령마다 다릅니다.
Q2. dry-run을 실행하면 설정 파일은 절대 바뀌지 않나요?
FreeLLMAPI의 지원되는 설정 생성기에서는 목표 설정 파일에 쓰지 않도록 설계되어 있습니다. 하지만 모든 프로그램의 dry-run이 동일한 보증을 제공하는 것은 아닙니다.
Q3. dry-run에서 성공하면 AI 모델도 바로 사용할 수 있나요?
그렇지 않습니다. 실제 서버 실행, 업체 키, 모델 지원 여부, API 요청 결과는 별도 확인이 필요합니다.
Q4. FreeLLMAPI의 keys 명령에도 --dry-run을 붙일 수 있나요?
공식 CLI 문서는 keys 명령에서 이 옵션을 지원하지 않고 요청 전에 거부한다고 명시합니다.
Q5. dry-run에 표시되는 마이너스와 플러스는 무슨 뜻인가요?
일반적인 diff에서 마이너스는 기존 또는 삭제 예정 내용, 플러스는 추가·변경될 내용을 나타냅니다.
Q6. npx로 dry-run을 실행하면 어떤 파일도 쓰지 않나요?
그렇게 일반화할 수 없습니다. 설정 생성기의 목표 파일 쓰기는 막지만, npx는 패키지 캐시 등을 사용할 수 있습니다.
Q7. 키를 명령줄에 적어도 dry-run이므로 안전한가요?
아닙니다. 명령 기록이나 로그에 인증값이 남을 수 있습니다. 실제 API 키를 공개 예시에 사용하지 마세요.
Q8. dry-run과 백업 중 하나만 해도 되나요?
용도가 달라 함께 검토하는 편이 좋습니다. 미리보기는 변경 위험을 줄이고, 백업은 복구 가능성을 확보합니다.
Q9. dry-run은 배포 전 승인과 같은 개념인가요?
아닙니다. dry-run은 기술적인 미리보기이고, 승인은 사람이 실제 변경을 허용하는 결정 단계입니다.
Q10. AI가 dry-run을 했다고 답했는데 결과가 없으면 어떻게 하나요?
실행한 명령, 종료 결과, 출력된 diff, 대상 파일과 미실행 사유를 확인하세요. 출력이 없는 상황에서 검증 성공이라고 결론 내리지 마세요.
핵심 정리
dry-run은 실제 설정을 바꾸기 전에 예정된 변경을 미리 살펴보는 기능입니다. 기억할 것은 세 가지입니다.
- 미리보기와 실제 적용은 다른 단계입니다.
- 명령마다 dry-run이 지원되는 범위가 다릅니다.
- dry-run은 모든 부작용을 차단하지 않으므로 백업·권한·사람 승인·사후 검증이 필요합니다. AI가 빨리 설정을 변경해 주는 시대일수록 중요한 것은 적용하기 전에 무엇이 바뀔지 알고 결정할 수 있는 절차입니다.
함께 읽으면 좋은 글
- CLI란? 명령어로 컴퓨터를 다루는 방법과 초보자 예시 — 용어의 기본 정의와 범위를 이어서 확인할 수 있습니다.
- 코드란 무엇일까? HTML·CSS·JavaScript와 AI 코딩 쉽게 이해하기 — 관련된 기본 개념과 적용 범위를 확인합니다.