Обзор методологии

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

Каждая инженерная команда накапливает невидимый долг - не в коде, а в решениях. Вы выбираете базу данных, стратегию аутентификации, проектируете поверхность API. Шесть месяцев спустя кто-то спрашивает: «Почему мы сделали это так?», и никто не помнит. Ветка в Slack потеряна. Google Doc просрочен. Человек, принявший решение, уволился из компании.

Это не проблема документации. Это проблема потери знаний. И она усугубляется: команды повторяют одни и те же ошибки, вновь обсуждают одни и те же вопросы и строят на предположениях, которые никто не может проверить.

Forgeplan существует, чтобы сделать решения отслеживаемыми, проверяемыми и долговечными.

Проблема

Решения разбросаны по веткам Slack, Google Docs и чьей-то памяти. PRD, которые никто не читает. RFC без последующих действий. Архитектурные решения, принятые интуитивно.

Forgeplan заставляет вас думать перед кодированием. Вместо «открыть IDE -> написать код -> развернуть» вы получаете:

Route -> Shape -> Validate -> Reason -> Build -> Prove -> Activate

Рассмотрим реальный сценарий: ваша команда решает использовать JWT для аутентификации. Шесть месяцев спустя аудит безопасности спрашивает, почему вы выбрали JWT вместо аутентификации на основе сессий. С Forgeplan, ADR объясняет обоснование, Evidence показывает результаты бенчмарков, а PRD отслеживает исходные требования. Без Forgeplan вы роетесь в истории Slack и надеетесь, что кто-то вспомнит.

Чем Forgeplan НЕ является

Не Jira. Не инструмент управления проектами.
Не трекер задач. Не для ежедневных стендапов.
Не генератор кода. ИИ помогает, вы решаете.

Forgeplan - это структурированная база знаний для инженерных решений - local-first, git-native, single binary. Думайте о нём как о лабораторном журнале для инженерии: вы записываете, что вы пробовали, почему и каковы были результаты.

Основные принципы

1. Конвейер - это руководство, а не бюрократия

Не создавайте все 10 типов артефактов для каждой задачи. Тактическая глубина = только код. Глубокая глубина = полный конвейер. Если ответ очевиден и обратим, пропустите бумажную работу. Исправление ошибки в одной строке не требует PRD.

2. Каждое требование: “[Действующее лицо] может [возможность]”

Никакой утечки реализации в PRD. Описывайте ЧТО, а не КАК. Пишите «Пользователь может сохранять и запрашивать структурированные данные с гарантиями ACID» - а не «Использовать PostgreSQL для хранения». В тот момент, когда вы называете технологию в требовании, вы отсекаете альтернативы до их оценки.

3. Дочерний артефакт ссылается на родительский

PRD -> Epic, RFC -> PRD, ADR -> RFC. Всегда отслеживается вверх. Это означает, что если вы читаете какой-либо артефакт, вы можете следовать по ссылкам вверх, чтобы понять полный контекст его существования.

4. Замещайте, не удаляйте

Старые артефакты получают status: superseded. История сохраняется. Когда ваша команда спрашивает: «Разве мы не пробовали этот подход раньше?», замещённый артефакт показывает, что было опробовано, почему от этого отказались и что его заменило.

5. R_eff = min(доказательство)

Доверие - это слабое звено. Не среднее - минимум. Одно слепое пятно тянет всё вниз. Если у вас есть три надёжных бенчмарка и одно совершенно непроверенное предположение о производственной нагрузке, надёжность вашего решения равна этому непроверенному предположению.

Полный цикл

1. Route:    forgeplan route "your task" -> determines depth
2. Shape:    forgeplan new prd "Title" -> create artifact
3. Validate: forgeplan validate PRD-XXX -> quality gates
4. Reason:   forgeplan reason PRD-XXX -> ADI hypotheses (Standard+)
5. Build:    write code, test every pub fn
6. Prove:    forgeplan new evidence -> link -> score
7. Activate: forgeplan activate PRD-XXX

Работа не считается завершённой, пока: PRD не заполнен + не валидирован + не создано доказательство + R_eff > 0 + не активирован.

Распространённые ошибки

