Metadata-Version: 2.4
Name: harnex-clarify
Version: 0.1.0
Summary: Clarify ambiguous development requirements for the harnex workflow.
Requires-Python: >=3.12
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# harnex-clarify

`harnex-clarify`는 harnex 워크플로에서 사용자의 개발 요구사항을 구현 가능한 수준으로 구체화하는 Python Typer CLI입니다.

사용자의 원본 요청을 분석해 Ambiguity Score를 계산하고, 구현 전에 더 확인해야 할 질문을 생성합니다. 점수가 `0.2` 이하로 낮아지면 Claude/Codex 같은 코딩 에이전트에 넘길 수 있는 최종 요구사항 Markdown을 JSON 결과로 출력합니다.

```text
GUI -> harnex-clarify -> agent adapter(Claude/Codex)
```

## 현재 범위

현재 버전은 MVP입니다.

- 규칙 기반 Ambiguity Score 계산
- 부족한 정보 기반 질문 생성
- 사용자 답변 반영 후 재평가
- 최종 요구사항 Markdown 렌더링
- GUI 연동용 JSON 결과 및 JSON Lines 이벤트 출력
- Typer 기반 CLI 명령 제공

아직 LLM 호출이나 GUI 인터랙션 자체는 포함하지 않습니다. GUI나 상위 오케스트레이터가 CLI를 실행하고 질문/답변 흐름을 이어가는 구조입니다.

## 요구사항

- Python `3.12` 이상
- 설치 실행 시 `pip`, `pipx`, 또는 `uv` 중 하나
- 개발 및 검증 시 `pytest`, `ruff`

## 설치해서 실행하기

로컬 소스 디렉토리에서 일반 CLI처럼 설치하려면 다음 중 하나를 사용합니다.

### venv + pip

```bash
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install .
harnex-clarify --help
```

개발 중인 소스를 바로 반영하려면 editable 모드로 설치합니다.

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/harnex-clarify --help
```

### pipx

```bash
pipx install .
harnex-clarify --help
```

### uv

`uv`를 사용하는 환경이라면 설치 없이 실행할 수 있습니다.

```bash
uv run harnex-clarify --help
```

개발 의존성까지 준비하려면 다음을 사용합니다.

```bash
uv sync --dev
uv run pytest
uv run ruff check .
```

## 빠른 실행 예시

먼저 요청 JSON을 만듭니다.

```bash
cat > request.json <<'JSON'
{
  "schema_version": "clarify.request.v1",
  "requirement": "Python Typer CLI로 JSON 입력을 받아 요구사항 모호함을 분석하고 결과 JSON을 출력해줘. 출력은 clarify.json과 events.jsonl이면 좋고, pytest 통과를 성공 기준으로 삼아줘.",
  "project_path": ".",
  "options": {}
}
JSON
```

단일 실행 명령은 입력을 분석하고 결과 JSON과 이벤트 JSONL을 한 번에 씁니다.

```bash
harnex-clarify run \
  --input request.json \
  --output clarify.json \
  --events events.jsonl
```

결과를 확인합니다.

```bash
cat clarify.json
cat events.jsonl
```

요구사항이 충분히 명확하면 결과의 `status`가 `ready`가 됩니다. 모호함이 남아 있으면 `status`가 `needs_input`이고, `questions` 배열에 다음 질문이 들어갑니다.

## CLI 명령

### `run`

GUI 연동을 단순화하기 위한 단일 실행 명령입니다.

```bash
harnex-clarify run \
  --input request.json \
  --output clarify.json \
  --events events.jsonl
```

동작:

- 요청 JSON을 읽습니다.
- Ambiguity Score를 계산합니다.
- 필요한 질문을 생성합니다.
- 최종 결과 JSON을 씁니다.
- 선택적으로 JSON Lines 이벤트 파일을 씁니다.

`run`은 사용자에게 직접 질문하지 않습니다. 결과 JSON에 질문을 담아 반환하고, GUI나 상위 프로세스가 다음 단계를 이어가야 합니다.

### `analyze`

초기 clarify 세션을 생성합니다.

```bash
harnex-clarify analyze \
  --input request.json \
  --output session.json
```

`--output`을 생략하면 stdout으로 세션 JSON을 출력합니다.

### `ask`

사용자 답변을 기존 세션에 반영하고 점수를 다시 계산합니다.

```bash
harnex-clarify ask \
  --session session.json \
  --answer answer.json \
  --output session.json
```

답변 JSON은 단일 답변 또는 여러 답변을 지원합니다.

단일 답변:

```json
{
  "question_id": "q_target",
  "answer": "src/harnex_clarify/cli.py의 run 명령을 대상으로 합니다."
}
```

여러 답변:

```json
{
  "answers": [
    {
      "question_id": "q_target",
      "answer": "src/harnex_clarify/cli.py의 run 명령을 대상으로 합니다."
    },
    {
      "question_id": "q_success",
      "answer": "pytest가 통과하고 결과 JSON에 status와 ambiguity_score가 있으면 성공입니다."
    }
  ]
}
```

### `finalize`

세션 JSON을 최종 결과 JSON으로 변환합니다.

```bash
harnex-clarify finalize \
  --session session.json \
  --output clarify.json
