Веб-разработкаОПУБЛИКОВАНО ОБНОВЛЕНО 6 МИН ЧТЕНИЯ

Claude Code + Obsidian без плоского журнала (flat log)

Когда я только начал пользоваться Claude Code, я задал ему одно простое правило в конфигурации: после каждого изменения кода записывать, что изменилось, зачем это было сделано и что это дало проекту - всё в один файл с названием RESULTS.md. Правило сработало даже слишком хорошо. Уже через неделю работы над проектом файл разросся до 407 строк, и читать его стало сложнее, чем сам код. Тогда я подключил Claude Code к Obsidian и изменил всего одну привычку: вместо того чтобы постоянно дописывать один большой файл, агент теперь создаёт одну небольшую заметку для каждого исправления и связывает их между собой. Настройка занимает около пяти минут. В этой статье я покажу весь процесс, разберу шаблон заметки из четырёх частей, благодаря которому всё работает, и расскажу, что вы получаете в итоге - заметки, которые действительно удобно читать, и одну страницу, где всегда видно текущее состояние проекта.

TL;DR

  • Один большой журнал со временем становится нечитаемым - и для вас, и для агента, который его написал. Одна небольшая заметка на каждое исправление всегда показывает текущее состояние.
  • Подключить Claude Code к Obsidian можно примерно за пять минут: один плагин, один ключ и одна команда.
  • Главное преимущество - это шаблон заметки из четырёх частей: «Изменено», «Что изменилось», «Польза» и «Проверено», который делает каждую заметку короткой, понятной и честной.

Почему один большой файл с результатами перестаёт работать

Старая система была хорошей идеей, которая просто перестала помещаться в один файл.

Когда я настраивал Claude Code, в его конфигурации было всего одно правило: после каждого изменения кода записывать шаги, что изменилось, зачем это было сделано и какую пользу принесло - всё в RESULTS.md. Первые несколько дней это работало отлично. Я мог открыть один файл и увидеть всё, что сделал агент, и почему.

Но файл продолжал расти. Уже через неделю в нём было 407 строк: одиннадцать записей для восьми реальных исправлений - и четыре из них относились к одному и тому же исправлению:

  • ## F1 — Серверный рендеринг всего коммерческого контента · Статус: частично
  • ## F1 (доработано) — Серверный рендеринг РЕАЛЬНОГО интерфейса продукта · Статус: выполнено, обнаружена одна регрессия
  • ## F1 (финальная версия) — Все карточки категорий присутствуют в DOM · Статус: выполнено, обнаружен один пробел
  • ## F1 (завершено) — Подключены все безлимитные тарифы, 100% покрытие планов · Статус: выполнено

Чтобы понять, что действительно попало в релиз, приходится прочитать все четыре записи и надеяться, что последняя - актуальная. Файл отлично отвечал на вопрос «что произошло», но совершенно не отвечал на единственный вопрос, который действительно важен утром в понедельник: «где мы сейчас?»

Агент не делал ничего неправильно. Я сказал ему дописывать всё в один файл - он именно это и делал. Файл, в который можно только дописывать, неизбежно будет только расти.

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

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

Одна заметка на каждое исправление: шаблон, который действительно работает

Одна заметка на каждое исправление: шаблон, который работает

Решением оказался не инструмент, а шаблон.

Всё ниже - это один небольшой абзац в файле проекта CLAUDE.md. Он говорит агенту вести два типа заметок:

  • Goals/{Goal Name}.md - одна заметка с общей картиной для каждой цели: что мы создаём, правила, таблица статуса, текущие результаты и открытые вопросы.
  • {Goal Name}/{Item}.md - одна небольшая заметка для каждого исправления или решения.

Каждая небольшая заметка состоит из четырёх частей:

  1. Изменено - какие файлы были затронуты.
  2. Что изменилось - два–четыре простых предложения.
  3. Польза - что это даёт, простыми словами.
  4. Проверено - какие команды были выполнены и что они показали.
Одно исправление, одна заметка: четыре коротких раздела.

Раздел «Проверено» делает заметки честными. Он заставляет агента записывать то, что действительно было запущено, а не то, что только планировалось выполнить. В одной из моих заметок он сам добавил такую запись: «локальный бэкенд возвращает price: 1 для всех тарифов, поэтому значения цен можно проверить только на preview — локально проверяется только структура». До Obsidian подобная деталь оставалась в окне чата и исчезала уже через несколько дней.

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

Каждая заметка заканчивается ссылками - на заметку с целью, а также на предыдущее и следующее исправление. Эта одна строка превращает папку с файлами в карту, по которой действительно можно ориентироваться.

Подключите Claude Code к Obsidian за пять минут

Установите один плагин, скопируйте один ключ и выполните одну команду.

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

  1. В Obsidian откройте Community plugins и установите Local REST API with MCP от Adam Coddington. Поддержка MCP появилась в версии 5.0.0 24 июля 2026 года; я использую 5.0.2 вместе с Obsidian 1.12.7.
  2. Откройте Settings → Local REST API и скопируйте API-ключ.
  3. Зарегистрируйте сервер в Claude Code:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \ --header "Authorization: Bearer YOUR_API_KEY" \ --scope user

