Projects로 지속 작업 조율하기

기준일: 2026-10-23
공식 기준: Let Claude coordinate ongoing work with Projects

개요

Project는 Claude가 관련 작업 흐름을 조율하는 하나의 지속 대화입니다. 할 일을 말하면 Claude가 작업마다 thread를 시작합니다. thread는 보통 클라우드 세션이며, 내 컴퓨터에만 있는 것이 필요한 작업은 Remote Control로 내 컴퓨터에서 실행하도록 요청할 수 있습니다. thread는 병렬로 돌고 휴대폰에서 확인·조향할 수 있으며, 클라우드 thread는 노트북을 닫아도 계속 돕니다(내 컴퓨터 thread는 컴퓨터가 깨어 있는 동안만).

• Pro/Max 퍼블릭 베타, 점진 롤아웃. Team/Enterprise는 아직 미제공. 사이드바(또는 More)에 Projects가 없으면 아직 계정에 도달하지 않은 것이며 대기 명단에 등록할 수 있습니다. 그동안은 Run agents in parallel을 참고하세요.
• 프로젝트 없이 여러 세션을 돌리면 작업 배정, 배경 반복 설명, 완료 확인을 직접 해야 합니다. 프로젝트에서는 한 곳으로 작업 전송 / 컨텍스트 한 번 설정 / 자리를 비웠다 돌아오면 완료된 작업을 확인합니다. Overview 창이 끝난 thread, 리뷰 준비된 PR, 내 답을 기다리는 thread를 보여줍니다.
• 이미 할 일이 분명하면 곧바로 "프로젝트 만들기"로 가세요.

핵심 개념

구성 요소	설명
프로젝트 대화	Claude가 coordinator로 동작하는 장수 세션. 보낸 것을 받아 thread로 만들지 결정하고 모든 thread를 추적. thread가 보고하는 것만 보고 모든 단계를 보지는 않음
Thread	자기 컨텍스트 창을 가진 별개 세션. 한 작업을 하고 끝나면 대화에 보고. 클라우드 thread는 자기 브랜치에서 작업하고 필요하면 PR을 엶
Overview 창	모든 thread와 내 입력이 필요한 것을 한눈에. 탭: Threads, Library(추가한 파일과 thread가 만든 파일), Pull requests, Scheduled tasks
프로젝트 메모리	Claude가 파일로 저장하는 요구사항·결정·함정 노트. 모든 클라우드 thread가 MEMORY.md 인덱스를 읽음
프로젝트 지침	각 새 thread와 프로젝트 대화의 Claude에 전달되는 텍스트(최대 16,000자)

모든 클라우드 thread가 시작 시 받는 것: 프로젝트의 저장소와 파일 + 지침·메모리, 각 저장소의 CLAUDE.md(저장소의 skills, .claude/settings.json, .mcp.json은 제외), claude.ai 계정의 커넥터, 네트워크 접근·환경 변수·네트워크 secret·설치 도구를 정하는 클라우드 환경. 클라우드 thread는 내 로컬 Claude Code 설정을 이어받지 않습니다.

상세

프로젝트가 적합한 경우

목표가 한 세션보다 오래가고 계속 작업을 만들어 낼 때 적합합니다.

• 여러 저장소에 걸친 하나의 목표: "모든 서비스를 새 lint 설정으로". 저장소마다 thread와 PR
• 계속 공급하는 영역: 한 서비스의 버그, 스택 트레이스, 리뷰 요청. 한 번 고친 뒤 기억하라고 한 함정은 다음 thread가 프로젝트 메모리에서 받음
• 한 세션보다 큰 빌드·마이그레이션: "docs/spec.md가 설명하는 것 구현", "deprecated ORM에서 이전". 초기에 기억하라고 한 결정이 이후 클라우드 thread에 전달되고 빌드 중 발견한 스펙 변경·버그도 같은 대화로
• 코드가 아닌 작업: 계약서 폴더, 지원 티켓 export 같은 문서를 업로드(저장소 대신)하고 질문을 반복. thread가 각 결과를 Library 탭의 파일로 전달

작업 묶음을 보내고 확인 없이 시작하라고 한 뒤 자리를 비울 수 있고, 돌아와 Waiting on you에서 내 입력이 필요한 thread를 찾습니다. 일부는 클라우드 예약 작업으로 일정에 올리도록 요청할 수도 있습니다.

다른 것이 더 맞는 경우: 세션 하나에 들어가는 한 작업("flaky 로그인 테스트 수정")은 직접 클라우드 세션 시작. 모든 작업이 내 머신을 요구(로컬 DB, 기기 에뮬레이터, VPN 뒤 API)하면 로컬 세션 또는 agent view(로컬 파일만 필요하면 프로젝트에 업로드). 대화 없이 일정에 맞춰 반복되는 한 작업("매주 월요일 의존성 리포트")은 단독 클라우드 예약 작업. Slack 채널에서 여러 명이 함께 조향하면 Claude Tag.

프로젝트는 다른 Claude Code 세션과 같은 플랜 한도를 더 빠르게 씁니다.

프로젝트 만들기

claude.ai/code, 데스크톱 앱 Code 탭, 모바일 앱에서 만들고 씁니다. 브라우저·데스크톱에서 시작하는 두 방법:

• 처음부터: New project 대화상자에서 이름 입력
• 이미 작업 중인 클라우드 세션에서: 세션 사이드바 메뉴의 Move to project -> Continue as new project. Claude가 세션이 하던 일에서 프로젝트 설정을 제안

사전 점검

