# 사용자 여정: 작업 환경을 골라 에이전트에게 일을 시킨다

## 0. 문서 정보

| 항목 | 내용 |
|---|---|
| 여정 식별자 | `JRN-agent-prompt-loop` |
| 여정명 | 작업 환경을 골라 에이전트에게 일을 시킨다 |
| 상태 | 초안 (v0.2.1) |
| 담당자 | 미지정 |
| 최종 수정일 | 2026-09-03 |
| 달성 가치 | V8 목적에 맞는 작업 환경 선택 · V3 끊김 없는 세션 연속성 |
| 연결 문서 | PRD [`claude-code-workload`](../prd/claude-code-workload.md)(AC-E1~E6) · [`lifecycle`](../prd/lifecycle.md)(AC-B1~B3) · mockup `new-session.html`·`agent-workspace.html` ([매핑](../mockups/README.md)) |

> 이 여정은 두 가지를 함께 담는다 — **타입을 고르는 순간**(`STP-workload-choice`, V8)과
> `claude-code` 타입의 **사용 루프**(나머지 단계). 다른 타입의 같은 자리는
> [`JRN-shell-interaction`](./JRN-shell-interaction.md)(`shell`)과
> [`JRN-approval-gated-work`](./JRN-approval-gated-work.md)(`approval-gated`)이며,
> **타입이 달라도 플랫폼 보장은 같다**는 것이 V8의 핵심이다.
> 타입이 셋으로 늘어난 뒤에도 고르는 순간은 이 여정의 `STP-workload-choice` 하나가 계속 담는다.

## 1. 서비스 개요 (참고)

