Разработка с Obsidian + Claude. Практический гайд

Содержание

В этой статье я расскажу, как усилить процесс разработки с применением ИИ на базе Obsidian и любого ИИ-агента, который умеет работать с MCP. В качестве примера будем использовать Claude.

Статья практическая. Покажу, как организовать базу знаний для проекта, как настроить нужные плагины и как конфигурировать Obsidian с Claude. Решение подойдет как для новых проектов, так и для существующих.

План действий:

1. Скачаем и настроим Obsidian

2. Создадим структуру базы знаний

3. Интегрируем Obsidian с Claude

4. Разберём, как писать код с ИИ в команде с другими разработчиками

Проблема и решение

Немного о проблемах, с которыми каждый из нас сталкивается при работе с ИИ:
Потеря памяти — при разработке проекта с агентом вы наверняка устали от переполнения контекста. А если начать новый чат, так и вообще приходится заново всё объяснять.
Лимиты на токены быстро исчерпываются даже на небольших задачах.

На просторах интернета вы наверняка уже видели, как многие говорят о волшебной связке ИИ с Obsidian.

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

Такой подход даёт множество преимуществ:

1. Можно начинать новый чат на каждую новую задачу, и модель не будет терять контекст.

2. Расход токенов падает в разы, так как ИИ не анализирует весь код при каждом запросе.

3. Можно работать с ИИ в команде с другими разработчиками (базу знаний легко интегрировать в отдельный Git-репозиторий)

4. У вас появляется полноценная документация по проекту

5. И многое другое. От ускоренного онбординга новых разработчиков до чат-ботов для клиентов (только не отдавайте клиентам бота со всей базой знаний, а то ваш сервис долго не проживёт)

Что такое Obsidian

Для тех забыл или не знаком с Obsidian.

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

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

Настройка Obsidian

Первым шагом скачиваем Obsidian с официального сайта.

После скачивания открываем и нажимаем на Create.