• 플랜: Pro 또는 Max이고 사이드바(또는 More)에 Projects 표시. New project 또는 Get started를 제공하는지 확인
• GitHub(코드 작업 시): 코드가 GitHub Enterprise Server/GitLab/Bitbucket이 아닌 github.com에 있고, 연결한 GitHub 계정이 push 권한을 갖고, Claude GitHub App이 설치돼 있어야 함. /web-setup으로 연결한 토큰은 다른 클라우드 세션에는 충분하지만 프로젝트의 클라우드 thread에는 Claude GitHub App이 필요
• 네트워크 접근, secret, 도구: 클라우드 thread는 프로젝트의 클라우드 환경에서 받음. 기본 환경은 일반 패키지 레지스트리에 이미 접근 가능. MCP 서버가 필요하면 claude.ai 커넥터에 연결 상태로 보이는지 확인

처음부터 시작

1. Projects 열기: claude.ai/code 또는 데스크톱 Code 탭의 왼쪽 사이드바 Projects(또는 More). 브라우저는 claude.ai/code/projects/browse로 바로 이동 가능. New project 선택(버튼이 Get started면 선택해 먼저 나열되는 기존 claude.ai 프로젝트를 업그레이드하거나 archive)
2. 대화상자 입력: 계속 작업을 추가할 하나의 흐름(예: API 하나를 지연 목표 아래로 유지하는 데 필요한 모든 것)으로 범위를 정합니다. Name(필수, Projects 목록 표시), Goal(선택, 한 줄 예: "Hold p95 API latency under 200 ms". 없으면 보낸 작업에서 판단, 나중에 Project settings > General에서 추가), Context(선택, 작업할 GitHub 저장소와 thread가 읽을 파일·폴더·Google Drive 폴더, 각각 Add. 대부분의 작업이 필요로 하는 저장소만 추가하고 나중에 Project settings > Environment에서 추가)
3. Create project. 대화가 열립니다. 첫 프로젝트는 먼저 메시지를 보내지 않으면 생성 직후 Claude가 자기 턴을 쓰며(플랜 사용), 읽을 수 있는 저장소가 있으면 아무것도 바꾸지 않고 탐색해 다음 단계를 제안하는 thread 하나를 시작하고 최근 클라우드 세션에서 도출한 Setup recommendations(추가할 저장소, 만들 예약 작업, 시작할 수 있는 thread)를 게시할 수 있습니다. 추천된 저장소와 예약 작업은 모두 켜진 채 시작하므로 원치 않는 것은 끄고 Update setup을 클릭하거나 무시하고 직접 작업을 설명합니다.

기존 클라우드 세션에서 시작: 세션 사이드바 메뉴의 Move to project에서 Continue as new project를 고르면 프로젝트가 열리고 Claude가 세션을 읽어 대화에 Setup recommendations를 게시합니다(원래 세션은 목록에 남고 턴 진행 중이면 계속 실행되므로 둘이 동시에 일하길 원치 않으면 직접 중지). 기존 프로젝트를 고르면 그 프로젝트가 열리고 내 이름으로 보낸 메시지가 Claude에 세션을 읽고 이어서 하도록 요청합니다(원래 세션은 그대로). 클라우드 세션의 메시지 상자 위에 Set up project 배너가 뜰 수도 있으며 이 경우 결과는 같지만 프로젝트가 열리면 세션의 진행 중 턴이 멈춥니다. 로컬 세션에는 이 옵션이 없으므로 작업을 프로젝트 대화에 설명하거나, 브랜치를 push하고 저장소를 프로젝트에 추가한 뒤 작업에 브랜치 이름을 적습니다.

GitHub 접근 설정: 대부분 한 번만 합니다(GitHub 계정은 Claude에 한 번 연결, Claude GitHub App은 저장소별 또는 모든 저장소를 준 조직별로 한 번 설치). 1) GitHub 계정 연결(처음 방문이면 안내, 아니면 GitHub 인증 옵션 사용). 2) 프로젝트 저장소에 Claude GitHub App 설치와 저장소 권한 부여 - GitHub 조직 소유 저장소는 조직 owner만 설치를 완료할 수 있고, 아니면 owner에게 설치 요청이 가며 승인 전까지 사용할 수 없음. 3) SAML SSO를 강제하는 조직은 GitHub를 재연결하고 그 조직에 Claude 앱을 승인(하기 전에는 그 조직의 비공개 저장소가 New project 대화상자와 Project settings > Environment에 나타나지 않음). 단계가 불완전하면 대화상자와 프로젝트 페이지가 빠진 단계를 명시하고 링크하며, 필요하면 Check again을 클릭합니다. 그래도 저장소가 안 보이면 github.com/settings/installations(개인 계정)에서 설치의 Repository access에 저장소가 있는지 확인합니다.

프로젝트에서 작업하기

첫 배치 전 준비

1. 프로젝트 지침 작성(브랜치 대상, 작업 검증 방법, 내 승인이 필요한 것)
2. 실제 작업의 작은 조각 하나를 보내거나 Claude가 제안한 thread 하나를 시작하고, 끝나면 thread를 열어 보고 방식과 브랜치 작업을 확인
3. Project settings > General의 Thread model과 Thread effort 확인. 새 프로젝트는 모든 thread를 Opus + high effort로 실행해 플랜을 가장 빨리 소모
4. Claude에게 thread를 시작 전에 제안하고 한 번에 몇 개만 돌리도록 요청하고, 몇 개가 마음에 들게 돌아오면 제한을 해제

