AI 지식 / / 2025. 6. 26. 17:53

Claude Task Manager - Claude 에이전트 작업 관리 라이브러리 (Claude Task Manager)

출처: GitHub Gist - grahama1970/Claude Task Manager

Claude Code와 함께 컨텍스트 격리 및 집중된 작업 실행을 관리하는 전문 도구로, 복잡한 다단계 프로젝트에서 Claude 작업 시 컨텍스트 길이 제한과 작업 집중도의 중요한 문제를 해결합니다.

Claude Task Manager란 무엇인가요?

Claude Task Manager는 복잡한 프로젝트에서 Claude와 같은 대형 언어 모델로 작업할 때 직면하는 근본적인 문제인 컨텍스트 길이 제한과 작업 집중도 유지 문제를 해결합니다.

문제점

Claude Code(또는 다른 LLM)로 복잡한 프로젝트를 작업할 때 일반적으로 다음과 같은 문제에 직면합니다:

  1. 컨텍스트 길이 제한: Claude는 제한된 컨텍스트 윈도우를 가지고 있습니다. 길고 복잡한 프로젝트는 이 제한을 초과할 수 있습니다.
  2. 작업 전환 혼란: 단일 대화에서 여러 작업을 처리할 때 Claude가 현재 작업 중인 작업에 대해 혼란을 겪을 수 있습니다.
  3. 프로젝트 조직화: 대규모 프로젝트는 진행 상황을 추적하기 위한 구조와 조직이 필요합니다.
  4. 효과적인 프롬프팅: 각 작업은 최적의 결과를 얻기 위해 구체적이고 집중된 지침이 필요합니다.

해결책

Claude Task Manager는 "부메랑" 접근 방식을 구현합니다:

  1. 작업 분해: 대규모 프로젝트 사양을 분석하고 지능적으로 더 작고 독립적인 작업으로 분해합니다.
  2. 컨텍스트 격리: 각 작업은 깨끗한 컨텍스트 윈도우에서 실행되어 Claude가 해당 작업에만 집중하도록 합니다.
  3. 프로젝트 조직화: 작업을 적절한 순서와 메타데이터로 프로젝트에 조직화합니다.
  4. 실행 관리: 작업을 개별적으로 또는 순차적으로 실행할 수 있으며, 결과가 캡처되고 조직화됩니다.

Claude Task Manager를 사용하는 이유

  • 컨텍스트 제한 극복: 대규모 프로젝트를 Claude의 컨텍스트 윈도우에 맞는 관리 가능한 청크로 분해
  • 집중도 유지: Claude가 이전 컨텍스트에 방해받지 않고 현재 작업에 집중하도록 보장
  • 품질 향상: 각 작업에 대해 명확하고 집중된 지침을 제공하여 더 나은 결과 획득
  • 복잡한 프로젝트 조직화: 적절한 구조와 순서로 다단계 프로젝트 관리
  • 진행 상황 추적: 작업 완료 및 프로젝트 상태 모니터링
  • MCP 통합: Model Context Protocol을 통한 에이전트 워크플로우와의 원활한 통합

사전 요구사항

이 패키지를 사용하려면 시스템에 다음이 설치되어 있어야 합니다:

  1. Claude Desktop - Claude Desktop 애플리케이션이 설치되어 있어야 함
  2. Claude Code - claude 명령줄 도구가 PATH에서 접근 가능해야 함
  3. Desktop Commander - 파일 시스템 액세스를 위해 필요 (아래 설치 지침 참조)

Desktop Commander 설치

Desktop Commander는 Claude가 파일 시스템에 액세스하고 명령을 실행할 수 있게 하는 중요한 종속성입니다. 설치하려면:

# npx 사용 (권장)
npx @wonderwhy-er/desktop-commander@latest setup

# 또는 Smithery 사용
npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude

자세한 내용은 Desktop Commander 웹사이트를 방문하세요.

설치 후 Claude Desktop을 다시 시작하고 채팅 인터페이스에서 해머 아이콘이 표시되는지 확인하여 Desktop Commander가 제대로 연결되었는지 확인하세요.

핵심 기능

  • 작업 분해: 복잡한 프로젝트를 집중된 독립적인 작업으로 지능적으로 파싱
  • 컨텍스트 격리: /clear 명령을 사용하여 깨끗한 컨텍스트 윈도우로 각 작업 실행
  • 프로젝트 관리: 적절한 메타데이터와 순서로 작업을 프로젝트에 조직화
  • 실행 제어: 작업을 개별적으로 또는 순차적으로 실행하며 적절한 결과 관리
  • 상태 추적: 프로젝트 진행 상황과 작업 완료 상태 모니터링
  • 모던 CLI: 풍부한 포맷팅을 가진 직관적인 명령줄 인터페이스
  • MCP 통합: FastMCP를 통한 에이전트 워크플로우와의 원활한 통합

