Цикл одного проекта · теория

Forgeplan как operational layer

Forgeplan - CLI плюс MCP-сервер, который стоит рядом с репо и забирает на себя механическую часть, оставляя вам только содержательные решения.

01 · Operational layer

POS для методологий

CLI + .forgeplan/ + MCP-сервер

→

02 · Artifacts + DAG

10 типов · 6 в ходу

PRD · RFC · ADR · Spec · Epic · Evidence

→

03 · Depth + Gates

4 уровня глубины

tac · std · deep · crit

01 · Forgeplan как operational layer

Концепция 01 · аналогия POS-терминала

Официант выбирает блюдо. Терминал помнит цены, НДС, дисконты, бонусы

Когда в ресторане официант принимает заказ, он не держит в голове прайс, состав блюд, НДС, дисконтные карты и бонусы. Он нажимает кнопки в POS-терминале, а терминал помнит всё. Роль официанта - выбрать блюдо. Роль терминала - правильно оформить.

Forgeplan - это POS для методологий. Конкретно - CLI плюс MCP-сервер, который встаёт рядом с репо и берёт на себя механическую часть FPF, BMAD, OpenSpec и QuintCode. Вы решаете, какую фичу строить. Forgeplan помнит, какие секции требует BMAD PRD, какой формат ожидает OpenSpec от delta, какую структуру имеет ADR с FPF reasoning, какие оси R_eff проставить на evidence.

В голове · до

Что приходится помнить руками

13 секций PRD из BMAD
Формат delta-spec ADDED / MODIFIED / REMOVED
Где лежат ADR и какой шаблон у frontmatter
F-G-R для каждого evidence из QuintCode
3 гипотезы из FPF на каждое серьёзное решение
Какой артефакт «выше» какого в DAG

одна методология в голове · реально

В инструменте · после

Что забирает Forgeplan

forgeplan new prd · уже с 13 секциями BMAD
forgeplan validate · OpenSpec consistency автоматом
.forgeplan/ · одна папка, индекс, шаблоны
forgeplan score · F-G-R посчитан, R_eff = min
forgeplan reason · ADI требует 3 гипотезы
forgeplan graph · DAG картинкой за 5 минут

четыре методологии в инструменте · работает

В репо появляется папка .forgeplan/ с шаблонами, индексом артефактов и графом связей. Через CLI создаёте новый артефакт:

      Терминал · создание ADR
$ forgeplan init
✓ .forgeplan/ created · templates · index · graph

$ forgeplan new adr "Vault architecture: Express + SQLite + Ollama + Anthropic"
✓ ADR-001 created with FPF reasoning skeleton
  → 3 hypothesis slots (Abduction)
  → Evidence section with F-G-R rubric
  → Decay triggers section
  → Frontmatter: depth=deep, related_artifacts=[]
Next: forgeplan reason ADR-001
    

Файл создаётся с готовой структурой: frontmatter с depth и related_artifacts, секция «Рассмотренные гипотезы» (минимум три, как требует FPF), секция «Evidence» (с F-G-R, как требует QuintCode), секция «Условия пересмотра» (как требует Evidence Decay). Остаётся заполнить по существу - не помнить, какие секции должны быть.

Вторая половина - MCP-сервер. После подключения Forgeplan в .mcp.json агент (Claude Code, Cursor, Windsurf) видит ваши артефакты. Когда вы пишете «добавь логирование в auth-сервис», агент сам подтягивает релевантный PRD и ADR и не противоречит принятым решениям. Это не «ещё одна папка с документами» - это память проекта, которую агент читает сам.

Дисциплина переходит из головы в инструмент

Одну методологию в голове удержать реально. Четыре - нет. CLI удерживает все четыре и напоминает о пропусках, пока вы решаете, что вообще строить. Это и есть смысл слова «интегратор» - не «новая методология сверху», а «общий слой под старыми».

02 · Типология артефактов и DAG зависимостей

Концепция 02 · типология артефактов

Шесть типов в активном ходу. Связи - через frontmatter, не через память

В типичной команде requirements живут в Jira, дизайн-решения в Confluence, ADR в docs/, evidence - в PR-комментариях и бенчмарках на Google Drive. Связи - в голове автора. Автор уходит, связи теряются. Через год никто не помнит, почему выбрали gRPC вместо REST.

Forgeplan сводит это в один файловый репозиторий с шестью основными типами артефактов (плюс четыре ситуативных - см. таблицу ниже):

