클로드 프로젝트 오류 해결 — 여러 갈래가 헤매면 설정 구멍 하나

프로젝트에 일을 맡겨 두면 갈래 여럿이 동시에 돕니다. 그러다 보면 몇 개가 엉뚱한 걸 전제하고 일을 끝냈거나, 닿지 못한 것을 우회했거나, 「막혔다」며 서 있는 상황이 생기죠. 이때 하나씩 붙잡고 고치면 같은 일이 반복됩니다.

문서가 알려 주는 진단이 명확합니다 — 여럿이 같이 헤매면 원인은 각 작업이 아니라 프로젝트 설정의 같은 구멍입니다. 저장소 오류 메시지도 세 가지가 각각 다른 원인을 가리키고요.

📌 30초 요약

• 여럿이 헤매면 구멍은 하나입니다.
• 먼저 조율 대화에 물어보세요.
• 고친 뒤 하나만 먼저 보냅니다.
• 저장소 오류는 세 갈래입니다.
• 한도에 닿아도 알아서 이어 갑니다.

1. 여럿이 헤맬 때의 순서

문서가 권하는 첫 단계는 고치는 게 아니라 어느 갈래가 멀쩡한지 가려내는 것입니다. 손대기 전에 판을 먼저 읽으라는 거죠. 조율하는 대화는 갈래가 보고한 것만 본다고 했지만, 물어보면 각 갈래를 읽어 와서 답합니다.

순서	무엇을 하나
① 판 읽기	열린 갈래마다 시킨 일·가정·기다리는 것을 나열시킴
② 잘못 간 것 정리	열어서 해결 표시하거나 다시 지시
③ 구멍 메우기	지시문이나 환경에서 한 번만 고침
④ 하나로 확인	갈래 하나만 먼저 보낸 뒤 나머지를 다시

넷째 줄이 실무에서 값이 큽니다. 고쳤다고 바로 전부 다시 보내면, 안 고쳐졌을 때 같은 실패가 여러 개로 늘어납니다. 하나로 확인하고 나머지를 푸는 편이 한도도 아끼고 정리할 것도 적습니다.

정리할 때 한 가지 유의하실 점은 치웠다고 흔적까지 사라지지 않는다는 겁니다. 잘못 간 갈래를 해결 표시해도 그 갈래가 만든 가지와 끌어올림 요청은 제가 지울 때까지 깃허브에 남습니다. 화면에서 안 보인다고 정리된 게 아니니 따로 훑어 주세요.

2. 저장소에 못 닿을 때

저장소 관련 메시지는 세 가지인데 각각 다른 곳을 가리킵니다. 문구를 보고 원인을 갈라야 헛수고가 없습니다.

언제 나오나	무엇을 뜻하나
갈래가 시작하기 전	앱이 안 깔렸거나·정지됐거나·계정에 안 묶임
갈래가 복제하다가	거부됐거나 이름·시작 가지를 못 찾음
저장소를 저장할 때	설치 링크와 재연결 링크를 함께 줌
조직 쪽이 막은 경우	버튼 대신 고치는 법 안내가 뜸

⚠️ 다른 세션은 되는데 프로젝트만 안 되는 경우

헷갈리기 딱 좋은 대목입니다. 평소 쓰던 클라우드 세션이 같은 저장소를 아무 문제 없이 복제하더라도, 프로젝트 갈래는 깃허브 쪽 사전 조건을 따로 갖춰야 합니다. 「어제까지 잘 되던 저장소인데 왜」라는 상황이 여기서 나옵니다. 특히 앱이 깃허브에 깔려 있으면서도 제가 연결한 계정에는 묶이지 않은 경우가 있어서, 메시지가 설치 링크와 재연결 링크를 함께 주는 겁니다 — 깔려 있으면 재연결 쪽을 보세요. 웹 세션의 깃허브 연결 방식과 나란히 두면 차이가 보입니다.

3. 한도에 닿았을 때

갈래나 조율 대화가 요금제 한도에 닿으면 스스로 재시도하다가 한도가 풀리면 이어 갑니다. 기다리는 동안 화면에는 「서비스가 바쁩니다」와 함께 계속 시도 중이라는 안내가 뜨고요. 제가 할 일은 없습니다 — 다만 다음 사용 구간을 쓰게 된다는 뜻이기도 합니다.

그게 싫으시면 그 갈래를 멈추거나, 프로젝트를 일시정지해서 모든 갈래를 한꺼번에 붙잡아 두시면 됩니다. 한도에 걸린 뒤 알아서 이어 가는 동작을 아신다면 성격이 비슷하다고 보시면 됩니다.

