# Запись

> Из чего состоит знание: заголовок, описание одной строкой, тип, область, тело и два признака. Как написать так, чтобы модель этим воспользовалась.

Одна запись — **один факт**. Не «всё про тесты», а «тесты падают без поднятого окружения».

_Иллюстрация: Редактор: заголовок и адрес, описание одной строкой, тип и область, тело в markdown, два признака._

## Поля

| Поле | Зачем |
| --- | --- |
| **Заголовок** | Как запись называется для человека. Из него автоматически получается **адрес** записи латиницей (`sborka-trebuet-tulcheyn`) — его можно поправить вручную. |
| **Описание одной строкой** | Самое важное поле. Именно по нему модель решает, открывать ли тело записи (см. [как это доходит до модели](/docs/knowledge/prompt)). |
| **Тип** | Правило, факт или ловушка — см. [типы](/docs/knowledge/types). Выбирается по тому, что запись меняет для читателя. |
| **Область** | Вся организация или один проект разработки — см. [области](/docs/knowledge/scopes). |
| **Тело** | Markdown: что именно нужно знать. Ссылки на другие записи — `[[имя-записи]]`. |
| **Показывать модели сразу** | Запись приходит к модели целиком в каждой задаче, а не открывается по необходимости. |
| **Перманентная** | ИИ не может её изменить или убрать в архив. Вы — можете. |

## Описание одной строкой — половина дела

Модель всегда видит **индекс**: строку на каждую запись вида «заголовок — описание». Тело она открывает только тогда, когда описание отвечает на её вопрос.

Поэтому описание пишется не как заголовок другими словами, а как ответ на вопрос «когда эта запись пригодится».

| Плохо | Хорошо |
| --- | --- |
| «Про тесты» | «Тесты падают, пока не поднято окружение» |
| «Правило про YAGNI» | «Делаем ровно то, что нужно текущей задаче — без «пригодится потом»» |
| «Модуль оплаты» | «Оплата ходит через внешний шлюз, тестовый контур поднимается отдельной командой» |

## Тело

Коротко и по делу: что знать, как проверить, что делать. Модель читает его целиком, поэтому лишний текст — это лишние токены в каждом обращении к записи.

Хорошее тело отвечает на три вопроса:

1. **Что именно верно.** «Тестам нужны запущенные сервисы, сами они не поднимаются».
2. **Как это проявляется.** «Тесты падают с невнятной ошибкой подключения».
3. **Что делать.** «Поднять окружение, дождаться готовности, затем прогонять тесты».

Связи с другими записями пишите как `[[имя-записи]]` — модель по ним переходит к смежному знанию.

## Секреты

Редактор предупредит, если в теле похоже на токен, пароль или ключ. Это предупреждение, а не запрет: решаете вы. Но помните, что база знаний уходит в промпт модели — секретам там не место, а настоящий засвеченный секрет нужно менять, а не прятать.

Записи, которые пытается сделать **ИИ**, проверяются жёстче: запись с секретом сервер просто не примет.

## Изменение записи

Запись меняется целиком: открыли, поправили, сохранили. Если за это время её успел изменить кто-то другой (человек или проход ИИ), сохранение не затрёт чужую правку — вы увидите предупреждение о конфликте и сможете свести изменения.