Агенты будут работать с Obsidian через MCP. Для этого в Obsidian есть отдельный плагин. Открываем настройки, проваливаемся в Community Plugins, нажимаем Browse и ищем плагин Local REST API (прямая ссылка на расширение — obsidian://show-plugin?id=obsidian-local-rest-api). Устанавливаем и включаем его.

Теперь задаём структуру базы знаний. Создавайте древовидную структуру, в каждой папке желательно иметь index-файл с ссылками на дочерние файлы, кратким описанием и, при необходимости, особыми инструкциями для агентов по работе с этим разделом. Адаптируйте её под свои нужды. Можно использовать ИИ для генерации основных разделов и корневых файлов.

Рассмотрим абстрактный пример под разработку интернет-магазина.

.|-- daily-changes|   |-- index.md|   └-- YYYY-MM-DD.md|-- context|   |-- index.md|   |-- техническое задание|    |-- index.md|    |-- термины и сокращения.md|    |-- технологические требования.md|    |-- описание задачи.md|    └-- ...| └-- записи встреч|     |-- index.md|     |-- kik-off по реализации с командой.md|     |-- обсуждение 1-го экрана.md|     └-- ...|-- structure|   |-- index.md|   |-- client|       |-- index.md|       |-- components|       |-- features|       |-- ...|   |-- server|       |-- index.md|       |-- database|           |-- index.md|           |-- ...|       |-- endpoints|       |-- ...|-- README.md

• daily-changes — логирование изменений агентом и разработчиком
  В файле index.md опишите агенту что и в каком формате надо логировать. Сделайте пустую таблицу формата ссылка + краткое описание. Поможет агенту помнить что происходило на той неделе.

• context — полезная информация о проекте
  В файле index.md сделайте таблицу ссылка + краткая информация о документе. Также опишите в этом файле характер информации.

• structure — структура кодовой базы + документация к ней
  В index.md опишите ключевую техническую информацию. Добавьте ссылки на отдельные сервисы вашего проекта: в текущем примере это папки client и server.

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

  Это основной раздел, с которым будет работать агент. Потому информация в нём должна полностью отражать текущее состояние вашего кода.

  Следите за размером файлов в этом разделе, и время от времени просите ИИ дробить файлы на части если агент сильно увлечется очередной фичей.

• README.md — корневой файл
  В нём нужно указать ссылки на корневые файлы всех ваших разделов и дать описание к ним. Агент должен чётко понимать, какую роль выполняет каждый из них. Также опишите особые инструкции по работе с базой знаний.

Пример README.md

# Содержание- [[context/index|context]] - Глобальная информация о проекте. Технические задания, референсы, требования к проекту, и другая полезная информация- [[daily-changes/index|daily-changes]] - Сводки изменений в процессе разработки проекта и изменений в базе знаний- [[structure/index|structure]] - Структура проекта, описывающая все части данной программы/сервиса. Необходимо учитывать при внесении изменений, и актуализировать при каждом изменении. Информация в этой папке должна полностью отвечать на вопросы как и для чего написан каждый отдельный файл в проекте.## Для агентовВ каждом разделе есть index файл с описанием раздела и требованиям к работе с ним.При добавлении артефакта, необходимо следить за его размером, большие файлы нужно выносить в отдельные папки и разбивать на небольшие файлыПри внесении изменений в базу знаний нужно задокументировать внесённые изменения в раздел [[daily-changes/index|daily-changes]] (требования к документированию этого раздела внутри).

Обязательно поэкспериментируйте с промптом. От качества ваших инструкций зависит качество работы ИИ, не забывайте это.

Для небольшого проекта можно начать с простой версии:

• README.md

• context.md

• structure.md

Настройка проекта

Переходим к вашему проекту. Заходите в директорию проекта из которой вы планируете работать с Claude или другим агентом.

CLAUDE.md

Создайте в корне проекта файл CLAUDE.md (или AGENTS.md, если используете не Claude). Этот файл будет по умолчанию включаться в ваш запрос к ИИ. С Claude это работает достаточно стабильно, если ваш агент что-то делает не так, попробуйте явно сослаться на этот файл.

Здесь мы напишем основной промпт, который опишет агенту, как работать с вашими запросами.

Пример:

# Роль и задача  Ты - профессиональный Software Developer, работающий в рамках одного конкретного проекта.Твоя задача - на основе базы знаний Obsidian (доступно по MCP) и полученной команды внести требуемые изменения в кодовую базу, и, при необходимости, в саму базу знаний.    ## Как отвечать на задачу пользователя  При первом получении запроса изучи README файл в Obsidian. Найди и прочитай информацию, которая поможет тебе в решении задачи.  ### Пример реализации технической задачи  `Корневая архитектура базы знаний (по разделам, предположим, что в каждом разделе глубокая древовидная структура со всей необходимой информацией) (может отличаться в проекте, актуальная структура находится в README Obsidian):`  - Контекст (данные о проекте, технические задания, бизнес-требования, записи встреч, просьбы заказчика)  - Стек (базовые технические требования, общий/клиентский/серверный стек технологий)  - Структура (техническая документация о всём проекте, структурно повторяет технический проект, описывает его функционал и объясняет почему функционал реализован тем или иным образом)    `Запрос пользователя:`  Создай форму авторизации в приложении и напиши запрос на сервер.  `Твои действия (пример):`1. Зашёл в Obsidian, увидел что в базе знаний есть информация о стеке, структуре проекта, и раздел с контекстной информацией2. Прочитал информацию о стеке клиента и о стеке сервера;  3. В разделе контекста находишь информацию о требованиях к авторизации из технического задания4. В базе знаний из раздела структуры находишь конкретное места в клиенте где необходимо внести изменения, а так же находишь реализованный механизм на сервере.  5. Вносишь изменения в кодовую базу на клиенте, основываясь на полученной информации.  6. Дополняешь в Obsidian раздел структуры, так как ты внес изменения и добавил новый функционал.  7. Задача выполнена (если нет дополнительных требований от базы знаний, или от пользователя)  ### Пример реализации задачи связанной с базой знаний  `Корневая архитектура базы знаний (по разделам, предположим, что в каждом разделе глубокая древовидная структура со всей необходимой информацией):`  - Данные (данные о проекте, технические задания, бизнес-требования, записи встреч, просьбы заказчика) - разделен на сырые данные (docx файлы, аудиозаписи) и на *parsed*-данные (md файлы с древовидной структурой)  - Список изменений (логирование вносимых изменений в базу знаний, ежедневная разбивка и отдельно разбивка по версиям)  `Требования к работе с базой знаний:` Все файлы хранятся в древовидной структуре. От корневого файлы должна быть возможность по ссылкам попасть в любой дочерний файл.  `Запрос пользователя:` Прочитай docx файл ТЗ и преобразуй его в новый модуль базы знаний в контексте.  `Твои действия: `  1. Прочитал README Obsidian  2. Узнал что в базе знаний есть раздел `Данные`, где предположительно должно быть ТЗ. Там две ссылки, на разделы parsed и на раздел raw. Файл ТЗ предположительно должен быть в raw.  3. По ссылкам в данных нашёл техническое задание в raw данных.  4. Начинаешь обработку задания и преобразование его в удобный, древовидный формат чтения в базе знаний  5. Создаешь папку 'ТЗ' в parsed, и index.md файл в ней  6. В новом index.md файле описываешь разделы ТЗ и ссылки на дочерние документы. Создаешь дочерние папки и файлы если требуется  7. В parsed/index.md добавляешь ссылку на корневой раздел ТЗ (так как это написано в требованиях базы знаний)  8. Задача выполнена (если нет дополнительных требований от базы знаний, или от пользователя)

Рекомендую указывать примеры запрос/ответ чтобы добиться наилучшего результата. Промпт-инженеры — ваш выход.

Этот файл можно коммитить в ваш проект, если не боитесь общественного осуждения.

Настройка .mcp.json

Ваш агент будет общаться с базой знаний через MCP благодаря установленному в Obsidian плагину.

Ниже процесс настройки MCP для Claude, для других агентов изучите их техническую документацию.

Для этого, в корне проекта создайте файл .mcp.json

{  "mcpServers": {  "obsidian": {  "command": "npx",  "args": ["-y", "obsidian-semantic-mcp"]      }}}

PS. на момент написания статьи obsidian-semantic-mcp находится в архиве и считается deprecated. Разработчики рекомендуют переходить на obsidian-mcp-plugin (GitHub) — но он пока в бета-версии, рекомендую открыть ссылку и проверить, не вышла ли стабильная версия.

Теперь вернёмся в Obsidian

1. В настройках проваливаемся в Community plugins

2. Ещё раз проверяем что плагин Local REST API включен

3. Нажимаем на настройки плагина

4. Копируем API-ключ и хост (обычно это https://127.0.0.1:27124/)

5. Скачиваем и устанавливаем сертификат либо включаем Non-encrypted HTTP Server и копируем соответствующий адрес

Теперь надо настроить окружение. Тут два варианта:

1. Создать/дополнить ваш файл .env

2. Вписать окружение прямо в .mcp.json (Obsidian у нас развёрнут локально, потому раскрыть API-ключ в целом не страшно)

Первый вариант через .env в корне проекта

OBSIDIAN_API_KEY=Скопированный ключOBSIDIAN_API_URL=Скопированный хостOBSIDIAN_VAULT_NAME=Название вашего хранилища obsidian, которое вы задавали при его создании

Второй вариант, прямо в .mcp.json

{  "mcpServers": {  "obsidian": {  "command": "npx",  "args": ["-y", "obsidian-semantic-mcp"],"env": {"OBSIDIAN_API_KEY": "Скопированный ключ",        "OBSIDIAN_API_URL": "Скопированный хост",        "OBSIDIAN_VAULT_NAME": "Название вашего хранилища Obsidian, которое вы задавали при его создании"}    }}}

Если переменные окружения вынесены в .env, файл .mcp.json можно коммитить. В противном случае — лучше не надо, так как у OBSIDIAN_API_KEY слишком низкий шанс совпасть с ключом вашего коллеги.

Настройка Claude в проекте (опционально)

Для удобства, можно сразу в корне проекта сделать папку .claude и записать в неё settings.json. Не нужно будет каждый раз подтверждать операции с Obsidian и указывать MCP.

{  "permissions": {    "allow": [      "mcp__obsidian__vault",      "mcp__obsidian__edit",      "mcp__obsidian__view"    ]  },  "enabledMcpjsonServers": [    "obsidian"  ]}

Файл можно коммитить, и лучше сразу расширить ваш .gitignore

.claude  !.claude/settings.json

Установка Claude

Если вы ещё не скачали Claude, переходите на официальный сайт.

Для VS Code у них есть неплохое расширение, рекомендую его установить. В остальных случаях скачиваем утилиту для терминала.

Проверяем настройки

Перезапустите VS Code чтобы Claude увидел свои настройки.

В новом чате напишите команду /mcp

Поздравляю, вы всё правильно настроили.

Для финального теста уточните в чате, видит ли агент ваш Obsidian. Если всё хорошо, то начните с формирования базы знаний.

Как работать ещё эффективнее?

Рекомендую давать агенту данные небольшими объемами и давать подробные инструкции по ведению базы знаний (особенно в первое время).

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

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

А ещё:

• Проверяйте на каждом этапе что именно пишет модель в базу знаний. Плохие данные = плохие ответы. Не превращайте базу знаний в мусорку мыслей ИИ.

• Помните, что база знаний будет приносить пользу в первую очередь вам.

• Формируйте базу знаний как документацию по проекту, не делайте упор на работу с ИИ.

• Пишите подробные промпты. В каждом разделе базы знаний можно в самом низу написать заголовок Для агентов и дать более конкретные инструкции.

• Старайтесь всегда давать модели подробные инструкции.

• Если вы пишите часть кода самостоятельно, дайте агенту задачу проанализировать ваши действия и актуализировать базу знаний.

Работа в команде

Данный подход хорошо укладывается в командную разработку. Но закладывать фундамент базы знаний лучше одному разработчику.

Базу знаний Obsidian добавьте в отдельный Git-репозиторий, не забывайте обновляться и грамотно решать конфликты версий.

Частые ошибки

• ИИ не вносит необходимые изменения? Вероятно, нужно поработать с промптами, попробуйте более подробно описать работу с частью, в которой возникают проблемы. При грамотных инструкциях внесение изменений будет работать стабильно, по крайней мере мне удалось этого достичь в крупном монорепозитории с тремя приложениями и пятью пакетами.

• Не подключается MCP? Проверьте, что Obsidian и плагин Local REST API запущены, откройте хост в браузере, в ответе должен быть status: ok. Нажмите кнопку Reconnect или выполните команду npx -y obsidian-semantic-mcp (не забудьте добавить необходимые переменные окружения, если вы не создавали файл .env). Лог ошибки поможет понять в чём дело.

• ИИ не видит инструкций? Явно укажите на ваш файл CLAUDE.md

Всегда ли это нужно?

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