dev-skills/decisions/16-directory-instead-of-file.md

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 строк архитектуры — там вопрос не стоит вовсе, и принимать по нему решение значит принимать его без предмета.