---
name: obsidian-documentation-rule
description: Все проекты документируются в локальном Obsidian vault (~/Documents/Obsidian Vault) — папка на проект + Overview/Architecture/Scenarios/Changelog/Decisions; обновляется после каждой реализованной задачи и сверяется с реальным кодом перед использованием
metadata: 
  node_type: memory
  type: feedback
  originSessionId: 93ae69a0-0326-487d-9594-f17d8193655b
---

Все проекты пользователя должны быть задокументированы и конспектированы в локальном Obsidian vault: **`/Users/cebers/Documents/Obsidian Vault/`**.

**Why:** Юзеру нужна единая база знаний про структуру, изменения, логику и сценарии использования всех своих проектов — чтобы не держать это в голове и чтобы я (и Gemini/Codex) могли сверяться с актуальным состоянием, а не галлюцинировать про чужой код. Vault установлен и пустой — структуру создаём по мере касания проектов.

**How to apply:**

1. **Расположение и структура.** Папка на проект внутри `Projects/`:
   ```
   /Users/cebers/Documents/Obsidian Vault/
     Projects.md                    ← MOC: индекс всех проектов с [[wiki-ссылками]]
     Projects/
       <project-name>/
         Overview.md                ← хаб проекта: что это, зачем, стек, точки входа, доступы, статус
         Architecture.md            ← модули, слои, потоки данных, БД-схема
         Scenarios.md               ← сценарии использования, user flows, edge cases
         Changelog.md               ← хронология что и когда сделано (новое сверху)
         Decisions.md               ← ADR: архитектурные решения с обоснованием
   ```
   В `Overview.md` всегда YAML-frontmatter с `status`, `stack`, `entry_points`, `last_updated` — для будущей фильтрации через Dataview. Связь между заметками — через `[[Architecture]]`, `[[Scenarios]]`, не через относительные пути.

2. **Когда писать/обновлять:**
   - **Первое касание проекта без записи в vault** → если в vault нет папки проекта, создать её и заполнить минимум `Overview.md` (+ запись в `Projects.md` MOC) **до начала работы**. Это касается и **давно существующих проектов** (cebers-pulse, avtero, zemlya-web, VakHunter, gaechkin, cebersrun, CebersPrint, TelegramWatch и т.д.) — если вижу проект впервые в Obsidian, надо его задокументировать на основе реального состояния кода, а не пропускать как «он же старый».
   - **После каждой реализованной задачи/спринта** → обновить `Changelog.md` (что сделано, дата, ссылка на коммит/PR если есть) и затронутые разделы (если поменялась архитектура — `Architecture.md`, если новый сценарий — `Scenarios.md`).
   - **При архитектурном решении** (выбор подхода/технологии, breaking change) → запись в `Decisions.md`.
   - **Не писать** на каждый микро-фикс — только содержательные изменения, иначе vault превратится в шум.

3. **Сверка перед использованием — обязательна.** Заметки могут устареть. Перед тем как опираться на инфу из Obsidian (например, «в проекте используется X»), проверить актуальность через чтение реального кода/конфигов. Никогда не выдавать содержимое заметки за факт, не сверившись.

   **Если нашёл расхождение** между Obsidian и реальным состоянием проекта — **не править молча в одну сторону**. Возможны три варианта:
   - заметка устарела → нужно обновить заметку под код;
   - код отклонился от изначального замысла → нужно поправить код (или Decisions.md, если отклонение было осознанным и не записано);
   - оба пути могут быть правильным ответом.

   **Сценарий действий:** показать юзеру конкретное расхождение (что говорит Obsidian, что в коде, путь к файлу), спросить «как правильно?», и **после ответа синхронизировать оба места одной правкой**: обновить заметку И при необходимости поправить код/конфиг, чтобы они снова совпадали. Расхождение фиксировать в `Changelog.md` затронутого проекта.

4. **Логика Obsidian (для самопроверки):**
   - Vault = просто папка с `.md` файлами на диске. Никакой БД.
   - Связи между заметками — `[[wiki-ссылки]]` (имя файла без `.md`), они дают backlinks и граф.
   - YAML-frontmatter в начале файла — это properties (для фильтрации/Dataview).
   - MOC (`Projects.md`) — индексная заметка-хаб, заменяет «папочную» навигацию.

5. **Перекрытие с auto-memory:** auto-memory (этот файл и соседи) — про **меня и стиль работы с юзером**, кратко и долгоживуще. Obsidian — про **проекты юзера**, детально и обновляемо. Не дублировать содержимое: в memory остаётся «overview-в-одну-строку + указатель», глубокая инфа живёт в vault.

Это правило также продублировано в `~/.gemini/GEMINI.md` (§10) и `~/.codex/AGENTS.md` — для Gemini CLI и Codex соответственно.

Связано: [[cebers_pulse_overview]], [[avtero_overview]], [[zemlya_web_overview]], [[vakhunter_overview]], [[cebersrun_overview]], [[gaechkin_planning]] — у всех у них есть auto-memory short-form, но детальная документация в vault'е пока не создана; при следующем касании каждого из них — заводить папку в Obsidian.
