Claude Code 프로젝트 관리: 이슈부터 리뷰까지

Claude Code는 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하며, git과 직접 연동하는 에이전트형 코딩 도구입니다. 터미널 하나에서 혼자 일하는 개발자에게는 관리가 전혀 필요하지 않습니다. 작업을 설명하고, 실행되는 모습을 지켜보고, diff를 검토하면 끝입니다. 이 루프는 빠르며, 이 가이드는 그 루프를 포기하라고 요구하지 않습니다.

문제는 팀이 이 도구에 의존하기 시작할 때 드러납니다. 개발자 다섯 명이 각자 Claude Code 세션을 돌리면 실질적인 결과물은 나오지만, 그 작업은 각자의 터미널 안에만 남습니다. 팀 운영에 반드시 필요한 질문들에 아무도 답할 수 없습니다. 이 변경을 누가 요청했는지, 지금 누가 실행하고 있는지, 그 실행이 실제로 무엇을 했는지, 병합 전에 누가 결과를 승인했는지 말입니다. 실행 자체는 훌륭하지만, 작업에 대한 기록은 존재하지 않습니다.

Claude Code 프로젝트 관리란 그 작업을 추적 가능하고 검토 가능한 프로젝트 작업으로 운영하는 방식입니다. 이슈가 목표와 경계, 완료 기준을 갖춘 범위 지정된 Task가 되고, 그 Task는 Claude Code로 실행하는 Agent에 배정되며, 실행은 직접 통제하는 머신의 격리된 워크트리에서 이루어지고, 결과는 검토를 위해 사람에게 돌아옵니다. 이 가이드는 Sharkly를 사용해 이 흐름을 따라갑니다. Sharkly는 Claude Code를 대체하는 도구가 아닙니다. 팀이 이미 사용하는 도구 주위에 공유된 작업, 컨텍스트, 제어, 검토 계층을 더해줍니다.

요약

Claude Code 작업을 프로젝트 작업처럼 관리하려면, 이슈를 목표와 경계, 완료 기준을 갖춘 범위 지정된 Task로 작성하고, Runtime이 Claude Code인 Agent에 배정합니다. 그러면 연결된 Computer의 격리된 git 워크트리에서 실행이 진행되고 진행 상황이 실시간으로 전달됩니다. 이후 Task에서 증거를 검토하고 승인하거나, 변경을 요청하거나, 다시 배정하면 됩니다. 실행은 Claude Code가 담당합니다. Sharkly는 그 주변에서 배정, 컨텍스트, 진행 상황, 블로커, 결과, 사람의 검토를 관리하므로, 병렬 실행이 개인 터미널 속으로 사라지지 않고 팀 전체에 보입니다. 빠르고 로컬 환경에서 부담 없는 작업에는 개인 터미널 세션이 여전히 적합한 도구입니다.

관리되는 Task가 일반 Claude Code 세션에 더하는 것

일반 세션과 관리되는 Task는 내부적으로 동일한 Claude Code를 실행합니다. 차이는 실행을 둘러싼 모든 것에 있고, 이는 터미널이 제공할 수 없는 네 가지 역량으로 나뉩니다.

공유된 가시성. Task는 요구사항, 작업 상태, 논의, 실행 기록, 검토를 각기 다른 개인 프롬프트와 세션에 흩어 놓지 않고 한곳에 모읍니다. 팀 동료가 SH-214를 열어 무엇을 요청했고, 무엇이 실행 중이며, 무엇이 돌아왔는지 확인할 수 있습니다.

책임 소재. Task는 사람의 책임과 Agent의 실행을 분리합니다. 결과에 대한 책임은 사람에게 있고, 실행 담당자는 Agent 또는 Crew입니다. 둘 다 기록되므로 “누가 이걸 책임지는가”에 대한 답은 항상 존재합니다.

검토 증거. 모든 실행은 실행 트레이스를 남깁니다. 언제 시작했고, 어떤 도구를 호출했고, 왜 대기열에 들어갔고, 어떻게 끝났는지 말입니다. Agent의 보고서는 그 트레이스에 연결된 댓글로 저장됩니다. 검토는 “터미널을 지켜본 사람을 믿는” 일이 아니라 “기록을 읽는” 일이 됩니다.

충돌 없는 병렬 실행. 각 Task에는 격리된 디렉터리가 주어지고, 저장소 기반 작업은 실행마다 별도의 git 워크트리를 사용할 수 있어 여러 Task가 동시에 같은 코드베이스를 수정할 수 있습니다. 병렬 실행의 작동 방식은 별도 가이드에서 다룹니다: 여러 Claude Code 에이전트를 병렬로 실행하는 방법.