Затем убедитесь, что всё работает: команда claude mcp list должна показать сервер и его статус, а команда /mcp внутри сессии - список доступных инструментов. Вы должны увидеть 16 инструментов с такими именами, как vault_read, vault_write, vault_patch и search_query.

Шестнадцать инструментов vault означают, что подключение работает.

Есть одна вещь, которая обычно занимает большую часть этих пяти минут: сертификат. Порт 27124 использует HTTPS с самоподписанным сертификатом, и строгие клиенты отклоняют его без каких-либо сообщений об ошибке:

curl https://127.0.0.1:27124/ # ничего не возвращает - сертификат отклонён curl -k https://127.0.0.1:27124/ # {"status":"OK","service":"Obsidian Local REST API", ...}

Есть два простых решения: доверить сертификат (плагин отдаёт его по адресу https://127.0.0.1:27124/obsidian-local-rest-api.crt) или включить обычный HTTP-сервер в настройках плагина и использовать http://127.0.0.1:27123/mcp/.

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

Настройте один раз и используйте в каждом проекте

Вы настраиваете это один раз. После этого все новые проекты получают подключение автоматически.

Claude Code может запоминать подключение на трёх уровнях, и именно уровень определяет, насколько широко оно будет использоваться:

  • local (по умолчанию) - только для текущего проекта; сохраняется в ~/.claude.json.
  • project - только для текущего проекта, но разделяется с командой через Git; сохраняется в .mcp.json внутри репозитория.
  • user - для всех ваших проектов; сохраняется в ~/.claude.json.

--scope user - лучший выбор по двум простым причинам. Хранилище Obsidian принадлежит вам, а не проекту. Кроме того, API-ключ - это пароль. Если использовать уровень проекта, этот пароль окажется сохранённым в репозитории и станет доступен всем.

{ "mcpServers": { "obsidian": { "type": "http", "url": "https://127.0.0.1:27124/mcp/", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } }

Этот блок записывается один раз в ~/.claude.json и затем автоматически используется во всех проектах на этом компьютере. Единственное, что нужно сделать для каждого нового проекта, - добавить один небольшой абзац в CLAUDE.md: указать, где хранить заметки, и использовать шаблон из второго раздела статьи. Если добавить строку repo: в каждую заметку с целью (у меня это repo: roamify-web), один vault сможет хранить заметки сразу для нескольких проектов, не смешивая их между собой.

И ещё одна полезная деталь: если один и тот же сервер определён сразу на двух уровнях, приоритет такой - local выше project, а project выше user. Используется только определение с наивысшим приоритетом.

Что вы получаете

Теперь те же восемь исправлений находятся в девяти небольших заметках - вместе они занимают меньше половины объёма старого файла и читать их гораздо проще.

Самое большое изменение очень простое: теперь обновления заменяют старый текст, а не накапливаются поверх него. Исправление F1 существует как одна заметка со статусом done; трёх устаревших версий больше нет, потому что агент редактирует существующую заметку, а не дописывает новую информацию внизу.

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

Обзор проекта: статус, результаты, открытые вопросы.

Если говорить совсем просто, вы получаете следующее:

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

Четыре небольших совета перед началом:

  • Без шаблона в CLAUDE.md агент будет придумывать новую структуру заметок в каждой сессии - именно шаблон делает всю систему рабочей.
  • Просите агента использовать vault_patch для обновлений; vault_write полностью перезаписывает заметку. Хранить vault в Git - простая и надёжная страховка.
  • Время от времени проверяйте раздел Verified - модель может написать «сборка проходит», даже если она её не запускала.
  • Граф Obsidian - это красивая визуализация, а не рабочий инструмент; настоящая ценность находится в ссылках между заметками.

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

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

Октай Искендеров

Дизайнер и фулстек-разработчик, веду klauzzdcode - студию одного человека в Баку. На фрилансе с 2023 года: выкатываю продукты от Figma до деплоя и записываю то, что переживает контакт с продакшеном.

ИСТОРИЯ →

FAQ

Нужен ли мне MCP-плагин, или Claude Code может просто редактировать папку vault напрямую?

Работают оба варианта. MCP особенно удобен, если vault находится вне репозитория, если вы хотите, чтобы агент обновлял существующие заметки вместо их полной перезаписи, и если не хотите смешивать документацию с Git-историей проекта.

Работает ли Obsidian MCP Server, если Obsidian закрыт?

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

Почему Claude Code не может подключиться к https://127.0.0.1:27124?

Порт 27124 использует HTTPS с самоподписанным сертификатом, который строгие клиенты отклоняют. Доверьте сертификат из настроек плагина или включите обычный HTTP-сервер и подключайтесь к порту 27123.

Можно ли поделиться настройкой Obsidian MCP с командой?

Самим подключением - нет. Использование уровня project сохранит ваш API-ключ в репозитории, где его увидят все. Лучше оставить подключение на уровне user, а шаблон заметок распространять через CLAUDE.md проекта.

Чем это отличается от README или CHANGELOG?

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