# Метод

**Правила, по которым работает команда из нейросети и человека.**
Версия 1.0 · aibolno.ru

Это один файл. Положи его в корень проекта рядом с кодом. Любой ассистент, который умеет читать файлы проекта, начнёт работать по этим правилам — их не надо повторять в каждом чате.

---

## Как этим пользоваться

1. Скопируй файл в корень репозитория. Если у твоего ассистента есть свой файл контекста (`CLAUDE.md`, `AGENTS.md`, `.cursorrules` — название зависит от инструмента) — либо переименуй этот файл в него, либо добавь туда одну строку: «Правила работы — в `aibolno-metod.md`, читать целиком перед любой задачей».
2. Заполни блок «Про этот проект» ниже. Пока он пустой, ассистент будет угадывать, а угадывание — источник половины поломок.
3. Дальше правила работают сами. Твоя часть — не подписывать то, что не прочитал.

Правила написаны от лица команды и обращены к обеим сторонам: и к ассистенту, и к человеку, который его проверяет. Где написано «владелец» — это ты.

```
## Про этот проект

Что строим:
Кто пользователь:
Стек (зафиксировать и дальше не оспаривать):
Что категорически нельзя трогать:
Где живут секреты (сам секрет здесь не пишем):
```

---

## 1. Только факты

Главное правило. Всё остальное — его следствия.

1. **«Сделано», «работает», «существует» — только с доказательством.** Доказательство — это вывод команды, строка лога, имя зелёного теста, хеш коммита, ссылка на файл и строку. Сначала сделал и проверил, потом сказал.
2. **«Не знаю» и «не проверял» — нормальные ответы.** Они стоят дешевле, чем уверенное неверное. Догадку помечай словом «гипотеза» и держи помеченной до проверки.
3. **Число называется только с источником.** Откуда оно: из базы, из лога, из прогона. Число без источника не произносится вовсе — ни в отчёте, ни в разговоре.
4. **Не ссылаться на то, чего не видел.** Прежде чем упомянуть файл, функцию, флаг или документ — убедиться, что он есть сейчас. «Вроде было» — не основание: файл могли удалить, флаг переименовать.
5. **Инструмент не дал результата — сказать прямо.** Пустой вывод и упавшая команда выглядят одинаково. Разницу надо назвать, а не заполнять выдумкой.

**Как это проверяется у себя.** Возьми последний отчёт ассистента и подчеркни каждое утверждение, под которым нет доказательства. Обычно подчёркнутого больше, чем ожидаешь.

---

## 2. Думать шире

Четыре пункта, которые обязаны быть в любом предложении. Без них предложение возвращается без разбора деталей.

1. **От первоисточника.** Как это делается правильно с нуля, по официальной документации — а не «как у нас уже привыкли». Привычка часто и есть источник проблемы.
2. **На два-три шага вперёд.** Что это решение сделает со следующей фазой, с масштабом, с соседней функцией. Последствие называется явно, а не остаётся «ну это потом».
3. **Хотя бы одна альтернатива сверх заданного вопроса.** Спросили «как сделать А» — ответ включает «а ещё есть Б, вот чем он лучше и хуже».
4. **Полный контур для новых данных.** Откуда приходят, в каком формате, кто владелец, кто читает, что с ними будет через полгода. Подсветить риск и не предложить решения — это половина работы.

---

## 3. Один дом для данных

У каждого типа данных ровно один дом: одна таблица или один файл, с явным ответом, кто туда пишет и кто читает.

- Новый тип данных — **сначала** строка в карте данных, **потом** код.
- Запись мимо назначенного дома или во «второй дом» — повод вернуть работу целиком.
- Одна и та же величина, лежащая в двух местах, начинает расходиться. Не «может разойтись» — расходится, вопрос только в том, когда это заметят.

**Отдельно про величины, которых нет в схеме.** Если величина нужна, но столбца под неё нет, это не значит, что величины не существует — возможно, она приезжает в сыром ответе и просто выбрасывается. Прежде чем заводить новый дом, посмотри сырые данные.

---

## 4. Процесс: от задачи до приёмки

```
1. Задание      пишется до кода, по шаблону ниже
2. Разбор       задание ломают ДО кода: что здесь недодумано
3. Подпись      владелец. Нет подписи — нет кода
4. Работа       строго по заданию. Шаг в сторону = стоп и вопрос
5. Приёмка      по доказательству на каждый пункт
6. Закрытие     только после живой проверки глазами
```

### Шаблон задания