본격적인 설명에 앞서 분명히 해둘 경계가 하나 있습니다. 모든 Claude Code 세션에 이 방식이 필요한 것은 아닙니다. 질문을 탐색하거나, 계획을 세우거나, 간단한 로컬 수정을 할 때는 독립형 Agent Chat이나 일반 터미널 세션을 사용하세요. 작업에 책임 소재, 상태, 실행 이력, 검토가 필요할 때 Task를 사용하면 됩니다.

1단계: 이슈를 Agent가 실행할 수 있는 Task로 바꾸기

이 흐름은 에이전트가 실행되기 전에 시작됩니다. Claude Code는 주어진 정보를 바탕으로 접근 방식을 계획하므로, 모호한 Task는 엉뚱한 방향으로 자신 있게 실행하는 결과를 낳습니다.

유용한 Task 제목은 주제가 아니라 결과를 명시합니다. 설명에는 새로 합류한 사람이나 Agent가 작업을 진행하는 데 필요한 내용이 담겨야 합니다. 이 작업이 왜 중요한지, 무엇이 범위 안이고 무엇이 범위 밖인지, 관련 파일과 링크 또는 관찰된 동작, 이미 내려진 제약과 결정, 그리고 완료 여부를 어떻게 검토할지입니다.

마지막 항목은 개인 작업 흐름에서 흔히 빠뜨리는 부분입니다. “완료란 기존 동작에서 실패하는 테스트가 재시도 로직에 추가된 상태”라고 설명에 적어두면, 검토자에게는 체크리스트가 생기고 Agent에게는 목표가 생깁니다. 변하지 않는 목표와 범위, 완료 기준은 설명에 두고, 논의에는 댓글을 사용하세요.

상태 카테고리도 여기서 중요합니다. Backlog에 있는 Task는 보류 상태이며, 여기에 Agent를 배정해도 실행이 시작되지 않습니다. 이는 의도된 기능입니다. 여러 Task를 한꺼번에 만들고 모두 배정한 뒤, 준비된 것부터 Backlog에서 꺼내 하나씩 실행시킬 수 있습니다.

이슈가 이미 다른 곳에 있다면 프로세스를 새로 만들 필요가 없습니다. Sharkly의 연동에는 Jira, Slack, GitHub이 포함되어 있어, 기존 트래커는 그대로 두면서 실행을 배정하고 추적할 수 있습니다. 에이전트가 실행할 수 있도록 작업을 작성하는 규율은 더 큰 변화의 일부이며, 에이전틱 코딩이란 무엇인가에서 다룹니다.

2단계: Runtime이 Claude Code인 Agent에 배정하기

Sharkly에서는 Claude Code에 직접 작업을 배정하지 않습니다. Agent에 배정하고, 그 Agent의 Runtime이 Claude Code입니다. 이 구분은 충분히 값어치가 있습니다.

Agent는 일회성 프롬프트가 아니라 저장된 작업 구성입니다. 지시사항, Runtime, Skills, 저장소, 환경 변수, 실행 설정이 그 Agent가 작업을 처리하는 방식을 결정합니다. 한 사람이 “Backend Fixer” Agent를 한 번 구성해 Space에 공유하면, 개발자마다 프롬프트를 즉흥적으로 짜는 대신 팀 전체가 동일한 검증된 구성에 작업을 배정합니다. 이 개념은 Sharkly의 Agent, 완전히 이해하기에서 자세히 다룹니다.

Runtime은 Computer에서 사용할 수 있는 구체적인 에이전트 도구입니다. 머신을 연결하면 작은 로컬 서비스가 그곳에 설치된 지원 에이전트 도구를 감지해 각각을 Runtime으로 보고합니다. Claude Code가 설치되어 있으면, 서비스가 인식하는 순간 사용 가능한 Runtime으로 나타납니다.

이 구조를 이해할 때 오해를 막아주는 세 가지 사실이 있습니다.

• Agent는 Runtime의 기본 모델을 따릅니다. Sharkly는 모델 이름을 표시하거나 보장하지 않으며, Agent에 모델 선택기나 사고 깊이 제어 기능이 없습니다. 모델을 바꾸려면 Claude Code 자체의 설정을 변경하세요.
• 모델 사용은 직접 준비하는 방식입니다. 실행은 해당 Computer의 Claude Code에 이미 구성된 Claude 구독 또는 API 키를 사용합니다. 모델 할당량은 팀이 연결한 AI 코딩 도구, 요금제, API 계정에 따라 달라집니다.
• 배정은 명시적입니다. Task의 담당자 컨트롤을 열고 동료에게 티켓을 배정하듯 Agent를 선택합니다. 책임자는 별도로 기록됩니다.