```

`status`가 `needs_input`인 세션도 결과 JSON으로 변환할 수 있습니다. 이 경우 남은 질문과 부족한 정보가 함께 포함됩니다.

## 단계형 사용 흐름

GUI가 질문/답변 인터뷰를 이어가려면 다음 흐름을 사용합니다.

```bash
harnex-clarify analyze --input request.json --output session.json
cat session.json
```

`session.json`의 `questions`를 사용자에게 보여준 뒤 답변을 저장합니다.

```bash
cat > answer.json <<'JSON'
{
  "question_id": "q_target",
  "answer": "src/harnex_clarify/core와 src/harnex_clarify/cli.py를 대상으로 하고, JSON 입력과 JSONL 이벤트 출력을 구현합니다. pytest 통과가 성공 기준입니다."
}
JSON
```

답변을 반영합니다.

```bash
harnex-clarify ask \
  --session session.json \
  --answer answer.json \
  --output session.json
```

`ambiguity_score`가 `0.2` 이하가 될 때까지 `questions`를 표시하고 `ask`를 반복합니다. 준비가 끝나면 최종 결과를 생성합니다.

```bash
harnex-clarify finalize --session session.json --output clarify.json
```

## 입력 JSON

`request.json`의 기본 형태는 다음과 같습니다.

```json
{
  "schema_version": "clarify.request.v1",
  "requirement": "구체화할 원본 요구사항",
  "project_path": "/path/to/project",
  "options": {}
}
```

필드:

- `schema_version`: 요청 스키마 버전입니다. 현재는 `clarify.request.v1`을 사용합니다.
- `requirement`: 필수입니다. 사용자가 입력한 원본 요구사항입니다.
- `project_path`: 선택입니다. 값이 있으면 존재하는 디렉토리인지 검증합니다.
- `options`: 선택입니다. 향후 질문 전략이나 출력 옵션을 전달하기 위한 객체입니다.

## 결과 JSON

`clarify.json`은 다음 필드를 포함합니다.

```json
{
  "schema_version": "clarify.result.v1",
  "ambiguity_score": 0.18,
  "status": "ready",
  "final_requirement_markdown": "# 구체화된 요구사항\n...",
  "questions": [],
  "answers": [],
  "risks": [],
  "missing_information": []
}
```

주요 필드:

- `ambiguity_score`: `0.0`부터 `1.0` 사이의 모호함 점수입니다. 낮을수록 명확합니다.
- `status`: `ready` 또는 `needs_input`입니다.
- `final_requirement_markdown`: 에이전트에 넘기기 좋은 Markdown 형태의 요구사항입니다.
- `questions`: 다음에 사용자에게 물어볼 질문 목록입니다.
- `answers`: 지금까지 반영된 답변 목록입니다.
- `risks`: 위험한 가정이나 범위 확대 가능성입니다.
- `missing_information`: 부족한 정보의 축과 상세 설명입니다.

## 이벤트 JSONL

`--events`를 지정하면 진행 이벤트를 JSON Lines로 씁니다.

예시:

```json
{"schema_version":"clarify.event.v1","type":"run_started"}
{"schema_version":"clarify.event.v1","type":"score_updated","ambiguity_score":0.18,"status":"ready"}
{"schema_version":"clarify.event.v1","type":"finalized","status":"ready"}
```

GUI는 이 파일을 줄 단위로 읽어 진행 상태, 점수 변화, 생성된 질문, 완료 상태를 표시할 수 있습니다.

## Ambiguity Score 기준

현재 점수화는 규칙 기반입니다. 다음 축에서 정보가 부족하면 점수가 올라갑니다.

- 목표: 무엇을 바꾸려는지
- 작업 대상: 어떤 파일, 모듈, 화면, 명령, 기능 영역인지
- 입출력: 입력 데이터와 출력 산출물이 무엇인지
- 성공 기준: 테스트나 수용 기준이 무엇인지
- 제약사항: 기술 스택, 구조, 금지사항이 있는지
- 위험한 가정: 범위가 넓거나 주관적인 표현이 있는지

`ambiguity_score <= 0.2`이면 `ready`로 판단합니다.

## 개발

pip 기반 개발 환경:

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install -e . pytest ruff
.venv/bin/python -m pytest
.venv/bin/ruff check .
```

uv 기반 개발 환경:

```bash
uv sync --dev
uv run pytest
uv run ruff check .
```

현재 테스트는 점수 계산, 인터뷰 상태 전이, CLI JSON 입출력을 검증합니다.