PRD

prefix · prd-

Что? Что строим и для кого

Продуктовые требования. Выход фазы Delivery в BMAD. Каждое FR в формате «[Actor] can [capability]», без implementation leakage.

RFC

prefix · rfc-

Как? Как это можно сделать

Предложение изменения с альтернативами. «Рассматриваем переход с REST на gRPC, вот три варианта». Открытое обсуждение, не финальное решение.

ADR

prefix · adr-

Почему? Почему именно так

Принятое архитектурное решение. Immutable после активации. Ссылается на RFC и Evidence. Меняется только через supersede.

Spec

prefix · spec-

Контракт? Как ведёт себя система

API-контракты и data models. OpenSpec-формат с ADDED / MODIFIED / REMOVED для delta. См. spec-cycle.html для деталей.

Epic

prefix · epic-

Связка? Что общего у группы PRD

Объединяет несколько PRD вокруг крупной цели. Используется в Critical-depth, когда фича не помещается в один PRD.

Evidence

prefix · evid-

Работает? Какие данные подтверждают

Бенчмарк, скриншот мониторинга, цитата документации, A/B-тест. С F-G-R из QuintCode. Считается в R_eff = min(scores).

Каждый артефакт ссылается на другие через frontmatter - это и есть DAG:

      .forgeplan/adrs/adr-001-vault-architecture.md · frontmatter
---
id: adr-001
type: adr
title: "Vault architecture: Express + SQLite + Ollama"
depth: deep
status: activated
related_artifacts:
  - prd-001       # откуда требование
  - rfc-001       # откуда обсуждение
  - evidence-001  # бенч p99 latency
valid_until: 2026-12-01
---
    

DAG · типичная цепочка от намерения к доказательствам

намерение

EPIC-001 ↓ PRD-001 streaming-эндпойнт, p50 первого токена ≤ 800 мс

обсуждение

RFC-001 SSE vs WebSockets vs HTTP/2 push

решение

ADR-001 общая архитектура Vault · immutable

контракт

SPEC-001 GET /query/stream поведение и invariants

доказательство

↑ EVID-001 бенчмарк SSE vs WS · F=7 G=6 R=8 · informs ADR-001

Через полгода - одна команда вместо археологии

Новый член команды открывает forgeplan graph --format mermaid и видит DAG одной картинкой. За пять минут понимает, откуда что взялось. Не «тогда казалось логичным» - явная цепочка от требования до evidence. Это превращает мнения в трейсируемые артефакты: у каждого есть источник, альтернативы и данные.

Полная таксономия · 10 типов

Тип	Prefix	Назначение	Использование
PRD	`prd-`	Продуктовые требования	core
RFC	`rfc-`	Архитектурное предложение	core
ADR	`adr-`	Принятое решение · immutable	core
Spec	`spec-`	API-контракты, поведение	core
Epic	`epic-`	Группа PRD вокруг цели	core
Evidence	`evid-`	Бенчмарк, тест, замер	core
Problem	`prob-`	Сигнал с контекстом · баг / риск	ситуативно
Solution	`sol-`	Сравнение 2-3 вариантов	ситуативно
Note	`note-`	Микро-решение · 90-day TTL	ситуативно
Refresh	`ref-`	Re-evaluation просроченного	ситуативно

03 · Depth calibration и quality gates

Концепция 03 · аналогия досмотра в аэропорту

Полный конвейер ко всему - остановит работу. Никакого - обрушит качество. Нужна калибровка

Даже с одним инструментом остаётся вопрос: на какой задаче применять полный конвейер, а на какой коммитить без артефактов? Переименование переменной не требует PRD. Переход на новую базу - требует всего. Между ними - континуум.

Аналогия - досмотр в аэропорту. Внутренний рейс - быстрая проверка. Международный - полный. Transit - своя процедура. «Полный» ко всем - аэропорт остановится. «Быстрый» ко всем - безопасность рухнет. Нужна калибровка под ситуацию.

● Tactical

Без артефактов

конвейер: none

Типографика, косметика, рефактор имён. Достаточно commit message.

● Standard

PRD + RFC

PRD → RFC → Evidence

Новая фича внутри одной команды, без breaking changes публичного API.

● Deep

+ SPEC + ADR

PRD → Spec → RFC → ADR → Full Review

Архитектурный выбор, новая внешняя зависимость, breaking change API.