작업 전송과 결과 읽기: 대화에 보낸 각 메시지의 경로는 Claude가 정합니다. 간단한 질문은 대화에서 답, 새 작업은 새 thread 또는 해당 영역을 이미 하는 thread로(어느 쪽인지 알려줌, 새 thread는 메시지 아래 카드로 표시), 관련 없는 여러 작업은 별개 thread. 원하는 경로가 아니면 말하세요. thread의 전체 결과는 thread에 남으므로 카드를 열어 읽고, thread가 만든 파일은 Overview의 Library 탭에도 있습니다. Claude가 thread를 시작하지 않고 Suggested threads 목록으로 제안하기도 하며, 항목의 화살표로 그 thread를 시작하고 여러 개면 목록 아래 버튼이 모두 시작합니다.

thread의 PR 리뷰: 클라우드 thread가 코드를 바꿀 때 기본 동작은 이렇습니다.

• 브랜치: 저장소 기본 브랜치에서 시작한 새 브랜치
• PR: 요청 시 열고, 버그 수정 등 구체적 변경에는 스스로 열 수 있음
• 열린 뒤: 다른 클라우드 세션의 auto-fix 설정과 무관하게 auto-fix를 켠 채 PR을 감시. CI 실패 시 수정 push, 리뷰 코멘트 처리, 체크가 통과하고 PR이 준비되면 thread에 회신

thread가 브랜치를 push했거나 PR을 열었으면 대화의 카드에 다음 단계 버튼이 표시됩니다. Resolve conflicts, Fix CI, Address comments, Merge it은 내 메시지로 thread에 지시를 보내고, Review PR은 GitHub에서 PR을 열고, Create PR은 유휴 thread가 브랜치를 push했지만 PR을 열지 않았을 때 나타나며 클릭하면 thread에 지시하지 않고 그 브랜치에서 직접 PR을 만듭니다. PR을 여는 시점이나 시작 브랜치를 바꾸려면 작업이나 프로젝트 지침에 적습니다.

Overview에서 내 입력이 필요한 것 보기: 대화 옆 Overview 창이 프로젝트의 thread를 추적합니다(새 프로젝트를 처음 열면 이미 열려 있음). 프로젝트 헤더의 Overview 버튼이 열고 닫으며 thread가 나를 기다리면 점이 표시됩니다. 데스크톱 앱은 Claude가 대화에 게시하거나, thread 오류가 나거나, 입력이 필요할 때 데스크톱 알림도 보냅니다(thread가 턴을 마칠 때마다 받거나 끄려면 프로젝트 사이드바 메뉴의 Notifications. 브라우저에서는 점으로 확인).

그룹	내용
Ready for review	PR이 열려 리뷰를 기다리는 thread
Waiting on you	내 답변·승인이 필요하거나 실패한 thread
Working	실행 중인 thread
Landing	PR이 승인되었거나 merge 대기열에 있는 thread
Idle	끝났고 기다리는 것이 없는 thread
Resolved	완료로 표시: 내가 thread 메뉴에서, 마지막 단계(PR merge 등)를 마친 뒤 Claude가, 또는 활동 없이 일주일 후 자동. 같은 메뉴에서 다시 열 수 있음

제어가 필요할 때 thread 열기: 대화의 카드나 Overview 행을 클릭하면 Overview 창에 transcript가 열립니다. 단계별로 읽고, thread 자체 메시지 상자에 써서 조향(thread에 바로 전달됨. 프로젝트 대화의 후속 메시지는 Claude가 그 thread와 매칭할 때만 닿음)하고, 기다리는 권한 프롬프트에 답하고, 작업 중 전송 버튼을 대체하는 Stop 또는 Esc로 중단합니다.

모델과 컨텍스트: Project settings > General에서 설정합니다. 새 프로젝트는 어디서나 Opus이며 thread는 high effort, 대화는 low effort입니다. Thread model/Thread effort는 thread, Coordinator model/Coordinator effort는 프로젝트 대화의 Claude에 적용됩니다. 한 작업에 다른 모델을 쓰려면 작업에서 요청하고, 실행 중인 thread는 그 thread의 모델 선택기를 씁니다. 컨텍스트 창을 직접 관리할 필요가 없습니다. thread는 자동으로 compact하고 대화는 전체 기록이 아니라 최근 메시지·최근 thread·프로젝트 메모리로 작동하므로 프로젝트가 도는 동안 계속됩니다. 절대 버리면 안 되는 것은 프로젝트 메모리에 둡니다.

Claude 운영 방식 조정

대화에서 동시 thread 수, 업데이트 시점, PR 여는 시점을 말합니다. 예:

• "Propose threads and wait for my go-ahead before starting them" 또는 "Start these now without asking me to confirm"
• "Run at most two threads at a time" 또는 "Reuse an existing thread for follow-ups in the same area"
• "Post shorter updates" 또는 "Only post when something finishes or is blocked"
• "Give me a status update on every thread"
• "Do this task with a smaller model"
• "Don't open a pull request until I've seen the plan"
• "Tell me what's wrong in these repositories and don't fix anything yet" (찾은 것들을 thread로 만들기 전에 검토하려 할 때)
• "Answer that here instead of starting a thread" (간단한 질문인데 Claude가 thread를 시작했을 때)

Claude는 이런 선호를 스스로 프로젝트 메모리에 저장해 이후 클라우드 thread에서 따릅니다. 강제 설정이 아니라 Claude가 지키는 지시이므로 thread 수 제한은 하드 캡이 아닙니다. 정확한 문구로 모든 thread에 처음부터 적용하려면 프로젝트 지침에 넣으세요.

