# Claude Code Projects: 코디네이터, 스레드, 베타 제한 사항

> Claude Code Projects의 클라우드 스레드 작동 방식: GitHub App, 지침, 메모리, 충돌 및 베타 제한 사항.

Source: https://ailoot.ai/blog/ko/claude-code-projects/
Canonical: https://ailoot.ai/blog/ko/claude-code-projects/
Language: ko
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-051
Revision: sha256-04756d2ac4652ceca9638f554629328a7bd655e6d3b8ae33c8a55be68381b5e5


Anthropic은 최근 Claude Code의 Projects를 새롭게 설계했습니다. 이제 Projects는 작업을 위한 병렬 클라우드 세션, 즉 스레드를 시작하고 그 결과를 전달받는 하나의 조정 대화입니다. 한 번의 세션보다 오래 지속되고 새로운 작업을 만들어 낼 목표가 있다면 프로젝트를 만들 만합니다. 예를 들어 몇 주 동안 GitHub 저장소를 개발하는 경우입니다. 병렬 작업이 필요하다는 이유만으로는 충분하지 않습니다. 지금 당장 파일 하나를 빠르게 수정해야 한다면 일반 세션으로 충분합니다.

작업은 코디네이터가 이끕니다. 코디네이터는 오래 지속되는 대화로, 사용자의 메시지 중 어떤 내용을 스레드의 작업으로 전환할지 Claude가 결정하는 곳입니다. 코드는 스레드가 작성합니다. 각 스레드는 자체 저장소 브랜치에서 실행되는 별도의 클라우드 Claude Code 세션입니다. 여러 스레드를 동시에 실행할 수 있으며, 각 스레드는 고유한 컨텍스트와 브랜치를 갖습니다. 코디네이터는 스레드가 완료 시 보고하는 내용은 확인하지만, 스레드가 수행하는 모든 단계까지 보지는 않습니다. 완료된 풀 리퀘스트(변경 사항 병합 요청)를 사용자에게 알리고, 사용자가 요청하면 스레드에 수정이나 병합을 요청합니다. 아래는 Anthropic의 공식 문서를 바탕으로 한 개요입니다. 무엇을 설정해야 하는지, 작업이 어떻게 구성되는지, 베타에는 어떤 제한이 있는지 살펴봅니다.

베타는 순차적으로 제공되고 있으며, 일반 채팅이나 Cowork에서 프로젝트를 만들지 않았고 클라우드 Claude Code 세션을 이미 사용한 Pro 및 Max 계정부터 이용할 수 있습니다. 아직 Projects 섹션이 보이지 않는다면 대기자 명단에 등록할 수 있습니다.



<div class="aside" data-semantic="ailoot-docs-link" aria-label="Ailoot 문서">

