Документация проекта

Статус: active. Это индекс документов и карта источников истины для разработчиков и агентов. Подробные правила находятся в самих документах, а обязательный краткий контракт — в AGENTS.md.

Порядок чтения

AGENTS.md — команды и обязательные инварианты.
Этот файл — выбрать актуальный документ по теме.
Соответствующий план или checklist темы.
Исходники, конфигурация и тесты рядом с изменяемым кодом.

Активные документы

Документ	Роль	Статус
`AGENTS.md`	Краткий обязательный контракт для агента	active
`docs/agent-workflow.md`	Подробный порядок исследования, изменения и проверки	active
`docs/testing-strategy.md`	Locator, fixture, i18n и fixme-policy для e2e	active
`docs/quality-gates.md`	Команды проверки, warnings и CI	active
`docs/backlog.md`	Продуктовые, UX- и инфраструктурные задачи	active
`docs/roadmap.md`	Общие направления развития	active
`docs/plan-seo.md`	SEO/GEO-план	active
`docs/plan-platform.md`	PWA/API/WASM-план	active
`docs/checklist-manual-testing.md`	Ручная приёмка production UI	active
`docs/tools-map.md`	Живая карта инструментов	active
`web/eslint-plugins/README.md`	Детали custom lint rules и token policy	active
`docs/archive/README.md`	Правила архивирования и удаления старых документов	active

docs/archive/ содержит временную историческую справку и не является текущим источником критериев приёмки. Для старых документов действует срок хранения 30 дней; после него их удаляют, а при необходимости достают из git history.

Где хранить новую информацию

Поведение, которое агент обязан соблюдать сразу, — кратко в AGENTS.md.
Точные команды, параметры скриптов и критерии качества — в docs/quality-gates.md или в README соответствующей подсистемы.
Архитектура, потоки данных и границы модулей — в отдельном architecture-плане или документе, не дублируя существующие планы.
Реализация lint-правил, fixtures и технические детали ESLint — в web/eslint-plugins/README.md и исходниках правил.
Продуктовые решения и ручная приёмка — в backlog, плане и checklist.

У документа должен быть один источник истины: остальные файлы ссылаются на него, а не пересказывают. Подробные материалы хранятся в docs/, чтобы не засорять корень репозитория. Не создавать отдельные docs/commands.md, docs/known-issues.md или копию backlog: команды принадлежат quality-gates, известные проблемы — backlog и checklist. README.md в корне остаётся кратким обзором продукта, а не вторым руководством агента.

Новый документ создаётся только когда темы нет в существующем файле; иначе обновляется источник истины. Активный документ имеет статус (draft, active, completed) и понятную область применения.

Подробные материалы хранятся в docs/, а не в корне. Новый файл создаётся только если темы нет в существующем документе; иначе обновляется источник истины.

Текущий baseline

production registry содержит 122 инструмента;
pnpm --dir web check проходит без ошибок и предупреждений;
pnpm --dir web test — 46 test files / 534 tests, включая тесты token audit, PostCSS HCT-плагина и правил линтинга;
pnpm --dir web test:rules — 5 test files / 104 tests;
pnpm --dir web lint:all — 0 errors, 0 i18n warnings и 0 unused design tokens от token audit;
coverage src/lib — statements 91.77%, branches 83.3%, functions 74.31%, lines 92.53% при порогах 90 / 82 / 72 / 91;
pnpm verify проходит;
pnpm --dir web test:e2e — 276 тестов в четырёх проектах: 276 passed, 0 skipped, 0 failed. Отказ декодера битого PNG зафиксирован per-engine в web/e2e/png-fixtures.spec.ts.

Состав проверок и их семантика описаны в docs/quality-gates.md, тестовая архитектура — в docs/testing-strategy.md. Baseline обновляется здесь при изменении любого из гейтов.

Правила актуальности

У активного документа есть статус: draft, active, completed или archived.
Ссылки на конкретный файл или команду проверяются при изменении источника истины.
Архивный документ не возвращается в live-критерии без явной сверки.
После каждого шага плана агент останавливается, показывает изменённые файлы, проверки и нерешённые решения, и ждёт ревью.