● Critical

+ Epic + Adversarial

Epic → PRD[] → Spec[] → RFC[] → ADR[] → Adversarial

Security, cross-team, регуляторика. Полный evidence-граф обязателен.

Калибровка не делается на глаз - её считает CLI:

      Терминал · forgeplan route
$ forgeplan route 'Add streaming endpoint GET /query/stream for Vault'
Depth: deep
Pipeline: PRD → RFC → SPEC → ADR
Reason: public API change, new external dependency (Anthropic streaming),
        cost-budget impact

$ forgeplan route 'Rename button color from blue to indigo'
Depth: tactical
Pipeline: (none)
Reason: pure cosmetic, no behavior change, no cross-team impact
    

Спорить можно, но с CLI. Это убирает бесконечное «а нужен ли тут RFC?». CLI знает правила (security → минимум deep, cross-team → минимум standard) и выдаёт ответ за полсекунды. Экономится не час работы - когнитивная нагрузка на сомнения.

forgeplan validate · 3 quality gates $ forgeplan validate PRD-018

01 BMAD validation Все 13 секций PRD заполнены. Acceptance Criteria измеримые. Non-Goals явные. pass

02 OpenSpec consistency Delta-spec ссылается на существующую базовую. DAG без циклов. ADDED/MODIFIED/REMOVED корректны. pass

03 FPF reasoning В ADR минимум 3 гипотезы. Отвергнутые альтернативы имеют причину отказа. Evidence с F-G-R. pass

Все три прошли - PASS. Хотя бы один упал - CLI возвращает конкретные pointers «что и где починить». Не «общая ошибка» - а строка и название секции, в которой что-то не так.

Жизненный цикл артефакта · activate как точка невозврата

draft

можно править свободно

→

validate

3 quality gates проходят

→

activate

immutable · правка через supersede

→

superseded · stale

история сохранена · timeline честный

Activate - самая важная команда

После forgeplan activate adr-001 файл нельзя править. Только forgeplan supersede adr-001 --by adr-002 создаёт замену с новым ID и явной ссылкой на superseded. Это даёт честную историю: видно, что решено тогда, что решено потом, в каком порядке. Не перезаписанный файл без следов изменений - а immutable timeline решений.

Цикл на одном проекте · Vault · streaming endpoint

Как Forgeplan ведёт от строки в Slack до активированного решения с evidence и DAG.

01 · route

`forgeplan route 'Add streaming endpoint GET /query/stream'`

CLI отвечает: depth = deep, конвейер = PRD → SPEC → RFC → ADR. Reason: public API change + new external dependency. Калибровка за полсекунды, без споров.

02 · new prd

`forgeplan new prd "Streaming endpoint for Vault queries"`

Создаётся файл с 13 секциями BMAD: Context, Problem, Goals, Non-Goals, Success Metrics, Target Users, User Stories, Acceptance Criteria, Technical Requirements, Risks, Dependencies, Open Questions, Timeline. Frontmatter автоматически: depth: deep, parent: epic-001.

03 · reason

`forgeplan reason PRD-018` · ADI

FPF требует минимум три гипотезы. SSE / WebSockets / HTTP/2 push. Для каждой - проверяемое следствие. Без этого activate заблокирован.

04 · validate

`forgeplan validate PRD-018` · 3 quality gates

BMAD validation (13 секций - pass). OpenSpec consistency (delta-spec ссылается на api-spec - pass). FPF reasoning (3 гипотезы и отвергнутые альтернативы - pass). Все три зелёные - переходим к evidence.

05 · evidence

`forgeplan new evidence "SSE vs WS benchmark"` + `link`

Бенчмарк p50 первого токена для SSE и WebSockets. F=7 (строгая методика), G=6 (числа на нагрузке 50 RPS, payload 2 KB), R=8 (свой замер на staging). forgeplan link EVID-001 ADR-001 --relation informs. R_eff пересчитывается автоматически.

06 · activate

`forgeplan activate ADR-001` · точка невозврата

R_eff > 0, все gates pass. ADR-001 уходит в status: activated. Файл immutable. Через год, если evidence протухнет - forgeplan supersede adr-001 --by adr-002 создаст замену с явной ссылкой. Timeline честный, история не теряется.

Полная документация · forgeplan.dev Methodology Overview · 10 Rules · CLI Reference · MCP Tools · Marketplace

↗