Obsidian и ИИ-агенты: как вести документацию проекта

Вы когда-нибудь тонули в тысячах строк заметок, пытаясь вспомнить, как работает конкретный модуль? На legacy-проектах это боль. Но Obsidian и ИИ-агенты могут превратить вашу документацию в удобную базу знаний, где агент сам находит нужное. В этой статье вы узнаете, как структурировать заметки с помощью MOC, чтобы ИИ-агент работал эффективно.

Что такое Obsidian и зачем он нужен

Obsidian — это приложение для заметок, которое хранит всё в виде обычных markdown-файлов. Оно позволяет гибко организовывать заметки, а благодаря тому, что файлы лежат на диске, любой агент, умеющий читать файловую систему, может получить доступ к вашей базе знаний.

Я использую Obsidian как личную документацию проекта: как работает система, почему принято то или иное решение, какие есть процессы. Это мой второй мозг.

Главная фишка, которая делает Obsidian удобным для агентов, — это связи. Obsidian позволяет создавать двунаправленные ссылки между заметками через [[Название заметки]]. Это превращает ваше хранилище из кучи файлов в граф, которому можно дать агенту одну точку входа.

Как я структурирую файлы

Obsidian гибок, и есть много способов организации. Вот мой вариант, который вы можете адаптировать под себя.

У меня две папки:

• MOC (Map of Content) — содержит по одному файлу на тему, названному <Тема> - MOC.
• Permanent Notes — все остальные заметки. Каждая заметка связана с MOC двунаправленно: в MOC есть ссылка на заметку, а в заметке — ссылка на MOC.

Пример структуры:

vault/
├── MOC/
│   └── Legacy Payments API - MOC.md
└── Permanent Notes/
    ├── Payments API - Endpoints.md
    ├── Payments API - Webhook Retry Logic.md
    ├── Payments API - Settlement Flow.md
    └── Payments API - Architecture Decisions.md

Сам MOC остаётся кратким:

# Legacy Payments API - MOC

Legacy-сервис для обработки карточных платежей.

## Ссылки

- [[Payments API - Endpoints]]
- [[Payments API - Webhook Retry Logic]]

## Дизайн

- [[Payments API - Settlement Flow]]
- [[Payments API - Architecture Decisions]]

В этом весь трюк: вместо того чтобы указывать агенту на папку и надеяться, что он прочитает нужное, вы указываете на один файл, который точно говорит, какие заметки важны и как они связаны. Вы контролируете контекст, а не позволяете файловой системе решать за вас.

Подключение агента к хранилищу

Никаких плагинов или интеграций не нужно. Так как заметки Obsidian — это просто markdown-файлы на диске, любой агент, умеющий читать файловую систему, может читать ваше хранилище.

Мой рабочий процесс прост: я открываю Claude в корне хранилища и прошу прочитать конкретный MOC-файл.

Прочитай MOC/Legacy Payments API - MOC.md и все заметки, на которые он ссылается.

Или можно вставить полный путь, если не хотите думать о том, откуда запущен агент.

Открывать нужно именно в корне, а не внутри MOC/, потому что ссылки ведут наружу. MOC лежит в одной папке, а заметки — в другой, и если агент ограничен папкой MOC/, ему придётся выходить за пределы рабочей директории, что может потребовать подтверждения доступа каждый раз.

Использование агента с MOC

Когда я начинаю исследовать тему, я сначала создаю MOC и даю агенту путь к нему.

На legacy-проекте это означало создать Legacy Payments API - MOC, а затем пройтись по кодовой базе, попросив Claude задокументировать эндпоинты API, бизнес-логику и процессы — каждый пункт ложился в отдельную постоянную заметку и связывался с MOC. Я также записывал архитектурные решения в хранилище, чтобы потом ссылаться на них, а не восстанавливать логику с нуля.

Когда MOC наполняется, он становится точкой входа для всего остального. Когда мне нужен план новой фичи, промпт примерно такой:

Прочитай MOC/Legacy Payments API - MOC.md и все заметки, на которые он ссылается.
Затем напиши план реализации частичного возврата в процессе расчётов.
Отметь всё, что в текущих заметках противоречит этому изменению.

Советы для эффективной работы

Прежде чем я пришёл к рабочей схеме, у меня было две проблемы.

Агенты пишут слишком много

Попросите агента задокументировать сервис — и получите целую книгу. Она становится слишком плотной для чтения человеком. Чем больше текста агент должен обработать, тем выше вероятность галлюцинаций.

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

Заметки устаревают

Новая информация всплывает в разговоре и никогда не попадает в хранилище, поэтому в следующий раз заметка будет неактуальной. Короткие заметки легче поддерживать. Если вы можете пробежаться по заголовкам за десять секунд, вы их обновите. Длинные заметки обновляются гораздо реже.

Что не стоит хранить в хранилище

Когда агент пишет за вас, возникает соблазн задокументировать всё, ведь это бесплатно. Но каждая строка, которую он пишет, — это строка, которую вы должны вычитать, и строка, которую агент будет читать при каждом следующем запуске.

Первое, что нужно вырезать, — детали кода. Не нужна заметка с перечислением всех параметров каждого метода или построчный разбор функций. Эта информация уже есть в самом коде.

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

Ещё два момента, которые я научился не включать.

Первое — рассуждения самого агента. Когда Claude решает задачу, он часто описывает ход мыслей: что отбросил, что проверил, почему пришёл к такому выводу. Это полезно читать в моменте, но в документе это шум.

Второе — всё, у чего есть авторитетный источник: документация фреймворков, справочники библиотек, тикеты с описанием требований, переписка в Slack, где было принято решение. Копирование этого в хранилище создаёт вторую копию, которая сразу начинает устаревать. Лучше поставьте ссылку.

Главная идея — держать заметки краткими и на высоком уровне, чтобы предотвратить галлюцинации ИИ-агента.

Хороший тест: если информация уже живёт в авторитетном источнике — репозитории, тикете, документации — дублировать её не нужно. Запишите то, что существует только в вашей голове.

Итоги

Документацию писать сложно, а поддерживать её актуальность ещё сложнее. На legacy-проекте без мейнтейнеров это отнимает всё время. Связка агента с Obsidian не убирает работу: вы всё равно вычитываете и синхронизируете. Но она меняет характер работы: вместо поиска информации вы проверяете её, а это гораздо проще.

Попробуйте этот подход на своём следующем проекте. Начните с создания MOC для одной темы и попросите агента заполнить его. Увидите разницу уже через неделю.