승인 대기 thread 풀기: thread의 모델이 지원하면 thread는 auto mode로 실행되어 대부분의 도구 호출이 묻지 않고 실행됩니다. 승인이 필요하면 프롬프트는 그 thread 안에 있고 거기서 답할 때까지 thread가 기다리며, 프로젝트 대화에서 진행하라고 해도 닿지 않습니다. 각 승인은 그 프롬프트 하나, 넓은 옵션을 고르면 그 thread의 나머지에 적용됩니다. 클라우드 thread는 저장소 .claude/settings.json의 permission 규칙을 읽지 않으므로 auto mode와 각 thread 안에서의 승인에 의존합니다.

내 컴퓨터에서 thread 실행: 로컬 DB, 기기 에뮬레이터, VPN 뒤 API처럼 내 컴퓨터에만 있는 것이 필요하면 프로젝트 대화에서 클라우드 대신 내 컴퓨터에서 그 작업의 thread를 실행하도록 요청합니다. thread는 내 머신 폴더의 Claude Code 세션이며 Remote Control로 연결됩니다. 프로젝트의 다른 thread는 계속 클라우드에서 돕니다. 클라우드 thread와 비교해 이 thread는 프로젝트 클라우드 환경이 아니라 그 머신의 파일·도구·MCP 서버·Claude Code 설정(hook과 권한 규칙 포함)을 사용하고, 프로젝트 지침으로 시작하지만 메모리 파일은 로드하지 않으며, 그 컴퓨터가 깨어 있고 Remote Control이 켜져 있는 동안만 실행됩니다.

1. 폴더 연결 (그 컴퓨터에서 두 방법 모두 Claude Code v2.1.280+): Claude 데스크톱 앱은 Settings > Claude Code에서 Use this computer from your phone and claude.ai를 켜고 스위치 아래 목록에 폴더 추가(앱이 열려 있는 동안 thread 실행 가능). 터미널은 폴더에서 claude remote-control을 실행해 두기. git 저장소에서는 --spawn worktree로 각 thread에 폴더 자체 대신 전용 worktree 제공
2. Work locally로 작업 요청: 프로젝트 대화에서 메시지 상자 옆 + 메뉴의 Work locally를 선택하면 메시지에 Local 태그가 붙고 하고 싶은 것을 씁니다. 메시지에서 내 컴퓨터에서 실행하라고 말해도 됩니다
3. 카드에서 허용: Claude가 Allow Claude to work in a folder on your device 카드로 응답합니다. 여러 폴더를 연결했으면 고르고, 같은 폴더에서 두 thread가 동시에 일하면 변경을 덮어쓸 수 있으므로 git 저장소면 폴더 옵션의 Worktree를 켜 전용 worktree를 줄 수 있습니다. 그 뒤 Allow once

thread는 auto mode로 실행되어 그 폴더에서 매번 묻지 않고 명령 실행·파일 수정을 합니다. 그 컴퓨터의 Claude Code에서 auto mode를 쓸 수 없거나 꺼져 있으면 auto mode 없이 실행되고 권한 프롬프트는 thread에서 내 답을 기다립니다. 실행 중에 thread 헤더의 노트북 아이콘이 컴퓨터 연결 여부를 보여주며 클릭하면 사용 중인 폴더를 보거나 연결을 끌 수 있습니다. 컴퓨터가 잠들면 thread가 일시정지하고 데스크톱 앱이나 claude remote-control이 종료되면 멈춥니다. 데스크톱 앱에서는 Settings > Claude Code의 Keep this computer awake for Remote Control을 켜 컴퓨터가 자동으로 잠들지 않게 할 수 있습니다. 계정에 Require trusted devices가 켜져 있으면 프로젝트가 내 컴퓨터에서 thread를 실행할 수 없습니다.

표준 컨텍스트 제공

컨텍스트	담는 것	설정 방법
프로젝트 메모리	요구사항·결정·함정 같은 노트(파일). 모든 클라우드 thread가 시작 시 인덱스 MEMORY.md를 읽고 필요할 때 나머지를 엶	프로젝트 대화나 아무 클라우드 thread에서 Claude에게 기억/잊으라고 요청. 파일은 Project settings > Memory에서 읽고 편집·삭제
프로젝트 지침	각 새 thread와 프로젝트 대화의 Claude에 전달되는 텍스트(최대 16,000자)	Project settings > Memory > Project instructions, 또는 Claude에게 지침 변경 요청
저장소·파일·환경	모든 클라우드 thread가 clone하는 저장소, /mnt/project-files 아래 읽을 수 있는 폴더·파일, 실행 환경	저장소와 환경은 Project settings > Environment 또는 대화에서 Claude에게 추가 요청. 파일·폴더는 Overview의 Library 탭 Add

Project settings > Memory는 Claude가 작업하며 직접 쓰므로 이 파일들을 Auto memory로 나열합니다. 둘 다 MEMORY.md 인덱스를 쓰지만 내 머신의 Claude Code auto memory와는 별개이고, 프로젝트 저장소의 CLAUDE.md와도 별개입니다. 클라우드 thread는 시작 시 clone에서 그 CLAUDE.md를 읽으므로 저장소에 대한 지침은 해당 CLAUDE.md에, 프로젝트에 대한 노트는 프로젝트 메모리에 둡니다.

