forgeplan export

forgeplan export сериализует всё рабочее пространство - артефакты, связи, записи доказательств, состояние скоринга и метаданные - в один JSON-файл. Это обязательный шаг резервного копирования перед любой деструктивной операцией над .forgeplan/ и единственный способ создать восстанавливаемый снимок, который фиксирует состояние, выходящее за рамки отслеживаемого markdown.

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

Всегда перед rm -rf .forgeplan, forgeplan init --force или любой другой деструктивной операцией с рабочим пространством. Без исключений.
Перед обновлением бинарного файла Forgeplan, в качестве подстраховки на случай сбоя forgeplan migrate.
Периодически в качестве резервной копии для аварийного восстановления, особенно перед крупными реструктуризациями методологии.
При перемещении рабочего пространства между машинами, когда требуется полное состояние (скоринг, устаревание доказательств), а не только markdown.
Для отладки - для обмена снимком рабочего пространства с коллегами или прикрепления его к задаче.

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

В качестве цели для ежедневного git-коммита - отслеживаемый markdown в .forgeplan/{adrs,prds,rfcs,...} уже является каноническим источником истины (ADR-003). Экспорт предназначен для состояния, хранящегося в LanceDB.
Для публикации или обмена с инструментами, отличными от Forgeplan, - схема JSON является внутренней и нестабильной между версиями.
В качестве замены git - это не инструмент истории версий, а лишь снимок состояния на определённый момент времени.

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

forgeplan export [OPTIONS]

Опции

  -o, --output <OUTPUT>  Путь к выходному файлу (по умолчанию: .forgeplan/export.json)
  -h, --help             Вывести справку
  -V, --version          Вывести версию

Примеры

Пример 1: Резервное копирование по умолчанию

forgeplan export

Записывает в .forgeplan/export.json. Удобно, но находится внутри той же папки, которую вы, возможно, собираетесь удалить - для реальных резервных копий предпочтительнее указывать явный внешний путь.

Пример 2: Резервное копирование перед повторной инициализацией

forgeplan export --output ~/backups/forgeplan-$(date +%Y%m%d-%H%M).json
cp -r .forgeplan .forgeplan-backup-$(date +%Y%m%d)
rm -rf .forgeplan
forgeplan init -y
forgeplan import ~/backups/forgeplan-*.json

Полный ритуал “безопасной повторной инициализации”. Экспорт сохраняется вне .forgeplan/, а копия всей папки на файловой системе обеспечивает дополнительную подстраховку.

Пример 3: Снимок перед обновлением

forgeplan export --output pre-v0.18-upgrade.json
cargo install forgeplan
forgeplan migrate
forgeplan health
# if anything looks wrong:
rm -rf .forgeplan && forgeplan init -y
forgeplan import pre-v0.18-upgrade.json

Недорогая страховка перед обновлением версии.

Пример 4: Обмен состоянием рабочего пространства с коллегой

forgeplan export --output snapshot.json
gh gist create snapshot.json   # or attach to an issue

Предоставляет коллеге всё необходимое для воспроизведения скоринга, вывода состояния здоровья и состояния устаревания - один только markdown не может этого сделать.

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

export - это операция безопасности, не являющаяся частью жизненного цикла артефакта. Это должно быть доведено до автоматизма перед любым из следующих действий:

rm -rf .forgeplan
forgeplan init --force
forgeplan migrate в значимом рабочем пространстве
Обновление бинарного файла до новой основной версии
Экспериментальные массовые изменения markdown

Правило простое: если вы собираетесь изменить рабочее пространство таким образом, что это нельзя отменить с помощью git, сначала выполните экспорт.

Примечания по безопасности

Путь по умолчанию находится внутри .forgeplan/. forgeplan export без аргументов записывает в .forgeplan/export.json, который будет потерян, если вы затем выполните rm -rf .forgeplan. Всегда передавайте -o с путём вне рабочего пространства для реальных резервных копий.
Экспортированные данные не шифруются. Они могут содержать подсказки LLM, внутренние заметки и другой конфиденциальный контент. Не коммитьте их в публичные репозитории.
Экспорт + копирование файловой системы - золотой стандарт. forgeplan export -o backup.json && cp -r .forgeplan .forgeplan-backup-$(date +%Y%m%d) даёт вам как структурированный путь восстановления, так и необработанный побитовый снимок.
config.yaml НЕ включается в экспорт. Настройки ключа API LLM находятся в .forgeplan/config.yaml и должны быть скопированы отдельно.
Экспортированные данные привязаны к версии бинарного файла. Резервная копия, сделанная в v0.17, может потребовать запуска forgeplan migrate после импорта в v0.18.

См. также

forgeplan import - соответствующая операция восстановления
forgeplan init - деструктивный шаг, которому обычно предшествует экспорт
forgeplan migrate - неразрушающее обновление схемы (всё равно сначала сделайте резервную копию)
forgeplan scan-import - перестроение индекса из отслеживаемого markdown
forgeplan health - проверка рабочего пространства до и после циклов резервного копирования