[`JRN-session-creation`](./JRN-session-creation.md#1-서비스-개요-참고)과 동일. 가치 정의는 [`../values.md`](../values.md).

## 2. 여정 정의

**대상 사용자 (페르소나)**
P1 멀티세션 작업자 ([README](./README.md#p1-멀티세션-작업자)).
단, "직접 명령을 치는 사람"과 "일을 맡기는 사람"이 같은 페르소나인지는 미확인 — [README 미해결 항목](./README.md#-열린-결정).

**진입 맥락**
새 작업을 시작하려는데, 명령을 하나씩 치기보다 목표를 설명하고 맡기는 편이 빠른 종류의 일이다.

**트리거**
"이건 시켜놓고 다른 거 하자"는 판단.

**사용자 목표**
자연어로 일을 맡기고, 맡긴 맥락이 다음 요청에도 이어지는 것. 환경을 바꾸려고 다른 도구로 옮기지 않아도 되는 것.

**완료 기준**
작업자가 **앞선 요청의 결과에 의존하는 후속 요청을 성공**시킨다 —
즉 두 번째 프롬프트가 첫 번째의 대화 맥락과 그 결과물(파일) 위에서 처리된다.

## 3. 단계별 상세

> 단계 식별자는 순번이 아닌 슬러그다. 순서가 바뀌어도 식별자는 유지한다.

### `STP-workload-choice` 작업 환경을 고른다

- **사용자 행동**: 세션을 만들면서 작업 환경을 고른다 — 직접 명령을 치는 쉘, 프롬프트로 일을 맡기는 에이전트,
  또는 **밖으로 나갈 때마다 내 승인을 받는 에이전트** 셋 중 하나다.
  에이전트 쪽을 고르면 사용할 모델도 함께 정하는데, 기본값 그대로 넘어갈 수 있다.
  **타입과 모델은 세션 수명 동안 바꿀 수 없다** — 바꾸려면 새 세션을 만든다.
  승인 게이트를 고른 뒤의 사용 루프는 [`JRN-approval-gated-work`](./JRN-approval-gated-work.md)가 다룬다.
- **터치포인트**: New session 모달의 workload type 카드 3종과 model 선택 (mockup `new-session.html`)
- **생각·감정**: "뭘 골라야 하지?" — 선택지가 셋이 되면서 차이를 읽어야 할 양이 늘었다.
  차이를 모르면 기본값으로 넘어가고, 되돌릴 수 없다는 안내가 없으면 나중에 당황한다.
- **페인포인트 / 이탈 위험**: 불변이라는 사실을 고른 뒤에 알게 되면 세션을 버리고 다시 만든다
  → 선택 시점에 불변임을 명시하고, 각 환경이 어떤 일에 맞는지 한 줄로 설명한다. 모델은 기본값으로 지나갈 수 있게 둔다.
- **관련 AC**: AC-E1, AC-E6, AC-F1 (보조 AC-A1·A2)

### `STP-prompt-submit` 프롬프트로 일을 맡긴다

- **사용자 행동**: 하려는 일을 자연어로 써서 보낸다. 보낸 뒤 응답을 기다리지 않고 다른 일을 봐도 된다.
  이전 요청이 아직 처리 중이면 다음 요청은 줄을 서고, 한 세션에서 두 실행이 겹치지 않는다.
- **터치포인트**: 에이전트 워크스페이스의 프롬프트 입력 행 (mockup `agent-workspace.html`) · 프롬프트 write API
- **생각·감정**: "보낸 게 접수는 된 건가?" — 즉시 반환되기 때문에 접수 표시가 없으면 두 번 보내게 된다.
- **페인포인트 / 이탈 위험**: 접수와 실행 시작을 구분하지 못하면 중복 제출이 쌓인다.
  너무 긴 프롬프트나 밀린 대기열이 거절될 때 이유가 불명확하면 재시도만 반복한다
  → 접수 여부를 즉시 보여주고, 거절은 사유(너무 큼·대기열 포화)와 다음 행동을 함께 알린다.
- **관련 AC**: AC-E2

### `STP-response-watch` 응답이 쌓이는 것을 본다

- **사용자 행동**: 화면을 보고 있으면 응답이 실행 중에 이어서 나타난다. 새로고침이나 수동 조회는 필요 없다.
  탭을 닫았다 다시 열면 놓친 부분부터 이어 붙고, 중간이 비거나 겹치지 않는다.
- **터치포인트**: 에이전트 워크스페이스의 출력 콘솔과 연결 상태 표시 (mockup `agent-workspace.html`)
- **생각·감정**: "지금 돌고 있는 거 맞지?" — 진행 신호가 없으면 멈춘 것으로 읽는다.
- **페인포인트 / 이탈 위험**: 연결이 끊겼는데 조용하면 작업자는 결과가 유실됐다고 판단해 같은 일을 다시 시킨다
  → 연결 상태를 화면에 드러내고, 끊김은 자동으로 이어 붙이며, 이어 붙일 수 없을 때만 전체를 다시 그린다.
  세션이 접혀 있다면 몰래 되살리지 말고 복원 화면으로 안내한다.
- **관련 AC**: AC-E3

### `STP-conversation-carry` 대화가 하나로 이어진다

- **사용자 행동**: 이어서 다음 프롬프트를 보낸다. 앞선 요청·응답이 문맥으로 남아 있어 "아까 그거"라고만 해도 통한다.
  이전 실행이 만든 파일도 그대로 남아 다음 실행이 이어 쓴다.
- **터치포인트**: 에이전트 워크스페이스의 conversation 패널 (mockup `agent-workspace.html`)
- **생각·감정**: "앞에서 한 얘기 다시 안 해도 되네." — 이 확신이 없으면 매번 전체 맥락을 붙여넣게 된다.
- **페인포인트 / 이탈 위험**: 어디까지 기억하는지 보이지 않으면 방어적으로 맥락을 반복 입력한다
  → 이어지는 대화 이력과 작업 디렉터리를 화면에 드러내, 무엇이 문맥인지 눈으로 확인하게 한다.
- **관련 AC**: AC-E4

### `STP-agent-freeze-resume` 접혔다 돌아와도 이어진다

- **사용자 행동**: 한동안 두었다가 다시 열어 다음 프롬프트를 보낸다. 동결 전 대화 맥락과 작업 디렉터리 위에서 응답이 이어진다.
  받아둔 출력 위치도 그대로 유효하다.
- **터치포인트**: 세션 목록의 `snapshot` 배지 → 복원 후 에이전트 워크스페이스 (mockup `agent-workspace.html`)
- **생각·감정**: "쉘 세션이랑 똑같이 동작하네." — 타입에 따라 경험이 갈리지 않는 것이 V8의 약속이다.
- **페인포인트 / 이탈 위험**: 타입마다 재개 경험이 다르면 "안전한 타입"을 골라 쓰게 되어 선택의 가치가 사라진다
  → 사용자가 보는 흐름은 `JRN-idle-resume`과 동일하게 유지하고, 내부 메커니즘 차이를 화면에 노출하지 않는다.
- **관련 AC**: AC-E5 (상위 AC-B1·B2·B3)

## 4. 분기·예외 흐름

| 상황 | 처리 | 이어지는 단계 |
|---|---|---|
| 프롬프트가 너무 큼 | 대기열에 넣지 않고 거절(413)하고 사유를 표시 | `STP-prompt-submit` |
| 대기열 포화 | 새 제출을 거절(429)하고 잠시 후 재시도를 안내 | `STP-prompt-submit` |
| 누적 출력이 한계에 도달 | 새 프롬프트를 거절(507)하고 상태를 표시. 복원 후에도 같은 상태가 유지된다 | `STP-conversation-carry` |
| 응답 연결이 끊김 | 놓친 지점부터 자동으로 이어 붙인다 | `STP-response-watch` |
| 이어 붙일 수 없는 지점까지 밀림 | 전체 이력을 다시 받아 콘솔을 교체한 뒤 이어 본다 | `STP-response-watch` |
| 보고 있는 중 세션이 접힘 | 자동 복원하지 않고 복원 화면으로 안내 | `JRN-idle-resume`의 `STP-reaccess` |
| 다른 모델·타입이 필요해짐 | 기존 세션을 바꾸지 않고 새 세션을 만든다 | `STP-workload-choice` |
| 외부 접근에 사람의 승인이 필요해짐 | `approval-gated` 타입으로 새 세션을 만든다 | `JRN-approval-gated-work`의 `STP-gated-prompt-submit` |

## 5. 측정 지표

| 지표 | 정의 | 목표 |
|---|---|---|
| 후속 프롬프트 도달률 | 두 번째 이상 프롬프트를 보낸 세션 수 / `claude-code` 세션 수 | TBD (문맥 연속성 체감) |
| 첫 응답 지연 | 제출 → 첫 출력 표시까지 시간 (p50/p95) | TBD |
| 중복 제출률 | 동일 내용이 60초 내 재제출된 비율 | TBD (접수 표시 실패 신호) |
| 거절 응답 비율 | 413·429·507 응답 수 / 전체 제출 수 | TBD |
| 타입 선택 분포 | `claude-code` 선택 세션 수 / 전체 생성 세션 수 | TBD (V8 채택 신호) |
| 타입 오선택 신호 | 생성 후 사용 없이 삭제된 `claude-code` 세션 비율 | TBD |

## 6. 변경 이력

| 버전 | 날짜 | 변경 내용 | 작성자 |
|---|---|---|---|
| v0.1 | 2026-08-08 | 최초 작성 (구 식별자 J6) — 워크로드 타입 확장과 V8 신설에 따라 신설 | 미지정 |
| v0.1.1 | 2026-08-09 | live output UX(자동 append·커서 재개·reset 복구) 반영 | 미지정 |
| v0.2 | 2026-08-30 | 전면 재작성 — 슬러그 식별자 전환. CLI 플래그·커서 인코딩·바이트 상한 등 계약 서술을 AC-E2~E6으로 위임하고 사용자 관측 경험만 남김. 여정 정의·분기·지표·변경 이력 추가, 구현 상태 절은 `../doc-tracker/`로 이관 | Claude |
| v0.2.1 | 2026-09-03 | `approval-gated` 타입(AC-F1) 신설 반영 — `STP-workload-choice`에 세 번째 선택지 추가, 신규 여정 `JRN-approval-gated-work`로의 연결과 분기 1행 추가. 단계 수·식별자 변화 없음 | Claude |