# hast: 방향성 가이드

## 이 문서의 목적

hastork은 현재 동작하는 자동 개발 도구다.
이 문서는 hastork이 "다음 단계"에서 무엇이어야 하는지를 정의한다.
구체적 구현은 네가 판단해라. 여기엔 원칙과 방향만 있다.

---

## 핵심 통찰: 지금 hastork에 빠져 있는 것

현재 hast auto의 흐름은 이렇다:

```
goal → worktree → RED → GREEN → evaluate → merge
```

이건 **인간 개발자 한 명의 워크플로우를 자동화한 것**이다.
순차적이고, 한 번에 하나의 경로만 탐색하고, 실패하면 retry한다.

문제: 에이전트의 근본적 강점을 활용하지 못하고 있다.

에이전트가 인간과 결정적으로 다른 점이 세 가지 있다:

1. **폐기 비용이 거의 0이다.** 인간은 3일 작업을 버리면 감정적/정치적 비용이 크다. 에이전트는 실패한 브랜치를 삭제하면 끝이다.

2. **의사결정을 병렬로 할 수 있다.** 인간은 A안과 B안을 동시에 평가 못 한다. 에이전트는 A안과 B안을 동시에 spike하고, evidence를 비교해서 30분 만에 채택할 수 있다.

3. **컨텍스트 스위칭 비용이 0이다.** 인간 리뷰어는 코드를 이해하는 데 반나절 걸린다. 에이전트는 즉시 로드해서 즉시 판단한다.

---

## hastork이 되어야 하는 것

### 원칙: "확정 → 구현" 순서를 절대 뒤집지 마라

지금 hastork의 가장 큰 생산성 병목은 코드 생성 속도가 아니다.
**"뭘 만들지"가 확정되지 않은 상태에서 구현에 들어가는 것**이다.

스펙 해석이 불확실한 상태에서 구현하면:
- 테스트와 구현이 같은 오해를 공유한다
- evaluate에서 통과해도 실제로는 틀린 방향이다
- retry가 같은 실수를 반복한다
- merge 후 회귀가 발생한다

hastork의 루프는 두 단계로 나뉘어야 한다:

### Phase 1: 불확실성 제거 (여기서 병렬화)

goal이 worktree에 들어가기 **전에**, 결정해야 할 것들을 먼저 확정한다.

병렬로 돌려야 하는 건 구현이 아니라 **의사결정**이다:

- **Contract 확정**: 이 goal의 수용 기준, 비목표(non-goal), 인터페이스가 뭔지
- **대안 탐색**: 접근법이 여러 개일 때, 가벼운 spike를 동시에 돌려서 evidence 기반으로 하나를 채택
- **테스트 선행**: Contract가 확정되면 RED 테스트는 구현 전에 이미 확정될 수 있다
- **리스크 사전 탐지**: 이 goal이 다른 goal과 충돌하는지, 머지 시 어떤 문제가 생길지

이 단계의 산출물: **확정된 contract + RED 테스트 + 채택된 접근법**

### Phase 2: 확정된 결정 위에서 구현 (여기서 속도)

Contract가 확정되었으므로:
- 스펙 해석 불일치가 없다
- 테스트가 이미 있으므로 "맞는지" 판별이 자동이다
- retry가 의미 있다 (같은 목표를 향해 다시 시도하니까)
- 여러 goal을 동시에 구현해도 충돌이 줄어든다

---

## hastork에 이걸 어떻게 녹일지

아래는 방향이지 구체적 구현 지시가 아니다. 네가 현재 코드베이스를 보고 가장 자연스러운 방식으로 녹여라.

### 1. goal 진입 전 "결정 단계"를 도입하라

지금은 goal → 바로 worktree → RED/GREEN이다.
goal이 worktree에 들어가기 전에, 그 goal의 불확실성 수준을 평가하고,
불확실성이 높으면 "결정 단계"를 먼저 거치게 하라.

불확실성이 낮은 goal (명확한 버그 수정, 단순 리팩토링 등)은 지금처럼 바로 들어가면 된다.
불확실성이 높은 goal (설계 선택이 필요한 것, 접근법이 여러 개인 것)은
contract를 먼저 확정하고 나서 구현에 들어가야 한다.

### 2. 대안 병렬 탐색을 지원하라

하나의 goal에 대해 접근법이 여러 개일 때,
각각을 가벼운 spike로 동시에 돌리고, evidence를 비교해서 하나를 채택하는 흐름.

지금 hastork에 이미 worktree 격리와 DAG 병렬 실행이 있으니,
"같은 goal의 대안 spike"를 병렬로 돌리는 건 구조적으로 가능할 것이다.

핵심: spike는 완성품이 아니다. 채택 판단에 필요한 최소한의 evidence만 만들면 된다.
나머지는 폐기한다. 폐기 비용은 0이다.

### 3. feedback 루프를 "결정 품질"까지 확장하라

지금 feedback은 주로 구현 결과(테스트 통과 여부, 머지 성공 여부)를 추적한다.
여기에 **결정 품질**도 추적하라:

- 이 goal의 contract가 구현 도중 변경되었는가? → contract 확정이 불충분했다는 신호
- retry 사유가 "스펙 오해"인 경우가 반복되는가? → 결정 단계가 필요하다는 신호
- merge 후 회귀가 발생했는가? → 리스크 사전 탐지가 부족했다는 신호

이 데이터가 쌓이면, "어떤 유형의 goal에 결정 단계가 필요한가"를
hast 스스로 학습할 수 있다.

### 4. policy decision의 판단 근거를 풍부하게 하라

지금 policy decision은 retry/escalate/block/advance를 결정한다.
여기에 "왜 실패했는가"의 분류를 추가하라:

- **스펙 불일치** → retry 무의미, 결정 단계로 돌아가야 함
- **구현 버그** → retry 의미 있음
- **환경 문제** → 다른 조치 필요
- **설계 한계** → escalate 또는 대안 탐색

실패를 원인별로 분류하지 않으면, 에이전트는 같은 실패를 같은 방식으로 반복한다.
인간은 경험에서 직감적으로 "이건 retry로 안 돼"를 알지만, 에이전트는 명시적 분류가 필요하다.

---

## 하지 말아야 할 것

- **모든 goal에 결정 단계를 강제하지 마라.** 단순한 goal은 오버헤드만 늘어난다. 불확실성 수준에 따라 분기하라.
- **대안 spike를 완성품 수준으로 만들지 마라.** spike는 판단 근거만 만들면 된다. "이 접근법이 가능한가, 어떤 트레이드오프가 있는가"만 알면 충분하다.
- **인간의 워크플로우를 흉내내지 마라.** hastork의 사용자는 에이전트다. 에이전트는 동시에 10개를 돌리고 9개를 버릴 수 있다. 이걸 활용하라.

---

## 한 문장 요약

> hastork의 다음 단계는 "코드를 더 빨리 짜는 것"이 아니라
> "무엇을 만들지를 빠르게 확정하고, 확정된 채점표 위에서 구현을 쏟아붓는 것"이다.