Создание артефактов для всего. Изменение цвета кнопки не требует PRD. Используйте forgeplan route, чтобы определить правильный уровень строгости - большинство задач являются Тактическими и не требуют документации.
Оставление заготовок PRD. Создание пустого PRD и переход к коду означает, что у вас теперь есть заготовка, которая засоряет состояние вашего проекта. Либо заполните его немедленно, либо не создавайте.
Активация без доказательств. Активный PRD без кода, без тестов и с R_eff = 0 - это ложное обещание. Он сообщает любому, кто читает ваш проект, что это решение валидировано, хотя это не так.
Пропуск ADI для глубоких решений. Если роутер указывает на глубокое решение, а вы сразу переходите к коду, вы ставите на свою первую идею, не проверив альтернативы. ADI занимает 10 минут; неправильная архитектура требует недель для исправления.
Отношение к конвейеру как к чек-листу. Конвейер - это инструмент мышления. Механическое выполнение действий (создать PRD, отметить; создать RFC, отметить) без фактического осмысления каждого шага сводит на нет цель.

10 типов артефактов

Тип	На какой вопрос отвечает	Когда использовать
PRD	Что и почему?	Планирование функций
RFC	Как построить?	Предложение архитектуры
ADR	Почему именно так?	Запись решения
Epic	Какова общая картина?	Инициатива, охватывающая несколько PRD
Spec	Каков контракт?	Модели API/данных
Problem	Каков сигнал?	Ошибка, риск, наблюдение
Evidence	Работает ли?	Результаты тестов, бенчмарки
Solution	Какой вариант?	Сравнение 2-3 вариантов
Note	Быстрое решение	Микро-решение (TTL 90 дней)
Refresh	Ещё актуально?	Переоценка просроченного артефакта

На практике большинство команд регулярно используют 5-6 типов: PRD, RFC, ADR, Evidence, Problem и Epic. Остальные (Note, Solution, Spec, Refresh) ситуативны. Не чувствуйте себя обязанными использовать все 10.

Когда НЕ следует создавать артефакт

Не каждая задача заслуживает структурирования. Вот краткое руководство:

Исправление ошибки в одном файле - просто исправьте. Возможно, Note, если первопричина была неожиданной.
Очевидный рефакторинг - без изменения поведения, артефакт не нужен.
Настройка внутреннего инструментария - если его используете только вы и он легко обратим, пропустите.
Всё, где ответ очевиден - не документируйте то, что не требует объяснений.

Лакмусовая бумажка: «Спросит ли кто-нибудь (включая меня в будущем), почему было принято это решение?» Если да, создайте артефакт. Если нет, просто выпускайте.

10 правил (краткий обзор)

Остальная часть методологии раскрывает десять правил. У каждого есть свой документ - этот список является оглавлением.

Роутинг перед кодированием - Роутинг и глубина
Shape → Validate → ADI → Code → Evidence → Activate - полный цикл, а не чек-лист
[Действующее лицо] может [возможность] - никакой утечки реализации в функциональных требованиях PRD
Дочерний артефакт ссылается на родительский - PRD→Epic, RFC→PRD, ADR→RFC
Замещайте, не удаляйте - Жизненный цикл
Гейты качества по глубине - Тактическая = ничего, Стандартная = Гейт верификации, Глубокая+ = Состязательная ревью
Начало сессии: health + восстановление из памяти - сначала исправьте сирот и слепые пятна
Работа не считается завершённой, пока R_eff > 0 + не активирован - Доказательство и оценка R_eff
ADI обязателен для Глубоких+ решений - Обоснование ADI
Просроченный = перевалидировать, не игнорировать - установите valid_until для каждого ADR

Инструментарий

В агентах ИИ-кодирования вся эта методология упакована как навык /forge. Установите его с помощью forgeplan setup-skill (офлайн, встроен в бинарный файл) или установите полный плагин forgeplan-workflow через /plugin install forgeplan-workflow@ForgePlan-marketplace. Навык объединяет route -> new -> validate -> reason -> activate в одну разговорную команду.

Дополнительные плагины предоставляют аудит кода (/audit), планирование спринтов (/sprint), обоснование FPF (/fpf) и многое другое. Полный каталог плагинов: Обзор Marketplace.

Следующие шаги

Быстрый старт - первый артефакт за 10 минут
Руководство по первому артефакту - практическое пошаговое руководство за 20 минут
Роутинг и глубина - как выбрать правильный уровень
Жизненный цикл артефакта - черновик → активный → завершённый
Доказательство и оценка R_eff - как измеряется доверие
Обоснование ADI - структурированное мышление перед созданием
Справочник CLI - каждая команда документирована
Руководство по фреймворку FPF - основа для обоснования