설치

# claude_mcp_configs 루트 디렉토리에서:
python setup_libs.py task-manager

# 또는 디렉토리에서 직접 설치
cd libs/claude_task_manager
pip install -e .

패키지는 pyproject.toml과 함께 최신 Python 패키징을 사용하여 최신 pip 및 빌드 도구와 호환됩니다.

종속성

FastMCP 통합을 위해서는 fastmcp 패키지를 설치해야 합니다:

pip install fastmcp

사용법

기본 워크플로우

Claude Task Manager를 사용한 일반적인 워크플로우는 다음과 같습니다:

  1. 프로젝트 생성: 새 프로젝트 구조 설정
  2. 작업 분해: 대규모 작업 사양을 더 작고 독립적인 작업으로 변환
  3. 작업 실행: 작업을 개별적으로 또는 완전한 프로젝트로 실행
  4. 진행 상황 모니터링: 작업 완료 및 프로젝트 상태 추적

명령줄 인터페이스

# 새 프로젝트 생성
claude-tasks create-project my_project /path/to/task_list.md

# 작업을 개별 작업으로 분해
claude-tasks break-task my_project /path/to/task_list.md

# 단일 작업 실행
claude-tasks run-task my_project 001_first_task.md

# 프로젝트의 모든 작업 실행
claude-tasks run-project my_project

# 사용 가능한 프로젝트 나열
claude-tasks list-projects

# 프로젝트의 작업 나열
claude-tasks list-tasks my_project

# 프로젝트 상태 확인
claude-tasks check-status my_project

# 기계 판독 가능한 스키마 가져오기 (MCP 호환)
claude-tasks schema

# MCP 호환 스키마 형식 가져오기
claude-tasks schema --mcp

MCP 호환 기능

CLI는 여러 MCP 호환 기능을 제공합니다:

  1. 기계 판독 가능한 JSON 출력:

    # 구조화된 JSON 출력을 위해 모든 명령에 --json 추가
claude-tasks list-tasks my_project --json

  2. 스키마 명령:

    # 모든 명령과 매개변수의 완전한 JSON 스키마 가져오기
claude-tasks schema
# MCP 형식으로 출력
claude-tasks schema --mcp

  3. 일관된 결과 구조: 모든 JSON 출력은 다음과 같은 일관된 구조를 따릅니다:

    • success 플래그 (boolean)
    • 명령별 결과 데이터
    • 해당하는 경우 오류 정보

  4. 풍부한 사람이 읽을 수 있는 출력: --json 없이 사용할 때 명령은 잘 포맷된 테이블과 패널을 제공합니다

Python API

from claude_task_manager import TaskManager

# 작업 관리자 초기화
manager = TaskManager('/path/to/base/directory')

# 새 프로젝트 생성
project_dir = manager.create_project('my_project', '/path/to/task_list.md')

# 작업을 개별 작업으로 분해
project_dir, created_files = manager.break_down_task('my_project', '/path/to/task_list.md')

# 단일 작업 실행
result_file = manager.run_task('my_project', '001_first_task.md')

# 프로젝트의 모든 작업 실행
results = manager.run_project('my_project')

# 사용 가능한 프로젝트 나열
projects = manager.list_projects()

# 프로젝트의 작업 나열
tasks = manager.list_tasks('my_project')

# 프로젝트 상태 확인
status = manager.check_project_status('my_project')

MCP 서버

Task Manager를 MCP 서버로 실행하려면:

# 기본 설정으로 서버 시작
python run_task_manager_server.py start

# 사용자 정의 설정으로 시작
python run_task_manager_server.py start --host 0.0.0.0 --port 5000 --base-dir /path/to/tasks --debug

# 진단 실행
python run_task_manager_server.py diagnostic

# 스키마 출력
python run_task_manager_server.py schema

서버는 다음 MCP 함수를 노출합니다:

  • create_project - 새 프로젝트 생성
  • break_task - 작업을 개별 작업 파일로 분해
  • run_task - 컨텍스트 격리로 단일 작업 실행
  • run_project - 프로젝트의 모든 작업 실행
  • list_projects - 모든 프로젝트 나열
  • list_tasks - 프로젝트의 모든 작업 나열
  • check_status - 프로젝트 상태 확인

작동 방식

작업 분해 프로세스

