software

작업 파이프라인에서 Claude AI CLI 요구사항을 실행하는 서브 에이전트

발행: (2026년 3월 20일 AM 03:40 GMT+9)
11 분 소요
원문: Dev.to

Source: Dev.to

위에 제공된 링크 외에 번역할 텍스트가 포함되어 있지 않습니다. 번역을 원하는 본문을 제공해 주시면 한국어로 번역해 드리겠습니다.

TL;DR

제가 uctm (Universal Claude Task Manager)를 만들었습니다 – Claude Code에 여섯 개의 특수 서브‑에이전트를 설치하는 npm 패키지입니다.
한 번 요청을 입력하면, 구조화된 XML 메시지를 통해 자동으로 계획하고, 구축하며, 검증하고, 커밋합니다 – 모두 한 번에 진행됩니다.

npm install -g uctm
cd your‑project && uctm init
claude
# Type: [new-feature] Add user authentication with JWT
# → Pipeline runs automatically

GitHub: UCJung/uc-taskmanager-claude-agent npm: uctm

문제

Claude Code는 강력하지만, 복잡한 무언가를 만들라고 요청하면 한 번에 모든 작업을 하려고 합니다.

  • 간단한 작업 → 괜찮음.
  • 여러 파일 프로젝트, 상호 의존 컴포넌트, 혹은 제대로 된 테스트 → 출력이 난잡해지고 토큰이 많이 소모되며 이해하기 어려워집니다.

나는 다음과 같은 시스템을 원했습니다:

목표왜 중요한가
복잡한 작업을 관리 가능한 조각으로 나눈다각 단계가 집중되고 테스트 가능하도록 유지
각 조각을 개별적으로 구축, 테스트, 커밋한다점진적으로 정확성을 보장
작업이 쌓여도 컨텍스트가 폭발하지 않는다토큰을 절약하고 환각을 줄임
외부 런타임 종속성이 전혀 없다순수 프롬프트, 이식 가능한 솔루션

Architecture – 6 Agents, 1 Pipeline

User Request
   │
Main Claude (orchestrator)
   │
   ├─ router      → decides execution mode
   ├─ planner     → decomposes request into TASKs (DAG)
   ├─ scheduler   → manages DAG, dispatches ready TASKs
   ├─ builder     → writes the actual code
   ├─ verifier    → runs tests / lint / acceptance checks
   └─ committer   → writes result report & git commits

핵심 제약: Claude Code 하위 에이전트는 다른 하위 에이전트를 호출할 수 없습니다.
따라서 Main Claude(CLI 터미널)가 오케스트레이터 역할을 하여 각 에이전트를 차례대로 호출하고 메시지를 전달합니다.

모든 요청에 여섯 개의 에이전트가 필요한 것은 아니며 – router가 사용할 하위 집합을 결정합니다.

실행 모드

모드조건무슨 일이 일어나는가
direct간단한 변경, 테스트 불필요라우터가 모든 작업을 단독으로 처리
pipeline테스트 필요, 단일 도메인router → builder → verifier → committer
full복잡한, 다중 파일, 의존성DAG 관리와 함께 6개의 에이전트 모두 사용

Source:

Structured XML Messaging

대화형 텍스트 대신 uctm은 XML을 사용합니다 – 파싱 가능하고, 검증 가능하며, 토큰 효율적입니다.
각 에이전트는 정확히 어떤 정보를 기대하고 반환해야 하는지 알 수 있습니다.

Dispatch (router → builder)

<dispatch>
  <project>my-app</project>
  <language>ko</language>
  <planPath>works/WORK-05/PLAN.md</planPath>

  <task>
    <path>works/WORK-05/TASK-00.md</path>
    <title>Add JWT authentication middleware</title>
    <type>implement</type>
    <description>Create auth middleware with token validation...</description>
  </task>
</dispatch>

Result (builder → verifier)

<result>
  <summary>JWT auth middleware implemented</summary>

  <details>
    <component>JWT verification middleware</component>
    <tests>12 test cases for auth flows</tests>
    <outcome>12/12 passed</outcome>
  </details>

  <metadata>
    <description>Auth middleware with JWT validation</description>
    <libraries>Used jsonwebtoken for RS256 support</libraries>
    <env>Requires JWT_SECRET env variable</env>
    <notes>None</notes>
  </metadata>
</result>

Why XML?

  • Parseable – 각 에이전트가 필요한 정보를 정확히 추출할 수 있습니다.
  • Validatable – 스키마 검증을 통해 잘못된 메시지를 조기에 잡아냅니다.
  • Token‑efficient – 불필요한 여백 없이 필요한 필드만 포함합니다.

슬라이딩‑윈도우 컨텍스트 핸드오프

멀티‑태스크 파이프라인에서 순진한 접근 방식은 이전 작업들의 전체 히스토리를 모두 전달하게 되어 토큰이 급증합니다.
uctm은 현재 작업으로부터의 거리에 따라 전달되는 내용을 제한합니다:

