code-last-mile — Последние 20%

Почему этот слой всегда выпадает

Когда задачу декомпозируют, декомпозируют существительное. «Сделать вики» распадается на ingestion, поиск, хранилище, слой LLM. Каждая часть выглядит необходимой, все они действительно нужны — и, будучи сделанными, дают систему, которой невозможно пользоваться.

Опыт использования не появляется в декомпозиции существительного. Значит, не становится задачей. Значит, не делается — и обнаруживается в конце как «работает, но что-то не то».

Лекарство: декомпозировать сцену, а не объект.

Шаг 1. Найди magic moment

Один конкретный момент, ради которого всё делается. Не «пользователь работает с системой», а сцена с деталями:

Человек вставляет ссылку на статью, уходит за кофе, возвращается — и видит, что статья уже разобрана на заметки, они связаны с тем, что он читал в прошлом месяце, и одна из связей его удивляет.

Если такую сцену не получается описать — это и есть главная находка. Продукта пока нет, есть набор компонентов.

Шаг 2. Разбери сцену по шагам

Пройди её как человек, а не как система. На каждом шаге отвечай:

• что он видит
• что он делает
• что он ждёт
• что он видит, если пошло не так

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

Дополнительно по каждому шагу:

• сколько он ждёт и понимает ли, что идёт работа
• сколько действий нужно, чтобы дойти сюда с нуля
• что он делает после — magic moment редко последний шаг

Шаг 3. Спецификация на уровне сантехники

То, что нашлось, описывается конкретно, а не пожеланиями. Не «улучшить обработку ошибок», а: «при таймауте парсера показать сообщение X, оставить ссылку в очереди, повторить через Y минут, при третьей неудаче написать в лог Z и показать пользователю кнопку W».

Уровень детализации такой, чтобы по описанию можно было реализовать, не додумывая. Формулировка, допускающая додумывание, будет додумана иначе, чем ты имел в виду.

Шаг 4. Золотые артефакты — руками, до генератора

Прежде чем писать код, который что-то генерирует, напиши руками один-два образцовых результата. Идеальную заметку. Идеальный ответ. Идеальное письмо.

Это делается вручную по двум причинам. Пока образца нет, «хорошо» не определено, и генератор невозможно оценить. И написание образца само вскрывает требования, которых не было в плане: обычно выясняется, что для хорошего результата нужны данные, которые никто не собирался собирать.

Золотые артефакты становятся приёмочным критерием: генератор готов, когда его вывод сравним с ними.

Шаг 5. Отдай результат списком

• сцена, разобранная по шагам
• что из неё уже есть
• чего нет, со спецификацией на уровне сантехники
• золотые артефакты
• что осознанно не делаем сейчас

Чего не делать

• Не подменяй сцену списком фич. «Нужны уведомления» — это фича; «он не понимает, что обработка идёт, и уходит» — это сцена.
• Не бери сразу три сценария. Один, разобранный до конца, полезнее трёх поверхностных.
• Не описывай счастливый путь и на этом останавливайся: ошибочные ветки и есть последние 20%.
• Не считай генератор готовым, пока не с чем сравнить его вывод.
• Не превращай это в редизайн: скилл достраивает то, что задумано, а не придумывает другое.