# 사용자 여정: 쉘에서 명령을 실행하고 상태를 이어간다

## 0. 문서 정보

| 항목 | 내용 |
|---|---|
| 여정 식별자 | `JRN-shell-interaction` |
| 여정명 | 쉘에서 명령을 실행하고 상태를 이어간다 |
| 상태 | 초안 (v0.2) |
| 담당자 | 미지정 |
| 최종 수정일 | 2026-08-30 |
| 달성 가치 | V3 끊김 없는 세션 연속성 (쉘 상태의 축적·보존) |
| 연결 문서 | PRD [`shell-workload`](../prd/shell-workload.md)(AC-D1~D5) · [`lifecycle`](../prd/lifecycle.md)(AC-B3) · mockup `workspace.html` ([매핑](../mockups/README.md)) |

> 이 여정은 `shell` 타입 세션의 **사용 루프**다. `JRN-session-creation`이 세션을 만드는 여정이라면
> 여기는 그 안에서 실제로 무엇을 하는가에 해당한다. `claude-code` 타입의 같은 자리는
> [`JRN-agent-prompt-loop`](./JRN-agent-prompt-loop.md)다.

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

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

## 2. 여정 정의

**대상 사용자 (페르소나)**
P1 멀티세션 작업자 ([README](./README.md#p1-멀티세션-작업자)).

**진입 맥락**
`shell` 타입으로 만든 세션이 `active` 상태이고, 작업자가 그 안에서 실제 작업을 시작하려 한다.

**트리거**
실행할 명령이 생겼다 — 빌드를 돌리거나, 로그를 뒤지거나, 디렉터리를 옮겨 다녀야 한다.

**사용자 목표**
평소 쓰던 터미널처럼 쓰는 것. 명령이 남긴 상태가 다음 명령에 그대로 이어지는 것.

**완료 기준**
작업자가 **상태에 의존하는 명령 연쇄를 성공**시킨다 — 예를 들어 디렉터리를 옮기고 환경 변수를 설정한 뒤
그 둘에 의존하는 명령이 의도대로 실행된다.

## 3. 단계별 상세

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

### `STP-shell-attach` 쉘에 붙는다

- **사용자 행동**: 세션을 열면 이미 떠 있는 인터랙티브 쉘 콘솔 앞에 앉는다. 별도의 접속 절차는 없다.
  재진입이면 이전 출력 이력이 그대로 다시 보인다.
- **터치포인트**: 워크스페이스의 session shell 콘솔 (mockup `workspace.html`)
- **생각·감정**: "그냥 터미널이네." — 익숙함이 곧 성공 지표다.
- **페인포인트 / 이탈 위험**: 빈 콘솔로 시작하면 이전 작업이 날아간 줄 안다
  → 재진입 시 이력을 먼저 채운 뒤 입력을 열고, 이력이 잘렸다면 잘렸다고 표시한다.
- **관련 AC**: AC-D1

### `STP-command-input` 명령을 친다

- **사용자 행동**: 프롬프트에 명령을 입력해 실행한다(`ls`, `cd /work`, `export KEY=…`).
- **터치포인트**: 콘솔의 `$` 입력 행 (mockup `workspace.html`) · 쉘 write API
- **생각·감정**: "터미널이랑 똑같이 동작하나?" — 탭 완성·시그널·인터랙티브 프롬프트에서 차이가 드러난다.
- **페인포인트 / 이탈 위험**: 일반 터미널과 미묘하게 다르면(개행 처리, 붙여넣기, 긴 출력 중 입력)
  작업자는 언제 다른지 예측할 수 없어 신뢰를 잃는다 → 차이가 있는 지점은 콘솔에서 명시적으로 알린다.
- **관련 AC**: AC-D2

### `STP-output-read` 출력을 본다

- **사용자 행동**: 명령 출력을 확인한다. 계속 보고 있으면 새 출력만 이어 붙고,
  나갔다 들어오면 처음부터의 이력을 다시 볼 수 있다.
- **터치포인트**: 콘솔의 출력 영역 (mockup `workspace.html`) · 쉘 read API
- **생각·감정**: "아까 그 에러 다시 봐야 하는데" — 출력이 사라지지 않는다는 확신이 있어야 작업 흐름이 끊기지 않는다.
- **페인포인트 / 이탈 위험**: 읽었다고 출력이 소비돼 사라지거나, 긴 빌드 로그가 잘리면 작업자는 스크롤을 신뢰하지 않고
  매번 파일로 리다이렉트하게 된다 → 읽기는 비파괴적으로 유지하고, 누적 한계에 걸리면 조용히 자르지 말고 표시한다.
- **관련 AC**: AC-D3

### `STP-shell-state-carry` 상태가 다음 명령으로 이어진다

- **사용자 행동**: 앞선 명령이 만든 상태(작업 디렉터리, 환경 변수, 쉘 변수·함수, 실행 중인 포그라운드 작업) 위에서
  다음 명령을 이어 실행한다. 이 쉘 상태가 곧 세션의 보존 대상이며, 동결·복원을 거쳐도 유지된다.
- **터치포인트**: 콘솔 · 워크스페이스의 Shell state 패널 (mockup `workspace.html`)
- **생각·감정**: "여기가 내 작업 상태다." — 상태가 쌓일수록 이 세션의 가치가 커지고, 잃을 때의 손실도 커진다.
- **페인포인트 / 이탈 위험**: 어떤 상태가 보존되는지 보이지 않으면 작업자는 방어적으로 스크립트로 재현하려 든다
  → 보존되는 것(cwd·env·변수·실행 중 작업)을 화면에서 보여주고, 보존되지 않는 것도 함께 밝힌다.
- **관련 AC**: AC-D4, AC-B3

## 4. 분기·예외 흐름

| 상황 | 처리 | 이어지는 단계 |
|---|---|---|
| 작업 중 유휴 한계 도달 | 쉘 상태를 통째로 동결하고 pod 회수 | `JRN-idle-resume`의 `STP-auto-freeze` |
| 동결된 세션에 명령 입력 | 복원 후 이전 cwd·env 위에서 실행 | `JRN-idle-resume`의 `STP-restore-resume` |
| 장시간 포그라운드 작업 실행 중 유휴 | 동결 대상이 되는지 **미결** — [README 미해결 항목](./README.md#-열린-결정) | `STP-shell-state-carry` |
| 출력이 누적 한계에 근접 | 잘림을 표시하고, 이미 받은 출력 위치는 계속 유효하게 유지 | `STP-output-read` |
| 컨테이너 재시작(복원 아님) | 새 쉘로 시작하므로 이어지지 않는다. 복원과 구분해 알린다 | `STP-shell-attach` |
| 쉘 프로세스가 죽음 | 세션을 되살릴지 정리할지 선택지를 제시 | `JRN-session-deletion`의 `STP-delete-intent` |

## 5. 측정 지표

| 지표 | 정의 | 목표 |
|---|---|---|
| 명령 왕복 지연 | 입력 → 첫 출력 도달까지 시간 (p50/p95) | TBD |
| 상태 연쇄 성공률 | 이전 상태에 의존한 명령이 의도대로 실행된 비율 | TBD |
| 재진입 이력 복원율 | 재진입 시 이전 출력 이력이 온전히 보인 비율 | TBD |
| 세션당 명령 수 | 세션 수명 동안 실행된 명령 수 중앙값 | TBD (실사용 깊이) |
| 동결 후 상태 손실 신고 | 복원 후 cwd·env가 달라졌다는 신고 건수 | TBD (0 유지) |

## 6. 변경 이력

| 버전 | 날짜 | 변경 내용 | 작성자 |
|---|---|---|---|
| v0.1 | 2026-07-01 | 최초 작성 (구 식별자 J5) — 세션 정체가 인터랙티브 쉘로 확정되며 신설 | 미지정 |
| v0.1.1 | 2026-08-08 | 참조 가치를 V6(삭제) → V3으로 재연결 | 미지정 |
| v0.2 | 2026-08-30 | 전면 재작성 — 슬러그 식별자 전환, 여정 정의·분기·지표·변경 이력 추가. 커서·offset 계약 서술을 AC-D3으로 위임하고 구현 상태 절은 `../doc-tracker/`로 이관 | Claude |