클로드 코드 준비 스크립트 — 두 번째 세션부터 안 돌고 띄운 건 사라짐

클라우드에서 세션을 띄울 때 미리 깔아 둬야 하는 것이 있습니다. 기본 이미지에 없는 도구, 프로젝트가 쓰는 꾸러미 같은 것들이죠. 이걸 해결하는 방법이 둘인데 — 환경에 등록하는 준비 스크립트와, 설정 파일에 넣는 세션 시작 훅입니다. 이름이 비슷해서 아무거나 쓰면 될 것 같지만 도는 시점도 장소도 다릅니다.

특히 준비 스크립트에는 「두 번째 세션부터는 아예 안 돈다」는 성질이 있습니다. 여기서 헷갈리는 일이 자주 생깁니다. 스크립트에 데이터베이스를 띄워 뒀는데 다음 세션에 가 보면 안 떠 있는 식이죠. 왜 그런지, 둘을 어떻게 갈라 쓰는지 정리해 보겠습니다.

📌 30초 요약

• 준비 스크립트는 클로드가 뜨기 전에 루트로 돕니다.
• 0이 아닌 값으로 끝나면 세션이 시작조차 안 됩니다.
• 두 번째 세션부터는 스냅숏이 대신합니다.
• 내 기계의 훅은 클라우드로 안 갑니다.

1. 클로드가 뜨기 전에 도는 스크립트

준비 스크립트는 새 클라우드 세션이 시작될 때, 클로드 코드가 뜨기 전에 도는 배시 스크립트입니다. 환경 설정 대화상자에 내용을 적어 두면 됩니다. 도는 환경이 우분투이고 권한이 루트라, 시스템 꾸러미 설치 명령도 대부분의 언어별 꾸러미 관리자도 그대로 씁니다. 기본 이미지에 없는 검사 도구 하나를 까는 정도면 두 줄이면 끝납니다.

간단해 보이지만 지켜야 할 제약이 셋입니다. 셋 다 안 지키면 조용히 실패하는 게 아니라 세션 자체가 안 뜨거나 캐시가 안 만들어지는 식으로 크게 나타납니다.

제약	안 지키면
0으로 끝날 것	세션이 시작 실패합니다. 덜 중요한 명령 뒤에는 실패해도 넘어가게 붙여 두세요.
5분 안에 끝낼 것	넘기면 캐시를 못 만듭니다. 서로 무관한 설치는 동시에 돌리고, 오래 걸리는 내려받기 하나는 훅으로 옮기세요.
나갈 길이 있을 것	망을 「없음」으로 잠갔다면 설치가 실패합니다. 기본값인 「신뢰」는 주요 저장소를 덮어 줍니다.

세 번째 줄은 바깥 연결 단계를 다룬 글과 이어집니다. 잠그는 쪽으로 설정을 바꿨다가 멀쩡하던 준비 스크립트가 갑자기 깨지는 경우가 여기서 나옵니다. 첫 번째 줄도 같은 성격입니다 — 설치 하나가 일시적으로 실패했을 뿐인데 세션 전체가 안 뜨는 상황이 되니, 없어도 되는 도구에는 미리 안전장치를 붙여 두는 편이 낫습니다.

쓰기 전에 하나 확인할 게 있습니다. 기본 이미지에 이미 상당히 많이 깔려 있습니다. 파이썬·노드·루비·PHP·자바·고·러스트·C 계열 도구 모음이 들어 있고, 컨테이너 도구와 데이터베이스 두 종까지 미리 준비돼 있습니다. 노드는 세 판올림이 동시에 깔려 있고 그중 최신이 기본입니다. 그러니 「이걸 깔아야지」 하기 전에 이미 있는지부터 보세요. 버전은 가상 기계에 든 확인 명령을 클로드에게 시켜 보면 나오는데, 몇몇 도구는 그 명령이 보고하지 않으니 그때는 각자의 버전 명령을 따로 시켜 보셔야 합니다.

