write-anti-patterns.md

Write Anti-Patterns

Purpose

Цей документ описує типові помилки при write/update workflow у memory-system.

Anti-patterns

1. Створювати новий note, коли вже є canonical doc

Погано:

• нова інформація явно стосується існуючої сутності;
• агент все одно створює ще один ізольований note.

Правильно:

• спочатку пройти write gate;
• якщо canonical doc знайдено і нова інформація його розширює, оновити існуючий документ.

2. Створювати новий decision, коли змінився лише контекст

Погано:

• проблема в уточненні поточного контексту;
• агент дублює архітектурне рішення замість оновлення context.

Правильно:

• новий decision створюється лише тоді, коли змінюється саме рішення, а не його пояснення.

3. Писати архітектурні пояснення в task

Погано:

• task перетворюється на довгу змішану документацію.

Правильно:

• task зберігає execution-state;
• пояснення йдуть у concept, decision, context або entity.

4. Оновлювати canonical doc без links

Погано:

• документ містить текст, але не має зв'язків;
• retrieval не може поставити його в підграф.

Правильно:

• будь-який новий або оновлений doc має бути змістовно залінкований.

5. Замінювати історію рішень переписуванням старого decision

Погано:

• старий decision повністю переписується під новий зміст.

Правильно:

• нове рішення оформлюється новим decision;
• старий документ переводиться в superseded через supersedes/superseded_by.