Привет, Хабр! Меня зовут Максим, и я хочу рассказать историю о том, как простая боль при работе с ИИ-ассистентами превратилась в open-source проект, который, надеюсь, пригодится и вам.
Предыстория: когда всё началось
Последний год я активно использую локальные ИИ-агенты для работы над проектами. Не просто «напиши функцию», а полноценная декомпозиция задач: разбиваю большой проект на модули, модули на задачи, задачи на подзадачи. Через час работы у меня красивая иерархия из 50+ пунктов.
И вот тут начинается веселье.
Боль №1: «Добавь подпункт к 3.2.1»
Пишу в чат:
— Добавь подпункт к 3.2.1
А ИИ добавляет к 3.2. Или к 3.1. Или вообще создаёт новый раздел 4. Потому что контекст переполнен, и модель уже не помнит точную структуру.
Боль №2: «Перепиши раздел 4»
Прошу переписать один раздел, а ИИ заодно «улучшает» разделы 3 и 5. Которые я уже согласовал с заказчиком. Которые были идеальны.
Боль №3: «Верни как было»
— Верни структуру как было 20 сообщений назад
ИИ начинает галлюцинировать «как было», потому что не помнит. И приходилось вручную откатывать изменения, перечитывая историю чата и восстанавливая структуру по памяти.
Боль №4: Хрупкие ссылки
Переместил пункт 2.3 в раздел 5. Теперь он 5.4. А все ссылки «см. пункт 2.3» в других местах — битые. И ИИ про них не знает.
Первые попытки решения
Сначала я просто копировал структуру в отдельный .txt файл. После каждого изменения — копировал заново. Это работало... примерно неделю.
Потом я начал делать версии: plan_v1.txt, plan_v2.txt, plan_v3_final.txt, plan_v3_final_FINAL.txt. Знакомо, да?
Потом я попробовал Notion, Obsidian, даже Excel. Но проблема оставалась: ИИ не знает, что можно менять, а что нельзя трогать.
Момент озарения
Однажды я работал над большим проектом с автономным агентом. Агент должен был выполнять задачи по плану. И я понял, что мне нужно:
Стабильные идентификаторы — чтобы ссылка на задачу не ломалась при перемещении
Защита от изменений — чтобы утверждённые разделы нельзя было случайно изменить
История изменений — чтобы можно было откатиться
Простой интерфейс — чтобы и я, и ИИ могли работать с этим
Так родился HBT — Hierarchical Block Text.
Что такое HBT
HBT — это CLI-инструмент для управления иерархическими задачами. Один Python-файл, никаких зависимостей, работает везде где есть Python 3.8+.
Ключевые идеи:
UUID вместо позиционных номеров
Каждый узел получает уникальный 12-символьный ID:
└── a1b2c3d4 ⚪ Разработка API ✍️ ├── b2c3d4e5 ⚪ Аутентификация ✍️ └── c3d4e5f6 ⚪ База данных ✍️
Переместил «Аутентификацию» в другой раздел? ID остался b2c3d4e5. Все ссылки работают.
Статус locked/editable
Утвердили структуру раздела? Блокируем:
hbt status --id b2c3d4e5 --mode locked
Теперь этот узел нельзя изменить или удалить. Даже случайно. Даже если очень хочется.
└── b2c3d4e5 ⚪ Аутентификация ? # Заблокировано!
Алиасы для удобства
Вместо b2c3d4e5 можно использовать человекочитаемое имя:
hbt alias --id b2c3d4e5 --name auth
Теперь можно писать @auth вместо ID:
hbt view --id @auth hbt add --to @auth --text "JWT токены"
Автоматические снапшоты
Каждое изменение сохраняется. Накосячили? Откат в одну команду:
hbt rollback --list # Посмотреть доступные точки hbt rollback --restore auto_20240218_100000.json # Восстановить
Как это выглядит на практике
Создаём структуру проекта
# Корневая задача hbt add --text "Мой крутой проект" --alias project --locked # Основные разделы hbt add --to @project --text "Backend" --alias api hbt add --to @project --text "Frontend" --alias fe hbt add --to @project --text "DevOps" --alias devops # Детализация hbt add --to @api --text "REST API" hbt add --to @api --text "База данных" hbt add --to @api --text "Авторизация" --alias auth
Смотрим что получилось
hbt view
└── a1b2c3d4 @project ⚪ Мой крутой проект ? ├── b2c3d4e5 @api ⚪ Backend ✍️ │ ├── c3d4e5f6 ⚪ REST API ✍️ │ ├── d4e5f6a7 ⚪ База данных ✍️ │ └── e5f6a7b8 @auth ⚪ Авторизация ✍️ ├── f6a7b8c9 @fe ⚪ Frontend ✍️ └── a7b8c9d0 @devops ⚪ DevOps ✍️
Быстро наполняем раздел
hbt rewrite --id @auth "JWT токены" "OAuth Google" "Refresh tokens" "Rate limiting"
Одной командой создали 4 подпункта.
Блокируем утверждённое
hbt status --id @api --mode locked --recursive
Теперь весь Backend заблокирован. Никто (включая вас в 3 часа ночи) не сможет случайно его сломать.
Отслеживаем прогресс
hbt set-progress --id @auth --state doing # Начали работу hbt set-progress --id @auth --state done # Закончили
└── e5f6a7b8 @auth ? Авторизация ? # Зелёный = done
Находим следующую задачу
hbt next
? Следующая задача: c3d4e5f6 — REST API [todo]
Идеально для автономных агентов: получил задачу → выполнил → отметил done → получил следующую.
Интеграция с ИИ-инструментами
Экспорт контекста для ИИ
Экспортируем структуру и передаём агенту:
hbt export context.txt cat context.txt
Теперь агент видит актуальную структуру и может ссылаться на узлы по ID или alias.
С Aider
# В сессии Aider /run hbt view --raw /run hbt next
С автономными агентами
Агент выполняет простой цикл:
1. hbt next → получить задачу 2. выполнить задачу 3. hbt set-progress → отметить done 4. goto 1
Что под капотом
Один файл
hbt.py— никаких зависимостей, только стандартная библиотека PythonJSON-хранилище
tasks.json— человекочитаемый формат, можно редактировать рукамиАтомарные операции — запись через временный файл, данные не потеряются при сбое
62 теста — всё покрыто, можно доверять
Какие боли закрывает HBT
Проблема |
Решение |
|---|---|
ИИ путает вложенность |
UUID-адресация — ID не меняется при перемещении |
Случайные изменения утверждённого |
Статус |
Нет истории |
Автоматические снапшоты каждого изменения |
Битые ссылки |
Алиасы |
Потеря контекста |
Экспорт актуальной структуры для нового чата |
Агент теряет фокус |
Команда |
Почему я решил поделиться
Инструмент решает мою конкретную боль. Но я уверен, что не один такой. Если вы:
Работаете с ИИ над сложными проектами
Устали от того, что структура «плывёт»
Хотите защитить утверждённые разделы от случайных изменений
Используете автономных агентов и нужен чёткий план
...то HBT может вам пригодиться.
Проект полностью open-source под лицензией CC BY 4.0. Используйте, форкайте, улучшайте.
Ссылки
Документация: в README.md репозитория
Буду рад обратной связи в комментариях. Если есть идеи по улучшению — welcome в Issues на GitHub.
Спасибо за внимание! ?
Комментарии (22)
zlib
20.03.2026 19:44Как вам кажется, HBT нужен в первую очередь слабым/локальным LLM, или даже топовые модели без stable IDs и locked-блоков всё равно будут регулярно плыть на длинных иерархиях?
DanielLetto2025 Автор
20.03.2026 19:44Для локальных агентов идеально. Например собираешь рой из qwen3.5-4b или qwen3.5-9b используя CrewAI и внедряешь HBT тогда мега контекст уже не нужен, если задачи декомпозированы и прописаны качественно и понятно, тогда локальная модель будет идеально справляться и показывать результат. Для больших моделей - тоже хорошо использовать, даже тот же gemini* с контекстом 1млн токенов плывет...
DanielLetto2025 Автор
20.03.2026 19:44В любом случае HBT это просто mvp-идея и ее можно развивать дальше наращивая функционал.
denisgrigoriev04
20.03.2026 19:44-- Потом я начал делать версии:
plan_v1.txt,plan_v2.txt,plan_v3_final.txt,plan_v3_final_FINAL.txt. Знакомо, да?-- git существует
DanielLetto2025 Автор
20.03.2026 19:44Вы абсолютно правы, без гита нет проекта. Но уверен что вы так же делаете периодический с файлами или с названиями веток или проектов - только никому не говорите :)
RranAmaru
20.03.2026 19:44git tag
а плодить файлы ...v1, ...v2 - верный способ в них запутаться.
Хотя, если у вас весь проект в одном файле, то можно и так, конечно. )))
DanielLetto2025 Автор
20.03.2026 19:44да, текущий проект в одном файле и без зависимостей, чем плохо то?)
И что вы прицепились к файлам с версиями как будто не делали так же?!)
Прям всегда идеально и по правилам у вас в проекте?
Очень большое кол-во проектов видел за 8 лет, идеальных проектов нет:)
alexanderniki
20.03.2026 19:44вы так же делаете [...] только никому не говорите
Очень редко и в очень ограниченном объеме. И практически никогда, если понимаю, что мне самому в будущем нужно будет пользоваться результатами своего труда :)
Для каких-то прям ситуативных мелких задач предпочитаю оставлять в названии временные метки типа "plan_yyyymmdd-hhmm.txt"
DanielLetto2025 Автор
20.03.2026 19:44ну в целом порешали :) Спасибо что уделили время на прочтение статьи! я рад что заинтересовала.
Conung_ViC
20.03.2026 19:44а мы по прежнему просто доверяем тому, что если агент прочитал "вот тот файл редактировать низя", то он ну точно-точно его редактировать не будет?
и история с емейлами у безопасницы - эт просто так получилось?
Olegun
20.03.2026 19:44Хорошо, что в интернете ещё не придумали ссылки. Так бы многие смогли бы понять вашу фразу про емейлы у безопасницы.
DanielLetto2025 Автор
20.03.2026 19:44не, ну конечно если давать ИИ полный доступ к tasks.json через простую файловую систему, он его рано или поздно перепишет. Но архитектурно HBT идеально ложится в MCP. Я же говорил что это MVP идея и этот инструмент прокачивается :)
Вот придумываешь идею, пишешь первую статью, а люди воспринимают просто как за готовый продукт и даже не пытаются придумать как это применять, а ссылаются косвенно на отсутствие безопасности или бесполезность... жаль.
Conung_ViC
20.03.2026 19:44Извините. Просто мне казалось, что я эту историю тут на хабре и читал.
но на всякий пожарный - вот что я имел ввиду
ИИ-агент удалил почту директора по безопасности ИИ в Meta* — Runet
ИИ-агент OpenClaw случайно удалил почту сотрудницы безопасности Meta
TimsTims
20.03.2026 19:44А почему бы не улучшить этот hbt, и в локальном агенте не прописать mcp до него + правила что вся работа с задачами (создать, взять, изменить) через этот mcp?
Человеку не придется каждую задачу заводить и менеджерить, все будет ИИ агент сам делать.
diffnotes-tech
20.03.2026 19:44Боль №2 из статьи (агент "улучшает" разделы которые не просили) решается не через locked в JSON, а через системный промпт агента. CLAUDE.md, .cursorrules, copilot-instructions.md - файлы которые агент читает при каждом запросе. Пишешь "не трогай раздел X без явного запроса" - агент слушается. locked в tasks.json агент может просто проигнорировать или перезаписать файл, Conung_ViC выше правильно заметил
Tassdesu
20.03.2026 19:44Мы похоже вошли в эру, когда каждый напишет себе свой инструмент для каждой своей задачи. Нет смысла разбираться в чём-то готовом, когда можно с ИИ написать своё и ровно то, что тебе надо. Да ещё и почувствовать, что ты сопричастен к этому.
Жаль, правда, делиться смысла нет, так как есть миллион похожих но других решений... Но самому, и правда, удобно и приятно.
Кстати, а что за модель не могла нормально пункты вставить в текстовый файл? Это на Aider было?
DanielLetto2025 Автор
20.03.2026 19:44то что "...каждый напишет себе свой инструмент" - а почему бы и нет если есть такая возможность которая закрывает личные потребности
"Нет смысла разбираться в чем то готовом" - ну если было бы так, тогда и ИИ писали бы с нуля каждый... верно?
"...Делиться смысла нет..." - я не прошу делиться, просто написал статью, как свою идею и все, я не говорил что это нереально крутая штука и все обязательно к установке. Просто может кому то нужно и все.
"Да ещё и почувствовать, что ты сопричастен к этому" - обязательно, т.к. ии просто кодер без идей, сама идея заложена в код. К сожалению с такими инструментами как ии и агенты многие даже прогеры не способны написать что то стоящее, что говорить про обычных людей не связанных с IT? Вывод, что мы просто перешли на новый абстрактный слой - идея/креатив/контроль реализации, разве не так?
-
"стати, а что за модель не могла нормально пункты вставить в текстовый файл" - да, аидер с моделью gemini 3 flash pro - т.к. более 40 пунктов он не выдерживает корректно на отрезке в неделю... каждый раз новый контекст, новые попытки поменять , он лезет в другие пункты, например qwen code cli лучше контролирует подобные вещи как изменение отдельных частей пунктов, но и тут глюки случаются можно потерять часть пунктов если не уследишь .... тут уже без git смысла нет редачить А HBT - это попытка закрыть данную проблему.
Идея HBT - некий git внутри одного файла, а не для файла в целом как сущности.
Спасибо что нашли время и прочитали статью!
Но я считаю что случаи и варианты кейсов очень много, если вам не пригодится, то можно просто прочитать и забыть.
Tassdesu
20.03.2026 19:44Если бы ИИ было также просто написать, как обычный код, но, наверное, да.
А вообще, я не то чтобы критиковал вашу статью. Просто высказал мысли в слух. Было любопытно почитать, пишите ещё.
RustTech
Вы молодец и ваш ИИ-агент тоже. Но уже есть backlog.md, agent.mail и ACML. Жгите токен-лимиты на то, что ещё не написано.
DanielLetto2025 Автор
Просто предложил идею, которую можно развивать дальше. А md файл не совсем то что нужно, только больше для заметок или стартового контекста.
IgorStepin
backlog.md — это приложение, просто название странное
RustTech
backlog.md это приложение для локального ведения задач. Написан специально для общения ии агентов и людей. Есть mcp для популярных моделей. Введите backlog.md как адрес в браузере, перейдете на gihub и описание.