🔸 У документации в команде вечная боль: она либо догоняет код (и через месяц уже устарела), либо опережает (и тогда столько утверждений и подписей, что лучше бы её не было). С AI-агентами эта боль становится острой: агент читает устаревшую инструкцию и уверенно делает не то.
🔸 Единственный способ это убить - не вести документацию отдельно. Пусть инструмент сам печатает её в момент работы а не отдельный человек поддерживает в стороне.
🔸 В ForgePlan каждая команда и каждый инструмент API (через который агенты вроде Claude Code общаются с программой) в своём ответе пишут ровно один маркер на следующий шаг. Пять штук покрывают весь рабочий цикл:
Next: основное действие, можно запускать как есть
Or: альтернативный путь
Wait: нужно подождать условие и попробовать снова
Done. всё, можно останавливаться
Fix: что делать, если случилась ошибка
🔸 В версии 0.25 такие подсказки были у 36% команд. После отдельного спринта выверки - у 100%. Каждая команда. Каждый инструмент API. Тесты следят, чтобы маркер не пропал в новой версии незаметно.
🔸 Что это даёт - документация рождается ровно в момент выполнения. Не отдельный файл, который кто-то забывает обновить. Строка вывода, которую печатает сам инструмент. Разойтись с кодом она физически не может - потому что она и есть код.
🔸 Побочный эффект, который я не планировал: введение в курс дела новых агентов стало тривиальным. Раньше - длинные инструкции в правилах проекта: «после
new сделай validate, потом reason, потом …». Сейчас - запускай команду, читай Next:. Раздел в правилах сократился с ~50 строк до ~10. Часть знания переехала из инструкций в строки вывода - и стала заметно надёжнее.🔹 https://github.com/ForgePlan/forgeplan
#forgeplan #ai