현재 작업으로부터 거리세부 수준전달되는 내용 (≈ 토큰)
Previous TASK (1)FULLwhat + why + caution + incomplete (~150)
2 tasks agoSUMMARYwhat only (~50)
3 + tasks agoDROPNothing (0)

따라서 작업이 몇 개 완료되었든 컨텍스트 크기는 대략 200 토큰 정도로 유지됩니다.

예시

TASK-00 → TASK-01 → TASK-02 → TASK-03

TASK‑03 빌더가 받는 내용:

출처세부 수준페이로드
TASK‑02FULLwhat / why / caution / incomplete
TASK‑01SUMMARYwhat only
TASK‑00DROP(nothing)

10‑태스크 작업에서는 모든 내용을 순진하게 전달하는 경우에 비해 ≈ 75 000 토큰을 절감할 수 있습니다.

실제 파이프라인 실행 (계산기 예시)

요청: “덧셈, 뺄셈, 곱셈, 나눗셈이 가능한 간단한 계산기를 만들어 주세요.”

단계입력출력
Router[new-feature] calc.js에 4개의 산술 함수를 생성execution-mode=pipeline + dispatch XML + PLAN.md + TASK-00.md
Builderrouter에서 dispatch XMLtask-result XML (calc.js 및 calc.test.js 생성)
VerifierBuilder의 task-result XML모든 8개의 테스트를 다시 실행하고, 수용 기준을 확인 → ALL PASS
CommitterBuilder와 verifier 결과TASK-00_result.md를 작성하고, git 커밋 feat(TASK-00): calc.js ESM module을 생성하며, 커밋 해시를 반환

측정값: 136 K 토큰, 96번의 도구 호출, 344 초 실행 시간. 모든 에이전트 간 메시지는 XML 사양을 준수했습니다.

Source: …

명세 기반 개발 (SDD) 철학

  1. 요구사항 → 아키텍처 → 설계가 진정한 자산이다.
  2. 명세 문서는 다음을 정의한다:
    • XML 스키마
    • 컨텍스트 전달 규칙
    • 파이프라인 동작
  3. 에이전트는 순수 .md 파일 – 순수 프롬프트 정의이다.
  4. 런타임 코드 제로, 의존성 제로 → 완전 이식 가능.

이것이 제공하는 것

속성이점
이식성uctm init 후 어떤 프로젝트에서도 동작
맞춤화.agent/router_rule_config.json을 편집해 모드 선택 규칙을 조정
투명성모든 WORK는 읽을 수 있는 마크다운 및 XML 파일들의 연속
결정론적숨겨진 로직이 없으며, 동작은 명세 자체에 의해 구동

Quick Start Recap

npm install -g uctm          # install the CLI globally
cd my-project && uctm init   # bootstrap the six agents
claude                       # start Claude Code
# Example request:
#   [new-feature] Add user authentication with JWT
# → uctm automatically runs the appropriate pipeline

이제 자체 포함형, 토큰 효율적인, 테스트 기반 파이프라인을 갖게 되었으며, Claude Code가 한 줄짜리 스크립트부터 완전한 다중 모듈 기능까지 컨텍스트를 초과하지 않고 처리할 수 있습니다.

개요

uctm (UC Task Manager)은 PLAN.md, TASK 파일, 진행 상황 추적 및 결과 보고서를 생성합니다.

설치

npm install -g uctm

빠른 시작

# Move to your project folder
cd your-project

# Initialise uctm in the project
uctm init

Claude 코드 실행 (중단 없는 파이프라인을 위한 우회 모드)

claude --dangerously-skip-permissions

태그된 요청으로 파이프라인 트리거

# [new-feature] Add a REST API for user management
# [bugfix]      Fix the race condition in data loader
# [enhancement] Improve search query performance

uctm init이 수행하는 작업

  • 12개의 에이전트 .md 파일을 .claude/agents/에 복사합니다
  • .agent/router_rule_config.json을 생성합니다
  • 에이전트 호출 규칙을 CLAUDE.md에 추가합니다
  • WORK 파일용 works/ 디렉터리를 생성합니다

로드맵 하이라이트

  • MCP Server Integration (Phase 2 완료, Phase 3 예정) – 외부‑툴 통합을 위한 HTTP 전송
  • Multi‑project orchestration – 종속 리포지토리 간 파이프라인 실행
  • Dashboard visualization – 실시간 파이프라인 모니터링

왜 uctm을 시도해볼까요?

Claude Code를 사용하고 복잡한 다중 파일 작업을 관리한다면, uctm이 워크플로우를 간소화할 수 있습니다. 이것은:

  • 무료 및 오픈‑소스
  • 설치에 ≈30 초 소요

GitHub: UCJung/uc-taskmanager-claude-agent npm: uctm

지원

  • GitHub 이슈 열기
  • Discord에서 유지 관리자를 찾기
0 조회
#software #programming #community
원문 보기
Share:
Back to Blog

관련 글

더 보기 »