대규모 작업 설명을 제공하면 Claude Task Manager는:

  1. 콘텐츠 분석: Claude 자체를 사용하여 작업 구조 이해
  2. 논리적 분할 식별: 작업의 자연스러운 분할점 결정
  3. 독립적인 작업 생성: 필요한 모든 컨텍스트가 포함된 작업 파일 생성
  4. 종속성 설정: 올바른 실행 순서 결정
  5. 메타데이터 생성: 프로젝트 정보 및 실행 계획 생성

시각적 워크플로우

다음 다이어그램은 작업 분해부터 실행까지의 완전한 워크플로우를 보여줍니다:

flowchart TD
    %% 단계 레이블
    PhaseA[작업 분해 단계]:::phaseLabel
    PhaseB[실행 단계]:::phaseLabel
    PhaseC[컨텍스트 격리 메커니즘]:::phaseLabel

    %% 작업 분해 단계 노드
    A[📋 원본 작업 목록] --> B[🧠 Claude 분석]
    B --> C{✂️ 작업으로 분할}
    C --> D[📑 작업 000: 프로젝트 개요]
    C --> E[📑 작업 001: 첫 번째 하위작업]
    C --> F[📑 작업 002: 두 번째 하위작업]
    C --> G[📑 작업 003: 세 번째 하위작업]
    D & E & F & G --> H[📋 작업 순서 생성]

    %% 단계 연결
    H --> I

    %% 실행 단계 노드
    I[🚀 작업 000 실행] --> J[🚀 작업 001 실행]
    J --> K[🚀 작업 002 실행]
    K --> L[🚀 작업 003 실행]

    %% 작업 000의 컨텍스트 격리
    I --> I1[🧹 /clear 컨텍스트]
    I1 --> I2[📥 작업 000 로드]
    I2 --> I3[⚙️ Claude Code로 실행]
    I3 --> I4[💾 결과 저장]

    %% 작업 001의 컨텍스트 격리
    J --> J1[🧹 /clear 컨텍스트]
    J1 --> J2[📥 작업 001 로드]
    J2 --> J3[⚙️ Claude Code로 실행]
    J3 --> J4[💾 결과 저장]

    %% 작업 002의 컨텍스트 격리
    K --> K1[🧹 /clear 컨텍스트]
    K1 --> K2[📥 작업 002 로드]
    K2 --> K3[⚙️ Claude Code로 실행]
    K3 --> K4[💾 결과 저장]

    %% 작업 003의 컨텍스트 격리
    L --> L1[🧹 /clear 컨텍스트]
    L1 --> L2[📥 작업 003 로드]
    L2 --> L3[⚙️ Claude Code로 실행]
    L3 --> L4[💾 결과 저장]

    %% 결과 수집
    I4 & J4 & K4 & L4 --> M[📊 모든 결과 수집]
    M --> N[✅ 프로젝트 완료]

컨텍스트 격리 메커니즘

각 작업이 실행될 때:

  1. 컨텍스트 지우기: /clear 명령으로 이전 컨텍스트 제거
  2. 작업 로드: 특정 작업 파일과 컨텍스트 로드
  3. 실행: Claude Code로 작업 실행
  4. 결과 저장: 출력을 결과 파일에 캡처
  5. 다음 작업으로: 다음 작업을 위해 프로세스 반복

이 접근 방식은 각 작업이 깨끗한 컨텍스트에서 시작하여 이전 작업의 혼란이나 간섭 없이 최적의 결과를 보장합니다.

프로젝트 구조

Claude Task Manager는 다음과 같은 구조로 프로젝트를 조직화합니다:

projects/
└── my_project/
    ├── tasks/
    │   ├── 000_project_overview.md
    │   ├── 001_first_task.md
    │   ├── 002_second_task.md
    │   └── 003_third_task.md
    ├── results/
    │   ├── 000_project_overview_result.md
    │   ├── 001_first_task_result.md
    │   ├── 002_second_task_result.md
    │   └── 003_third_task_result.md
    ├── project_info.json
    └── task_sequence.md

파일 설명

  • tasks/: 개별 작업 파일이 포함된 디렉토리
  • results/: 각 작업의 실행 결과가 저장되는 디렉토리
  • project_info.json: 프로젝트 메타데이터 및 구성
  • task_sequence.md: 작업 실행 순서 및 종속성

고급 기능

조건부 실행

작업에는 실행을 위한 조건을 포함할 수 있습니다:

# 작업 002: 데이터베이스 마이그레이션

**조건**: 작업 001이 성공적으로 완료된 경우에만 실행

**설명**: 
데이터베이스 스키마를 새 버전으로 마이그레이션합니다.

병렬 실행