반대로 이 목록 밖의 도구 모음은 저장소가 기본 허용 목록에 들어 있어도 깔려 있지 않습니다. 받을 수 있는 것과 깔려 있는 것은 별개입니다. 꾸러미 저장소가 열려 있다는 건 받아서 깔 수는 있다는 뜻일 뿐이죠. 그런 건 준비 스크립트가 맡을 자리가 맞습니다. 그리고 여기에 비밀값을 적으면 안 됩니다 — 환경 변수와 준비 스크립트는 그 환경을 쓰는 사람이면 누구나 읽을 수 있고, 설정 화면에도 그 경고가 붙어 있습니다.

2. 두 번째 세션부터는 안 돕니다

여기가 가장 헷갈리는 대목입니다. 준비 스크립트는 그 환경에서 세션을 처음 띄울 때만 돕니다. 한 번 끝나고 나면 그 시점의 파일 시스템을 통째로 찍어 두고, 이후 세션은 그 스냅숏에서 출발합니다. 스크립트 단계는 건너뜁니다. 큰 도구 모음을 깔거나 컨테이너 이미지를 받아 두는 스크립트라도 두 번째부터는 세션이 빨리 뜨는 이유입니다.

⚠️ 디스크에 쓴 건 남고, 돌고 있던 건 사라집니다

캐시는 파일 시스템 스냅숏이라 성질이 분명하게 갈립니다. 설치한 꾸러미, 받아 둔 컨테이너 이미지, 써 놓은 파일은 그대로 넘어옵니다. 반면 스크립트가 띄워 둔 데이터베이스나 컨테이너 묶음처럼 「돌고 있던 것」은 안 넘어옵니다. 그래서 「첫 세션에는 되던 게 두 번째부터 안 된다」가 생깁니다. 돌아야 하는 것은 준비 스크립트가 아니라 세션마다 도는 쪽에서 띄우세요 — 세션 시작 훅에 넣거나 클로드에게 시키면 됩니다.

그러면 스크립트를 고쳤을 때는 어떻게 될까요. 다시 돕니다. 캐시가 새로 만들어지는 경우는 셋인데 — 준비 스크립트를 바꿨을 때, 허용한 주소 목록을 바꿨을 때, 그리고 캐시가 약 일주일 지나 만료됐을 때입니다. 반대로 이미 있던 세션을 이어서 열면 준비 스크립트는 절대 다시 안 돕니다. 스크립트를 고쳐 놓고 기존 세션을 재개하면서 「왜 반영이 안 되지」 하는 경우가 여기 해당합니다. 새 세션을 띄워야 합니다.

3. 시작 훅과 가르는 기준

기준은 한 문장으로 정리됩니다. 가상 기계 자체를 갖추는 일은 준비 스크립트, 프로젝트를 준비하는 일은 세션 시작 훅입니다. 기본 이미지에 없는 도구 모음을 까는 건 앞쪽이고, 꾸러미를 받아 설치하는 것처럼 내 노트북에서도 똑같이 해야 하는 일은 뒤쪽입니다. 훅으로 넣어 두면 로컬에서도 같이 돌기 때문입니다.

견주는 점	준비 스크립트	세션 시작 훅
어디에 적나	환경 설정 대화상자	설정 파일
언제 도나	클로드가 뜨기 전. 캐시가 있으면 건너뜀	클로드가 뜬 뒤. 재개 포함 매 세션
어디서 도나	클라우드에서만	로컬과 클라우드 양쪽

표에서 가장 중요한 칸은 「재개 포함 매 세션」입니다. 시작 훅은 세션을 열 때마다 도니까 시작이 느려지는 대가가 있습니다. 준비 스크립트는 캐시 덕을 보지만 훅은 그런 게 없습니다. 그래서 설치 훅을 쓰신다면 이미 깔려 있는지 먼저 확인하고 넘어가도록 짜 두는 게 좋습니다. 훅을 셸 없이 돌리는 방법까지 알아 두면 시작 비용을 더 줄일 수 있습니다.

4. 내 기계의 훅은 안 따라갑니다

