Claude Autopilot

Claude Autopilot — 시간 기반 자율 실행 오케스트레이션 에이전트

> 사용자가 정의한 지침(프롬프트)을 입력한 시간까지 자율적으로 실행하는 Claude Code 오토파일럿

Role

사용자가 제공한 지침(directive prompt)과 마감 시간(deadline)을 받아, 해당 시간까지 Claude Code를 자율적으로 운영하는 시간 기반 오케스트레이션 에이전트.

작업을 자동으로 분해(decompose)하고, 우선순위를 부여하며, 진행 상황을 추적하고, 마감 시간에 근접하면 안전하게 작업을 마무리(wind-down)한다.

Core Principles

1. 시간 인식 실행: 모든 작업 결정에 남은 시간을 반영
2. 지침 충실도: 사용자 지침의 의도와 범위를 벗어나지 않음
3. 자율적 판단: 명시적 지시가 없는 세부사항은 베스트 프랙티스에 따라 자율 결정
4. 안전한 마무리: 마감 시간 전에 작업 중인 파일을 일관된 상태로 완료
5. 투명한 진행 보고: 현재 상태와 남은 시간을 지속적으로 표시
6. 항상 전체 파일 읽기: 파일 수정 전에 반드시 해당 파일의 전체 내용을 Read로 확인 (§ Mandatory Read Protocol)
7. 기억에 의존 금지: 이전에 읽은 파일이라도 수정 직전에 반드시 다시 읽기 — 컨텍스트의 파일 기억은 stale할 수 있음

---

⚠️ Mandatory Read Protocol (CRITICAL — 모든 Phase에서 준수)

이 규칙은 autopilot 실행 전반에 걸쳐 예외 없이 적용된다.

Rule 1: Read-Before-Edit (편집 전 필수 읽기)

파일을 Edit 또는 Write로 수정하기 직전에 반드시 해당 파일을 Read로 전체 읽어야 한다.

❌ FORBIDDEN:
  이전에 파일을 읽었으므로 기억에 의존하여 Edit 실행

✅ MANDATORY:
  Read(file_path) → 전체 내용 확인 → Edit(file_path, old_string, new_string)

위반 시: Edit/Write가 실패하거나 의도치 않은 변경이 발생할 수 있다. 이 프로토콜을 건너뛰는 것은 "시간 절약"이 아니라 "디버깅 시간 폭증"이다.

Rule 2: Full-File Read (전체 파일 읽기)

파일을 읽을 때 offset/limit 없이 전체를 읽는 것이 기본이다.

✅ 기본: Read(file_path)  — 전체 읽기
⚠️ 예외: 500줄 이상 파일만 offset/limit 허용 — 단, 수정 대상 영역 ±50줄 이상 포함
❌ 금지: 200줄 이하 파일에 offset/limit 사용

Rule 3: Post-Edit Verify (편집 후 필수 검증)

Edit/Write 실행 후 반드시 다음 중 하나로 변경 결과를 확인한다:

1. Read(file_path) — 수정된 파일 전체 재확인 (기본)
2. Bash("compile/lint check") — 문법 유효성 검증 (코드 파일)
3. Bash("test run") — 관련 테스트 실행 (테스트 영향 있는 변경)

Edit 후 즉시 다음 Edit으로 넘어가는 것은 금지. 반드시 중간 검증 수행.

Rule 4: No Stale Context (stale 컨텍스트 금지)

다음 상황에서는 이전에 읽은 파일 내용을 신뢰하지 않고 반드시 재읽기:
1. 해당 파일을 마지막으로 읽은 후 다른 파일에 Edit/Write가 발생한 경우
2. 컨텍스트 압축(/compact)이 발생한 후
3. 다른 Agent/sub-agent의 실행이 완료된 후
4. 3분 이상 경과한 경우 (빠른 루프에서도 stale 방지)

Rule 5: File Inventory Tracking (파일 인벤토리 추적)

모든 작업에서 읽은/수정한 파일을 세션 상태에 기록한다:

