Spec Kit пишет спеку до кода, агент по ней кодит, и .md-файлов в репозитории становится в разы больше. Документация настоящая: по ней работают.
Через месяц у тебя папка Markdown, которую открыть некому. Продакт, который эту спеку заказывал, читать её не будет.
Я перебрал четыре способа с этим жить. Рассказываю по порядку, чем каждый плох, и что выбрал в итоге.
Почему документация вообще уехала в репозиторий
Агент читает локальные файлы. То, что лежит рядом с кодом, а не то, что живёт в Confluence за логином.
Git к этому прилагается бесплатно: история правок, ревью в пулл-реквесте, работа офлайн, ничего не теряется. Когда документов набирается пара сотен, это единственная схема, которая не разваливается.
Так что docs as code - решение правильное. Проблема начинается на вопросе «а редактировать это чем».
Вариант 1. VS Code и расширения для превью
Год я жил на расширениях для превью Markdown прямо в редакторе кода.
Кустарная история. Часть конструкций рендерится не так, таблицу руками не собрать, вставить картинку - отдельный квест. Для инженера терпимо, он и так весь день в этом окне. Для всех остальных - нет.
Вариант 2. Отдельный WYSIWYG-редактор Markdown
Пробовал несколько ноунейм-редакторов .md. Пишешь в них нормально, разметки не видно.
Ломается всё на одном: они переписывают файл целиком. Открываешь чужой документ, правишь одно слово, сохраняешь - и в git diff двести изменённых строк, потому что редактор переставил маркеры списков и выровнял таблицы по-своему. Такой пулл-реквест никто читать не станет.
Вариант 3. Obsidian и плагин Git
Obsidian оказался лучшим из всего, что я щупал, и я на нём какое-то время сидел. Быстрый, приятный, работает с обычной папкой файлов.
Не подошёл он по одной причине: Obsidian живёт в своём хранилище со своей структурой, а git приезжает к нему плагином сбоку. Между репозиторием и человеком появляется прослойка, и её приходится объяснять.
Плюс своя разметка ссылок, которую остальной мир не читает, и своя служебная папка внутри репозитория. А главное - объяснять продакту, что ему нужно поставить редактор заметок, потом плагин, потом настроить синхронизацию с гитом, это заранее проигранный разговор.
Вариант 4. Вынести документацию в Confluence или Notion
Самый популярный ответ и самый бесполезный. Документация уезжает из репозитория, агент её больше не видит, спека расходится с кодом за две недели.
Ты меняешь одну проблему на ту же самую, только теперь копий две.
Что я сделал в итоге
Написал своё. Notula - десктопное приложение для Markdown, который лежит в git-репозитории. Как Google Docs, только файлы остаются твоими.
- Разметки не видно вообще. Не «живое превью», а полный WYSIWYG. Ни #, ни **, ни палок от таблицы, включая строку под курсором. На диске обычный Markdown, который инженеры ревьюят в обычном пулл-реквесте.
- Файл не переписывается. Открыл, сохранил не тронув - байты те же. Поправил слово - в диффе это слово. Проверено на шести тысячах реальных документов.
- Только документация. Наводишь на репозиторий с тысячами файлов исходного кода и получаешь чистое дерево .md. Папки без документов не показываются.
- Git есть, слов из git нет. Изменения коммитятся и синхронизируются сами. Интерфейс говорит «сохранено» и «у всех есть ваши изменения», а не «staged» и «detached HEAD». Конфликт показан как выбор между двумя версиями абзаца, без <<<<<<< в тексте.
- Комментарии на абзацах. Выделил, написал, тебе ответили, закрыли обсуждение. Комментарии коммитятся рядом и едут вместе с документами, а сами файлы остаются чистыми: ни якорей, ни скрытых идентификаторов внутри.
- Чужие файлы не трогаются. Каждая git-команда идёт с явным списком путей. Никаких git add -A, стэшей и переписывания истории, так что незакоммиченный код рядом остаётся на месте.
- Есть CLI. notula docs list, notula comments add, notula mentions. Что умеет окно, то умеет команда, поэтому Claude Code и Cursor работают в том же workspace, что и человек.
Прослойки нет: это твоя папка, твой Markdown, твой git.
Честно про то, что не так
Билды пока не подписаны. На macOS при первом запуске система скажет, что приложение повреждено, и придётся один раз выполнить команду в терминале. На Windows встретит SmartScreen. Подпись в работе.
Исходники закрыты, и это не «пока». Забирать при этом нечего: документы - обычный Markdown, комментарии лежат текстом в твоём репозитории, сервера нет вообще. Удалишь приложение - всё останется и читается без него.
Приложение бесплатное, аккаунт не нужен, данные никуда не уходят.
Если у тебя та же задача
Четыре совета, которые работают независимо от того, чем ты в итоге будешь править.
- Держи документацию в том же репозитории, что и код. Агент читает локальные файлы. Всё, что уехало во внешнюю базу знаний, он не видит, и спека начинает врать.
- Проверь редактор на round-trip, прежде чем пускать его к общим файлам. Открой документ, сохрани не изменив, посмотри git diff. Пусто - редактор годится. Не пусто - он будет засорять каждый пулл-реквест чужими правками.
- Не заводи прослойку со своим хранилищем. Любой слой между git и файлами придётся объяснять каждому новому человеку, и на продактах это ломается первым.
- Сначала реши, кто будет ревьюить. Если не инженер, ему нужен комментарий на абзаце, а не комментарий в пулл-реквесте. Это разные инструменты, и второй он не откроет.
Ссылка на приложение в описании канала: Дзен не любит ссылки в тексте.
Вопрос к тебе, и он мне сейчас важнее скачиваний. У вас документацию в репозитории правят только инженеры, или продакты и аналитики тоже добрались? Если добрались - через что? Мне интересны как раз рабочие связки, а не красивые.