# Recipes

> Where to start a knowledge base, what to write for a legacy project, what never to write, and how to tell an entry is bad.

## Where to start

Create three or four entries and no more — the base grows by itself.

**1. The organisation’s development rules** (scope: organisation, “show to the model upfront”):

> **YAGNI, always**
> We do exactly what the current task needs — no “might come in handy later”
> No abstractions for the future, no configurators and layers for a single consumer. A second real consumer — that is when we generalise.

**2. Language and style** (organisation, “show to the model upfront”):

> **We answer and comment in Russian**
> The language of communication and code comments is Russian; entity names are in English

**3. What the project is** (project, type “fact”):

> **This is a project reverse-engineering protocol X**
> There is no specification: behaviour is worked out from the traffic and the client code

## A space without code

A department without a repository gets the same three or four entries, only about documents — scope: the space.

**Rule:**

> **We answer a customer within one working day**
> The deadline for answering a customer on any channel is the end of the working day of the request
> If the answer needs approval, the customer gets confirmation that the request has been received, and the deadline, on the same day.

**Fact:**

> **The current price list is in the Sales/Price lists folder**
> Take current prices only from this folder; prices in old commercial proposals are out of date

**Pitfall:**

> **The 2024 procurement regulation is outdated — use the 2026 edition**
> The folder holds both editions; thresholds, approval procedure and the number of quotes follow the 2026 edition
> 2024 edition: thresholds 50/300 thousand, approval by email. 2026 edition: 100/500 thousand, electronic document exchange, three quotes from 200 thousand, a lawyer checks auto-renewal.

A discrepancy between documents found by an answer is a ready candidate for a pitfall: until the documents are put in order, the entry says which one to trust. A selection by department is in [Recipes by role](/en/docs/roles).

## A legacy project

A poorly documented project is the case where the knowledge base pays off immediately. What to write down:

- **what is really going on here** — the reports module calculates something other than what its name says;
- **what must not be touched** — “the calculation module is frozen until the migration; changes only by agreement”;
- **how to run it** — build and test pitfalls that cannot be read from the README;
- **what it used to be** — “the code was carried over from the old system as is; the style was not brought into line”.

## Environment pitfalls

The AI usually writes these itself, but it helps to write the first one or two by hand — they set the pattern:

> **Tests fail without the environment up**
> Bring the environment up first, then run the tests
> Without running services, the tests fail with an unclear connection error. Order: bring the environment up, wait until it is ready, then run the tests.

## What not to write

| Do not write | Why |
| --- | --- |
| Directory structure, paths, file names | Read from the code, and the first to go stale |
| A retelling of the README | The model will read the README itself |
| A one-off fix | It is already in the code, the reason in the commit |
| Work state (“we are now doing task No. 12”) | Stale by evening |
| Secrets, tokens, passwords | Goes into the prompt; there are [credentials](/en/docs/repositories) for access |
| Long texts “just in case” | Every opening of an entry costs tokens |

## Signs of a bad entry

- **The description repeats the title.** The model will not understand when to open it.
- **Three topics in one entry.** Split it: one entry — one fact.
- **An entry that cannot be checked.** “Everything is complicated here” is not knowledge.
- **A rule without justification where it is not obvious.** In a month it will be dropped as incomprehensible.

## Regular hygiene

Every couple of weeks:

1. the **“Written by AI”** filter — look through what the model has learned in that time;
2. the **“Need review”** filter — entries where the consolidation pass found a discrepancy with the code;
3. the **“Always visible”** filter — check that what the model receives in full in every task has not grown too large.

The [consolidation pass](/en/docs/knowledge/passes) will do the rest.