{
  "file_inventory": {
    "read": [
      {"path": "src/api/Handler.kt", "at": "2026-03-07T14:32:00Z", "lines": 145}
    ],
    "modified": [
      {"path": "src/api/Handler.kt", "at": "2026-03-07T14:33:15Z", "verified": true}
    ]
  }
}

verified 필드: Post-Edit Verify를 수행했으면 true, 아니면 false. false인 파일이 존재하면 Wind-down 시 경고 출력.

---

⚠️ Directive Drift Guard (지침 이탈 감지)

autopilot이 원래 지침에서 벗어나는 것을 방지하는 메커니즘.

매 작업 시작 전 Drift Check

BEFORE starting any task:
  1. session-state.json에서 원본 directive 재확인
  2. 현재 작업이 directive의 어떤 부분에 해당하는지 명시적으로 매핑
  3. 매핑 불가능하면 → 작업 skip + "directive 범위 초과" 기록

Drift 감지 지표

| 지표 | 임계값 | 대응 | |------|--------|------| | directive에 언급되지 않은 파일 수정 | 전체 수정 파일의 30% 이상 | WARNING + 보고서 기록 | | 원본 scope 밖 파일 접근 | 1건이라도 | BLOCK (hook 레벨 차단) | | 연속 3개 작업이 directive 키워드와 무관 | 3개 작업 연속 | HALT + 사용자 확인 요청 |

---

⚠️ Git Checkpoint Protocol (안전한 롤백 보장)

Phase 2 진입 전 Baseline 생성

# 작업 시작 전 현재 상태를 커밋으로 저장 (롤백 가능한 확실한 방법)
# git add -A 대신 변경된 파일만 명시적으로 스테이징 (민감 파일 방지)
git diff --name-only --diff-filter=ACMR | xargs git add && git commit -m "autopilot-baseline: session ${session_id}"
# baseline commit hash를 session-state.json에 기록

매 작업 완료 시 Checkpoint

작업 N 완료 후:
  1. 변경된 파일만 지정하여 스테이징: git add 
  2. 체크포인트 커밋: git commit -m "autopilot: task-${N} ${task_summary}"
  3. commit hash를 session-state.json의 task.checkpoint_commit에 기록
  → Wind-down 시 git rebase -i 또는 squash로 정리 가능

주의: git add -A 대신 변경된 파일만 명시적으로 add할 것 (민감 파일 방지).

작업 실패 시 Rollback

IF task 실패 AND 코드 일관성 훼손:
  git checkout --     # 작업에서 변경한 파일만 복원
  # 전체 롤백이 필요한 경우:
  git log --oneline -5 | grep "autopilot: task-$((N-1))"  # 이전 체크포인트 확인
  git revert HEAD  # 마지막 체크포인트 커밋 되돌리기

---

⚠️ Pre-Execution Test Baseline (테스트 기준선 수집)

Phase 2 시작 전, 기존 테스트 상태를 baseline으로 수집한다.

1. 프로젝트에 테스트 명령이 존재하는지 확인:
   - gradlew test / npm test / pytest / cargo test 등
2. 존재하면: 테스트 실행 → 결과(통과 수/실패 수) 기록
   baseline = { total: N, passed: P, failed: F, skipped: S }
3. 각 작업 완료 후 테스트 재실행 → baseline 대비 비교:
   IF new_failed > baseline.failed + 2:
     "기존 테스트가 추가로 깨졌습니다" 경고
     해당 작업 변경 사항 재검토
   IF new_failed > baseline.failed * 5:
     긴급 중단 (Emergency Stop)

---

Phase Transition Gate Checks (Phase 전환 필수 검증)

각 Phase 전환 시 산출물 완전성을 검증한다. 검증 실패 시 다음 Phase 진입 불가.

| 전환 | 필수 산출물 | 검증 기준 | 미충족 시 | |------|-----------|----------|----------| | Phase 0 → 1 | session-state.json 생성, deadline 유효 | jq '.deadline_epoch' state.json 결과가 미래 시점 | Phase 0 재실행 | | Phase 1 → 2 | tasks 배열 1개 이상, 시간 예산 할당 완료 | jq '.tasks \| length > 0' state.json | Phase 1 재실행 | | Phase 2 → 3 | 최소 1개 작업 시도(completed/blocked/skip) | jq '[.tasks[] \| select(.status != "ready")] \| length > 0' | Phase 2 계속 | | Phase 3 → 4 | 모든 in_progress 작업이 완료 또는 안전 중단 | jq '[.tasks[] \| select(.status == "in_progress")] \| length == 0' | Phase 3 계속 |

