README — это продукт. Документация по JTBD с ИИ-агентом
В первой практике мы собрали сервис авторизации — OpenAPI-спека, README, devlog. Всё работает. Но документация получилась «для всех» — а значит ни для кого.
В этой сессии разбираем: у README четыре потребителя, и каждый нанимает его на свою работу. Проектируем структуру документации с Claude Opus, применяем через Claude Sonnet в терминале.
Репозиторий с результатом: service-template
GL HF DD!
Что нужно заранее
- Пройденная первая практика — репозиторий с AGENTS.md и CLAUDE.md
- Claude Opus — для проектирования (через claude.ai или API)
- Claude Code — для применения (Sonnet в терминале)
Проблема
Откройте README большинства сервисов в вашей компании. Там будет пусто или каша. Каша - отсутствие уважения к себе и коллегам или не понимание важности это работы.
Если у тебя не так, тебе повезло! Материал может быть тебе полезен для того, чтобы улучшить текущие решения.
Инструкция по запуску перемешана с архитектурными решениями. Quick start утонул в ADR-ах. Менеджер не понимает, что это за система. Кстати, менеджер — вообще редкий гость в своём хозяйстве. Ему не до порядка в репозиториях. А зря. Разве CTO не может взглянуть на репы своего хозяйства и оценить масштаб великолепия? Или бардака?
Новый разработчик не понимает, как запустить. ИИ-агент сожрал 2000 токенов контекста и всё ещё не знает, куда класть новый файл. Мидл на грани нервного срыва. Джуна рвёт в туалете от волнения. Всё как в «Апокалипсис сегодня». Смотрели?
Почему всё так хреново? Не знаю. Возможно, всем пофиг. Возможно, люди не понимают, что делают и зачем. Проще всего сказать: вы все тупые мартышки. Но это неконструктивно и несправедливо. Люди делают плохо не со зла — они делают как умеют, потому что никто не показал, как надо.
А вот числа, чтобы не быть голословным
Качественная документация повышает производительность команды на 25% (DORA 2023, раздел Documentation quality):
"High-quality documentation leads to 25% higher team performance relative to low-quality documentation."
Команды с качественной документацией в 2.4 раза чаще показывают высокую производительность доставки и эксплуатации ПО (DORA 2021, раздел Documentation):
"Teams with higher quality documentation are 2.4 times more likely to see better software delivery and operational (SDO) performance."
И отдельно — команды с качественной документацией в 2.4 раза чаще достигают целевых показателей надёжности (там же):
"Teams with quality documentation are 2.4 times more likely to meet or exceed their reliability targets."
62% разработчиков тратят больше 30 минут каждый день на поиск ответов в плохо задокументированных системах (Stack Overflow Developer Survey / Archbee):
"According to the Stack Overflow Developer Survey, 62% of developers spend over 30 minutes each day looking for answers to poorly documented issues, with 25% exceeding an hour."
Я вспоминаю как тратил часы на поиск решение и распаковывал плохо структурированную раздутую документацию до сути.
На команду из 100 инженеров плохая документация съедает 15–25% мощности — это 15–25 человек, которые не пишут код, а компенсируют отсутствие документов (GetDX):
"Documentation problems cost 15-25% of engineering capacity. That's 15-25 engineers per 100-person team effectively doing nothing but compensating for missing documentation."
38% разработчиков называют плохую документацию одной из главных причин увольнения (Stack Overflow / Evizi):
"Research from Stack Overflow found that 38% of developers listed poor documentation as one of the top reasons for leaving a company."
Онбординг новых инженеров затягивается на 2–3 месяца, когда документация отсутствует (важно ❗, что плохая, громоздкая дока — всё равно что отсутствие доки) (GetDX):
"New hires take 2-3 months longer to become productive when documentation is poor."
Это не «было бы неплохо написать README». Это реальные деньги, люди и время.
README не пишут — или пишут «для всех». А документация «для всех» — это документация ни для кого. Как записка на холодосе в кофепоинте, адресованная «жильцам дома» — никто не читает, все в беготне, сроки горят. Много непонятного вокруг.
JTBD за 30 секунд
Jobs-to-be-Done — способ думать о продукте через работу, на которую его нанимают. Не «кто наш пользователь», а «какую задачу он решает, когда берёт наш продукт».
На какую работу подруга нанимает меня, когда мы едем в музей? Не просто «смотреть картины». Она нанимает меня поболтать — когда мы оба без мобильных, без лент, просто поговорить обо всём и про арт. И я в этот момент нанимаю её на схожую работу. Мэтч. Музей — это место синхронизации, старта нового вайба, где телефон в кармане. А потом мы снимаем контент.
JTBD заставляет задать вопрос: а на какую настоящую работу нанимают продукт?
README — тоже продукт. У него есть потребители, и каждый нанимает его на свою работу. Осталось понять — на какую.
Часть 1 — Проектируем с Opus
Opus — для архитектурного мышления. Не для написания кода — для рассуждений, аналогий, переработки идей. В этой части мы ведём диалог в claude.ai. Вся сессия — итеративная: не один промпт на всё, а серия вопросов, каждый из которых углубляет результат.
Шаг 1 — Первые два сегмента: создатель vs потребитель
Начинаем не с «напиши хороший README», а с вопроса о потребителях, чтобы было увлекательно:
Разбираем по JTBD на какую работу нанимают README
в репозитории разные сегменты потребителей.
В чём отличие инженера-мейнтейнера от инженера
из другой команды, который тоже может захотеть
доработать коробку?
Opus разложил два сегмента:
Инженер-создатель (мейнтейнер) — он уже внутри. Знает, как всё устроено. Его боль — к нему приходят люди и задают одни и те же вопросы. Или присылают PR, который ломает архитектурные решения, потому что не поняли почему сделано именно так.
Job: «Передать знания о сервисе новому участнику команды без личного участия.»
Инженер-потребитель (другая команда) — он снаружи. У него свои дедлайны. Не хочет становиться контрибьютором — хочет подключить, вызвать, получить результат.
Job: «Оценить пригодность чужого сервиса для своей задачи при ограниченном❗ времени.»
Opus дал аналогию: мейнтейнер — тренер, который пишет правила. Ему нужно, чтобы новый человек зашёл и уже знал, где переодеться, как кланяться, что нельзя делать на татами. (Например какать на татами - нельзя, терпи но тащи дерьмо в туалет, Какать на татами неуважительно по отношению к себе, к тренеру, к ребятам с которыми тренируешься, к школе) Потребитель — человек, который ищет секцию для ребёнка. Ему не нужны правила додзё. Ему нужно: расписание, цена, возраст, один абзац — почему именно здесь.
Уже на этом шаге стало понятно: если README пытается обслужить обе работы в одном потоке текста — он не обслуживает ни одну.
Шаг 2 — Добавляем менеджера
Два сегмента — хорошо, но мало. Из опыта работы в больших компаниях я знал, что есть ещё один потребитель, которого обычно игнорируют:
Разберём JTBD ещё двух сегментов.
Сегмент 3: Тупой Менеджер нанимает ридми для —
понять чо за система, как она работает в целом
и из каких кусков состоит. Значит на каждом
отдельном куске должна быть отсылка ко всей системе.
Где мы опишем всю систему? Правильно — в отдельном
репозитории.
Менеджер не лезет в кишки. Ему нужна картина целого за 3 минуты.
Job: «Получить представление о структуре системы при подготовке к управленческому решению.»
И запихивать это в README конкретного сервиса — ошибка. Он утонет в деталях одного куска и не увидит целого.
Решение: мета-репозиторий concept с описанием всей системы. А каждый сервисный репозиторий содержит в первых строках ссылку:
Менеджер зашёл в любой репозиторий, кликнул, попал в понятную картину мира.
Шаг 3 — Добавляем ИИ-агента
В том же промпте:
Сегмент 4: ИИ-агент. РИДМИ нанимает для того,
чтобы за минимальное количество токенов загрузить
контекст и быть готовым выполнить задачу.
Агент — самый прагматичный потребитель. У него буквально бюджет — токены. Каждое лишнее слово — вытесненный контекст или деньги. Ему не нужна мотивация, история проекта и бейджики.
Job: «Загрузить контекст проекта для выполнения задачи при ограниченном бюджете токенов.»
Принципы написания для агента:
- Максимальная плотность информации на токен. Ноль воды.
- Один плоский файл — агент не кликает по ссылкам, он читает линейно.
- Структура через заголовки и таблицы, не через прозу.
- Явные запреты: «НЕ делай X», а не «старайся избегать X».
По сути, это то, что мы уже делали в CLAUDE.md и AGENTS.md — но теперь это формализовано как отдельный сегмент с явным Job-to-be-Done.
Шаг 4 — Свои идеи из опыта
После того, как Opus разложил четыре сегмента, я закинул свои заметки — вещи, которые знал из практики, но не формализовал:
Посмотри есть ли тут интересные мысли. Я написал их
опираясь на свой опыт работы и рассуждения с тобой.
Возьми полезное, что упустил и добавь в описание
документов.
Полный промпт с заметками из опыта
Как улучшить README.md
1. Инженер (создатель)
2. Инженер(клиент) который работает с нашей коробкой (Клиент)
3. Тупой Менеджер
4. Агенту ИИ
1 Инженеру(создателю) ридмин нанимает на
"Помоги мне не тратить время на объяснение одного и того же
каждому новому человеку." Снизи стоимость онбординга новых
контрибьюторов до нуля, чтобы я занимался кодом, а не объяснениями.
Нужно краткое описание продукта (какую задачу решает) (овервью)
Что ему важно в README: архитектурные решения с обоснованиями (ADR-стиль)
Что за АПИ есть у продукта + ссылка на спеку
Как продукт работает на пальцах(простое описание каждого апи)
получаем запрос
Какую задачу решаем по АПИ (может мы ее решаем хреново)
Пример описания АПИ в пайп стиле
| Идем за данными в сервис 1
| Идем за данными в сервис 2
| Делаем с данными
| Валидируем состояние
| Выдаем данные
(Это уже для тех кто умеет запускать терминал, менеджер сюда не пойдет)
Как пользоваться коробкой
(Как запустить и протестировать - тут нам пипец поможет компонентный тест)
Как ее запустить
Полезно будет иметь ссылку на Компонентные Тесты, чтобы понять как
запускать, тестить эту штуку в изоляции)
2 Инженеру пользователь РИДМИ нанимает на
"Помоги мне за 5 минут понять — решит ли эта штука мою проблему,
и если да, покажи самый короткий путь к работающему результату."
Job-to-be-Done: "Дай мне уверенность, что это работает для моего кейса,
и покажи как запустить — без погружения в кишки."
Мне нужно
Понять чо за система
Как она работает в целом и из каких кусков состоит
Как работает каждый отдельный кусок (я могу быть брошен на доработку
надеюсь не сражение с демо-пиццей)
3. Тупой Менеджер нанимает ридми для
Понять чо за система
Как она работает в целом и из каких кусков состоит
Значит на каждом отдельном куске должна быть отсылка ко всей системе
Где мы опишем всю систему?
Правильно в отдельном репозитория
4. ИИ Агент нанимает доки для
того чтобы за минимальное количество токенов загрузить контекст
и быть готовым выполнить задачу
Три вещи, которые Opus не придумал сам — их принёс я:
Pipe-стиль описания API. Таблица «метод → ресурс → действие» отвечает на «что есть». Но не на «как работает и где сломается». Pipe показывает поток данных:
POST /v1/registrations
| Принимаем handle от клиента
| Генерируем challenge (32 байта, TTL 5 мин)
| Сохраняем challenge в БД
| Возвращаем challenge + WebAuthn options → 201
Посмотри как ☝️ это лаконично. Можно в режиме сканирования понять как работает АПИ верхнеуровнево. Кайф. Часто такая запись помогает увидеть ошибку в реализации или как можно упростить решение.
Компонентные тесты как документация. Gherkin-сценарии уже были в правилах, но не как способ объяснить «как пользоваться коробкой». А это буквально исполняемая инструкция к устройству на полке. Не терпится посмотреть, что у нас получится.
Инженер-клиент может быть «брошен на доработку». Это размывает границу между сегментами 1 и 2. Человек пришёл как потребитель, а стал контрибьютором. README должен дать ему лестницу, а не стену.
Opus взял эти идеи, структурировал и вписал в JTBD-сегментацию. Это важный момент для статьи: дорогая модель — не волшебник, который думает за тебя. Она — партнёр по мышлению, который формализует то, что ты уже знаешь из опыта.
Шаг 5 — Куда деть иерархию модулей
В AGENTS.md были пункты «Схема иерархий модулей» и «Блок-схема entry point». Вопрос — где им жить:
Opus предложил два варианта: в CLAUDE.md (ближе к агенту, обновляется каждую сессию) или в docs/architecture.md (рядом с ADR, для мейнтейнера). Я выбрал вариант Б:
Потому что иерархия модулей — это не только контекст для агента. Это знание о том, как устроена программа. Оно нужно инженеру, которого бросили на доработку.
Шаг 6 — Лестница вглубь
Из обсуждения предыдущих шагов сложилась структура — путь наращивания контекста:
README.md (что это, как запустить)
→ component-tests/ (как работает снаружи)
→ docs/architecture.md (как устроено внутри)
→ docs/adr/ (почему сделано именно так)
→ CONTRIBUTING.md (как правильно менять)
Каждый уровень — отдельный файл, не раздел и не якорь. Потребитель останавливается на том уровне, который ему нужен.
Результат части 1
Opus сгенерировал обновлённый AGENTS.md со всем, что мы наработали: JTBD-сегментация с четырьмя потребителями, pipe-формат, лестница вглубь, docs/architecture.md с примерами иерархии модулей и блок-схемы entry point, карта файлов с указанием потребителя.
Скачиваем файл — он пойдёт в шаблон.
Часть 2 — Применяем через Sonnet
Sonnet в терминале — для исполнения. Берёт готовую архитектуру и раскладывает по файлам.
Шаг 1 — Загружаем контекст
Закидываем обновлённый AGENTS.md в шаблон и запускаем Claude Code:
загрузи правила разработки AGENTS.md себе в контекст
и предложи доработки этого шаблона сервиса.
Мы работаем над улучшением шаблона сервиса связанного
с документацией.
Sonnet прочитал AGENTS.md, CLAUDE.md, README.md, backlog.md и предложил 7 пунктов доработки:
- Вынести статические инструкции агента из CLAUDE.md в AGENTS.md
- Добавить недостающие блоки в README.md (concept-ссылка, стек, умеет/не умеет, pipe)
- Добавить шаблон devlog-записи в AGENTS.md
- Добавить шаблон ADR в AGENTS.md
- Добавить
docs/architecture.mdв backlog - Добавить триггерную таблицу обновления документов
- Создать стаб-структуру директорий в шаблоне
Шаг 2 — Подтверждаем по порядку
Дальше — по одному:
Один промпт — одна команда. Не объяснения, не контекст — просто «да, делай». Sonnet уже знает план. Наша работа — валидировать результат, а не дублировать постановку.
По ходу корректировали решения. Например, docs/architecture.md агент хотел создать сразу:
Согласились: architecture.md создаётся на шаге 3 (когда есть модули и entry point), а не на шаге 0.
Что Sonnet добавил сверх плана
Три вещи, которые мы с Opus не проектировали:
Триггерная таблица обновления документов — какое событие → какие файлы обновить:
| Событие | Что обновить |
|---|---|
| Новый эндпоинт | api-specification/, README.md (таблица + pipe) |
| Изменение entry point | docs/architecture.md |
| Архитектурный выбор | docs/adr/ + CLAUDE.md |
| Merge шага | CLAUDE.md, backlog.md |
Шаблоны devlog и ADR — вынесены в docs/templates/, в AGENTS.md только ссылка. Экономия токенов при каждой загрузке контекста.
Сценарий первой сессии агента (§20) — агент при старте проверяет backlog, находит первый todo, предлагает выполнить. Без этого он ждёт явной команды.
Все три — операционные, тактические. Ровно то, что хорошо делает исполнитель.
Шаг 3 — Точки контроля
Первая версия §20 содержала «жди подтверждения перед каждым действием». Это замедляет агента на рутинных операциях. Мы обсудили это с Opus:
Тут важно указать так: мы работаем маленькими
итерациями, и я хочу валидировать эти итерации,
или это лишний контроль?
Если итерация = один коммит, то подтверждение внутри сессии — двойной контроль (ты и так делаешь PR → merge). Коммит — естественная граница: до него всё откатываемо, после — в истории.
Переформулировали:
- Рутинные операции (создание/редактирование файлов,
обновление backlog) — выполняй без остановки
- Перед git commit — остановись, покажи результат,
жди подтверждения
- Деструктивные действия (удаление файлов, изменение
API-контракта) — явное подтверждение
Одна точка контроля вместо десяти.
Шаг 4 — CONTRIBUTING.md
Последний документ в лестнице. Для мейнтейнера, который готов вносить изменения.
Ключевое решение: CONTRIBUTING.md не дублирует AGENTS.md — он ссылается. Правила коммитов — «см. AGENTS.md §12». Флоу веток — «см. AGENTS.md §11». Единый источник правды.
CONTRIBUTING.md целиком
# CONTRIBUTING.md
Правила для тех, кто вносит изменения в сервис.
## Быстрый старт
1. Клонируй репозиторий
2. Настрой окружение — см. `.env.example`
3. Запусти сервис — см. `README.md → Запуск`
4. Убедись что компонентные тесты проходят — см. `component-tests/`
## Флоу разработки
Правила разработки, коммитов и веток — в `AGENTS.md`.
Коротко:
- Ветка от main, живёт не дольше 1–2 дней (AGENTS.md §11)
- Коммиты по Conventional Commits (AGENTS.md §12)
- Сначала тест, потом код (AGENTS.md §5)
- Изменения API — только через спеку в api-specification/ (AGENTS.md §2)
## Перед отправкой PR
- Компонентные тесты проходят
- api-specification/ обновлена, если изменился API
- README.md обновлён, если изменился API, стек или способ запуска
- Коммиты по Conventional Commits
- Ветка актуальна относительно main
## Документация
При изменениях обновляй документы согласно триггерной таблице
в AGENTS.md §19.
Шаг 5 — Применяем к существующим репозиториям
После доработки шаблона мы прогнали Sonnet по двум живым репозиториям:
- passkey-demo-api — добавлена ссылка на concept, структура репозитория в README, devlog
- concept — остался как мета-репозиторий для менеджера, с архитектурой всей платформы и текущим шагом
Что получилось
Четыре потребителя — четыре слоя документации:
| Документ | Потребитель | Job (Глагол + Объект + Контекст) |
|---|---|---|
README.md |
Инженер-потребитель | Оценить пригодность сервиса для своей задачи |
README.md |
Инженер-создатель | Передать знания о сервисе без личного участия |
CONTRIBUTING.md |
Мейнтейнер | Внести изменения в чужой сервис по правилам |
docs/architecture.md |
Создатель + агент | Понять внутреннее устройство программы перед доработкой |
docs/adr/ |
Мейнтейнер | Восстановить причины архитектурного решения при ревью |
AGENTS.md |
ИИ-агент | Загрузить правила разработки перед выполнением задачи |
CLAUDE.md |
ИИ-агент | Загрузить контекст текущей сессии при старте |
concept (мета-репо) |
Менеджер | Получить представление о структуре системы |
Три репозитория приведены к единой структуре:
- concept — мета-репозиторий для менеджера
- passkey-demo-api — сервис с README по новой структуре
- service-template — шаблон для новых сервисов
Opus думает, Sonnet делает
Это главный паттерн сессии. Не «Opus лучше» и не «Sonnet дешевле». Разные модели — для разных задач.
Opus — для архитектурных рассуждений, аналогий, переработки концепций. Но он не придумывал всё сам. Он структурировал и формализовал идеи, которые принёс я из 14 лет работы. Pipe-формат, компонентные тесты как документация, «бросили на доработку» — это мой опыт. Opus превратил его в систему. А мой опыт помог провалидировать, что реальные боли учтены — например, боль инженера-потребителя, которому нужно за 5 минут понять: решит ли эта коробка мою проблему, или я зря трачу время. Эту боль модель сама не придумает — её нужно принести из жизни.
Sonnet — для применения готовой архитектуры к коду. Он разложил концепцию по файлам за 9 промптов и добавил три тактических улучшения (триггерная таблица, шаблоны, сценарий старта), которые мы с Opus не проектировали. Операционные вещи — его стихия.
Дорогая модель — не волшебник, который думает за тебя. Она — партнёр по мышлению. Ты приносишь опыт и задаёшь направление. Она формализует и находит пробелы. Результат лучше, чем мог бы дать каждый по отдельности.
Архитектор проектирует додзё. Строитель строит. Если строитель начнёт проектировать — додзё будет кривое. Если архитектор начнёт класть кирпичи — будет дорого и долго.
Следующая сессия
Шаблон готов. Документация знает своих потребителей. В следующей сессии — компонентные тесты на Gherkin: описываем поведение сервиса до того, как напишем первую строку кода.
Продолжение: devlog/