작고 잘 정의된 작업이라면 Task를 하나의 Agent에 직접 배정하세요. Crew — 한 명의 리더 Agent가 조율하는 People과 Agents의 재사용 가능한 그룹 — 는 리더가 목표를 직접 해석하고 다른 구성원의 결과를 하나의 Task로 모아야 할 때만 사용하세요. 첫 배정의 단계별 과정은 AI 에이전트에 첫 작업을 배정하는 방법에 있습니다.

3단계: Computer에서, 격리된 워크트리로 실행하기

Task가 Backlog에서 나오고 Agent가 준비되면, Sharkly는 실행을 대기열에 넣고 선택된 Computer — 노트북, 원격 서버, 컨테이너 — 로 전달합니다. 그 머신의 로컬 서비스가 실행을 받아 작업 디렉터리를 준비하고, Claude Code를 시작한 뒤 진행 상황을 실시간으로 전송합니다. 여러분의 코드와 자격 증명, Claude Code 설치 환경은 직접 통제하는 하드웨어를 벗어나지 않습니다.

관심사의 분리는 명확히 짚을 가치가 있습니다. Agent는 작업을 어떻게 처리할지 정의하고, Computer는 호스트와 로컬 리소스를 제공하며, Runtime은 실제 에이전트 세션을 수행하고, Task는 공유 기록으로 남습니다.

저장소 작업의 경우 권장 작업 디렉터리 모드는 Temporary입니다. 각 Task에 격리된 디렉터리가 주어지고, 로컬 서비스는 캐시된 저장소 데이터로부터 실행마다 새 git 워크트리를 준비할 수 있습니다. 같은 저장소를 다루는 두 Task는 디스크상 서로 다른 디렉터리에 쓰기 때문에 병렬 실행이 서로를 덮어쓰지 않습니다. 이 기본 요소는 AI 코딩 에이전트와 git 워크트리를 함께 사용하는 방법에서 다룹니다. Specified 모드 — 실행이 재사용하는 하나의 구성된 로컬 디렉터리 — 는 정직한 예외 상황을 위해 존재합니다. 매우 큰 저장소, 비용이 큰 로컬 캐시, 특정 경로에 묶인 도구 같은 경우입니다.

Claude Code가 작업하는 동안 실행은 눈에 보이는 상태를 거칩니다. queued, dispatched, running, 그리고 completed, failed, canceled입니다. 실행 상태는 Task 상태와 별개이며, 이 분리는 유용합니다. Task는 Agent가 작업 중이거나, 사람의 답변을 기다리거나, 오류를 보고하는 동안에도 In Progress로 남을 수 있고, 어느 쪽인지 알기 위해 터미널을 들여다볼 필요가 없습니다.

4단계: 진행 상황과 블로커는 Task로 돌아옵니다

팀이 확인해야 하는 모든 것이 한곳으로 돌아옵니다. Agent의 보고서는 실행 트레이스에 연결된 댓글로 저장됩니다. Activity는 댓글과 Task 변경 사항을 하나의 타임라인에 보여줍니다. Executions에는 트리거 출처, 시작과 종료 시각, 도구 호출, 실패 세부 정보 등 실행 이력이 담깁니다.

블로커는 조용히 멈춰 있는 대신 드러납니다. Agent는 Task를 사람의 답변이나 검토를 기다리는 상태로 남길 수 있고, 막힌 작업은 Inbox로 흘러갑니다. Inbox는 주의가 필요한 Task와 우선순위가 낮은 업데이트를 구분해주는 개인 대기열입니다. 차이는 구조적입니다. 멈춘 세션은 누군가 우연히 탭을 열어볼 때까지 기다리지만, 블로킹된 Task는 책임자에게 스스로 알립니다.

작업을 이어가는 것은 새 세션이 아니라 댓글입니다. 여전히 Agent에 배정된 Task에 유효한 댓글을 달면 Task에 누적된 컨텍스트를 가지고 후속 실행이 시작되며, 빠르게 이어지는 댓글은 하나로 합쳐져 중복 실행이 생기지 않습니다.

5단계: 사람의 검토와 승인

이 흐름은 마땅히 그래야 하는 곳, 즉 사람에게서 끝납니다. 에이전트는 조사하고, 실행하고, 테스트하고, 보고합니다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 승인합니다.

관리되는 Task에서의 검토는 세션을 다시 보는 것이 아니라 증거를 읽는 일입니다. 검토자는 1단계에서 작성한 완료 기준에 비추어 Agent의 보고서를 확인합니다. 범위를 벗어나지 않았는지, 관련 검사를 실행했는지, 결론에 대한 근거를 제시했는지, 추측하는 대신 불확실성을 기록했는지 말입니다. 요약만으로 부족할 때는 실행 트레이스를 확인하면 됩니다.

