Третий раз переписывал одно и то же API-описание. Буквально одни и те же слова, только в другом порядке. Доку унаследовал от предыдущего разработчика, который, судя по стилю, писал её в полпятого утра перед релизом. Сел за ноутбук, открыл Claude — и за час сделал то, на что обычно уходило полдня. Это не магия и не реклама. Это конкретный опыт, где что-то получилось, а где-то я упёрся в стену. Расскажу как есть.
С чего я начал: дал Claude правильный контекст
Первая мысль была — кинуть ссылку на код и попросить «опиши». Не работает. Claude честно выдаёт общие слова, которые подошли бы любому API на планете. «Система предоставляет возможность управления данными» — и все, приехали.
Поменялось всё, когда я начал читать вслух то, что получалось. Слышу ерунду — и переспрашиваю точнее. Примерно так:
Плохо: «Опиши эндпоинт /users» Хорошо: «Напиши описание для GET /users/{id}. Эндпоинт возвращает пользователя по UUID, если он существует и не удалён. Если не найден — 404. Пример запроса: curl... Пример ответа: {...}»
Разница огромная. Во втором случае Claude знает, что от него хотят. Он знает формат ошибки, знает про soft delete, знает формат запроса. На выходе — текст, который не стыдно показать.
Что реально умеет делать Claude в документации
Я заметил, что есть задачи, где Claude экономит время, и задачи, где он скорее мешает.
Хорошо идёт: — Генерация первой версии описаний для эндпоинтов, когда у тебя уже есть сигнатуры и форматы данных. Берёшь ответ в JSON, кидаешь в Claude с просьбой «переведи в человеческий текст» — и получаешь основу, которую потом правишь. — Приведение в порядок неструктурированных заметок. Бывает, накидал в Notion список «надо задокументировать», а там каша из терминов и обрывков. Claude умеет это свернуть в связный текст. — Генерация примеров кода на разных языках по готовому описанию. Описываешь логику один раз — получаешь Python, Go, curl. — Проверка консистентности. Попросил «проверь, везде ли одинаково описан формат дат» — нашёл три расхождения за минуту.
Плохо: — Написать документацию с нуля по непонятной кодовой базе. Без контекста он придумывает, как работает система, — и придумывает красиво, с уверенным видом. Это опасно. — Заменить экспертизу. Если ты сам не понимаешь, как работает feature, текст от Claude будет уверенно нести ерунду.
Пример из практики: документация для микросервиса авторизации
У меня был микросервис на Go, 12 эндпоинтов, half-baked readme и три месяца без документации. Задача — за два дня сделать что-то приличное для новых разработчиков.
Что сделал. Собрал все хендлеры в одном файле, вытащил форматы запросов и ответов. Попросил Claude сгенерировать таблицу по схеме: эндпоинт, метод, описание, параметры, формат ошибок. Потом каждую строку таблицы раскрыл в параграф.
Получилось 70% готового текста. Оставшиеся 30% — проверка на реальном коде и исправление неточностей. Особенно Claude любит «под капотом используется продвинутый алгоритм» вместо реального объяснения. Прямо чувствуешь, как он уклоняется от конкретики.
Три приёма, которые реально помогают
Первый: использовать роль. «Ты — технический писатель в компании X, которая делает Y. Пиши для разработчиков, которые впервые видят наш продукт». Это не магическая формула, но работает. Claude начинает держать тон и уровень объяснений.
Второй: итерации вместо одного промпта. Не пытаюсь сразу получить идеальный текст. Первый промпт — черновик. Второй — «сделай короче, убери канцелярит». Третий — «добавь конкретики в раздел про аутентификацию». Между итерациями читаю вслух — если звучит нелепо, значит, хромает логика.
Третий: заставляю его сомневаться. «Какие вопросы могут возникнуть у разработчика, который читает этот раздел?» — полезный вопрос, который вытаскивает пробелы. Ответы Claude не всегда правильные, но направляют внимание.
Где я упёрся в стену
Был раздел про архитектуру — схема взаимодействия сервисов, порядок вызовов. Попробовал описать словами и дать Claude дорисовать. Не вышло. Он генерировал красивые, но неточные диаграммы. В итоге нарисовал в Miro за 20 минут, вставил скриншот. Иногда руками быстрее.
Ещё проблема: дублирование. Claude легко генерирует текст, и текста становится много. Потом ловишь себя на том, что один и тот же концепт объяснён тремя разными способами на шести страницах. Без чёткого плана доку получается как этот абзац — вроде всё есть, но ощущение каши.
Коротко
Claude хорошо работает как усилитель. Он ускоряет рутинные куски, но не заменяет понимание продукта. Если ты сам знаешь, как работает система — экономит часы. Если не знаешь — генерирует уверенно выглядящую ерунду.
Мой рабочий процесс сейчас: сначала руками набрасываю структуру и факты, потом кидаю в Claude на расшивку текста, потом редактирую. Между вторым и третьим шагом обычно всплывает «а, это я неправильно понял» — и это нормально.
