forgeplan route

forgeplan route - это первая команда, которую вы запускаете для любой новой задачи. Принимая описание задачи на естественном языке, она возвращает глубину (Tactical / Standard / Deep / Critical), конвейер (какие артефакты создать, например, PRD → RFC или Epic → PRD[] → Spec[] → RFC[] → ADR[]), оценку уверенности и короткий список альтернатив на случай, если основное предложение покажется неподходящим.

Роутинг по умолчанию основан на правилах (Уровень 0 - быстрый, детерминированный, не требует LLM). Передайте --level 1, чтобы получить роутинг, классифицированный LLM, с объяснениями. Цель та же: не дать вам чрезмерно усложнять исправление, занимающее час, и не позволить пропустить PRD при рефакторинге, занимающем неделю.

Когда использовать

• Начиная любую новую задачу - баг, фичу, рефакторинг, обновление документации
• Принимая решение, нужен ли вам PRD, RFC, ADR или просто Note
• Сомневаясь в себе: «Это действительно Tactical? Может быть, Standard?»
• Онбординг - помогает новым участникам откалиброваться по методологии
• Предварительная проверка перед спринтом - роутинг каждой задачи, суммирование глубин, проверка пропускной способности

Когда НЕ использовать

• Задача уже имеет артефакт - используйте forgeplan calibrate <ID> для перероутинга вместо этого
• Вы находитесь в процессе реализации - роутинг является инструментом планирования, а не проверкой в процессе выполнения
• Для чистого хотфикса в main - вы всё равно пропускаете методологию
• Для коммитов по хозяйственным вопросам (обновление зависимостей, исправление линтинга) - просто коммит, без роутинга

Использование

forgeplan route [OPTIONS] <DESCRIPTION>

Аргументы

  <DESCRIPTION>  Описание задачи на естественном языке

Опции

      --explain        Использует LLM для объяснения решения о роутинге (устарело, используйте --level 1)
      --level <LEVEL>  Уровень роутинга: 0 = ключевые слова (по умолчанию), 1 = классификация LLM
  -h, --help           Вывести справку
  -V, --version        Вывести версию

Примеры

Пример 1: Быстрый роутинг на основе правил (по умолчанию)

forgeplan route "add rate limiting to API"

Вывод:

Depth:      Standard
Pipeline:   PRD → RFC
Confidence: 88%
Rationale:  new capability, multiple components, reversible within a sprint
Alternatives:
  - Deep (if rate limiter is cross-service)
  - Tactical (if single middleware with existing library)

Пример 2: Роутинг, классифицированный LLM, для тонких задач

forgeplan route --level 1 "refactor embedding pipeline to support BGE-M3"

Уровень 1 вызывает настроенный LLM (Gemini, GPT, Claude) для классификации задачи по эвристикам FPF. Медленнее (~2с), но лучше справляется с неоднозначными формулировками и сквозными проблемами, чем сопоставитель по ключевым словам.

Пример 3: Тривиальная задача - артефакт не требуется

forgeplan route "fix typo in README"

Вывод:

Depth:      Tactical
Pipeline:   (none - commit directly)
Confidence: 99%

Вы можете пропустить артефакт. Просто сделайте коммит.

Пример 4: Критическая задача - полный конвейер

forgeplan route "redesign artifact storage to use content-addressable hashing"

Вывод:

Depth:      Critical
Pipeline:   Epic → PRD[] → Spec[] → RFC[] → ADR[]
Confidence: 92%
Rationale:  irreversible, cross-cutting, affects all existing artifacts

Не сокращайте этот путь. Сначала создайте Epic.

Интерпретация вывода

• Глубина - один из четырёх уровней. Определяет гейты качества: Tactical = без гейтов, Standard = гейт верификации, Deep = состязательная ревью, Critical = ревью + ADR
• Конвейер - упорядоченный список артефактов для создания. Это руководство, а не контракт - вы можете объединять шаги, если это позволяет фаза проекта
• Уверенность - 0-100%. Ниже 70% означает, что описание неоднозначно; повторите запуск с большей детализацией или используйте --level 1
• Альтернативы - два или три других правдоподобных маршрута. Выберите один, если основной не соответствует вашей интуиции

Красные флаги:

• Уверенность < 50% - описание слишком расплывчато, добавьте контекст («компонент X», «для пользователя», «влияет на схему БД»)
• Маршрут говорит Tactical для того, что кажется недельной работой - добавьте детали о радиусе поражения
• Маршрут говорит Critical для однострочника - упростите описание

Память навыков роутинга (v0.17+, PRD-040)

Начиная с v0.17.0 (PRD-040, Scoring Intelligence) маршрутизатор ведёт память навыков роутинга - постоянно обновляемый журнал прошлых предсказаний глубины и их впоследствии наблюдаемой точности. Эта память затухает по 90-дневному экспоненциальному окну с 30-дневным периодом полураспада: правильное предсказание, сделанное вчера, несёт почти полный вес, правильное предсказание двухмесячной давности несёт примерно четверть своего веса, а всё, что старше 90 дней, фактически забывается.

Маршрутизатор использует эту память двумя способами:

1. Самокалибровка. Каждый раз, когда вы маршрутизируете задачу и затем активируете полученный артефакт, маршрутизатор узнаёт, насколько точной оказалась предсказанная глубина для вашего рабочего пространства. Со временем движок правил смещается в сторону глубин, которые исторически были правильными.
2. Автоматическая эскалация до Уровня 1. Если Уровень 0 (правила по ключевым словам) выдаёт глубину, для которой историческая уверенность упала ниже 60% для схожих форм задач, маршрутизатор автоматически эскалирует до Уровня 1 (классификатор LLM) вместо того, чтобы возвращать предположение с низкой уверенностью. Вы получаете лучший ответ, не вспоминая --level 1 самостоятельно.

Почему это важно

Роутинг субъективен, и эти мнения могут быть неверны для некоторых рабочих пространств. Команда, занимающаяся в основном инфраструктурной работой, получит иное распределение глубин, чем команда, занимающаяся в основном продуктовыми фичами. Память навыков роутинга позволяет маршрутизатору адаптироваться к фактическим паттернам принятия решений вашей команды вместо использования фиксированного набора правил, который в среднем верен, но ошибочен для вас.

Настройка не требуется - память начинается пустой в новом рабочем пространстве и автоматически накапливается каждый раз, когда вы forgeplan activate артефакт, который ранее был маршрутизирован. По состоянию на v0.18.0 ещё нет специального флага route --stats; память используется внутренне командой route и проявляется только через оценку уверенности и список альтернатив. Если вы хотите увидеть, влияет ли память на решение, запустите forgeplan route --level 1 и прочитайте обоснование LLM - оно ссылается на исторический сигнал, когда это уместно.

Как это вписывается в рабочий процесс

[route] → Shape → Validate → Reason → Code → Evidence → Activate
  ^
вы здесь

• До: просмотр задачи в TODO.md или системе отслеживания ошибок
• После: forgeplan new prd|rfc|note на основе предложенного конвейера
• Для Deep/Critical, продолжите с forgeplan reason (ADI обязательно)

См. также

• forgeplan new - создать артефакт, предложенный маршрутом
• forgeplan reason - требуется для глубины Deep/Critical
• forgeplan calibrate - перероутинг существующего артефакта
• forgeplan health - проверка начала сессии
• Методология: калибровка глубины