프로젝트 지침 작성: 프로젝트 헤더의 톱니바퀴로 Project settings를 열고 Memory > Project instructions로 갑니다. 프로젝트 목적, 작업 위치(저장소, 시작 브랜치, PR 이름 규칙), thread가 끝났다고 하기 전 스스로 검증하는 방법, 필요한 것이 없을 때 할 일, 먼저 내 승인이 필요한 것을 담습니다. 예:

This project holds p95 latency for the payments API under 200 ms: profiling, query and caching fixes, and the dependency upgrades that come with them, in the payments-api repository.

- Branch from main and open one draft pull request per thread.
- Before you call work done, run `make test` and `make lint` and paste the summary lines in your final message.
- If you can't reach something you need, such as a repository, a secret, an API, or a connector, say exactly what's missing in your first message and stop. Don't substitute, mock, or guess.
- Don't merge, force-push, or change CI configuration without asking me in the thread.

저장소 하나에 대한 규칙(빌드 명령 등)은 해당 저장소의 CLAUDE.md에 두면 모든 클라우드 thread가 읽습니다. 작업 중 thread를 교정할 때는 Claude에게 그 교정을 기억하라고도 하면 프로젝트 메모리에 들어가 이후 클라우드 thread가 받습니다.

추가할 저장소 결정: 프로젝트에 추가한 저장소는 모든 클라우드 thread에 코드와 CLAUDE.md가 들어옵니다(skills, .claude/settings.json, .mcp.json은 제외). 추가하지 않은 저장소도 닿을 수 있습니다. 클라우드 thread가 작업에 필요하면 스스로 추가할 수 있습니다.

• 프로젝트에 추가: New project 대화상자, Project settings > Environment, 또는 대화에서 Claude에게 요청. 이후 모든 클라우드 thread가 작업이 건드리든 아니든 그 저장소를 clone하고 CLAUDE.md를 로드한 채 시작
• 추가하지 않고 thread가 필요할 때 추가: thread 안 메모가 이 thread에만 추가되었다고 알림. clone이 작업 도중이므로 그 저장소의 CLAUDE.md는 thread 시작 시 없었고 다음 thread는 그것 없이 시작. 이렇게 추가한 저장소도 프로젝트 저장소와 같은 사전 요건(Claude GitHub App 설치, GitHub 계정의 push 권한) 필요

프로젝트는 저장소가 아예 없어도 됩니다. 클라우드 thread는 자기 샌드박스에서 조사하고 문서를 쓰고 코드를 쓰고 실행하며 파일을 Library 탭으로 전달합니다. 프로젝트에 이미 저장소가 있으면 Claude가 추가할 수 있는 저장소는 프로젝트가 이미 쓰는 GitHub owner의 것뿐입니다(프로젝트 추가든 thread 자체 추가든). 다른 owner의 저장소는 Project settings > Environment에서 직접 추가합니다. 서버·웹·모바일·데스크톱처럼 많은 저장소에 걸친 프로젝트는 거의 모든 작업이 건드리는 한두 개를 추가하고 나머지는 프로젝트 지침에 이름을 적어 Claude가 코드 위치를 알게 하면 thread가 작게 시작해 필요한 작업에서만 나머지를 끌어옵니다.

파일·폴더 추가: New project 대화상자의 Context 필드 또는 나중에 Overview의 Library 탭 Add. 제한:

• Library 탭: 한 번에 최대 100개 파일과 2 GB, 단일 파일 최대 480 MB
• New project 대화상자: 30 MB 초과 파일은 건너뛰므로 큰 파일은 생성 후 Library 탭에서 추가
• 폴더: 어느 쪽에서든 처음 100개 파일 최대 200 MB의 복사본을 받되 30 MB 초과 파일, 숨김 파일, node_modules는 제외. 프로젝트는 폴더와 Google Drive 폴더를 합쳐 최대 10개(단일 파일은 미집계)
• 업로드 후 변경: 업로드는 복사본이므로 내 컴퓨터에서의 변경은 다시 업로드하고 기존 이름에 대해 Replace를 고를 때까지 프로젝트에 반영되지 않음

thread가 저장소에서 가져가는 것: 저장소가 하나든 여럿이든 클라우드 thread는 각 저장소의 CLAUDE.md 지침은 로드하지만 skills, .mcp.json 서버, .claude/settings.json은 로드하지 않습니다.

저장소 내 항목	클라우드 thread
저장소 루트의 CLAUDE.md, .claude/CLAUDE.md, .claude/rules/	thread 시작 시 모든 저장소에서 로드. 하위 디렉터리의 CLAUDE.md와 path-specific rules는 로드 안 됨
.claude/skills/의 skills	로드 안 됨. 대신 claude.ai 계정에 skill 활성화
.claude/ 아래 agents와 commands	로드 안 됨. 쓰려면 내 컴퓨터에서 thread 실행
.mcp.json의 MCP 서버	로드 안 됨. 대신 claude.ai 계정 커넥터 사용
.claude/settings.json에서 활성화한 플러그인	로드 안 됨. 대신 Project settings > Plugins에 플러그인 추가
.claude/settings.json의 permission 규칙	적용 안 됨. thread 안에서 도구 호출 승인, 또는 내 컴퓨터에서 thread 실행
.claude/settings.json의 hooks	실행 안 됨. hook을 쓰려면 내 컴퓨터에서 thread 실행
.claude/settings.json의 env	적용 안 됨. 클라우드 환경에 환경 변수 설정

