Рецепты
С чего начать базу знаний, что писать для легаси-проекта, чего не писать никогда и как понять, что запись плохая.
С чего начать
Заведите три-четыре записи и не больше — база растёт сама.
1. Правила разработки организации (область: организация, «показывать модели сразу»):
Обязательно YAGNI Делаем ровно то, что нужно текущей задаче — без «пригодится потом» Никаких абстракций на будущее, конфигураторов и слоёв под одного потребителя. Второй реальный потребитель — вот тогда и обобщаем.
2. Язык и стиль (организация, «показывать модели сразу»):
Отвечаем и комментируем по-русски Язык общения и комментариев в коде — русский, имена сущностей — английские
3. Чем является проект (проект, тип «факт»):
Это проект по реверс-инжинирингу протокола X Спецификации нет: поведение выясняется по трафику и по коду клиента
Легаси-проект
Плохо документированный проект — тот случай, где база знаний окупается сразу. Что записать:
- что здесь на самом деле происходит — модуль отчётов считает не то, что написано в его названии;
- что трогать нельзя — «модуль расчёта заморожен до миграции, правки только по согласованию»;
- как запустить — ловушки сборки и тестов, которые не читаются из README;
- чем это было — «код перенесён из старой системы как есть, стиль не приводили».
Ловушки окружения
Их обычно пишет ИИ сам, но первую-две полезно записать руками — они задают образец:
Тесты падают без поднятого окружения Сначала поднять окружение, потом прогонять тесты Без запущенных сервисов тесты падают с невнятной ошибкой подключения. Порядок: поднять окружение, дождаться готовности, затем прогонять тесты.
Чего не писать
| Не пишите | Почему |
|---|---|
| Структуру каталогов, пути, имена файлов | Читается из кода и устаревает первым |
| Пересказ README | Модель прочитает README сама |
| Единичный фикс | Он уже в коде, причина — в коммите |
| Состояние работы («сейчас делаем задачу №12») | Устареет к вечеру |
| Секреты, токены, пароли | Уходит в промпт; для доступов есть учётные данные |
| Длинные тексты «на всякий случай» | Каждое открытие записи — это токены |
Признаки плохой записи
- Описание повторяет заголовок. Модель не поймёт, когда её открывать.
- В одной записи три темы. Разбейте: одна запись — один факт.
- Запись, которую нельзя проверить. «Здесь всё сложно» — не знание.
- Правило без обоснования там, где оно неочевидно. Через месяц его отменят как непонятное.
Регулярная гигиена
Раз в пару недель:
- фильтр «Написано ИИ» — просмотреть, что модель узнала за это время;
- фильтр «Требуют проверки» — записи, где проход консолидации нашёл расхождение с кодом;
- фильтр «Видно всегда» — не разрослось ли то, что модель получает целиком в каждой задаче.
Остальное сделает проход консолидации.