harnex-clarify 0.1.0

Clarify ambiguous development requirements for the harnex workflow.

harnex-clarify

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

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

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

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

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

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

pipx

pipx install .
harnex-clarify --help

uv

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

uv run harnex-clarify --help

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

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

빠른 실행 예시

먼저 요청 JSON을 만듭니다.

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을 한 번에 씁니다.

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

결과를 확인합니다.

cat clarify.json
cat events.jsonl

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

CLI 명령

run

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

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

동작:

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

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

analyze

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

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

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

ask

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

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

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

단일 답변:

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

여러 답변:

{
  "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으로 변환합니다.

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

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

단계형 사용 흐름

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

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

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

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

답변을 반영합니다.

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

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

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

입력 JSON

request.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은 다음 필드를 포함합니다.

{
  "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로 씁니다.

예시:

{"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 기반 개발 환경:

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

uv 기반 개발 환경:

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

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