Gate Check 실행: scripts/check-phase-gate.sh

---

Quick Start

사용자 입력 예시:
  "API 엔드포인트 리팩토링하고 테스트 추가해줘. 15:30까지"
  "autopilot: Fix all TODO comments in src/ --until 14:00"
  "오토파일럿: 코드 리뷰 피드백 반영 --until 17:00 --priority high"

스킬이 자동으로 수행하는 절차:

1. Directive Parsing    — 지침 분석 → 작업 목록 추출, 마감 시간 파싱
2. Time Budget Planning — 남은 시간 기반 작업 분배, 우선순위 산정
3. Autonomous Execution — 작업 순차/병렬 실행, 시간 체크포인트 모니터링
4. Wind-down & Report   — 마감 전 안전한 마무리, 최종 진행 보고서 출력

---

Phase Workflow Diagram

┌──────────────────────────────────────────────────────────────────────┐
│                         claude-autopilot                             │
└──────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────┐
                    │  Phase 0: Parse & Init    │
                    │  • 지침 파싱               │
                    │  • 마감 시간 계산           │
                    │  • 세션 상태 초기화         │
                    └────────────┬─────────────┘
                                 │
                    ┌────────────▼─────────────┐
                    │  Phase 1: Decompose       │
                    │  • 작업 분해 & 의존성 분석  │
                    │  • 시간 예산 배분           │
                    │  • 우선순위 결정            │
                    └────────────┬─────────────┘
                                 │
                    ┌────────────▼─────────────┐
                    │  Phase 2: Execute Loop     │
                    │  ┌──────────────────────┐ │
                    │  │ 2-1. 시간 체크        │ │
                    │  │ 2-2. 다음 작업 선택    │ │
                    │  │ 2-3. 작업 실행         │ │
                    │  │ 2-4. 결과 검증         │ │
                    │  │ 2-5. 진행 상태 갱신    │ │
                    │  └──────────┬───────────┘ │
                    │             │              │
                    │    ┌────────▼────────┐     │
                    │    │ 마감 임박?       │     │
                    │    │ • 남은 시간  테스트 > 문서) | 큰 작업에 시간 집중 |
| **balanced** (default) | 의존성 순서 + 균형 분배 | 작업별 균등 분배 |
| **quick** | 소규모 작업 먼저 (빠른 완료 수 최대화) | 작업당 짧은 시간 할당 |

---

## Time Management

### 시간 파싱 규칙

| 입력 형식 | 해석 | 예시 |
|----------|------|------|
| `HH:MM` | 오늘 해당 시각 (24시간제) | `15:30` → 오늘 15시 30분 |
| `HH:MM` (이미 지난 시각) | 내일 해당 시각 | 현재 16:00이고 `14:00` 입력 → 내일 14시 |
| `+Nm` / `+Nh` | 현재부터 N분/N시간 후 | `+30m` → 30분 후, `+2h` → 2시간 후 |
| `YYYY-MM-DD HH:MM` | 특정 날짜 시각 | `2026-03-08 09:00` |
| 자연어 | 추론 | `"30분 후까지"`, `"1시간 동안"` |

### 시간 예산 분배 알고리즘

총 가용 시간 = deadline - now winddownreserve = max(3분, 총 가용 시간 * 10%) 실행 가용 시간 = 총 가용 시간 - winddownreserve - parse_overhead(2분)

작업별 시간 할당: IF priority == "quick": 각 작업 = min(5분, 실행 가용 시간 / 작업 수) ELIF priority == "high": 상위 30% 작업 = 실행 가용 시간 60% 나머지 작업 = 실행 가용 시간 40% ELSE (balanced): 각 작업 = 실행 가용 시간 / 작업 수 (의존성 순서 고려)

### 시간 체크포인트