예외가 하나 있습니다. 정해진 시각에 도는 작업이 시작한 갈래는 기다리지 않습니다. 그 차례가 한도 오류로 그냥 멈추고, 한도가 풀린 뒤에 제가 메시지를 보내야 다시 갑니다. 밤새 돌게 해 두셨다면 아침에 확인이 필요한 쪽이죠.

4. 나머지 메시지 읽는 법

나머지는 문구가 원인을 직접 말해 줍니다. 몇 가지만 짚으면, 문맥을 다 썼다는 메시지는 두 갈래로 읽힙니다 — 새 세션에서 계속한다고 적혀 있으면 알아서 이어 가고, 아니면 남은 일을 새 갈래로 다시 시작하라고 조율 대화에 부탁하셔야 합니다.

차례 상한에 닿았다는 메시지도 있습니다. 에이전트가 몇 번까지 돌지 정해 둔 값에 걸린 것이라, 메시지를 한 번 더 보내 이어 가거나 그 값을 올리시면 됩니다. 준비 스크립트가 실패하는 경우도 목록에 있는데, 이때는 오류에서 바로 스크립트를 고쳐 다시 보낼 수 있습니다.

비슷해 보이지만 갈라 읽어야 하는 짝도 있습니다. 저장소에 연결하지 못했다는 문구가 두 번 나오는데, 「깃허브에 못 닿았다」면 잠시 뒤 다시 보내면 되는 일시적 문제이고, 「저장소나 환경에 접근하지 못했다」면 권한과 환경을 봐야 합니다. 이 경우 제 깃허브 계정에 밀어넣을 수 있는 권한이 있어야 하고, 쓰던 환경이 아직 남아 있어야 하거든요. 읽기만 되는 권한으로는 갈래가 일을 마무리하지 못합니다.

크레딧이 필요하다는 안내도 있습니다. 제 요금제가 크레딧으로만 감당하는 요청을 — 이를테면 요금제에 안 들어 있는 모델이나 더 큰 문맥을 — 했을 때 뜨죠. 켜거나 사는 권한이 요금제마다 다르니 확인이 필요하고, 준비된 뒤에는 메시지를 한 번 더 보내면 이어집니다. 끝으로 「설정 제안을 못 보여 준다」는 문구는 열어 둔 앱이 클로드가 보낸 제안보다 오래됐다는 뜻이라, 새로고침하거나 앱을 다시 켜시면 됩니다.

조율 대화 자체가 먹통일 때도 있습니다. 답이 프로젝트에 닿지 않으면 안내 띠가 뜨는데, 거기서 클로드를 다시 시작하면 됩니다. 이때 쓰던 중이던 답은 사라지지만 갈래들은 영향을 받지 않습니다. 환경이 지워졌다는 메시지라면 다른 환경을 고르시면 되고, 바뀐 환경은 새로 뜨는 갈래부터 적용됩니다.

자주 묻는 질문 (FAQ)

Q. 갈래 서너 개가 동시에 이상합니다

하나씩 고치지 마세요. 여럿이 같이 헤매면 원인은 프로젝트 설정의 같은 구멍일 가능성이 큽니다. 조율 대화에 「무엇을 가정했고 무엇에 못 닿았는지」부터 물어보시고, 구멍을 한 번 고친 뒤 갈래 하나로 확인하세요.

Q. 평소 세션에서는 잘 되는 저장소입니다

그래도 프로젝트 갈래는 깃허브 사전 조건을 따로 갖춰야 합니다. 앱이 깔려 있어도 제가 연결한 계정에 묶이지 않았을 수 있으니, 메시지가 주는 두 링크 중 재연결 쪽을 먼저 보세요.

Q. 잘못 간 갈래를 정리했는데 깃허브가 지저분합니다

정상입니다. 해결 표시를 해도 그 갈래가 만든 가지와 끌어올림 요청은 제가 지울 때까지 남습니다. 화면 정리와 저장소 정리는 별개이니 따로 훑어 주세요.

Q. 밤새 돌려 뒀는데 아침에 멈춰 있습니다

정해진 시각에 도는 작업이 시작한 갈래라면 한도에 걸렸을 때 기다리지 않고 그냥 멈춥니다. 보통 갈래와 다른 점이니, 그런 작업은 아침에 한 번 확인하시는 편이 좋습니다.

정리하면

• 여럿이 헤매면 구멍은 하나입니다.
• 고치기 전에 판을 읽으세요.
• 고친 뒤 하나로 확인합니다.
• 가지와 요청은 남습니다.
• 정기 작업은 안 기다립니다.

※ 공개된 프로젝트 문서의 문제 해결 절을 읽고 정리했습니다. 화면 이름과 메시지 문구는 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 이 기능은 베타 단계로 소개돼 있어 메시지와 대응 절차가 바뀔 수 있습니다. 원문과 대조해 확인하세요.