훅을 쓰기로 했다면 어디에 적어 두느냐가 결과를 가릅니다. 사용자 수준 설정 파일에 넣어 둔 시작 훅은 클라우드 세션에서 돌지 않습니다. 그 설정은 내 기계에 남기 때문입니다. 로컬에서는 잘 돌던 훅이 클라우드에서만 조용히 빠지는 이유가 이겁니다.

클라우드에서 실제로 도는 건 저장소에 커밋해 둔 설정의 훅과, 조직이 서버에서 내려 주는 설정의 훅입니다. 그러니 팀이 함께 쓰는 준비 절차라면 저장소 쪽에 적어 두는 게 맞습니다. 자체 호스팅 환경이라면 여기에 더해 운영자가 러너 쪽에 심어 둔 훅과 러너 이미지의 관리 설정에 든 훅까지 함께 돕니다. 어느 환경에서 도느냐에 따라 같은 저장소인데 실행되는 훅 수가 달라진다는 뜻입니다.

한 가지 더. 기본 이미지를 통째로 다른 것으로 바꾸는 건 아직 안 됩니다. 필요한 걸 준비 스크립트로 얹거나, 클로드 옆에 컨테이너로 따로 띄우는 방식만 가능합니다. 세션이 쓰는 자원에도 상한이 있어 메모리를 많이 먹는 빌드나 테스트는 도중에 중단될 수 있습니다. 그런 작업은 클라우드로 넘기는 대신 내 하드웨어에서 돌리는 쪽이 낫고, 환경에 키를 두는 방식을 쓰신다면 준비 스크립트 단계에서는 아직 그 키가 안 붙는다는 점도 함께 기억해 두세요.

자주 묻는 질문 (FAQ)

Q. 준비 스크립트를 고쳤는데 반영이 안 됩니다

기존 세션을 이어서 여신 게 아닌지 보세요. 재개할 때는 준비 스크립트가 절대 다시 안 돕니다. 새 세션을 띄우면 스크립트가 바뀐 걸 감지해 캐시를 다시 만듭니다. 허용 주소 목록을 바꿔도 마찬가지로 다시 돕니다.

Q. 첫 세션에는 되던 서비스가 두 번째부터 안 뜹니다

캐시가 파일 시스템만 찍어 두기 때문입니다. 깔아 둔 것은 남지만 띄워 둔 프로세스는 안 남습니다. 데이터베이스나 컨테이너 묶음을 쓰신다면 준비 스크립트가 아니라 세션마다 도는 쪽으로 옮기세요.

Q. 로컬에서 잘 돌던 훅이 클라우드에서 안 돕니다

사용자 수준 설정에 넣어 두신 것 같습니다. 그 설정은 내 기계에 남아 클라우드로 안 갑니다. 클라우드에서 돌아야 한다면 저장소에 커밋하는 설정으로 옮기세요. 조직이 서버에서 내려 주는 설정의 훅도 함께 돕니다.

Q. 설치할 게 많아 5분을 넘길 것 같습니다

두 가지를 함께 쓰세요. 서로 무관한 설치는 동시에 돌리고 기다리는 방식으로 묶고, 그래도 안 맞는 큰 내려받기 하나는 시작 훅으로 옮겨 배경에서 받게 합니다. 5분을 넘기면 캐시가 안 만들어져 매번 처음부터 도는 셈이 됩니다.

정리하면

• 준비 스크립트는 첫 세션에만 돕니다.
• 깐 것은 남고 띄운 것은 사라집니다.
• 재개할 때는 절대 다시 안 돕니다.
• 기계를 갖추는 일은 스크립트, 프로젝트 준비는 훅입니다.
• 내 기계 설정의 훅은 클라우드로 안 갑니다.

※ 공개된 클라우드 환경 설정 문서를 읽고 정리했습니다. 설정 항목 이름과 명령은 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 실행 시간 상한과 캐시 만료 기간은 대략적인 값으로 안내돼 있고 판올림에 따라 달라질 수 있습니다. 기본 이미지 교체도 지금은 안 되지만 나중에 열릴 수 있으니 원문과 대조해 확인하세요.