# 업무 실행 원칙과 결과 보기

> **이 장에서 배우는 것**
> 에이전트에게 업무를 맡겼을 때 내부에서 어떤 공간(Worktree)에서 작업이 이루어지는지, 왜 수시로 커밋해야 하는지, 그리고 작업 결과를 대시보드에서 어떻게 풍부하게 시각화하여 확인하는지 배웁니다.
>
> **업무를 처음 맡겨본다면** [첫 업무 맡기기](/guide/ht-first-task)를 먼저 진행하세요.

---

## 1. 업무가 실행되는 공간: Git Worktree

업무를 시작하면 에이전트는 원본 작업 공간을 직접 훼손하거나 변경하지 않고, **해당 업무만을 위한 독립된 Git Worktree(격리된 폴더와 브랜치)**에서 작업합니다.

```mermaid
sequenceDiagram
    autonumber
    participant HT as HyperTeams 관제 시스템
    participant WT as 격리된 작업 폴더 (Worktree)
    participant Base as 기준 브랜치 (Base Branch)

    HT->>WT: 1. 업무 전용 Worktree 생성 & 브랜치 체크아웃
    Note over WT: 에이전트 작업 수행 및 단위 완료마다 git commit
    HT->>Base: 2. 업무 완료 시 자동 브랜치 머지 (Auto Merge)
    HT->>WT: 3. 작업 폴더 삭제 및 정리 (Prune)
    Note over WT: ⚠️ 커밋되지 않은 변경사항은 영구 삭제!
    HT->>WT: 4. 다음 턴 시작 시 깨끗한 새 Worktree 할당
```

### 핵심 규칙: 왜 작업 단위마다 커밋해야 하나요?

업무 턴이 종료되거나 병합될 때 HyperTeams는 작업 폴더를 정리(Prune)합니다. **오직 커밋된 변경사항만 메인 브랜치로 살아남습니다.**

```mermaid
flowchart TD
    Start["업무 완료 및 턴 종료"] --> Check{"파일 상태 판정"}
    Check -->|"Git Commit 완료"| Saved["✅ 안전하게 보존 (Survives)<br/>기준 브랜치로 자동 병합"]
    Check -->|"Uncommitted 변경사항"| Deleted["❌ 영구 삭제 (Deleted)<br/>폴더 삭제와 함께 소멸"]
    Check -->|"Git-ignored 파일 (node_modules, .env.local 등)"| Deleted
```

| 구분 | 하지 말아야 할 것 (Don't) | 반드시 해야 할 것 (Do) |
|---|---|---|
| **작업 공간** | 임의로 다른 브랜치를 만들거나 바꾸기, 기준 브랜치에 직접 푸시 | 주어진 작업 폴더 안에서만 작업 (머지는 시스템이 전담) |
| **커밋** | 커밋하지 않고 턴을 마치기 | **작업 단위마다 수시로 `git commit` 남기기** |

---

## 2. 백그라운드 프로세스와 자원 관리

에이전트가 업무 중에 개발 서버나 감시 명령(`tail -f`, watcher)을 띄운 채 턴을 마치면, 그 프로세스는 계속 살아남아 **머신의 동시 실행 슬롯(Concurrency Slot)을 점유**합니다.

```mermaid
flowchart TD
    subgraph MachineSlots ["머신 가용 동시성 슬롯"]
        Slot1["슬롯 1: Task A (정상 실행 중)"]
        Slot2["슬롯 2: 종료된 업무의 백그라운드 프로세스 점유 ⚠️"]
        Slot3["슬롯 3: Task C (슬롯 부족으로 무한 대기)"]
    end

    Slot2 --> Block["🚨 치명적 현상: 후속 업무 시작 불가 (Block)<br/>화면에 원인 설명 없이 멈춤 현상 발생!"]
```

> **규칙 하나**: 업무가 끝나기 전에 오래 실행되는 백그라운드 프로세스는 반드시 종료(`kill`)해야 합니다.
> 
> **오래 켜두어야 하는 서버가 필요하다면?** 업무 창에서 띄우지 말고, 화면을 닫아도 안전하게 유지되는 [터미널](/guide/ht-terminal)에서 실행하세요.

---

## 3. 대시보드 결과 렌더링

에이전트가 작업한 결과는 웹 대시보드에 마크다운으로 표시됩니다. 적재적소에 알맞은 시각화 문법을 사용합니다.

```mermaid
flowchart LR
    Output["답변 결과물"] --> Type{"표현 대상"}
    Type -->|"만든 파일/스크린샷"| Embed["파일 임베드<br/>! [설명] (&lt;절대경로&gt;)"]
    Type -->|"구조/순서/와이어프레임"| Mermaid["다이어그램<br/>```mermaid"]
    Type -->|"근거 출처"| Footnote["각주<br/>[^1]: 경로#L라인"]
    Type -->|"통계/수치 데이터"| Chart["차트<br/>```chart"]
```

### 3.1 파일 및 미디어 보여주기 (`![desc](<path>)`)

새로 만들거나 수정한 파일을 대시보드에서 바로 확인하고 재생할 수 있습니다.
- **문법**: 반드시 `![설명](<절대경로>)` 형태로 작성합니다 (공백 경로 인식을 위해 `< >` 필수).
- **지원 형식**: 이미지(`.png`, `.jpg`), 비디오(`.mp4`, `.webm`), 오디오(`.mp3`, `.wav`)는 즉시 인라인으로 재생되며, 기타 파일은 다운로드 칩으로 표시됩니다.

```mermaid
flowchart TD
    FilePath["파일 저장 경로 판정"] --> CheckZone{"저장 위치"}
    CheckZone -->|"/tmp 임시 폴더"| TempOk["✅ 접근 허용 (적극 권장 🌟)<br/>스크린샷, 차트, 녹화본 등 일회성 시각 자료"]
    CheckZone -->|"Worktree 내부"| WorktreeOk["✅ 접근 허용<br/>⚠️ 단, 태스크 머지 후 폴더 삭제 시 링크 깨짐"]
    CheckZone -->|"Home 디렉토리 / 바탕화면"| Rejected["❌ 접근 거부 (보안 격리로 렌더링 불가)"]
```

> 💡 **스크린샷과 일회성 결과물은 `/tmp`에 두세요**: Worktree 폴더는 머지 후 삭제되므로, 화면 확인용 스크린샷을 워크트리 안에 두면 나중에 링크가 깨집니다.

### 3.2 다이어그램과 UI 와이어프레임 (`mermaid`)

- **세로 흐름 원칙 (`graph TD`)**: 대시보드 패널은 좁고 세로로 스크롤되므로 `LR` 대신 `graph TD`를 사용합니다.
- **UI 와이어프레임 (`block-beta`)**: 화면 배치를 그릴 때는 `mermaid` 블록 첫 줄에 `block-beta`를 씁니다.

```mermaid
block-beta
columns 3
header["헤더 영역 (GNB)"]:3
sidebar["사이드바 (LNB)"] main["메인 콘텐츠 영역"]:2
footer["푸터 영역 (Status)"]:3
```

---

## 요약

1. 업무는 **격리된 Git Worktree**에서 실행되므로, 변경사항은 **반드시 `git commit`**해야 머지 후에도 남습니다.
2. 백그라운드 프로세스는 **턴 종료 전에 kill**하고, 계속 살아있어야 하는 서버는 [터미널](/guide/ht-terminal)에서 실행합니다.
3. 스크린샷 등 결과 시각 자료는 **`/tmp` 폴더에 생성**하여 대시보드에 임베드합니다.