ddadminandClaude Fable 5
0d9a83d6af
Зачем: собранная спека заказов стала базовой документацией сервиса, а жанр спеки-события ей мал: дата в имени врёт, целиком в контекст агента она не влезает, а трекер с резолюциями долговечным хранилищем не считается. Решение владельца — держать детальное устройство компонента связным набором живых документов (ADR 0011) и совместить переезд с проходом на вычитание (#84). Что: docs/architecture/orders/ — индекс README и файлы по частям устройства: проекция, слепок и доставка, судьба, классы расхождений, опись, мост к склейке, стартовый мир, правила кода; спека приёма переехала в ingestion.md без содержательных правок. Резы вычитания по итогам двух слепых линий: тела разделов о проводе и приёме сведены к указателям на мастер-спеку, исследование формата и ADR (порядок строк слепка — единственное правило, оставшееся на месте); замеры канонического зерна и повторы-пояснения срезаны; списки отклонённых вариантов сохранены как долговечная запись. Датированные файлы удалены, ссылки из мастер-спеки, спеки генератора, ADR 0008/0010, исследования формата и storage.md перенацелены; раздел «Структура» AGENTS.md дополнен правилом подпапки. Проверка: grep по репозиторию не находит ссылок на удалённые файлы; все относительные ссылки внутри набора разрешаются в существующие файлы; впереди холодная сверка «ни одно решение не потеряно» и приёмка #88. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3.3 KiB
ADR 0011. Устройство компонента — связный набор живых документов
Дата: 16 августа 2026 года. Статус: принято.
Решение
Детальное устройство крупного компонента живёт в docs/architecture/
подпапкой: индекс README.md — целевая картина и указатели — и отдельный
файл на каждую часть устройства. Имена — слаги без дат; набор правится по
мере постройки, как и остальные справочники этой папки.
Первый такой набор — заказы бэкенда,
собранный из спеки этапа 3 и спеки приёма. Датированные файлы
2026-08-16-orders.md и 2026-08-16-order-ingestion.md удалены, ссылки на
них перенацелены; историю держит git.
Почему
Спека и базовая документация — разные жанры, а файл был один. Спека — событие: проект изменения с датой в имени, замерзающий после приёмки. Но собранная спека заказов сразу стала и детальным устройством сервиса — тем документом, по которому этап 3 будут строить и с которым потом сверяться. Живому устройству дата в имени врёт, а замерзать ему нельзя.
Один большой документ плохо читается обоими читателями. Агент, строящий судьбу заказа, вынужден везти в контексте формат провода и приём; человек листает пятьсот строк ради одного раздела. Индекс с файлами по частям даёт обоим одно и то же: загружается только нужная часть, а карта целого — один экран.
Долговечно только то, что в git. Резолюции развилок живут в трекере, а трекер долговечным хранилищем не считается. Поэтому решения — вместе с отклонёнными вариантами при каждом правиле — лежат в файлах набора; ссылки на тикеты остаются вежливостью, не записью.
Следствия
docs/specs/остаётся событиям: мастер-спека и спека генератора живут как есть; переводить ли их в живую форму — отдельное решение, когда встанет.- Раздел «Структура» в AGENTS.md обновлён тем же коммитом.
- Ссылки из ADR 0008 и 0010, мастер-спеки, спеки генератора, исследования формата и доки хранилища перенацелены на набор.