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

• Скачаем и настроим Obsidian
  
• Создадим структуру базы знаний
  
• Интегрируем Obsidian с Claude
  
• Разберём, как писать код с ИИ в команде с другими разработчиками

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

.
|-- 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 - корневой файл
  В нём нужно указать ссылки на корневые файлы всех ваших разделов и дать описание к ним. Агент должен чётко понимать, какую роль выполняет каждый из них. Также опишите особые инструкции по работе с базой знаний.

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

• README.md
  
• context.md
  
• structure.md

# Роль и задача
Ты - профессиональный 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. Задача выполнена (если нет дополнительных требований от базы знаний, или от пользователя)

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

• В настройках проваливаемся в Community plugins
  
• Ещё раз проверяем что плагин Local REST API включен
  
• Нажимаем на настройки плагина
  
• Копируем API-ключ и хост (обычно это https://127.0.0.1:27124/)
  
• Скачиваем и устанавливаем сертификат либо включаем Non-encrypted HTTP Server и копируем соответствующий адрес

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

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

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

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

.claude
!.claude/settings.json

• Проверяйте на каждом этапе что именно пишет модель в базу знаний. Плохие данные = плохие ответы. Не превращайте базу знаний в мусорку мыслей ИИ.
  
• Помните, что база знаний будет приносить пользу в первую очередь вам.
  
• Формируйте базу знаний как документацию по проекту, не делайте упор на работу с ИИ.
  
• Пишите подробные промпты. В каждом разделе базы знаний можно в самом низу написать заголовок Для агентов и дать более конкретные инструкции.
  
• Старайтесь всегда давать модели подробные инструкции.
  
• Если вы пишите часть кода самостоятельно, дайте агенту задачу проанализировать ваши действия и актуализировать базу знаний.

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