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 большинства сервисов в вашей компании. Там будет пусто или каша. Каша - отсутствие уважения к себе и коллегам или не понимание важности это работы.

Если у тебя не так, тебе повезло! Материал может быть тебе полезен для того, чтобы улучшить текущие решения.

Хаотичный 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."

Что это значит в деньгах? Упрощение: performance в DORA — это не скорость рук, это эффективность всей системы доставки (частота деплоев, lead time, время восстановления, процент сбоев). Но если перевести в ёмкость команды: команда из 100 человек с плохой докой работает как 75. Вы теряете 25 инженеров. Не потому что они плохие — потому что система плохая. При Full Cost 413 000 ₽/мес на Middle-разработчика (2026) — это 124 млн ₽ в год. На ИТ-департамент в 1 500 человек — 375 потерянных FTE и 1,86 млрд ₽ в год.

Команды с качественной документацией в 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."

Я вспоминаю как тратил часы на поиск решения и распаковывал плохо структурированную раздутую документацию месяц до 15ти минутной сути.

Считаем потери в деньгах

30 минут в день — звучит невинно. Посчитаем для российского рынка.

Исходные данные:

Параметр	Значение	Источник
Рабочих дней в году	217	С учётом отпуска и праздников
Потеря времени на поиск	0,5 ч/день	Stack Overflow
Потери на 1 сотрудника в год	108,5 ч	217 × 0,5
Медианная зарплата Middle (net)	240 000 ₽/мес	Хабр Карьера, 2026
Full Cost на сотрудника	413 000 ₽/мес	+НДФЛ, взносы, накладные
Стоимость часа (Full Cost)	2 850 ₽	413 000 / 145 ч

Потери:

Показатель	1 сотрудник	100 человек	1 500 человек
Потери времени	108,5 ч	10 850 ч	162 750 ч
Финансовые потери	309 225 ₽	30,9 млн ₽	463,8 млн ₽
Потери в FTE*	0,06	6,25	93,7

*FTE — сколько сотрудников фактически «не работают» весь год, занимаясь только поиском информации.

464 миллиона рублей. 94 инженера, которые не пишут код. И это только от 30 минут в день.

Сокращение времени поиска всего на 10 минут (с 30 до 20) экономит 155 млн рублей ежегодно на департамент из 1 500 человек.

На команду из 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."

Эти люди не бездельничают. Они отвечают на вопросы коллег, объясняют как запустить, показывают где что лежит, разбирают чужой код без контекста. Они работают — но не над продуктом. Они работают справочным бюро. Берём середину — 20%:

Показатель	100 человек	1 500 человек
Потерянные FTE (20%)	20	300
Финансовые потери (Full Cost 413 000 ₽/мес)	99 млн ₽/год	1,49 млрд ₽/год

Сравним с DORA: разные исследования, разные методологии — один порядок потерь. Это не совпадение.

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."

В деньгах: 2,5 месяца × 413 000 ₽ = 1 032 500 ₽ на каждого нового сотрудника. Нанял 10 человек за год — потерял 10,3 млн ₽ только на том, что они сидели и разбирались вместо того, чтобы писать код. А если текучка 15% в департаменте из 1 500 человек — это 225 новичков в год и 232 млн ₽ потерь на онбординге.

Это не «было бы неплохо написать README». Это реальные деньги, люди и время.

README не пишут — или пишут «для всех». А документация «для всех» — это документация ни для кого. Как записка на холодосе в кофепоинте, адресованная «жильцам дома» — никто не читает, все в беготне, сроки горят. Много непонятного вокруг.

JTBD за 30 секунд

Jobs-to-be-Done — способ думать о продукте через работу, на которую его нанимают. Не «кто наш пользователь», а «какую задачу он решает, когда берёт наш продукт». Подход придумал Тони Ульвик в 1990 году после 10 лет работы продакт-менеджером в IBM — после провала IBM PCjr он понял, что проблема в том, как компании понимают потребности клиентов. Изначально подход назывался Outcome-Driven Innovation (ODI) и был обкатан в 1000+ проектах в 30+ индустриях с показателем успешности 86% — в пять раз выше среднего. Клейтон Кристенсен узнал о нём от Ульвика в 1999 году и популяризировал под названием «jobs-to-be-done» в книге The Innovator's Solution (2003).

Но не все так очевидно, как кажется на первый взгляд. На какую работу подруга нанимает меня, когда мы едем в музей? Точно не как такси. Не просто «смотреть картины». Она нанимает меня поболтать — когда мы оба без мобильных, без лент, просто поговорить обо всём и про арт. И я в этот момент нанимаю её на схожую работу. Мэтч. Музей — это место синхронизации, старта нового вайба, где телефон в кармане. А потом мы снимаем контент.

JTBD заставляет задать вопрос: а на какую настоящую работу нанимают продукт?

YouTube создавали как сайт видео-знакомств. Загрузи ролик о себе — найди пару. Люди проигнорировали задумку и начали заливать котиков и скейт-трюки. Основатели поняли: продукт нанимают не на знакомства, а на «покажи моё видео миру». Работа изменилась — продукт адаптировался. Кто не адаптируется — умирает.