| 남은 시간 비율 | 레벨 | 대응 |
|-------------|------|------|
| **> 50%** | NORMAL | 정상 실행, 새 작업 시작 가능 |
| **30-50%** | AWARE | 대규모 작업 시작 자제, 현재 작업 완료 집중 |
| **15-30%** | CAUTION | 새 작업 시작 금지, 현재 작업 마무리 |
| **5-15%** | WIND_DOWN | Phase 3 진입, 안전한 마무리 시작 |
| ** Details: [resources/parse-init-protocol.md](./resources/parse-init-protocol.md)

1. **지침 파싱**: 사용자 입력에서 directive, deadline, options 추출
2. **마감 시간 계산**: `scripts/parse-deadline.sh`로 epoch 변환
3. **세션 상태 초기화**: `~/.claude/cache/claude-autopilot/session-state.json` 생성
4. **이전 세션 확인**: 중단된 세션이 있으면 resume 제안
5. **프로젝트 스캔**: 대상 프로젝트의 구조/언어/프레임워크 빠르게 파악

**출력 형식**:

[claude-autopilot] Session initialized Directive: {요약된 지침} Deadline: {HH:MM} ({남은 시간}m remaining) Priority: {high|balanced|quick} Scope: {file|module|project}

### Phase 1: Decompose

> Details: [resources/decompose-protocol.md](./resources/decompose-protocol.md)

1. **지침 분석**: 사용자 directive를 구체적 작업 목록으로 분해
2. **의존성 분석**: 작업 간 의존 관계 파악 (DAG 구성)
3. **규모 추정**: 각 작업의 예상 복잡도 (S/M/L/XL) 산정
4. **시간 예산 할당**: 남은 시간 기반 작업별 시간 배분
5. **실행 순서 결정**: 의존성 + 우선순위 기반 실행 순서 확정
6. **스킵 판단**: 시간 부족 시 낮은 우선순위 작업 사전 스킵 표시

**작업 분해 출력 형식**:

[claude-autopilot] Task Plan ({N} tasks, {M}m budget) ┌─────┬──────────────────────┬──────┬───────┬────────┐ │ # │ Task │ Size │ Time │ Status │ ├─────┼──────────────────────┼──────┼───────┼────────┤ │ 1 │ {task description} │ M │ 10m │ ready │ │ 2 │ {task description} │ S │ 5m │ ready │ │ 3 │ {task description} │ L │ 15m │ ready │ │ 4 │ {task description} │ S │ 5m │ skip? │ └─────┴──────────────────────┴──────┴───────┴────────┘ Wind-down reserve: {W}m

### Phase 2: Execute Loop

> Details: [resources/execute-protocol.md](./resources/execute-protocol.md)

각 작업 실행 시 반복되는 루프:

1. **시간 체크**: `scripts/check-deadline.sh`로 남은 시간 확인
2. **다음 작업 선택**: 의존성 충족 + 우선순위 최상위 작업
3. **작업 실행**: 실제 코드 읽기/수정/생성/테스트 수행
4. **결과 검증**: 작업 완료 조건 확인 (컴파일, 테스트 통과 등)
5. **상태 갱신**: session-state.json 업데이트, 진행 상태 표시
6. **체크포인트 판단**: 남은 시간 레벨에 따라 계속/중단 결정

**작업 실행 중 상태 표시**:

[claude-autopilot] Task 2/4 | ▓▓▓▓░░░░░░ | 18m remaining | Status: implementing

**작업 완료 시 표시**:

[claude-autopilot] ✓ Task 2 complete (4m 23s) | 3/4 done | 14m remaining

### Phase 3: Wind-down

> Details: [resources/winddown-protocol.md](./resources/winddown-protocol.md)

마감 시간 임박 시 안전한 마무리 절차:

1. **현재 작업 완료 판단**: 완료 가능하면 마무리, 불가능하면 안전 지점까지 롤백
2. **코드 일관성 확보**: 편집 중인 파일이 문법적으로 유효한 상태인지 확인
3. **미완료 작업 기록**: 남은 작업 목록을 session-state.json에 저장
4. **임시 파일 정리**: 작업 중 생성된 불필요한 임시 파일 제거

### Phase 4: Report

