Запись
Из чего состоит знание: заголовок, описание одной строкой, тип, область, тело и два признака. Как написать так, чтобы модель этим воспользовалась.
Одна запись — один факт. Не «всё про тесты», а «тесты падают без поднятого окружения».
Поля
| Поле | Зачем |
|---|---|
| Заголовок | Как запись называется для человека. Из него автоматически получается адрес записи латиницей (sborka-trebuet-tulcheyn) — его можно поправить вручную. |
| Описание одной строкой | Самое важное поле. Именно по нему модель решает, открывать ли тело записи (см. как это доходит до модели). |
| Тип | Правило, факт или ловушка — см. типы. Выбирается по тому, что запись меняет для читателя. |
| Область | Вся организация или один проект разработки — см. области. |
| Тело | Markdown: что именно нужно знать. Ссылки на другие записи — [[имя-записи]]. |
| Показывать модели сразу | Запись приходит к модели целиком в каждой задаче, а не открывается по необходимости. |
| Перманентная | ИИ не может её изменить или убрать в архив. Вы — можете. |
Описание одной строкой — половина дела
Модель всегда видит индекс: строку на каждую запись вида «заголовок — описание». Тело она открывает только тогда, когда описание отвечает на её вопрос.
Поэтому описание пишется не как заголовок другими словами, а как ответ на вопрос «когда эта запись пригодится».
| Плохо | Хорошо |
|---|---|
| «Про тесты» | «Тесты падают, пока не поднято окружение» |
| «Правило про YAGNI» | «Делаем ровно то, что нужно текущей задаче — без «пригодится потом»» |
| «Модуль оплаты» | «Оплата ходит через внешний шлюз, тестовый контур поднимается отдельной командой» |
Тело
Коротко и по делу: что знать, как проверить, что делать. Модель читает его целиком, поэтому лишний текст — это лишние токены в каждом обращении к записи.
Хорошее тело отвечает на три вопроса:
- Что именно верно. «Тестам нужны запущенные сервисы, сами они не поднимаются».
- Как это проявляется. «Тесты падают с невнятной ошибкой подключения».
- Что делать. «Поднять окружение, дождаться готовности, затем прогонять тесты».
Связи с другими записями пишите как [[имя-записи]] — модель по ним переходит к смежному знанию.
Секреты
Редактор предупредит, если в теле похоже на токен, пароль или ключ. Это предупреждение, а не запрет: решаете вы. Но помните, что база знаний уходит в промпт модели — секретам там не место, а настоящий засвеченный секрет нужно менять, а не прятать.
Записи, которые пытается сделать ИИ, проверяются жёстче: запись с секретом сервер просто не примет.
Изменение записи
Запись меняется целиком: открыли, поправили, сохранили. Если за это время её успел изменить кто-то другой (человек или проход ИИ), сохранение не затрёт чужую правку — вы увидите предупреждение о конфликте и сможете свести изменения.