hztz

Turn “I don’t know what” in your Technical Specs into actionable code and questions.

CLI-инструмент, который помогает разбираться с сырыми, размытыми или противоречивыми техническими заданиями с помощью LLM.

Начать Смотреть команды
hztz audit --file spec.md 
🧠 Проанализировал. Одно место меня смущает...
Вы пишете "система должна быть отказоустойчивой",
но не говорите, что значит "отказ". Это потеря диска?
Ошибка в коде? Просто хотел уточнить, чтобы не ошибиться...

— Ваш покорный слуга, лейтенант Коломбо

Что это

Аббревиатура «хз в тз» — реальная боль разработчиков и аналитиков. hztz принимает файл ТЗ и помогает превратить неопределённость в конкретные вопросы, риски и задачи.

Метод Фейнмана

Если нельзя пересказать требование просто и логично — в исходнике есть скрытые противоречия. Инструмент сводит формулировки к базовым сущностям: данные, действия, условия. Если нельзя придумать тест-кейс — требование считается «хз».

Голос Коломбо

В hztz ask и hztz chat с вами общается лейтенант Коломбо: вежливо, слегка неуклюже, но проницательно. Не ругает — с обманчивой простотой указывает, что «тут какая-то мелочь не сходится».

Основные возможности

Четыре команды. Один вход — файл ТЗ.

01

hztz audit

Сканирует ТЗ на дыры, логические противоречия и белые пятна. Использует технику Фейнмана: пытается объяснить каждый раздел — если спотыкается, фиксирует проблему с уровнем риска.

02

hztz ask

Формирует конкретные технические развилки и вопросы с вариантами ответов для автора ТЗ — не открытые «а как вы это видите?», а инженерные trade-offs.

03

hztz decompose

Превращает размытый текст в атомарные, готовые к оценке задачи (issues/tickets) для Jira или GitHub Issues — в Markdown или JSON.

04

hztz chat

Интерактивный допрос документной базы в терминале. Можно спрашивать по ТЗ, не читая его целиком, и использовать слэш-команды внутри сессии.

Примеры использования

Инструмент принимает файл ТЗ (markdown, txt, pdf) и выдаёт результат в консоль, сохраняет в файл или ведёт диалог.

Анализ на логические дыры, двусмысленности и отсутствие краевых случаев.

hztz audit --file spec.md --model gpt-4o
🔍 Анализ ТЗ: spec.md
📊 Общая оценка ясности: 4/10 (Требует доработки)

⚠️ Обнаруженные проблемы (ХЗ):
  [HIGH] Секция 3.2: "Сделать быстро и красиво."
         -> Неопределенные метрики. Что значит "быстро" (мс)?
  [MED]  Секция 5.1: "Интеграция с внешней системой оплаты."
         -> Не указан протокол, что делать при тайм-ауте.
  [LOW]  Секция 8: Обработка ошибок только для 500-го статуса.

Готовый список вопросов с вариантами — можно сразу отправить автору ТЗ.

hztz ask --file spec.md --output questions.md

«В ТЗ не указан тайм-аут для внешнего API. Предлагаем два варианта на выбор для согласования: А) 3 секунды (быстрый отказ, защита UX), Б) 10 секунд (повышенная надежность при медленной сети). Какой вариант утверждаем?»

Из водянистого ТЗ — структурированный бэклог.

hztz decompose --file spec.md --format markdown

Интерактивная сессия по документу прямо в терминале.

hztz chat --file spec.md
🤖 hz-cli > Загружено ТЗ: spec.md (24 страницы)
Вы можете задавать вопросы по документу. (Введите 'exit' для выхода)

> Что будет с сессией, если пропадет интернет во время оплаты?
> В текущей версии ТЗ этот сценарий не описан.
  Рекомендую добавить обработку статуса PENDING.

Workflow

Типичный путь от сырого ТЗ к понятным следующим шагам.

1

Прогнать audit

Найти дыры, противоречия и места, где требование нельзя проверить.

hztz audit --file spec.md
2

Собрать вопросы через ask

Получить инженерные развилки с вариантами — и отправить автору ТЗ.

hztz ask --file spec.md --output questions.md
3

Разложить на задачи или уточнить в chat

decompose — в бэклог. chat — если документ большой и нужно допросить отдельные места.

hztz decompose --file spec.md --format markdown
hztz chat --file spec.md

Installation

Placeholder

Инструкции по установке пока не зафиксированы в документации проекта.

Здесь появится способ установки, когда он будет описан.

Documentation

Справка по командам, чату и конфигурации.

Команда Что делает
hztz audit Сканирует ТЗ на дыры, логические противоречия и белые пятна.
hztz ask Формирует конкретные технические развилки и вопросы с вариантами ответов для автора.
hztz decompose Превращает размытый текст в атомарные, готовые к оценке задачи (issues/tickets).
hztz chat Интерактивный допрос документной базы в терминале.

Внутри интерактивной сессии доступны:

Команда Описание
/summary Краткая выжимка ТЗ.
/risks Топ-3 самых опасных места.
/brainstorm Три альтернативные архитектуры для выбранного раздела.
/save Сохранить историю диалога в файл.

Чтобы не указывать ключи API и модель каждый раз — простой конфиг ~/.hzrc:

provider: openai
model: gpt-4o-mini
temperature: 0.2
system_prompt: "Ты — строгий, но конструктивный лид-разработчик и системный аналитик..."

Placeholder

Расширенная документация, ссылки на репозиторий и релизы — появятся здесь, когда будут доступны.

FAQ

Короткие ответы по тому, что уже описано в концепции и CLI.

Что такое hztz?

CLI-инструмент, который помогает разбираться с сырыми, размытыми или противоречивыми техническими заданиями с помощью LLM. Название от аббревиатуры «хз в тз».

Какие форматы ТЗ принимает инструмент?

Файл ТЗ в форматах markdown, txt или pdf.

Какие команды доступны?
  • hztz audit — сканирует ТЗ на дыры, противоречия и белые пятна.
  • hztz ask — формирует технические развилки и вопросы с вариантами ответов.
  • hztz decompose — превращает размытый текст в атомарные задачи.
  • hztz chat — интерактивный допрос документа в терминале.
Чем ask отличается от обычных «открытых вопросов»?

Вместо формулировок вроде «А как вы это видите?» инструмент генерирует инженерные развилки (trade-offs) с готовыми вариантами решений — чтобы автору ТЗ было из чего выбирать.

Кто такой «лейтенант Коломбо» в CLI?

Это голос и стиль взаимодействия инструмента. В hztz ask и hztz chat с вами общается Коломбо: вежливо, слегка неуклюже, но проницательно указывает на детали, которые «не сходятся» в ТЗ.

Где хранится конфигурация?

В простом конфиге ~/.hzrc — чтобы не указывать ключи API и модель каждый раз. Пример полей: provider, model, temperature, system_prompt.

Как установить hztz?

Placeholder

Инструкции по установке пока не зафиксированы в документации проекта.