CarryCtx 핵심 스킬
CarryCtx는 AI 코딩 에이전트를 위한 퍼스트클래스 프로젝트 상태 및 컨텍스트 연속성을 제공합니다. 에이전트가 작업을 관리하고, 세분화된 진행 상황을 추적하고, 체크포인트 스냅샷을 만들고, AST 코드 종속성 그래프를 유지하고, stdio MCP 서버를 실행하고, 워크플로우 프리셋을 적용하며, 세션 재시작 및 Git 워크트리 간에 컨텍스트를 원활하게 보존할 수 있도록 합니다.
적용 시점
다음과 같은 경우 CarryCtx 명령을 사용하세요.
- 새 작업 또는 세션 시작 시: 에이전트 ID 등록, 세션 시작, 컨텍스트 복원 (
carryctx resume). - 프로젝트 작업 관리 시: 작업 생성, 할당, 시작, 완료, 차단 또는 취소 (
carryctx task ...). - 세분화된 진행 상황 추적 시: 구조화된
todo,block,risk,note항목 기록. - 상태 저장 / 체크포인트 생성 시: 세션 종료 또는 초점 전환 전에 현재 작업 진행 상황, git 상태, 남은 작업을 캡처.
- 코드 그래프 탐색 시: AST 모듈 종속성 스캔 (
carryctx graph scan) 및 Mermaid/DOT/ASCII 다이어그램 내보내기 (carryctx graph export). - AI 에이전트 도구 통합 (MCP) 시: Model Context Protocol stdio 서버를 통해 Cursor / Windsurf / AGY에 프로젝트 컨텍스트 노출 (
carryctx mcp). - 워크플로우 표준화 (프리셋) 시: 프로젝트 워크플로우 청사진, 코딩 규칙, 에이전트 페르소나 나열, 조사 및 적용 (
carryctx preset ...). - 병렬 작업 수행 시: 전용 Git 워크트리에서 작업 생성 및 격리 (
carryctx worktree ...). - 상태 문제 진단 시:
carryctx doctor를 실행하여 고립된 작업, 누락된 훅, DB 문제 발견. - 오래된 데이터 정리 시:
carryctx project prune을 사용하여 완료된 작업 정리 및 DB 크기 유지. - 에이전트 분석 시:
carryctx stats를 사용하여 에이전트 세션 길이, 작업 메트릭 감사 및 Markdown/CSV 보고서 내보내기. - 이전 작업 내용 검색 시:
carryctx search "<query>"를 사용하여 SQL을 직접 작성하거나 커밋 메시지를 grep하지 않고 키워드로 작업, 진행 항목, 체크포인트 또는 결정을 검색.
사전 요구 사항
- CarryCtx CLI 설치 (
cargo install carryctx또는 사전 빌드된 바이너리). - 프로젝트 리포지토리에서 CarryCtx 초기화:
carryctx init.
빠른 참조
| 액션 | 명령 | 목적 |
|---|---|---|
| 에이전트 설정 | carryctx agent register --name "$(whoami)" --provider "claude-code" | 에이전트 ID 등록 |
| 현재 에이전트 | carryctx agent current | 활성 에이전트 ID 표시 |
| 세션 시작 | carryctx session start | 추적 작업 세션 시작 |
| 컨텍스트 복원 | carryctx resume | 현재 작업, 진행 상황 및 다음 작업 가져오기 |
| 작업 생성 | carryctx task create --title "..." [--depends-on CTX-0001] | 새 작업 정의 |
| 작업 할당 | carryctx task claim CTX-0001 | 현재 에이전트에 작업 할당 |
| 작업 편집 | carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...] | 작업 제목, 우선순위 또는 설명 업데이트 |
| 작업 시작 | carryctx task start CTX-0001 | 작업을 진행 중으로 표시 |
| 진행 상황 추적 | `carryctx progress <todo | block |
| 체크포인트 | carryctx checkpoint --done "..." --remaining "..." | 의미론적으로 풍부한 상태 스냅샷 저장 |
| 코드 그래프 스캔 | carryctx graph scan | SQLite 그래프로 AST 종속성 추출 |
| 그래프 내보내기 | `carryctx graph export --type <mermaid | dot |
| MCP Stdio 서버 | carryctx mcp | 6개의 에이전트 도구와 함께 MCP stdio 서버 시작 |
| 프리셋 적용 | carryctx preset apply <preset_name> | 워크플로우 SOP, 규칙 또는 페르소나 주입 |
| 워크트리 | carryctx worktree create CTX-0001 | 작업을 위한 격리된 git 워크트리 생성 |
| 세션 종료 | carryctx session end | 체크포인트와 함께 안전하게 세션 종료 |
| 닥터 | carryctx doctor | 프로젝트 상태 진단 |
| 훅 설치 | carryctx hooks install | 모든 git 커밋 시 자동 체크포인트 |
| 데이터 정리 | carryctx project prune --older-than 30 | 오래된 완료 작업 정리 |
| 에이전트 통계 | carryctx stats [--markdown] [--output file.csv] | 메트릭 보기 및 성능 보고서 내보내기 |
| 결정 | carryctx decision add --title "..." --task CTX-0001 | 아키텍처 결정 기록 |
| 인계 | carryctx handoff create --target <agent> --task CTX-0001 | 에이전트 간 작업 전송 |
| 세션 일시 정지 | carryctx session pause | 활성 세션 타이머 일시 정지 |
| 세션 재개 | carryctx session resume | 일시 정지된 세션 재개 |
| 검색 | `carryctx search "" [--type task | progress |
출력 동작 (0.5.2 이상)
텍스트 출력(기본 --format text)은 의도적으로 간결합니다: 엔티티 명령은 레코드당 짧은 한 줄을 출력합니다(Task created: CTX-0321, agent current는 이름만 출력, 목록은 display_id, 상태 및 잘린 제목/요약을 표시) 따라서 에이전트 컨텍스트가 작게 유지됩니다. 전체 레코드가 필요한 경우:
--verbose(전역 플래그) 또는.carryctx/config.toml의[output] verbose = true가 전체 예쁘게 출력된 레코드를 복원합니다.--fields display_id,status,summary(전역 플래그) 또는 명령별[output.fields]테이블이 텍스트 및 JSON에서 레코드를 허용 목록으로 축소합니다.--format json은 항상 전체 엔벨로프를 반환합니다.
JSON 출력은 변경되지 않으며 기계 간의 계약으로 유지됩니다: 모든 성공은 stdout의 단일 엔벨로프, 모든 오류는 stderr의 단일 엔벨로프입니다.
표준 에이전트 워크플로우
1. 세션 초기화 및 컨텍스트 복원
상호 작용 시작 또는 에이전트 재시작 시:
# 아직 구성되지 않은 경우 ID 등록 및 설정
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"
# 세션 시작 및 현재 컨텍스트 로드
carryctx session start
carryctx resume
세션 일시 정지 및 재개:
carryctx session pause # 활성 세션 일시 정지 (타이머 중지)
carryctx session resume # 일시 정지된 세션 재개
carryctx session end # 선택적 체크포인트와 함께 세션 종료
carryctx session abandon # 체크포인트 없이 세션 종료
2. 코드 종속성 분석 (그래프 하위 시스템)
코드를 수정하거나 모듈을 리팩토링하기 전:
# 1. 코드베이스 AST 종속성 스캔
carryctx graph scan
# 2. 특정 모듈을 중심으로 하위 그래프 내보내기
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2
# 3. 모듈 수준의 간결한 ASCII 아키텍처 개요 내보내기
carryctx graph export --type ascii --compact
3. 워크플로우 프리셋 및 규칙 주입
표준 운영 절차 또는 코딩 지침 주입:
# 사용 가능한 워크플로우 프리셋 나열
carryctx preset list
# 현재 프로젝트에 표준 버그 수정 워크플로우 프리셋 적용
carryctx preset apply workflows/bugfix
4. 작업 수명 주기
# 열린 작업 나열
carryctx task list --status ready
# 작업 할당 및 시작
carryctx task claim CTX-0001
carryctx task start CTX-0001
# 확인 후 작업 완료 표시
carryctx task complete CTX-0001
5. 세분화된 진행 상황 추적
작업이 진행됨에 따라 구조화된 진행 항목 기록:
carryctx progress todo "인증 미들웨어에 대한 단위 테스트 작성"
carryctx progress todo "JWT 토큰 검증 구현"
carryctx progress block "API 엔드포인트 사양 확인 대기 중"
carryctx progress risk "상위 종속성의 변경 사항 변경"
carryctx progress note "토큰 조회 최적화를 위해 LRU 캐시 사용"
# 완료된 todo 표시:
carryctx progress complete PX-0001
6. 체크포인트 생성
세션 종료, 작업 전환 또는 작업 인계 전에 상태 저장:
carryctx checkpoint \
--done "백엔드 인증 엔드포인트 완료" \
--remaining "프론트엔드 로그인 양식 통합" \
--blocker "없음"
7. 워크트리 병렬 처리
독립적인 작업을 동시에 수행할 때:
carryctx worktree create CTX-0002
# CTX-0002에 연결된 격리된 워크트리 디렉토리로 전환
7a. 결정 및 인계 기록
아키텍처 결정을 캡처하고 에이전트 간 작업 인계:
# 작업에 연결된 아키텍처 결정 기록 (ADR)
carryctx decision add --title "스토리지에 SQLite 사용" --task CTX-0001
# 결정 나열 또는 검색
carryctx decision list
carryctx decision search --keyword SQLite
# 결정을 최신 결정으로 대체됨으로 표시
carryctx decision supersede DEC-0001 --by DEC-0002
# 다른 에이전트로 작업을 인계하기 위한 핸드오프 생성
carryctx handoff create --target <agent-ulid> --summary "API 구현" --task CTX-0001
# 핸드오프 수락, 거부 또는 종료
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "내 영역이 아님"
carryctx handoff close HO-0001
7b. 프로젝트 기록 전체 텍스트 검색
어떤 분기나 작업이 관련되었는지 기억할 필요 없이 내용으로 이전 작업을 찾습니다. 작업 제목/설명, 진행 항목, 체크포인트 메모 및 결정을 모두 관련성 순으로 검색:
# 모든 항목 검색
carryctx search "마크다운 작업자 프로토콜"
# 하나의 엔티티 종류로 범위 지정
carryctx search "재시도 백오프" --type checkpoint
# 소유 작업의 상태 또는 소유자 에이전트로 좁히기
carryctx search "인증" --status in_progress
carryctx search "인증" --owner claude-code
각 결과에는 소유 작업의 표시 ID, 상태 및 (알려진 경우) 작업이 수행된 분기가 포함됩니다. 관련 작업을 시작하기 전에 이 기능을 사용하여 이미 해결된 문제를 중복해서 해결하지 않도록 하고, 인계 전에 수신 에이전트가 이전 선택을 설명하는 정확한 체크포인트나 결정을 가리키도록 합니다.
8. 세션 종료 및 보고
# 작업 세션 종료
carryctx session end
# PR 설명 또는 문서를 위한 프로젝트 통계 보고서 내보내기
carryctx stats --markdown --output /tmp/project_stats.md
9. Model Context Protocol (MCP) 통합
CarryCtx를 Cursor / Windsurf / AGY에 직접 연결하려면:
{
"mcpServers": {
"carryctx": {
"command": "carryctx",
"args": ["mcp"]
}
}
}
노출된 MCP 도구:
carryctx_graph_explorer: 프로젝트 컨텍스트 그래프 쿼리, 스캔 및 내보내기carryctx_context_manager: 영구 컨텍스트, 체크포인트 및 상태 스냅샷 관리carryctx_task_manager: 프로젝트 작업, 종속성 및 우선순위 관리carryctx_progress_tracker: 작업 진행 상황, 메모 및 차단 항목 관리carryctx_decision_logger: 아키텍처 결정 레코드 기록 및 검색carryctx_project_admin: 프로젝트 데이터베이스, 통계, 콜드 스토리지 아카이빙 및 구성 관리
10. 디버깅 및 문제 해결
구조화된 디버그 로깅을 활성화하여 문제 진단:
# CarryCtx 작업에 대한 디버그 로그 표시
export RUST_LOG=carryctx=debug
carryctx task list # 명령 결과 전에 디버그 출력 확인
# 오류만 표시
export RUST_LOG=error
carryctx status
# 진단 실행
carryctx doctor # 프로젝트 상태 확인
carryctx doctor --json # 기계 판독 가능 진단 출력
코딩 에이전트를 위한 모범 사례
- 시작할 때 항상
carryctx resume실행: 에이전트를 현재 작업과 진행 상황에 즉시 다시 정렬합니다. - 대규모 리팩토링 전에 코드 그래프 스캔:
carryctx graph scan은 상위 종속성 손상을 방지합니다. - 명시적으로 작업 할당: 여러 에이전트가 동일한 리포지토리에서 작업할 때 중복 실행을 방지합니다.
- 구조화된 진행 항목 사용: 실행 단계 중에
todo,done및block을 업데이트된 상태로 유지합니다. - 중단하기 전에 체크포인트 생성: 제어권을 양도하거나 복잡한 다단계 작업을 완료하기 전에 항상 체크포인트를 만듭니다.
- 처음 사용하거나 업그레이드 후
carryctx doctor실행: 런타임 오류가 발생하기 전에 설정 문제를 표면화합니다.