av
bf6a173115
- DECISIONS.md (4040 строк, 65 тем) → decisions/, файл на тему плюс указатель; - буквенные метки решений заменены сквозными Р1–Р234, следствия получили префикс С при прежних номерах: схема букв выродилась до пятибуквенных и сломалась — `АЕАКЛ` была занята и темой 53, и темой 65; - 42 перекрёстные ссылки переписаны под новые номера и стали живыми; где номер означал тему, а слово стояло «решение», формулировка исправлена.
74 lines
6.4 KiB
Markdown
74 lines
6.4 KiB
Markdown
# 16. Каталог вместо файла в `docs/` — отложено до переезда healthlog (2026-08-04)
|
||
|
||
## Что было
|
||
|
||
Вопрос: разрешить документам в корне `docs/` быть не только файлом, но и
|
||
каталогом — когда документ описывает несколько принципиальных решений или
|
||
перерастает 400–500 строк. Паспорт остаётся файлом в любом случае: компактность
|
||
и есть его функция.
|
||
|
||
Механизм в каноне уже работает — `conventions/`, `research/`, `adr/` каталоги с
|
||
обязательным `README.md`-индексом, — так что вопрос не «можно ли», а «от чего
|
||
лечим».
|
||
|
||
## Решено
|
||
|
||
**Р55. Порог в строках триггером не становится.** Замер по проектам: у порога
|
||
ровно один документ — `healthlog/docs/architecture.md`, 1662 строки. В нём
|
||
десять маркеров долга, а разделы — «Слои гранулярности» (211 строк), «Тренировки
|
||
и прочие секции» (222), «Условный запрос», «Свёртка и размер ответа», «Форма
|
||
ответа». Это **поведение**, чей нормативный дом `openspec/specs/`, где у проекта
|
||
уже лежат пять capability. Остальные документы 108–438 строк, `jellybit` — 169.
|
||
Порог сработал бы ровно там, где надо не разносить, а доводить переезд, и дал бы
|
||
долгу постоянное жильё: разложить 1662 строки по файлам дешевле, чем вынести их
|
||
в спеки, а после раскладки давление исчезнет и второй дом поведения останется
|
||
навсегда.
|
||
|
||
**Р56. Шов выноса — другой читатель или другой срок жизни, а не размер.** По
|
||
этому критерию кандидатов два. `review.md` — сильнее прочих: у него уже записаны
|
||
два раздела с разными сроками жизни, настройка конвейера стабильна и читается
|
||
проходами, а журнал дефектов растёт неограниченно. `architecture.md` — по шву
|
||
«окружение, деплой, наблюдатель», у которого отдельный читатель `ops`. А вот
|
||
расщепление архитектуры **по принципиальным решениям отвергнуто**: у факта
|
||
«почему решено так» дом `adr/`, и вынесенные разделы немедленно станут его
|
||
вторым домом.
|
||
|
||
**Р57. `security.md` и `passport.md` каталогом не становятся.** У `security.md`
|
||
ценность именно в цельности: периметр первой строкой и «что вне модели» читаются
|
||
враждебным проходом за один раз, а разнесённые — расходятся первыми. У
|
||
`database.md` механизм заводить не под что: 241 и 211 строк.
|
||
|
||
**Р58. Если вводить — точка входа остаётся одна.** `docs/architecture.md`
|
||
упомянут в репозитории 66 раз: девять charter'ов, карта `project-facts.md`,
|
||
`docs.py`, скелеты. Развилка «файл или каталог» размножится на девять «прочитай
|
||
либо обойди». Поэтому форма жёсткая: каталог легален только при
|
||
`<имя>/README.md`, и он **и есть** прежний документ — обзор целиком со ссылками
|
||
на вынесенное, а не оглавление к нему. Каждый файл каталога обязан быть достижим
|
||
ссылкой из `README.md`; это проверяется сегодняшним механизмом ссылок `docs.py`
|
||
и ловит файл-сироту. Вынеся раздел, `README.md` на него **ссылается, а не
|
||
пересказывает** — тот же приём, которым в архитектуре уже описаны компоненты со
|
||
ссылкой на capability.
|
||
|
||
**Р59. Решение отложено до конца переезда `healthlog` (шаг 2 TODO).** Порядок:
|
||
довести поведение в спеки, замерить остаток. Жмёт после этого — вводить каноном
|
||
версии 3, и сразу для `review.md` и `architecture.md`, а не для всех документов
|
||
корня скопом.
|
||
|
||
## Что из этого следует
|
||
|
||
**С65. Цена изменения — версия канона, а не правка одного файла.** Обратной
|
||
совместимости у канона нет, поэтому в счёт входят: `docs.py` (`check_stray` с
|
||
его `ALLOWED_FILES`/`ALLOWED_DIRS`, `check_required` — обязательный путь
|
||
становится развилкой, `check_capabilities` — сегодня читает ровно один файл),
|
||
`skeletons.md`, `project-facts.md`, девять charter'ов, запись в `changelog.md`
|
||
канона и ветка `upgrade` в скилле `canon`.
|
||
|
||
**С66. Раздутый документ канона — сначала подозреваемый, потом кандидат на
|
||
вынос.** Диагностика перед раскладкой — счёт маркеров долга (`grep -c "<!--
|
||
канон:"`) и вопрос, не поведение ли это. Разложить дрейф по файлам значит
|
||
перестать его видеть.
|
||
|
||
**С67. Материал для решения даёт `healthlog`, а не `jellybit`.** У второго 169
|
||
строк архитектуры — там вопрос не стоит вовсе, и принимать по нему решение
|
||
значит принимать его без предмета.
|