обвязка: идентификаторы правил описаны через префиксы
- LANGUAGE.md: раздел «Идентификаторы» переписан под префиксы, в список машинных проверок добавлена сверка с реестром - GUIDE.md перенумерован под префикс META, «номер правила» заменён на «идентификатор»
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
---
|
||||
prefix: META
|
||||
---
|
||||
|
||||
# Как мы ведём конвенции
|
||||
|
||||
Конвенция описывает повторяющийся выбор: как называть директории, как
|
||||
@@ -29,11 +33,10 @@
|
||||
## Оформление
|
||||
|
||||
Имя файла — kebab-case по теме: `app-directories.md`. Правилом это не
|
||||
записано: обоснование сводится к «чтобы адрес правила
|
||||
(`stack/ansible/app-directories.md R4`) писался одним способом», а
|
||||
проверить нарушение всё равно проще глазом, чем сформулировать норму. Номер
|
||||
R16, под которым это правило существовало, оставлен свободным и не
|
||||
переиспользуется.
|
||||
записано: обоснование сводится к «чтобы имя файла в реестре префиксов
|
||||
писалось одним способом», а проверить нарушение всё равно проще глазом, чем
|
||||
сформулировать норму. Номер META-16, под которым это правило существовало,
|
||||
оставлен свободным и не переиспользуется.
|
||||
|
||||
## Канон и копии
|
||||
|
||||
@@ -51,7 +54,7 @@ R16, под которым это правило существовало, ос
|
||||
|
||||
## Правила
|
||||
|
||||
### R1. Одна конвенция — один файл
|
||||
### META-1. Одна конвенция — один файл
|
||||
|
||||
**ДОЛЖЕН.** Файл описывает ровно один повторяющийся выбор.
|
||||
|
||||
@@ -61,7 +64,7 @@ R16, под которым это правило существовало, ос
|
||||
позже дорого: путь файла — часть адреса правила, и после разреза внешние
|
||||
ссылки указывают не туда.
|
||||
|
||||
### R2. Конвенция заводится, когда решение принимается третий раз
|
||||
### META-2. Конвенция заводится, когда решение принимается третий раз
|
||||
|
||||
**СЛЕДУЕТ.** Поводом служит одно и то же решение, принятое третий раз и
|
||||
каждый раз чуть по-другому.
|
||||
@@ -72,7 +75,7 @@ R16, под которым это правило существовало, ос
|
||||
спорный, читателю нужен вместе с мотивом — это ADR, где мотив и есть
|
||||
содержание записи.
|
||||
|
||||
### R3. Новая конвенция пишется там, где заболело
|
||||
### META-3. Новая конвенция пишется там, где заболело
|
||||
|
||||
**СЛЕДУЕТ.** Первые шаги пути «находка → конвенция → правило линтера →
|
||||
удаление прозы» делаются в репозитории, где случилась находка; в канон
|
||||
@@ -83,7 +86,7 @@ R16, под которым это правило существовало, ос
|
||||
платят за это все потребители сразу. Формулировка, обкатанная на одном
|
||||
репозитории, приезжает в канон уже с известной границей.
|
||||
|
||||
### R4. В тексте конвенции нет утверждений о состоянии репозитория
|
||||
### META-4. В тексте конвенции нет утверждений о состоянии репозитория
|
||||
|
||||
**НЕ ДОЛЖЕН.** Норма пишется в настоящем предписывающем времени, без
|
||||
описаний того, как сейчас устроен конкретный репозиторий.
|
||||
@@ -94,7 +97,7 @@ R16, под которым это правило существовало, ос
|
||||
с первого дня. «Так сделано у нас» — содержимое региона отступлений, где оно
|
||||
и локально, и проверяемо.
|
||||
|
||||
### R5. Расхождение кода с правилом — отступление, а не повод переписать правило
|
||||
### META-5. Расхождение кода с правилом — отступление, а не повод переписать правило
|
||||
|
||||
**ДОЛЖЕН.** Правило правится, только когда неверно по существу: содержит
|
||||
фактическую ошибку, внутреннее противоречие или условие применимости,
|
||||
@@ -105,7 +108,7 @@ R16, под которым это правило существовало, ос
|
||||
переписывает его снова. Направление «конвенция → код» держится ровно тем,
|
||||
что факт не считается аргументом.
|
||||
|
||||
### R6. `ДОЛЖЕН` без механической проверки либо механизируется, либо понижается
|
||||
### META-6. `ДОЛЖЕН` без механической проверки либо механизируется, либо понижается
|
||||
|
||||
**ДОЛЖЕН.** Правило, нарушение которого объявлено ошибкой, получает
|
||||
машинную проверку или переводится в СЛЕДУЕТ.
|
||||
@@ -119,18 +122,18 @@ R16, под которым это правило существовало, ос
|
||||
(вкус формулировки, выбор границы, суждение о ситуации), не может быть
|
||||
ДОЛЖЕН — его модальность СЛЕДУЕТ по построению, а не по слабости.
|
||||
|
||||
### R7. Факт механизации фиксируется в локальном регионе со ссылкой на номер
|
||||
### META-7. Факт механизации фиксируется в локальном регионе со ссылкой на правило
|
||||
|
||||
**ДОЛЖЕН.** Регион `механизировано` называет номер правила и конкретную
|
||||
проверку.
|
||||
**ДОЛЖЕН.** Регион `механизировано` называет идентификатор правила и
|
||||
конкретную проверку.
|
||||
|
||||
**Почему.** Механизация — состояние конкретного репозитория, канон о ней не
|
||||
знает, а без записи следующий автор либо заведёт вторую проверку того же,
|
||||
либо будет вычитывать глазами уже проверенное машиной. Без номера правила
|
||||
либо будет вычитывать глазами уже проверенное машиной. Без идентификатора
|
||||
читатель догадывается сам, к какому утверждению относится проверка, — и
|
||||
догадывается по-разному.
|
||||
|
||||
### R8. Формулировка не удаляется из канона, пока механизирована не у всех
|
||||
### META-8. Формулировка не удаляется из канона, пока механизирована не у всех
|
||||
|
||||
**НЕ ДОЛЖЕН.** Норма остаётся в каноне, пока хотя бы у одного потребителя
|
||||
машинной проверки нет.
|
||||
@@ -145,7 +148,7 @@ R16, под которым это правило существовало, ос
|
||||
удалению нормы, а не то, что можно проверить машиной (см. `LANGUAGE.md`,
|
||||
состояние МЕХАНИЗИРОВАНО).
|
||||
|
||||
### R9. Общая механизация разрешает удалить норму из канона
|
||||
### META-9. Общая механизация разрешает удалить норму из канона
|
||||
|
||||
**ДОПУСКАЕТСЯ.** Правило, уехавшее в общий конфиг линтера или в общую роль,
|
||||
удаляется из канона одним `push`.
|
||||
@@ -153,10 +156,10 @@ R16, под которым это правило существовало, ос
|
||||
**Почему.** Формулировка, дублирующая работающую у всех проверку,
|
||||
размазывает внимание: файл на несколько сотен строк заставляет человека и
|
||||
агента добросовестно вычитывать тривиальное именование и не доходить до
|
||||
формы решения. Явное разрешение нужно, чтобы R8 не читался как запрет
|
||||
формы решения. Явное разрешение нужно, чтобы META-8 не читался как запрет
|
||||
удалять вообще.
|
||||
|
||||
### R10. Обоснование не удаляется никогда
|
||||
### META-10. Обоснование не удаляется никогда
|
||||
|
||||
**НЕ ДОЛЖЕН.** Блок «Почему» остаётся и после того, как норма уехала в
|
||||
линтер.
|
||||
@@ -165,7 +168,7 @@ R16, под которым это правило существовало, ос
|
||||
существует. Без обоснования не видно, когда причина отпала, — проверка
|
||||
продолжает работать по инерции, и возразить ей нечем, кроме как отключив.
|
||||
|
||||
### R11. У трудноизменяемого слоя область действия пишется явно
|
||||
### META-11. У трудноизменяемого слоя область действия пишется явно
|
||||
|
||||
**ДОЛЖЕН.** Конвенция о схеме БД, формате хранения или раскладке директорий
|
||||
называет, к чему применяется: к новым таблицам и миграциям, а не к
|
||||
@@ -177,7 +180,7 @@ R16, под которым это правило существовало, ос
|
||||
состоянию, и оба исхода плохи — миграция живых данных ради опрятности либо
|
||||
молчаливый вывод, что конвенция не соблюдается совсем.
|
||||
|
||||
### R12. Механизируется граница изменения, а не состояние
|
||||
### META-12. Механизируется граница изменения, а не состояние
|
||||
|
||||
**ДОЛЖЕН.** Проверка запрещает нарушение в новых миграциях, а не в уже
|
||||
существующей схеме.
|
||||
@@ -187,7 +190,7 @@ R16, под которым это правило существовало, ос
|
||||
новое, ради чего заводилась. Проверка границы оставляет старое в покое и
|
||||
делает новую ошибку невозможной.
|
||||
|
||||
### R13. Список отступлений трудноизменяемого слоя — постоянный
|
||||
### META-13. Список отступлений трудноизменяемого слоя — постоянный
|
||||
|
||||
**ДОЛЖЕН.** Перечисленные старые таблицы и раскладки живут как есть, а не
|
||||
как задачи на дочистку.
|
||||
@@ -197,25 +200,25 @@ R16, под которым это правило существовало, ос
|
||||
тем, что список перестают вести, — и пропадает единственное место, где видно,
|
||||
где именно правило не действует.
|
||||
|
||||
### R14. Отступления перечисляются поимённо, со ссылкой на номера правил
|
||||
### META-14. Отступления перечисляются поимённо, со ссылкой на правила
|
||||
|
||||
**ДОЛЖЕН.** В локальном регионе перечислены отступления, которые уже есть в
|
||||
коде, с номером правила и причиной.
|
||||
коде, с идентификатором правила и причиной.
|
||||
|
||||
**Почему.** Иначе репозиторий выглядит соблюдающим конвенцию, а проверить
|
||||
это можно только чтением всего кода. Со ссылками отступления счётны: видно,
|
||||
сколько правил конвенции репозиторий реально не соблюдает. Пустой регион при
|
||||
этом почти всегда означает не отсутствие отступлений, а то, что их не искали.
|
||||
|
||||
### R15. Запись в регионе отступлений разбирается по масштабу
|
||||
### META-15. Запись в регионе отступлений разбирается по масштабу
|
||||
|
||||
**ДОЛЖЕН.** Судьба записи зависит от того, что в ней сказано:
|
||||
|
||||
| № | Что записано | Куда идёт |
|
||||
|---|---|---|
|
||||
| R15.1 | правилу не следуем в перечисленных местах, причина названа | остаётся отступлением |
|
||||
| R15.2 | правило не применяется в репозитории целиком | чинится условие применимости — в каноне |
|
||||
| R15.3 | конвенция репозиторию не нужна | копия удаляется, подписки нет |
|
||||
| META-15.1 | правилу не следуем в перечисленных местах, причина названа | остаётся отступлением |
|
||||
| META-15.2 | правило не применяется в репозитории целиком | чинится условие применимости — в каноне |
|
||||
| META-15.3 | конвенция репозиторию не нужна | копия удаляется, подписки нет |
|
||||
|
||||
**Почему.** Отступление описывает исключение, и по нему видно, какая часть
|
||||
правила нарушена. Запись «мы это правило вообще не применяем» такой
|
||||
@@ -223,7 +226,7 @@ R16, под которым это правило существовало, ос
|
||||
правила в каноне, которую чинят один раз для всех, или лишнюю подписку,
|
||||
где файл просто не нужен. Оставленная отступлением, она прячет обе.
|
||||
|
||||
### R17. Репо-специфичная часть «Связано» — в локальном регионе
|
||||
### META-17. Репо-специфичная часть «Связано» — в локальном регионе
|
||||
|
||||
**ДОЛЖЕН.** Раздел «Связано» стоит в конце файла; канонические ссылки — в
|
||||
общем тексте, ссылки на ADR, код и файлы конкретного репозитория — в
|
||||
@@ -233,7 +236,7 @@ R16, под которым это правило существовало, ос
|
||||
чужой файл у них битая с первого дня. Регион исключён из сравнения, поэтому
|
||||
та же ссылка внутри него никого не задевает и не даёт вечного шума в `diff`.
|
||||
|
||||
### R18. README директории перечисляет конвенции с однострочным описанием
|
||||
### META-18. README директории перечисляет конвенции с однострочным описанием
|
||||
|
||||
**СЛЕДУЕТ.** Одна плоская таблица: файл и строка о том, про что он.
|
||||
|
||||
@@ -241,15 +244,16 @@ R16, под которым это правило существовало, ос
|
||||
«какая из них про мой случай» решается открыванием каждой. Ценой в десяток
|
||||
файлов это означает, что не открывают ни одной.
|
||||
|
||||
### R19. Короткие инварианты дублируются в точку входа агента
|
||||
### META-19. Короткие инварианты дублируются в точку входа агента
|
||||
|
||||
**ДОЛЖЕН.** В `AGENTS.md` / `CLAUDE.md` едет одна строка на правило с его
|
||||
номером; детали остаются в конвенции.
|
||||
идентификатором; детали остаются в конвенции.
|
||||
|
||||
**Почему.** Сама по себе конвенция агенту не видна: он дойдёт до неё, только
|
||||
если его туда отправили, — а безусловно он читает точку входа. Строка с
|
||||
номером служит и напоминанием, и адресом, по которому за подробностями
|
||||
идут; перенос деталей туда же вернул бы задачу поддержки двух текстов.
|
||||
идентификатором служит и напоминанием, и адресом, по которому за
|
||||
подробностями идут; перенос деталей туда же вернул бы задачу поддержки двух
|
||||
текстов.
|
||||
|
||||
<!-- local:точки-входа -->
|
||||
<!-- /local -->
|
||||
|
||||
Reference in New Issue
Block a user