thread 환경 선택: 새 클라우드 thread는 항상 프로젝트의 클라우드 환경에서 시작합니다. 환경은 접근 가능한 도메인, 환경 변수, 요청에 추가되는 네트워크 secret, Claude 시작 전 setup script가 설치하는 것을 정합니다. Project settings > Environment에서 고르기 전까지는 기본 Anthropic 호스티드 환경입니다. 내부 API나 비공개 패키지 레지스트리에 닿거나 내 머신이 보통 가진 토큰이 필요하면 프로젝트가 아니라 환경을 바꿉니다(Network access, Add network secrets, Setup scripts).

skills, 플러그인, 커넥터, 도구 가져오기: 클라우드 thread에는 내 머신에만 설치된 skills, MCP 서버, 플러그인, 도구가 없습니다(Remote Control로 내 머신에서 실행하는 thread는 거기 설치된 것을 사용).

• Skills: claude.ai 계정에 활성화하면 클라우드 thread가 로드(셀프호스티드 환경의 일부 thread 제외). 저장소 .claude/skills/에 커밋된 skills는 로드 안 됨
• 플러그인: Project settings > Plugins에 추가하면 각 새 클라우드 thread에 로드. 저장소 .claude/settings.json이 선언한 플러그인은 클라우드 thread에 로드 안 됨
• MCP 서버: 클라우드 thread의 MCP 도구는 claude.ai/customize/connectors에서 한 번 연결한 계정 커넥터에서 옴. 프로젝트별 설정 없이 모든 클라우드 thread가 모두 사용. 프로젝트 대화 자체에는 커넥터가 없으므로 커넥터가 필요한 작업은 클라우드 thread 작업으로 보냄
• CLI 도구·패키지: 환경의 setup script에서 설치

실행 중 클라우드 thread의 커넥터는 thread를 열고 메시지 상자 옆 + 메뉴의 Connectors에서 봅니다. 거기서 끄면 그 thread에서 제거되고 계정 기본값으로 저장되어 다시 켤 때까지 새 thread와 claude.ai 채팅이 그것 없이 시작합니다. 클라우드 thread는 커넥터를 추가·재연결한 뒤 다음에 보내는 메시지부터 반영합니다.

프로젝트 설정 레퍼런스

settings.json이 아니라 claude.ai/code나 데스크톱 앱에서 바꿉니다. 프로젝트 사이드바 메뉴의 Settings 또는 헤더의 톱니바퀴로 Project settings를 엽니다. 변경은 즉시 저장되며(편집 중 텍스트 필드는 떠나기 전까지 Save changes/Discard), 지침·저장소·플러그인·환경 변경은 실행 중 thread가 아니라 새 thread에 반영됩니다.

설정	섹션	제어하는 것
Name, icon, goal	General	사이드바의 프로젝트 이름·아이콘과 한 줄 목표
Coordinator model and effort	General	프로젝트 대화의 Claude 모델과 effort
Thread model and effort	General	thread의 모델과 effort
Project instructions	Memory	모든 새 thread가 받는 표준 규칙
Project repositories	Environment	새 클라우드 thread가 clone하는 저장소
Cloud environment	Environment	새 클라우드 thread가 실행되는 클라우드 환경
Plugins	Plugins	각 새 클라우드 thread에 로드되는 플러그인
Usage	Usage	thread별·모델별 토큰 사용
Memory	Memory	프로젝트의 메모리 파일
Restart Claude	General	Claude가 응답을 멈췄을 때 프로젝트 대화 재시작
Pause, Archive, Delete	General	프로젝트 중지·숨김·삭제

일시정지·보관·삭제(Project settings > General 하단):

• Pause: 모든 것을 한 번에 중지. 실행 중 thread와 대화가 중단되고, 새 thread가 시작되지 않으며, 예약 작업이 실행되지 않고, 재개할 때까지 메시지를 받지 않음. 같은 곳이나 메시지 상자 위 배너의 Resume. 일시정지된 thread는 이후 메시지를 보내면 이어서 진행
• Archive: 사이드바에서 숨기고 thread를 archive해 실행·PR 감시를 멈춤. 보관 중에는 예약 작업이 실행되지 않음. Projects 페이지에서 열어 Unarchive. thread는 세션 목록에서 개별로 unarchive하기 전까지 보관 상태
• Delete: 프로젝트와 thread, 메모리, 파일을 영구 삭제하고 예약 작업을 끔. 되돌릴 수 없음. thread가 GitHub에 push한 브랜치와 PR은 영향 없음

사용량과 비용

프로젝트 사용량은 다른 Claude Code 세션과 같은 플랜 한도에 집계되며 프로젝트가 스스로 한도를 넘겨 쓰지 못합니다. 플랜 한도에 도달한 thread는 기다렸다가 한도가 리셋되면 스스로 이어가므로, 두고 간 작업이 다음 사용 window를 사용하기 시작할 수 있습니다. 플랜 한도를 넘는 작업은 계정에 사용량 크레딧을 켠 경우에만 가능하며 thread가 대신 켤 수 없습니다.

플랜을 사용하는 부분(프로젝트는 단일 세션보다 한도를 빨리 소모하며 Pro에서는 프로젝트를 돌리는 날 더 일찍 한도에 도달):

• 실행 중 thread: 각각 전체 세션이며 동시에 여러 개. 고정 수는 없고 작업이 필요로 하는 만큼 시작하며 요청한 제한은 선호일 뿐 캡이 아님. 강제 제한은 프로젝트 전체에서 하루 200개 신규 thread
• 대화: thread 보고를 읽고 다음을 결정하는 데 Claude 자신의 토큰 사용
• PR을 감시하는 thread: 유휴 thread가 PR에서 CI 실패나 리뷰 코멘트가 오면 깨어나 다시 플랜을 사용. 막으려면 thread에서 PR 감시를 멈추라고 요청