Подгузники. Казалось бы — продукт для младенцев. Но водители покупают их зимой и кладут в машину — впитывать влагу и слякоть. Производитель думает, что продаёт гигиену для детей. Водитель нанимает подгузник на работу «сохрани мне сухой салон».

Клейтон Кристенсен, популяризатор 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 с описанием всей системы. А каждый сервисный репозиторий содержит в первых строках ссылку:

> Часть платформы [Ubik](https://github.com/ubik-life/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

Посмотри как ☝️ это лаконично. Можно в режиме сканирования понять как работает АПИ верхнеуровнево. Кайф. Часто такая запись помогает увидеть ошибку в реализации или как можно упростить решение.

Но главное — pipe учит инженера объяснять «на пальцах», как работает поток. Без ORM, без middleware, без фреймворковой магии — просто шаги, которые проходят данные. Это ценно по нескольким причинам:

Снижение когнитивной нагрузки. Рабочая память удерживает 4±1 чанка (Cowan, 2001¹). Pipe-запись — это готовые чанки: один шаг = один чанк. Таблица «метод → ресурс → действие» заставляет собирать поток в голове самому.
Чёрный ящик становится прозрачным. Инженер видит не интерфейс коробки, а что происходит внутри — и в каком порядке. Это разница между «POST возвращает 201» и «мы генерируем challenge, кладём в базу и только потом отвечаем».
Ошибки видны на уровне текста. Если шаг пропущен или стоит не в том месте — это заметно при чтении, без запуска кода. По сути, pipe — это code review до написания кода.
Общий язык между ролями. Фронтендер, бэкендер и тестировщик читают один и тот же pipe и одинаково понимают контракт. Исследования distributed cognition (Hutchins, 1995²) показывают: общее внешнее представление снижает ошибки координации в команде.

А если шагов много? Главная критика pipe: «процесс на 15 шагов превратится в простыню». Но это не баг нотации — это сигнал. Если pipe не помещается в голову, проблема не в записи, а в дизайне endpoint-а.

Те же 4±1 чанка Cowan-а¹ работают и здесь: pipe длиннее ~5 шагов нужно либо группировать в суб-пайпы, либо упрощать сам процесс.
Ousterhout в A Philosophy of Software Design (2018)³ вводит понятие «complexity signals» — если модуль нельзя описать коротко, он слишком сложный. Длинный pipe — буквально такой детектор.
Правило 5 строк Sandi Metz⁴ — эвристика из Ruby-сообщества: метод длиннее 5 строк — кандидат на разбиение. Pipe работает аналогично: больше 5 шагов — стоит спросить «а это точно один endpoint?».
Цикломатическая сложность McCabe (1976)⁵: чем больше ветвлений, тем больше ошибок. Pipe с ветвлениями (if → path A / path B) — сигнал, что endpoint делает слишком много.
Rich Hickey в докладе Simple Made Easy (2011)⁶: simple ≠ easy. Длинный pipe показывает complected (переплетённую) логику. Это приглашение распутать, а не записать покороче.

Pipe — это одновременно документация и линтер дизайна. Если запись раздувается, это обратная связь от системы: «упрости меня».

Компонентные тесты как документация. Gherkin-сценарии уже были в правилах, но не как способ объяснить «как пользоваться коробкой». А это буквально исполняемая инструкция к устройству на полке. Не терпится посмотреть, что у нас получится.

Инженер-клиент может быть «брошен на доработку». Это размывает границу между сегментами 1 и 2. Человек пришёл как потребитель, а стал контрибьютором. README должен дать ему лестницу, а не стену.

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

Шаг 5 — Куда деть иерархию модулей

В AGENTS.md были пункты «Схема иерархий модулей» и «Блок-схема entry point». Вопрос — где им жить:

Где будут описаны эти пункты?
4. Схема иерархий модулей
5. Блок-схема алгоритма головного модуля

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:

cd service-template
claude --model claude-sonnet-4-5

загрузи правила разработки 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 — Подтверждаем по порядку

работай по порядку

Дальше — по одному:

пункт 2 — да

пункт 3 — да

Один промпт — одна команда. Не объяснения, не контекст — просто «да, делай». Sonnet уже знает план. Наша работа — валидировать результат, а не дублировать постановку.

По ходу корректировали решения. Например, docs/architecture.md агент хотел создать сразу:

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`	Инженер-создатель	Передать знания о сервисе без личного участия
`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/

Cowan N. The magical number 4 in short-term memory: A reconsideration of mental storage capacity. Behavioral and Brain Sciences, 2001. ↩↩
Hutchins E. Cognition in the Wild. MIT Press, 1995 — классическая работа о том, как внешние представления (карты, схемы, чек-листы) разгружают когнитивную систему команды. ↩
Ousterhout J. A Philosophy of Software Design. Yaknyam Press, 2018. ↩
Metz S. Practical Object-Oriented Design. Addison-Wesley, 2012 — правило «5 строк на метод» как эвристика декомпозиции. ↩
McCabe T. A Complexity Measure. IEEE Transactions on Software Engineering, 1976. ↩
Hickey R. Simple Made Easy. Strange Loop Conference, 2011 — доклад о разнице между простотой и лёгкостью, и о цене переплетённой (complected) логики. ↩