1. Цель — одной фразой, наблюдаемой снаружи.
2. Кто участвует.
3. Данные: что читаем, что пишем, где дом.
4. Поведение, включая крайние случаи и «что делать, когда пусто».
5. Результат, который видно без залезания в код.
6. Признаки готовности — каждый проверяемый.
7. Что в эту задачу **не** входит.
8. Оценка. Не влезает в несколько дней — резать на части.

Статусы задания: черновик → разобран → подписан. После подписи задание меняется только новой версией с явным списком изменений и новой подписью.

### Правила размера

- **Один кусок работы в работе.** Не три параллельно.
- **Ни строки кода без подписанного задания.** Это звучит бюрократично, пока не увидишь, во что превращается «давай просто попробуем» за месяц.
- **Не плодить сущности.** Дорабатываем то, что есть. Новая версия заменяет старую, а старую помечаем мёртвой в тот же день. Параллельные версии одного и того же — запрещены.

### Приёмка по доказательству

Это место, где метод либо работает, либо становится декорацией.

- Каждый пункт готовности — **именованный артефакт**: имя теста, команда и её вывод, ссылка на лог, скриншот.
- Формулировки «покрыто косвенно», «работает через другое», «должно работать» — пункт **не** закрыт.
- Написано «проверено пять случаев» — в отчёте пять имён тестов, по одному на случай.
- Проверяет **не автор**. Автор своей работы не видит: он проверяет то, что задумал, а не то, что написал.
- Последний шаг — живая проверка руками, глазами пользователя. Зелёные тесты не закрывают работу. Работу закрывает то, что оно делает то, что обещано.

---

## 5. Дисциплина дебага

1. **Сначала факты, потом гипотезы.** Разбор начинается с логов и состояния данных, а не с версии в голове. В описании починки — цитата, доказывающая корень.
2. **Чинить слой, не случай.** Если корень в общем месте, чинится общее место плюс тест на него. Обязательный вопрос: «где ещё это проявляется?» — с письменным ответом. Заплатки по одному случаю за год превращают проект в музей.
3. **Красный тест до починки.** Сначала тест, который падает и показывает баг. Потом починка. Потом зелёный. Починка без такого теста не принимается: без него неизвестно, что именно исправлено.
4. **Никаких «заодно».** Рефакторинг в починке запрещён. Иначе непонятно, что из двух подействовало.
5. **Одна задача — одна сессия.** Длинный чат «поплыл» — начать новый, правила перечитаются заново.
6. **Не останавливаться на первом найденном.** Первое объяснение — гипотеза. Перед выводом «оно работает так» — обойти все слои, где тема встречается, и сказать в ответе, какие слои обошёл. Правдоподобная причина, найденная за минуту, регулярно оказывается не причиной.
7. **Правки живых данных — только записанным скриптом.** Разовая команда руками не воспроизводится и ничего не доказывает.

---

## 6. Git-дисциплина

1. Перед любой работой — свежая основная ветка.
2. Перед отправкой на ревью — перенести ветку на свежую основу. Увидел в изменениях удаление файлов, которых не трогал — ветка устарела.
3. После вливания — обновить основную ветку и убрать слитые локальные.
4. Одна задача — одна короткоживущая ветка.

Отдельно: **прежде чем переключить ветку, посмотри, что на текущей живёт.** Если на ней лежат работающие скрипты, которых нет в основной, переключение молча их унесёт, и сломается то, что вообще не относится к задаче. Другую ветку можно читать, не переключаясь на неё.

---

## 7. Разбор граблей

Здесь то, на чём мы спотыкались сами. Собраны не страшилки: это места, где проверка выглядит выполненной, а на деле не выполнена. Почти все они одного класса — **молчание принимают за ответ «нет»**.

### Проверки, которые ничего не проверяют

**Пустой вывод читается как ноль.** Команда упала, ответила отказом, не дошла до сервера — а на экране ничего. Выглядит как «данных нет». Печатай код возврата и число найденного, а не только сам результат. Если внешний сервис умеет отвечать «сейчас не могу», его пустой ответ — не доказательство отсутствия.

**Код возврата теряется в конвейере.** В некоторых оболочках массив статусов конвейера пуст, и проверка «упало или нет» всегда отвечает «не упало». Проверка есть, вердикта нет.

**Зелёный тест закрепляет дефект.** Тест, написанный после кода и под код, фиксирует не требование, а поведение. Дефект переезжает в эталон, и дальше его защищает CI. Отсюда правило про красный тест до починки.

**Заглушка врёт вместе с кодом.** Если подделка внешнего сервиса написана по тем же неверным представлениям, что и код, тест зелёный и оба неправы. Хотя бы один тест должен идти сквозь настоящую доставку результата до конца.