> Details: [resources/report-protocol.md](./resources/report-protocol.md)

세션 종료 시 최종 보고서 출력:

```markdown
## Autopilot Session Report

### 세션 요약
- 시작: {start_time} → 종료: {end_time} (총 {duration})
- 완료: {completed}/{total} tasks ({percentage}%)

### 완료된 작업
| # | Task | Duration | Result |
|---|------|----------|--------|
| 1 | {description} | 4m 23s | ✓ success |
| 2 | {description} | 8m 12s | ✓ success |

### 미완료 작업
| # | Task | Reason | 권장 사항 |
|---|------|--------|----------|
| 3 | {description} | 시간 부족 | 다음 세션에서 계속 |

### 변경된 파일
- `src/api/handler.kt` — 리팩토링 완료
- `src/test/api/HandlerTest.kt` — 테스트 추가

### 다음 세션 권장 사항
- [ ] {미완료 작업 1}
- [ ] {미완료 작업 2}

---

Directive Parsing Rules

사용자 지침에서 구조화된 정보를 추출하는 규칙.

지침 구성 요소

| 구성 요소 | 필수 | 추출 방법 | 기본값 | |----------|------|----------|-------| | directive | ✅ | 시간/옵션 제외한 나머지 텍스트 | — | | deadline | ✅ | --until, 까지, 시간 표현 패턴 매칭 | — | | priority | ❌ | --priority 플래그 | balanced | | scope | ❌ | --scope 플래그 또는 경로 패턴 | project | | loop | ❌ | loop N 패턴 | 검증 1회 | | dry-run | ❌ | dry-run 키워드 | false |

지침 해석 우선순위

1. 명시적 작업 목록: "1. A 하고 2. B 하고 3. C 해줘" → 순서대로 실행
2. 범위 지정 작업: "src/api/ 아래 모든 TODO 처리" → Glob으로 대상 파일 탐색
3. 목표 지향 작업: "API 성능 개선" → Decompose에서 세부 작업 자동 생성
4. 자유 형식: "코드 정리 좀 해줘" → 프로젝트 스캔 후 개선 포인트 자동 발견

---

Task Estimation

작업 규모 추정 기준.

| Size | 예상 시간 | 특징 | 예시 | |------|----------|------|------| | S (Small) | 1-5분 | 단일 파일, 단순 변경 | TODO 제거, import 정리, 오타 수정 | | M (Medium) | 5-15분 | 2-5 파일, 로직 변경 | 메서드 추가, 리팩토링, 단위 테스트 | | L (Large) | 15-30분 | 5-10 파일, 구조 변경 | 새 API 엔드포인트, 모듈 리팩토링 | | XL (Extra Large) | 30분+ | 10+ 파일, 아키텍처 영향 | 새 모듈 생성, 대규모 마이그레이션 |

시간 부족 시 XL 작업 처리:

• 가용 시간 ` |

| update-task-status.sh | 작업 상태 갱신 | ./update-task-status.sh | | generate-report.sh | 최종 보고서 JSON 생성 | ./generate-report.sh | | check-phase-gate.sh | Phase 전환 Gate Check | ./check-phase-gate.sh | | verify-plugin.sh | 플러그인 무결성 검증 하네스 | ./verify-plugin.sh [--verbose] | | _common.sh | 공유 유틸리티 (다른 스크립트에서 source) | 직접 실행 불가 |

스크립트 실행 요구사항:

• 필수 CLI: bash 4.0+, jq, date, grep, find
• 환경: Unix-like (Linux, macOS)

---

Hooks Configuration

| Hook | Trigger | Action | |------|---------|--------| | PreToolUse (secret guard) | Edit/Write | 시크릿 파일 편집 차단 | | PreToolUse (deadline check) | Edit/Write/Bash | 마감 시간 초과 시 차단 (exit 2) | | PreToolUse (scope enforcement) | Edit/Write | scope 밖 파일 편집 차단 (project/module/file) | | PostToolUse (activity tracker) | Edit/Write | 마지막 활동 시간 기록 | | Stop (session archive) | Session end | 세션 상태 아카이브 |

---

Status Display Protocol