그다음 승인은 세 가지 정직한 경로 중 하나를 따릅니다. 작업을 승인하고 Task를 완료 상태로 옮기거나, 핵심을 짚은 댓글로 변경을 요청해 전체 컨텍스트를 담은 후속 실행을 시작하거나, 실행이 잘못됐다고 판단해 취소하고 실행 로그를 확인한 뒤 재시도하거나 다른 Agent에 배정합니다.

이 모든 것이 기존의 git 검토를 대체하지는 않습니다. Claude Code는 평소 사용하는 git 호스팅을 통해 브랜치를 만들고, 커밋을 작성하고, 풀 리퀘스트를 엽니다. 병합 검토는 지금 있는 곳에 그대로 남습니다. Task는 PR 페이지가 볼 수 없는 것을 더합니다. 최초 요청, 실행 증거, 기록된 승인입니다.

개인 세션 vs 관리되는 Task

왼쪽 열이 틀린 선택은 아닙니다. 탐색과 빠른 수정에는 그쪽이 맞는 도구입니다. 오른쪽 열은 작업이 가시적이고, 검토 가능하고, 병렬로 처리되어야 할 때 값어치를 합니다.

Task 하나에서 관리되는 프로젝트로

위의 모든 내용은 형태를 바꾸지 않고 Task 하나에서 계획 전체로 확장됩니다. 여러 Task가 하나의 결과에 기여하면 Project로 묶이고, 이번 기간에 무엇을 출시하는지가 문제라면 Sprint로 묶입니다. View는 팀이 반복적으로 던지는 질문, 예컨대 검토를 기다리는 Task 같은 것을 저장해 둡니다.

이것이 이 워크플로의 핵심 명제입니다. 팀의 레버리지는 AI 채팅을 더 많이 여는 데서 나오지 않습니다. 역할과 규칙, 컨텍스트, 워크플로를 공유하는 데서 나옵니다. 이 규율이 더 넓은 지형에서 어디에 위치하는지는 필러 가이드인 AI 에이전트 프로젝트 관리란 무엇인가에서 다룹니다.

필요하다고 느껴지는 것보다 작게 시작하세요. Computer 하나를 연결하고, Claude Code가 사용 가능한 Runtime으로 나타나는지 확인하고, 좁은 역할을 가진 Agent 하나를 만들고, 실제 완료 기준을 가진 위험도 낮은 Task 하나를 배정하세요. 새 팀원의 첫 풀 리퀘스트를 검토하듯 결과를 검토하세요. Sharkly 문서에서 각 개념을 더 깊이 다룹니다.

FAQ

Sharkly가 Claude Code를 대체하나요?

아니요. Sharkly는 Claude Code, Codex 또는 다른 실행 도구를 대체하지 않습니다. 실행은 Claude Code가 담당합니다. 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하고, git과 연동합니다. Sharkly는 그 주위에 팀 차원의 계층을 더해 배정, Task 컨텍스트, 진행 상황, 블로커, 결과, 사람의 검토를 관리합니다.

Sharkly를 통해 Claude Code를 실행하려면 별도의 모델 구독이 필요한가요?

아니요. 모델 사용은 연결된 Computer의 Claude Code에 이미 구성된 구독이나 API 키를 통해 계속 이루어집니다. 모델 할당량은 팀이 연결한 AI 코딩 도구, 요금제, API 계정에 따라 달라집니다.

터미널에서 Claude Code를 직접 계속 사용할 수 있나요?

네, 그리고 그렇게 하는 게 좋습니다. 질문을 탐색하거나, 계획을 세우거나, 간단한 로컬 수정을 할 때는 직접 세션이나 독립형 Agent Chat이 적합한 도구입니다. 작업에 책임 소재, 상태, 실행 이력, 검토가 필요해지면 Task로 옮기세요.

실행이 실패하면 어떻게 되나요?

해당 실행은 Task에서 실패로 표시되고, 실행 로그에 제목과 모델 서비스가 제공한 원래 기술 세부 정보가 기록됩니다. Sharkly의 문제 해결 안내는 속도 제한, 할당량 소진, 인증 오류 같은 흔한 사례를 다음 단계에 연결해주고, Claude Code 자체의 오류 참조 문서도 링크합니다. 원인을 해결한 뒤 재시도하거나 Task를 다른 Agent에 배정하세요.

여러 Claude Code Task가 같은 저장소에서 동시에 실행될 수 있나요?

네. Temporary 작업 디렉터리 모드에서는 각 Task가 자체 격리된 디렉터리에서 실행되고, 저장소 기반 실행은 각각 새 git 워크트리를 받을 수 있어 동시에 실행되는 Task가 공유 체크아웃에 쓰지 않습니다. Agent와 Computer의 동시 실행 한도가 한 번에 실행되는 수를 제한합니다.