Skip to content

README.ru.md

Latest commit

 

History

History
127 lines (99 loc) · 11.1 KB

README.ru.md

File metadata and controls

127 lines (99 loc) · 11.1 KB
Raw

English · Русский

Указатель документации

Производственная документация проекта Forgeplan.

Локальные заметки (исследования, планирование, сессии, исходные материалы) находятся в .local/ (gitignored) — не являются частью этого дерева.

Структура

docs/
├── README.md          ← этот файл — навигационный указатель
├── methodology/       ← как работает методология Forgeplan (для людей)
├── operations/        ← хуки агентов, enforcement, защита репозитория (devops)
└── schemas/           ← формальные схемы артефактов (контракты для валидатора)

Артефакты (PRD, RFC, ADR, Epic, Spec, Evidence, Problem, Note) хранятся в рабочем пространстве Forgeplan в .forgeplan/ — см. раздел Артефакты ниже.

Методология — начните здесь

Полный справочник по методологии. Каноничный источник для людей, изучающих Forgeplan.

Документ Назначение
FORGEPLAN-GUIDE.md Начните здесь — полный гайд: методология + CLI + evidence + lifecycle
HOW-TO-USE.md 10 правил методологии с практическими примерами
ARTIFACT-MODEL.md Иерархия артефактов: Epic → PRD → Spec → RFC → ADR + lifecycle
PRD-RFC-ADR-FLOW.md Дерево решений: какой тип артефакта создать
DEPTH-CALIBRATION.md Tactical → Standard → Deep → Critical с авто-эскалацией
QUALITY-GATES.md Verification Gate + Adversarial Review + R_eff scoring
UNIFIED-WORKFLOW.md Интеграция Forgeplan × Orchestra × Hindsight
USAGE-BY-ROLE.md Как использовать Forgeplan в зависимости от роли
METHODOLOGY-COURSE.md Полный курс обучения (формат курса)
GLOSSARY.md 31 термин + справочная таблица lifecycle
LESSONS.ru.md Lessons learned — dependent sprint verification, audit incidents, улучшения процесса
agent-protocol.md Hint contract (PRD-071) — 5 маркеров (Next/Or/Wait/Done/Fix), good/bad примеры, agent reading protocol
release-workflow.md End-to-end рецепт релиза — dependabot triage gate, version bump, стратегия release/* PR, post-release sync (CLAUDE.md red lines #9 + #10), hotfix flow, антипаттерны

Операции

Настройка, хуки и защита репозитория.

Документ Назначение
AGENT-ENFORCEMENT.md Правила и ограничения для AI-агентов, работающих в проекте
AGENT-HOOKS.md Хуки PreToolUse / PostToolUse (безопасность, форматирование, тесты)
MULTI-AGENT.md v0.24.0+ multi-agent dispatch — MCP-инструменты forgeplan_dispatch/claim/release/claims, file-overlap detection, skill routing
REPO-PROTECTION-GUIDE.md Защита веток, правила PR, предотвращение деструктивных действий
GIT-WORKFLOW.ru.md Полные Git-правила — lifecycle веток, PR pipeline, процесс релиза, worktrees
RELEASE-PROTOCOL.ru.md (en) Канонический процесс релиза — 10 шагов любого среза release/vX.Y.Z, pre-conditions и обязательный post-merge sync-PR (RED LINE #9)
dependabot-triage-YYYY-MM-DD.md Триаж алертов зависимостей на релиз (RED LINE #10) — каждый открытый алерт помечен addressed / scheduled / accepted-with-justification. По файлу на релизное окно
SOURCE-PORTING.ru.md Reference Code map — что портировано из sources/{quint-code,git-adr,BMAD,OpenSpec,ccpm} в наши crates
PLAYBOOK-AUTHORING.ru.md v0.26.0+ авторинг playbook'ов — декларативные YAML-workflow, 5 типов делегации, fallback hints, DAG ordering. v0.27.0+ Subprocess lifecycle секция (real dispatchers, kill_on_drop, timeout policy, security model) per ADR-010/PRD-072
INGEST-MAPPINGS.ru.md v0.26.0+ авторинг ingest mapping'ов — перевод output плагинов в forge-артефакты с invariant'ом ## Sources (PRD-066/SPEC-004)
QUALITY-GATES.ru.md v0.28.0+ CI quality gates — все CI-гейты (fmt, clippy, test, health, validate, drift detector) с командами для локального запуска и руководствами по исправлению ошибок. Примечание: docs/methodology/QUALITY-GATES.md описывает методологические гейты (R_eff, Verification Gate).

Схемы

Формальные спецификации, которые применяет валидатор.

Документ Назначение
PRD-SCHEMA.md PRD: обязательные секции, калибровка глубины, правила валидации
EPIC-SCHEMA.md Epic: агрегированный прогресс, правила дочерних элементов
SPEC-SCHEMA.md Spec: API-контракты, модели данных, версионирование

Артефакты

Расположение: .forgeplan/ в корне репозитория.

Модель хранения (согласно ADR-003):

  • Markdown-файлы в .forgeplan/{adrs,rfcs,prds,epics,specs,evidence,problems,solutions,notes,refresh,memory}/ = источник истины (отслеживаются git)
  • LanceDB в .forgeplan/lance/ = производный индексный слой (git-ignored, восстанавливаемый)
  • Конфигурация .forgeplan/config.yaml = локальные LLM-ключи (git-ignored)

Директории:

Директория Содержимое
.forgeplan/epics/ Epic — стратегические группировки
.forgeplan/prds/ Product Requirements Documents
.forgeplan/rfcs/ RFC — архитектурные предложения с фазами реализации
.forgeplan/adrs/ Architecture Decision Records
.forgeplan/specs/ Формальные спецификации (API-контракты, модели данных)
.forgeplan/evidence/ EvidencePack — тесты, бенчмарки, измерения
.forgeplan/problems/ ProblemCard — формулировка проблем с индикаторами anti-Goodhart
.forgeplan/solutions/ SolutionPortfolio — 2-3+ варианта с оценкой по слабейшему звену
.forgeplan/notes/ Микро-решения (автоматически истекают через 90 дней)
.forgeplan/refresh/ RefreshReport — переоценка устаревших артефактов
.forgeplan/memory/ Память решений

Управление артефактами: всегда используйте CLI forgeplan — не редактируйте YAML frontmatter вручную.

forgeplan new prd "Title"        # создать новый артефакт
forgeplan list -t adr            # список всех ADR
forgeplan get ADR-003            # прочитать один
forgeplan validate PRD-024       # проверить качество
forgeplan score PRD-024          # вычислить R_eff
forgeplan reindex                # пересобрать LanceDB-индекс из markdown

Процесс при свежем клонировании:

git clone <repo> && cd forgeplan
forgeplan init -y                # создаёт .forgeplan/lance/ локально (пустую)
forgeplan reindex                # синхронизирует отслеживаемые markdown в LanceDB
forgeplan list                   # проверка — должны отображаться все артефакты

См. также

  • CLAUDE.md — инструкции проекта для Claude Code
  • AGENTS.md — стандартные инструкции для других AI-агентов (Aider, Cursor и др.)
  • README.md — README проекта для людей
  • templates/ — markdown-шаблоны для каждого типа артефакта
  • .local/ (gitignored) — локальные исследования, планирование, сессии, исходные материалы

Соглашения

  • Все пути в документах указаны относительно корня репозитория.
  • Файлы артефактов в .forgeplan/ управляются CLI forgeplan — ручное редактирование работает, но может вызвать рассинхронизацию с индексом LanceDB до запуска reindex.
  • Документация методологии здесь является авторитетной — если руководство и схема расходятся, приоритет у схемы.
  • Активированные артефакты неизменяемы — замена через forgeplan supersede, историю не переписывать.