**Мой список тестов — не множество того, что я ломаю.** Прогоняешь тесты вокруг правки, а ломается соседняя область. Прежде чем считать проверку достаточной, найди, кто ещё читает то, что ты изменил.

**Зелёная ветка и зелёная основа — разные вещи.** Если на ветку запускается сокращённый набор проверок, зелёная галочка означает только то, что сокращённый набор прошёл.

### Величины, которые измерены не то

**Окно замера сверять с кодом.** Отчёт называется недельным, а цифра в нём — за всё время. Прежде чем объяснять «странное» число, посмотри, за какой период его считает код. Несколько «дефектов» подряд так и растворяются.

**Моё разбиение — не разбиение кода.** Ты делишь людей на группы по своему смыслу, код делит по своему. Сумма сходится, вывод неверен.

**Значение по умолчанию в коде — не живое состояние.** В коде написано «по умолчанию выключено» — это не значит, что оно выключено сейчас. Настройка могла приехать снаружи.

**Порядок задач — не хронология событий.** Список задач отсортирован так, как удобно планировщику. Читать по нему последовательность произошедшего нельзя.

**Отсутствие записи — не доказательство, что не было.** Поиск по сегодняшнему дню не отвечает на вопрос «случалось ли когда-нибудь». Нет строки о подключении — может значить и «не подключался», и «строку пишут в другом месте».

**Дефект подписи невидим для проверки запроса.** Числа верны, а подпись над ними неверна — и тест запроса это пропускает, потому что смотрит на числа. Сторож ставится на итоговое собранное сообщение, то, которое увидит человек.

### Побочные эффекты, которых не ждали

**Отметка «событие было» — не замок.** Если она проверяется один раз на запуск, а не на каждый элемент, два одновременных запуска сделают работу дважды. Вопрос к такой отметке один: где именно она проверяется.

**Источник чистить после подтверждённой доставки.** Сначала подтверждение, потом очистка очереди. Наоборот — потерянные данные без следа.

**Сокращение флага глотает чужое значение.** Некоторые разборщики аргументов принимают неполное имя флага, и значение уходит не туда, куда ты смотрел. Флаги писать целиком.

**Починка внутри задачи не догоняет уже закрытых.** Если задача помечает обработанный период, то после починки она в этот период не вернётся. Нужен отдельный проход.

**Отмена изменений в файле стирает файл целиком.** Команда, которая возвращает файл к состоянию в репозитории, унесёт и то, что ты в нём наработал. Ломать что-то для проверки — скриптом, чтобы откат был тоже скриптом.

**Свой же сторож — первый подозреваемый.** Прежде чем объяснять «процесс умер» внешними причинами, проверь журнал собственного перезапускающего механизма. Чаще всего это он.

### Дисциплина внимания

**Правдоподобная причина — ещё не причина.** Особенно когда объяснение нашлось быстро и красиво. Отдельно проверь свои же прежние записи: ответ часто уже написан там, и мимо него проходят именно потому, что ищут снаружи.

**Прежде чем предлагать варианты, поищи свою же работу.** Половина «давай сделаем» уже начата на какой-то ветке.

**Данные, появившиеся после разговора, могут быть его следствием.** Прежде чем объявлять расхождение ошибкой, проверь, не сделал ли человек то, о чём его попросили.

---

## 8. Чего метод не делает

Честный список, чтобы не было разочарования.

- **Не решает, что строить.** Дисциплина исполнения не заменяет решение. Исправно и дёшево идти не туда — тоже возможно.
- **Не работает без твоей подписи.** Подписываешь задания не читая — получаешь те же результаты, что раньше, плюс лишние шаги.
- **Не ускоряет первую неделю.** Правила добавляют работы на входе и убирают её потом, на разборе поломок.
- **Не настраивается один раз навсегда.** Инструменты обновляются и иногда ломают то, что работало. Сторожа существуют ровно поэтому.

---

## Проверка за вечер

Не верь файлу на слово. Возьми задачу, которая у тебя уже есть, и проведи её по этому пути: задание по шаблону → разбор до кода → твоя подпись → работа → приёмка с доказательством на каждый пункт. Одной задачи достаточно, чтобы понять, ваше это или нет.

---

_Метод — дисциплина для того чата, который у тебя уже есть. Полная система — несколько рабочих контуров, которые работают, пока ты спишь, и отчитываются в мессенджер — это отдельный продукт: aibolno.ru_

---

Файл бесплатный: пользуйся в своих проектах и меняй под себя.
Полная инфраструктура ИИ-разработки — aibolno.ru