Ailoot 사용 방법은 [문서](https://ailoot.ai/docs/)에서 확인할 수 있습니다.

</div>

## Claude Code Projects란 무엇인가요? 쉽게 설명하면

프로젝트는 저장소, 메모리, 지침이 연결된 코디네이터와의 단일 장기 대화입니다. 코디네이터에게 메시지를 보내면 즉시 답변할지 아니면 스레드를 시작할지 결정합니다. 각 작업마다 새 세션을 수동으로 열 필요가 없습니다.

스레드는 완전한 클라우드 Claude Code 세션입니다. 자체 컨텍스트와 저장소 브랜치가 있으며, 필요한 경우 풀 리퀘스트를 엽니다. 코디네이터는 여러 스레드를 동시에 열어 둘 수 있습니다. 예를 들어 한 스레드는 버그를 수정하고, 다른 스레드는 테스트를 작성하고, 세 번째 스레드는 문서를 업데이트하는 동안 기본 대화에서 사용자의 질문에 답할 수 있습니다.

비교를 위해 저장소의 각기 다른 작업 사본에서 실행되는 여러 로컬 Claude Code 세션을 탭으로 열어 둔 상황을 떠올려 보세요. 이러한 사본은 워크트리라고 합니다. 각 브랜치에 별도의 폴더를 두어 로컬 세션끼리 서로 간섭하지 않도록 하는 것입니다. 세션 간 전환과 각 세션에 할당할 작업은 사용자가 직접 결정합니다. 클라우드 스레드에는 워크트리가 필요하지 않습니다. 각 스레드가 저장소를 자체 격리 클라우드 환경에 복제하기 때문입니다. Projects는 조정을 맡아 새 스레드를 만들지, 기존 스레드로 충분할지 결정합니다.

프로젝트에는 모든 새 스레드가 받는 공유 메모리와 지침이 있습니다. 설정 섹션에서는 메모리와 지침에 무엇을 저장하고 스레드에 어떻게 전달하는지 설명합니다.



## 일반 세션 및 에이전트 팀과의 차이점

단일 Claude Code 세션 안에서 [중첩 서브에이전트](https://ailoot.ai/blog/ko/claude-code-nested-subagents/)를 이미 실행하고 있다면, 이를 에이전트 팀 및 프로젝트 스레드와 구분하는 것이 좋습니다. 에이전트 팀은 작업을 위임하는 또 다른 방식입니다. 하나의 세션이 특정 작업을 위해 팀원 세션을 시작합니다. 자신의 컴퓨터에서도, 클라우드 세션 안에서도 실행할 수 있습니다.

- **에이전트 팀**—로컬이나 클라우드에서 시작할 수 있는, 하나의 특정 작업을 위한 팀원 세션입니다. 별도의 프로젝트 스레드는 아닙니다.
- **프로젝트와 해당 스레드**—작업이 클라우드에서 실행됩니다. 각 스레드는 자체 브랜치의 별도 세션이며 노트북을 닫은 뒤에도 계속 실행됩니다. 로컬 세션은 프로젝트에 포함될 수 없습니다.
- **Agent view**—컴퓨터에서 여러 로컬 세션을 관찰하는 화면입니다. 코디네이터가 없으므로 각 세션에 무엇을 할당할지는 사용자가 결정합니다.

Anthropic의 공식 문서는 별도의 요점을 강조합니다. 병렬 작업만으로는 프로젝트를 만들 이유가 되지 않습니다. 프로젝트에서는 Claude가 직접 세션을 시작하고 결과를 전달받으며, 모든 세션은 공유 저장소, 지침, 메모리를 가지고 시작합니다. 작업이 진행되는 동안 내내 클라우드에서 수행됩니다.

코디네이터가 에이전트에게 작업을 배분하는 비슷한 방식은 다른 도구에도 구현되어 있으며, [Cursor Projects](https://ailoot.ai/blog/ko/cursor-projects-coordinator-agents/)에 관한 글에서 다룹니다. 메커니즘은 다르지만, 이 경우에도 코디네이터가 누구에게 무엇을 맡길지 결정합니다.

## 첫 프로젝트 전에 설정할 항목

프로젝트를 만들기 전에 세 가지를 확인하세요.

**1. GitHub 계정과 Claude GitHub App.** 이미 `/web-setup`을 통해 GitHub를 연결했다면 해당 토큰으로 일반 클라우드 세션이 저장소에 접근할 수 있습니다. 하지만 프로젝트 스레드에는 그것만으로 충분하지 않습니다. 저장소에 푸시할 수 있는 권한을 가진 GitHub 연결 계정과 해당 저장소에 설치된 Claude GitHub App이 필요합니다. 그렇지 않으면 스레드가 저장소를 복제하거나 풀 리퀘스트를 열 수 없습니다.

**2. 프로젝트 지침.** 프로젝트 지침은 최대 16 000자까지 작성할 수 있는 텍스트로, 새 스레드와 코디네이터 모두에게 전달됩니다. 매 세션마다 다시 설명해야 하는 정보를 여기에 적으세요. 저장소 구조, 코드 규칙, 풀 리퀘스트 전에 필요한 검사 등이 해당합니다.

**3. 모델과 노력 수준.** 기본적으로 새 프로젝트는 각 스레드에 높은 노력 수준의 Opus 모델을 사용하고, 코디네이터에는 낮은 노력 수준을 사용합니다. 문서에 따르면 이 설정은 “요금제 사용량을 가장 빠르게 소모합니다”(번역; 원문: draws on your plan fastest). 작업이 단순하다면 **Project settings \> General**에서 비용이 더 낮은 모델을 선택하거나 노력 수준을 낮출 수 있습니다. 스레드와 코디네이터 설정은 별도로 변경하며, 문서에는 더 경제적인 옵션이 설명되어 있습니다.

프로젝트 메모리는 일반 파일로 저장되며, 인덱스 파일의 이름은 `MEMORY.md`입니다. 새 스레드는 시작할 때 이 파일을 읽고 필요에 따라 다른 파일에 접근합니다. 한 스레드가 메모리에 저장한 발견 사항은 다음 스레드에서 다시 설명하지 않아도 사용할 수 있습니다.

## 스레드가 같은 코드를 변경할 때 대처하는 방법

각 스레드는 자체 브랜치에서 작업하며, 필요하면 직접 풀 리퀘스트를 엽니다. 하지만 코디네이터가 작업이 겹치지 않도록 보장하지는 않습니다. 여러 스레드가 같은 코드 영역을 작업하게 되면 인터페이스에서 해당 스레드에 충돌 해결을 요청할 수 있습니다. 풀 리퀘스트 옆에 있는 Resolve conflicts 버튼을 누르면 사용자가 보내는 메시지로 스레드에 지침이 전달됩니다.

공식 문서에서는 프로젝트 지침에 스레드 수에 관한 선호 사항을 지정하라고 제안합니다. 예를 들어 코디네이터에게 동시에 두 개 이하의 스레드만 시작하거나 같은 영역의 새 작업에 기존 스레드를 재사용하도록 요청할 수 있습니다. 이는 코디네이터가 따르려고 하는 선호 사항이지 엄격한 제한은 아닙니다. 이 설정만으로 스레드가 같은 파일에서 충돌하지 않는다고 보장할 수는 없습니다. 이미 발생한 충돌은 별도로 해결해야 합니다. 같은 영역의 관련 작업에는 활성 또는 유휴 스레드를 재사용할 수 있습니다. 한 시간 넘게 유휴 상태였다면 새 메시지를 받았을 때 전체 기록을 다시 읽으며, 이로 인해 구독 사용량이 늘어납니다.

작업이 파일이나 모듈별로 명확히 나뉘어 있을수록 병렬 작업이 쉬워집니다. 큰 작업을 독립적인 부분으로 나누는 방법은 별도 글인 수천 명의 에이전트에게 코딩을 위임하는 방법에서 다룹니다. 규모는 다르지만 작업을 나누는 원칙은 같습니다.

대화 캐시가 활성 상태인 동안(Pro 및 Max 요금제에서, 요금제 한도 내에서 한 시간 이내) 스레드는 기록을 다시 처리할 때 구독 사용량에서 더 적은 토큰을 사용합니다. 캐시가 만료되면 새 메시지를 받은 스레드는 작업을 시작하기 전에 전체 기록을 다시 읽습니다. 새로운 독립 작업이라면 코디네이터에게 새 스레드를 만들어 달라고 요청하는 편이 더 경제적일 수 있습니다. 캐시가 만료된 뒤 기록이 긴 이전 세션을 계속하는 것보다 동일한 구독 사용량에서 토큰을 덜 쓸 수 있습니다.

## 미리 알아둘 베타 제한 사항

중요한 작업을 위해 프로젝트를 만들기 전에 베타의 제한 사항을 확인하세요.

- **Pro 및 Max에서만 이용 가능.** Team 및 Enterprise는 아직 지원되지 않습니다.
- **계정당 하루에 새 스레드 200개로 제한**되며, 모든 프로젝트를 합산합니다.
- **프로젝트는 한 사용자에게만 속합니다.** 다른 사람에게 프로젝트나 개별 스레드의 공유 액세스 권한을 줄 수 없으며, 베타에는 팀을 위한 조직 설정도 없습니다.
- **claude.ai/code, 데스크톱 앱, 모바일 앱을 통해서만 접근 가능.** Projects는 터미널 CLI, Amazon Bedrock, Google Cloud Agent Platform 또는 Microsoft Foundry에서는 작동하지 않습니다.
- **프로젝트에서는 로컬 파일과 도구를 볼 수 없습니다.** 스레드는 GitHub 저장소, 업로드한 파일, Google Drive 폴더를 사용할 수 있지만 컴퓨터에만 있는 항목에는 접근할 수 없습니다.

터미널 액세스나 컴퓨터에서만 사용할 수 있는 도구가 필요하다면 로컬 세션을 사용하거나 여러 로컬 세션을 위한 Agent view를 사용하세요. 여러 사람이 하나의 작업 공간에서 협업해야 한다면 Anthropic은 Team 및 Enterprise용 별도 팀 제품인 Claude Tag를 제공합니다. Claude Tag는 Slack 채널에서 작동하며, 채널의 모든 구성원이 Claude에게 작업을 맡기고 작업 내용을 확인하고 지시할 수 있습니다. 프로젝트는 다르게 작동합니다. 사용자 본인에게만 속합니다. 특정 로컬 파일만 필요하다면 프로젝트에 업로드하면 각 스레드가 해당 파일에 접근할 수 있습니다. 그렇더라도 로컬 도구에 대한 액세스는 제공되지 않습니다.

## 다음 단계

워크플로를 Projects로 옮기기 전에 중요하지 않은 저장소에서 테스트 프로젝트를 하나 만들어 보세요. GitHub App을 연결하고, 짧은 지침을 작성하고, 코디네이터에게 독립적인 작업 하나를 맡긴 다음 어떻게 처리하는지 살펴보세요. 이 첫 실행으로 코디네이터와 스레드 인터페이스를 이해했는지 확인할 수 있습니다. 병렬 작업, 충돌, 여러 작업에 걸친 사용량은 확인할 수 없으므로 별도로 테스트해야 합니다.

<div class="section" role="doc-bibliography" aria-label="출처">

### 출처

- [Claude Code Projects - Anthropic 공식 문서](https://code.claude.com/docs/en/claude-projects)

</div>





<div class="aside" data-semantic="ailoot-link" aria-label="Ailoot">

[ailoot.ai](https://ailoot.ai/)에서 Ailoot를 계속 살펴볼 수 있습니다.

</div>

## Claude Code Projects: 코디네이터, 스레드, 베타 제한 사항: 자주 묻는 질문

### 병렬 작업을 한다는 이유만으로 Project를 만들어야 하나요?

여러 세션에 걸친 목표이며 저장소, 지침, 메모리 공유가 유용할 때 Project를 쓰세요. 빠른 로컬 수정은 일반 세션에서 할 수 있습니다. Projects의 스레드는 격리된 클라우드 환경에서 작동합니다.

### 스레드가 저장소를 복제하지 못하면 무엇을 확인하나요?

연결한 GitHub 계정에 push 권한이 있는지, 해당 저장소에 Claude GitHub App이 설치됐는지 확인하세요. 일반 클라우드 세션에 쓰던 토큰만으로는 Project 스레드에 충분하지 않습니다.


## Ailoot · 회사와 그 프로젝트 포트폴리오

Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.

회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.

Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.