# Рецепты

> С чего начать базу знаний, что писать для легаси-проекта, чего не писать никогда и как понять, что запись плохая.

## С чего начать

Заведите три-четыре записи и не больше — база растёт сама.

**1. Правила разработки организации** (область: организация, «показывать модели сразу»):

> **Обязательно YAGNI**
> Делаем ровно то, что нужно текущей задаче — без «пригодится потом»
> Никаких абстракций на будущее, конфигураторов и слоёв под одного потребителя. Второй реальный потребитель — вот тогда и обобщаем.

**2. Язык и стиль** (организация, «показывать модели сразу»):

> **Отвечаем и комментируем по-русски**
> Язык общения и комментариев в коде — русский, имена сущностей — английские

**3. Чем является проект** (проект, тип «факт»):

> **Это проект по реверс-инжинирингу протокола X**
> Спецификации нет: поведение выясняется по трафику и по коду клиента

## Легаси-проект

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

- **что здесь на самом деле происходит** — модуль отчётов считает не то, что написано в его названии;
- **что трогать нельзя** — «модуль расчёта заморожен до миграции, правки только по согласованию»;
- **как запустить** — ловушки сборки и тестов, которые не читаются из README;
- **чем это было** — «код перенесён из старой системы как есть, стиль не приводили».

## Ловушки окружения

Их обычно пишет ИИ сам, но первую-две полезно записать руками — они задают образец:

> **Тесты падают без поднятого окружения**
> Сначала поднять окружение, потом прогонять тесты
> Без запущенных сервисов тесты падают с невнятной ошибкой подключения. Порядок: поднять окружение, дождаться готовности, затем прогонять тесты.

## Чего не писать

| Не пишите | Почему |
| --- | --- |
| Структуру каталогов, пути, имена файлов | Читается из кода и устаревает первым |
| Пересказ README | Модель прочитает README сама |
| Единичный фикс | Он уже в коде, причина — в коммите |
| Состояние работы («сейчас делаем задачу №12») | Устареет к вечеру |
| Секреты, токены, пароли | Уходит в промпт; для доступов есть [учётные данные](/docs/repositories) |
| Длинные тексты «на всякий случай» | Каждое открытие записи — это токены |

## Признаки плохой записи

- **Описание повторяет заголовок.** Модель не поймёт, когда её открывать.
- **В одной записи три темы.** Разбейте: одна запись — один факт.
- **Запись, которую нельзя проверить.** «Здесь всё сложно» — не знание.
- **Правило без обоснования там, где оно неочевидно.** Через месяц его отменят как непонятное.

## Регулярная гигиена

Раз в пару недель:

1. фильтр **«Написано ИИ»** — просмотреть, что модель узнала за это время;
2. фильтр **«Требуют проверки»** — записи, где проход консолидации нашёл расхождение с кодом;
3. фильтр **«Видно всегда»** — не разрослось ли то, что модель получает целиком в каждой задаче.

Остальное сделает [проход консолидации](/docs/knowledge/passes).