실행 중 thread, 감시 PR, 새 메시지가 없는 프로젝트와 archive된 프로젝트는 유휴 시 플랜을 쓰지 않습니다.

사용량 확인과 줄이기: Project settings의 Usage에서 thread별·모델별 토큰 사용과 프로젝트 대화에 쓴 양을 봅니다. 줄이려면 cache lifetime(Pro/Max 한도 내에서 한 시간)보다 오래 유휴인 thread로 라우팅된 후속 메시지는 먼저 그 thread의 전체 대화를 다시 읽으므로, 새 작업은 큰 옛 thread를 되살리기보다 새 thread를 시작하라고 요청하는 편이 덜 쓸 수 있습니다. 가장 큰 모델이 필요 없는 작업은 thread와 대화의 모델·effort를 낮추고, Claude에게 동시 thread를 줄이거나 작은 질문은 직접 답하라고 요청합니다.

다른 Claude Code 기능과의 관계

• Claude Tag: Team/Enterprise의 Slack 채널 Claude. 채널의 누구나 작업을 줄 수 있고 모두가 보고 조향하며 관리자가 채널에 설정한 연결을 사용. 프로젝트는 나 혼자 쓰고 내 GitHub 접근과 커넥터를 쓰며 Pro/Max
• 클라우드 세션: 내 머신에서 실행하도록 요청하지 않는 한 모든 thread는 클라우드 세션. 직접 시작한 클라우드 세션의 작업은 Move to project로 가져올 수 있음
• 예약 작업: 프로젝트에서 예약 작업을 요청하면 Claude가 그 프로젝트의 thread로 실행되는 클라우드 예약 작업을 만들고 Scheduled tasks 탭에 나타남. 프로젝트 밖에서 만든 예약 작업은 독립적으로 계속 동작
• Remote Control: 내 컴퓨터에서 thread를 실행하도록 요청하면 프로젝트가 Remote Control로 수행
• 로컬 세션과 agent view: 터미널·IDE·데스크톱 앱 로컬 환경에서 직접 시작한 세션은 프로젝트에 추가할 수 없음. agent view는 여러 로컬 세션을 나란히 추적하는 화면이며 각 세션은 직접 시작해 작업을 줌
• Worktrees: 로컬 세션마다 작업 복사본을 주는 기능. 클라우드 thread는 각자 클라우드 샌드박스에 clone하고 자기 브랜치에서 작업하므로 불필요
• Agent teams: 한 작업을 위해 팀원 세션을 시작하고 그 작업과 함께 끝나는 하나의 세션
• Subagents: 한 세션 안에서 자기 컨텍스트 창으로 부수 작업을 하고 요약을 돌려줌. 프로젝트의 thread는 Claude가 시작하고 프로젝트 대화에 보고하는 전체 세션이며 thread도 자기 부수 작업에 subagent를 쓸 수 있음
• claude.ai 채팅/Cowork의 Projects: 대화와 참조 파일을 묶는 이전 Projects 경험. 재설계 경험이 도달하기 전까지 지금처럼 동작

제한

• claude.ai/code, 데스크톱 앱, 모바일 앱에서 사용 가능. 터미널 CLI, VS Code 확장, JetBrains 플러그인과 Amazon Bedrock/Google Cloud Agent Platform/Microsoft Foundry에서는 불가
• thread는 클라우드 세션 또는 Remote Control로 내 머신의 세션이며 두 경우 모두 Anthropic이 모델 프로바이더
• 내 머신에서 직접 시작한 세션은 프로젝트에 추가할 수 없음. 프로젝트가 내 머신에 닿는 방법은 Remote Control로 thread를 실행하는 것뿐
• 클라우드 thread의 샌드박스는 턴 사이에 일시정지되고 thread가 이어질 때 재개. 재개하지 못하면 새 clone에서 이어가 미커밋 변경이 유실될 수 있으므로 긴 작업은 진행 중인 작업을 commit/push하라고 요청
• 프로젝트는 한 사용자에게 속하며 프로젝트나 thread를 다른 사용자와 공유할 수 없고 thread transcript에 다른 클라우드 세션의 공유 옵션이 없음. 베타 동안 조직 수준 제어 없음
• thread는 시작한 프로젝트 하나에 속하며 다른 프로젝트로 이동·복사하거나 독립시킬 수 없음. Move to project는 반대 방향(클라우드 세션 작업을 프로젝트로)만 가능. 두 프로젝트를 병합할 수 없음

트러블슈팅

• thread가 멈춘 것 같음: Claude는 thread의 모든 단계를 게시하지 않으므로 실행 중인데 새 메시지가 없으면 보통 계속 작업 중입니다. 새 클라우드 thread는 Claude 시작 전에 클라우드 환경을 프로비저닝해 첫 업데이트가 조금 걸립니다. thread를 열어 transcript를 읽고 권한 프롬프트를 기다리면 거기서 답합니다.

• thread가 묻는 대신 추측하거나 멈춤: 여러 thread가 잘못 가정했거나 접근 누락을 우회했거나 "blocked"로 멈춘 경우 보통 각 작업이 아니라 프로젝트 설정의 같은 공백이 원인입니다. (1) 대화에서 "For every open thread, list what you asked it to do, what it assumed or couldn't reach, and what it's waiting on."이라고 묻습니다. (2) 잘못된 가정으로 시작한 thread는 Overview에서 열어 메뉴에서 resolved로 표시하거나 메시지 상자에서 대신 할 일을 알립니다(브랜치와 PR은 삭제하기 전까지 GitHub에 남음). (3) 프로젝트 지침이나 환경에서 공백을 한 번 고치고 나머지 작업을 새 thread로 다시 보내기 전에 thread 하나를 보냅니다.