일부 작업은 병렬로 실행될 수 있습니다:

# 작업 003: 프론트엔드 테스트
# 작업 004: 백엔드 테스트

**병렬 실행 가능**: 이 작업들은 동시에 실행할 수 있습니다.

에러 처리

작업 실행 중 오류가 발생하면:

  1. 오류 캡처: 오류 메시지와 컨텍스트가 결과 파일에 저장됩니다
  2. 재시도 옵션: 실패한 작업을 다시 실행할 수 있습니다
  3. 의존성 관리: 실패한 작업에 의존하는 작업은 건너뜁니다

모범 사례

효과적인 작업 분해

  1. 명확한 목표: 각 작업은 명확하고 측정 가능한 목표를 가져야 합니다
  2. 독립성: 작업은 가능한 한 독립적이어야 합니다
  3. 적절한 크기: 작업은 너무 크지도 작지도 않아야 합니다 (일반적으로 1-2시간 작업)
  4. 명확한 입력/출력: 각 작업의 입력과 예상 출력을 명확히 정의합니다

프로젝트 조직화

  1. 논리적 순서: 작업을 논리적 순서로 배열합니다
  2. 종속성 최소화: 작업 간 종속성을 최소화합니다
  3. 체크포인트: 중요한 단계에서 체크포인트를 설정합니다
  4. 문서화: 각 작업과 프로젝트를 잘 문서화합니다

문제 해결

일반적인 문제

  1. Claude Code 연결 실패

    • Claude Desktop이 실행 중인지 확인
    • Desktop Commander가 올바르게 설치되었는지 확인
    • 해머 아이콘이 표시되는지 확인

  2. 작업 실행 실패

    • 작업 파일의 구문을 확인
    • 필요한 파일과 디렉토리가 존재하는지 확인
    • 권한 문제가 없는지 확인

  3. 컨텍스트 격리 문제

    • /clear 명령이 올바르게 작동하는지 확인
    • Claude Code 버전이 최신인지 확인

디버깅

디버그 모드를 활성화하려면:

# CLI에서 디버그 모드
claude-tasks --debug run-task my_project 001_task.md

# MCP 서버에서 디버그 모드
python run_task_manager_server.py start --debug

API 참조

TaskManager 클래스

class TaskManager:
    def __init__(self, base_dir: str)
    def create_project(self, project_name: str, source_file: str) -> str
    def break_down_task(self, project_name: str, source_file: str) -> Tuple[str, List[str]]
    def run_task(self, project_name: str, task_filename: str) -> str
    def run_project(self, project_name: str) -> List[str]
    def list_projects(self) -> List[str]
    def list_tasks(self, project_name: str) -> List[str]
    def check_project_status(self, project_name: str) -> Dict[str, Any]

타입 정의

패키지는 TypeScript 스타일의 타입 힌트를 사용합니다:

class ProjectCreationResult(TypedDict):
    """프로젝트 생성 작업의 결과."""
    success: bool
    project_name: str
    project_dir: str
    source_file: str

class TaskBreakdownResult(TypedDict):
    """작업 분해 작업의 결과."""
    success: bool
    project_name: str
    project_dir: str
    source_file: str
    created_files: List[str]
    file_count: int
    next_step_command: str

class TaskRunResult(TypedDict):
    """작업 실행 작업의 결과."""
    success: bool
    project_name: str
    task_filename: str
    result_file: str

결론

Claude Task Manager는 복잡한 프로젝트에서 Claude Code의 효율성을 극대화하는 강력한 도구입니다. 컨텍스트 격리와 지능적인 작업 분해를 통해 대규모 프로젝트를 관리 가능한 단위로 나누고, 각 작업에서 최적의 결과를 얻을 수 있습니다.

이 도구는 특히 다음과 같은 경우에 유용합니다:

  • 복잡한 소프트웨어 개발 프로젝트
  • 대규모 문서 작성 및 편집
  • 다단계 데이터 분석 작업
  • 시스템 마이그레이션 및 업그레이드
  • 교육 콘텐츠 개발

Claude Task Manager를 사용하여 프로젝트의 복잡성을 관리하고, Claude의 능력을 최대한 활용하여 더 나은 결과를 얻으세요.

관련 태그: claude-code, task-management, ai-workflow, mcp, project-management, context-isolation

GitHub Gist: https://gist.github.com/grahama1970/44a9da6a3da6769132037f06966945c2

반응형
저작자표시 (새창열림)
  • 네이버 블로그 공유
  • 네이버 밴드 공유
  • 페이스북 공유
  • 카카오스토리 공유
AI 지식 관련 글
글 더보기

티스토리툴바