Сижу над README.md третий час. Описание проекта, установка, API — всё написано, но выглядит как инструкция к микроволновке, а не как документация. Начинаю переписывать с нуля — и понимаю, что так можно до утра проторчать.
Знакомо? Мне — да. И я попробовал делегировать это Claude. Не всю работу, а конкретные куски. Результат удивил.
Зачем вообще заморачиваться
Техническая документация — это, пожалуй, самая неблагодарная часть разработки. Пишешь код — видишь результат сразу. Пишешь документацию — тишина, пока кто-то не застрянет на ровном месте и не придёт с вопросом, на который ответ есть, но написан так, что понять невозможно.
Проблема обычно не в лени. Дело в том, что хорошая документация требует постоянного переключения контекста: сегодня ты ходишь в шкуре разработчика, завтра — в шкуре человека, который впервые открывает твой проект. Это разные люди с разными вопросами.
Claude хорош именно здесь — он умеет держать оба контекста одновременно, потому что у него нет «слепоты разработчика». Он не знает, что «и так понятно», и честно переспрашивает неочевидное.
Что я делаю конкретно
Первый подход — превращаю хаос в черновик. Беру всё что есть: комментарии в коде, slack-переписку с вопросами клиента, тикет в багтрекере, даже «ну тут вроде работает» от коллеги. Скармливаю это Claude и прошу: «Напиши черновик документации по модулю X, используя эту информацию». Результат обычно сырой, но это сырьё, с которым уже можно работать.
Второй подход — редактура готового. Беру текст, написанный человеком, и прошу переработать. Критерии задаю конкретные: «Перепиши для новичка в Go», «Добавь примеры ошибок и что они значат», «Сделай короче в два раза, сохранив техническую точность». Без критериев Claude выдаёт средний текст — правильный, но безликий.
Третий подход — тестирование. Пишу документацию сам, потом прошу Claude притвориться новым разработчиком и задать вопросы по тексту. Он находит места, где я неявно предположил слишком многое. Это дешевле, чем потом отвечать на вопросы в чате.
Промпты, которые у меня заработали
Самый частый косяк — просить «напиши документацию». Без контекста получишь общий текст, который подойдёт любому проекту и поэтому не нужен никому.
Вот рабочие шаблоны.
Для черновика:
У меня есть REST API на Go (описание эндпоинтов ниже).
Напиши раздел «Быстрый старт» для README.md.
Аудитория — разработчики, которые первый раз видят этот сервис.
Включи: установку, запуск, один рабочий запрос с curl.
Для ревью:
Вот текущий текст раздела про аутентификацию.
Он написан для опытных разработчиков.
Перепиши для джуниоров: объясни термины, добавь пояснения «почему именно так».
Длина — не больше 300 слов.
Для проверки:
Я написал документацию по установке.
Спроектируй 5–7 вопросов, которые возникнут у человека, который делает это впервые.
Отметь, на какие вопросы мой текст отвечает, а на какие — нет.
Последний промпт — самый недооценённый. Я им регулярно пользуюсь, потому что он находит дыры, которые я сам не замечаю.
Где Claude реально слаб
Честности ради — есть места, где я ему не доверяю.
Первое: точность фактов о коде. Если не дам ему исходники или не укажу конкретную версию, он может подставить правдоподобную, но неверную деталь. Имена переменных, форматы ответов, лимиты — всё это лучше перепроверить.
Второе: тон. Claude по умолчанию пишет чуть формальнее, чем хотелось бы. README получается правильный, но без характера. Мне нравится, когда у проекта есть голос — пусть даже в документации. Это не критично, но читать приятнее.
Третье: длинные документы. Если попросить написать целую документацию с нуля одним промптом — качество деградирует к концу. Он начинает повторяться и растекаться. Лучше разбивать на секции и собирать.
Как я теперь работаю
Раньше: садишься, открываешь пустой файл, смотришь в потолок, пишешь полторы строки в час.
Теперь: открываю файл, открываю Claude, делаю три итерации — черновик, редактура, проверка вопросами. На выходе — текст, который я потом правлю, но правки точечные, не «всё сначала». Разница во времени — часа два-три на документ, который раньше откладывал на неделю.
Главное, что изменилось: документация перестала быть подвигом воли. Она стала задачей, которую можно разложить на понятные шаги. А это значит — она хотя бы будет существовать.
На этом всё. Если есть вопросы по промптам — пишите, разберём.