• Claude hasn't responded: Claude는 실행 중인데 응답이 프로젝트에 닿지 않을 때 배너가 뜹니다. 배너의 Restart Claude 또는 Project settings > General의 Restart Claude 행 Restart를 클릭합니다. 작성 중이던 응답은 사라지고 thread는 영향이 없습니다.

• 저장소 접근 오류: 다른 클라우드 세션이 같은 저장소를 문제없이 clone해도 프로젝트의 클라우드 thread에는 GitHub 사전 요건이 필요합니다.

  • "Couldn't start the session — Claude doesn't have GitHub access to this project's repository": thread 시작 전, Claude GitHub App이 해당 저장소에 설치되지 않았거나 정지되었거나 연결한 GitHub 계정과 연결되지 않음
  • "Unable to access your repository": thread의 clone 실패. GitHub가 clone을 거부했거나, 프로젝트가 가진 이름으로 저장소가 없거나, thread가 시작하도록 요청받은 브랜치가 없음
  • "Claude can't access" 저장소: New project 대화상자나 Project settings에서 저장소를 저장할 때. 설치 링크와 재연결 링크가 이어지며 GitHub App이 그 저장소에 없으면 설치 링크, 있으면 재연결 링크(GitHub에 설치돼도 Claude에 연결한 계정과 연결되지 않을 수 있음). 정지됨/저장소 미포함이면 GitHub로 가는 링크로 해결

  메시지의 버튼(Install GitHub App, Select repositories on GitHub)을 누르고 Check again. 조직 쪽 차단(owner가 승인 안 함, Claude를 제외한 IP allow list)이면 See how to fix 링크가 표시되고, 버튼이 없으면 GitHub 접근 설정을 따른 뒤 메시지를 다시 보내 재시도합니다.

• thread가 사용 한도에 도달: thread나 프로젝트 대화가 플랜의 5시간 또는 주간 한도에 도달하면 스스로 재시도하다 한도가 리셋되면 이어갑니다. 예약 작업이 시작한 thread는 기다리지 않고 한도 오류로 턴이 멈추며 한도 리셋 후 메시지를 보내야 합니다. 대기 중 thread는 Service is busy와 "Claude is still retrying and will continue automatically."를 표시합니다. 다음 사용 window를 쓰지 않게 하려면 thread의 Stop을 클릭하거나 프로젝트를 pause해 모든 thread를 멈춥니다.

• Additional usage credits are required: 플랜이 사용량 크레딧으로만 커버하는 요청(플랜에 없는 모델·컨텍스트 크기)인데 계정에 크레딧이 꺼져 있음. 누가 켜거나 살 수 있는지는 costs 문서의 "Add usage credits to your subscription"을 보고, 크레딧이 가능해지면 메시지를 다시 보내 재시도

• Lost contact with your folder: 내 컴퓨터에서 실행하는 thread의 Claude Code 세션이 응답을 멈췄을 때(보통 컴퓨터 잠듦 또는 데스크톱 앱/claude remote-control 종료). 컴퓨터를 깨우고, 앱이나 claude remote-control이 실행 중이 아니면 다시 시작: 앱을 다시 열어 Settings > Claude Code의 Use this computer from your phone and claude.ai가 켜져 있는지 확인하거나 같은 폴더에서 claude remote-control을 다시 실행

메시지	조치
"Unable to connect to repository" + "Claude couldn't reach GitHub to fetch your repository"	잠시 기다린 뒤 메시지를 다시 보내 재시도
"Unable to connect to repository" + "Claude couldn't access your repository or environment"	GitHub 계정에 저장소 push 권한이 필요하고 환경이 아직 있어야 함. Project settings > Environment에서 둘을 확인하고 재시도
"Couldn't show the setup proposal"	열려 있는 앱이 Claude가 보낸 Setup recommendations보다 오래됨. 페이지를 새로고침/데스크톱 앱 재시작하거나 Claude에 설정을 다시 제안하도록 요청
"The project's environment was removed"	Project settings > Environment에서 다른 환경 선택(새 thread에 적용)
"Setup script failed"	오류의 Edit setup script를 클릭해 환경의 스크립트를 고치고 메시지를 다시 보냄
"Claude ran out of context on this turn"	thread가 컨텍스트 창을 가득 채움. 메시지가 새 세션에서 이어진다고 하면 스스로 계속하고, 아니면 프로젝트 대화에서 남은 작업을 위한 새 thread를 요청
"Couldn't start in" + 폴더 이름	내 컴퓨터에서 thread를 허용했으나 세션이 거기서 시작하지 못함. 메시지 아래 줄에 이유가 있으면 고친 뒤 Claude에게 다시 실행하도록 요청
"Claude is out of date on your device"	선택한 컴퓨터의 Claude Code가 v2.1.280 미만. 거기서 업데이트(폴더를 연결하는 것이 데스크톱 앱이면 앱 업데이트)한 뒤 다시 요청
"Reached the turn limit"	thread가 CLAUDE_CODE_MAX_TURNS가 정한 에이전트 턴 상한에 도달. 메시지를 보내 계속하거나 그 변수를 올리거나 제거

함께 보기

• Run agents in parallel
• Claude Code on the web
• Cloud environments
• Routines (scheduled tasks)
• Agent view
• Remote Control
• Projects redesigned: from folder to conversation