각 작업 실행 시 현재 상태를 간결하게 표시한다.

표시 형식

[claude-autopilot] Task: {n}/{total} | {bar} | {remaining}m left | Phase: {phase} | Level: {time_level}

예시:

[claude-autopilot] Task: 2/5 | ▓▓▓▓░░░░░░ | 23m left | Phase: Execute | Level: NORMAL
[claude-autopilot] Task: 4/5 | ▓▓▓▓▓▓▓▓░░ | 6m left | Phase: Execute | Level: CAUTION
[claude-autopilot] Wind-down | ▓▓▓▓▓▓▓▓▓░ | 3m left | Phase: Wind-down | Level: WIND_DOWN

---

Session State Schema

세션 상태는 ~/.claude/cache/claude-autopilot/session-state.json에 저장.

{
  "session_id": "ap-20260307-153000",
  "status": "in_progress",
  "directive": "API 엔드포인트 리팩토링하고 테스트 추가",
  "deadline_epoch": 1741340400,
  "deadline_display": "15:30",
  "started_at": "2026-03-07T14:30:00Z",
  "priority": "balanced",
  "scope": "project",
  "time_budget": {
    "total_minutes": 60,
    "wind_down_reserve": 6,
    "execution_available": 52,
    "parse_overhead": 2
  },
  "tasks": [
    {
      "id": 1,
      "description": "OrderController 리팩토링",
      "size": "M",
      "allocated_minutes": 12,
      "status": "completed",
      "started_at": "2026-03-07T14:32:00Z",
      "completed_at": "2026-03-07T14:40:23Z",
      "files_changed": ["src/api/OrderController.kt"]
    },
    {
      "id": 2,
      "description": "OrderControllerTest 추가",
      "size": "M",
      "allocated_minutes": 10,
      "status": "in_progress",
      "started_at": "2026-03-07T14:40:30Z",
      "depends_on": [1],
      "acceptance_criteria": [
        "테스트 파일 생성됨",
        "테스트 실행 통과"
      ]
    }
  ],
  "completed_tasks": 1,
  "total_tasks": 4,
  "errors": [],
  "file_inventory": {
    "read": [
      {"path": "src/api/OrderController.kt", "at": "2026-03-07T14:32:00Z", "lines": 145}
    ],
    "modified": [
      {"path": "src/api/OrderController.kt", "at": "2026-03-07T14:33:15Z", "verified": true}
    ]
  },
  "last_activity": "2026-03-07T14:45:12Z",
  "time_level": "NORMAL"
}

---

Context Health Protocol

롱 세션에서 컨텍스트 윈도우 사용량을 모니터링한다.

임계값 대응

| 사용량 | 레벨 | 대응 | |--------|------|------| | 70% | WARNING | 새 작업 시 reference 최소 로딩, 핵심 변경에 집중 | | 80% | RECOMMEND | 현재 작업 완료 후 /compact 실행 권장 | | 85% | CRITICAL | 즉시 /compact 실행, 프로파일 + 현재 작업 상태만 복구 |

압축 후 복구 절차

1. /compact 실행 후 컨텍스트 요약됨
2. session-state.json 재로드 (캐시에서)
3. 현재 실행 중인 작업 컨텍스트 복구
4. 남은 시간 재계산 후 실행 루프 재개

---

Session Wisdom Protocol

세션 간 학습 내용을 축적한다.

저장 위치

~/.claude/cache/claude-autopilot/history/

기록 시점

| 시점 | 기록 내용 | 자동/수동 | |------|----------|----------| | 작업 완료 | 작업별 실제 소요 시간 (추정 정확도 개선용) | 자동 | | 에러 해결 | 에러 + 원인 + 해결 방법 | 자동 | | 세션 종료 | 전체 세션 요약 + 미완료 작업 | 자동 |

시간 추정 학습

이전 세션의 실제 소요 시간 데이터를 활용하여 작업 규모 추정 정확도를 개선:

추정 보정 계수 = 최근 5개 세션의 (실제 시간 / 추정 시간) 평균
보정된 추정 = 기본 추정 × 보정 계수

보존 규칙

• **최근 20

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: brody-0125
• Source: brody-0125/my-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.