jtprogru code-last-mile — Последние 20%
Почему этот слой всегда выпадает
Когда задачу декомпозируют, декомпозируют существительное. «Сделать вики» распадается на ingestion, поиск, хранилище, слой LLM. Каждая часть выглядит необходимой, все они действительно нужны — и, будучи сделанными, дают систему, которой невозможно пользоваться.
Опыт использования не появляется в декомпозиции существительного. Значит, не становится задачей. Значит, не делается — и обнаруживается в конце как «работает, но что-то не то».
Лекарство: декомпозировать сцену, а не объект.
Шаг 1. Найди magic moment
Один конкретный момент, ради которого всё делается. Не «пользователь работает с системой», а сцена с деталями:
Человек вставляет ссылку на статью, уходит за кофе, возвращается — и видит, что статья уже разобрана на заметки, они связаны с тем, что он читал в прошлом месяце, и одна из связей его удивляет.
Если такую сцену не получается описать — это и есть главная находка. Продукта пока нет, есть набор компонентов.
Шаг 2. Разбери сцену по шагам
Пройди её как человек, а не как система. На каждом шаге отвечай:
- что он видит
- что он делает
- что он ждёт
- что он видит, если пошло не так
Последний вопрос вскрывает больше всего пропусков. В планах почти никогда нет ответа на «что показать, когда парсер не справился со статьёй».
Дополнительно по каждому шагу:
- сколько он ждёт и понимает ли, что идёт работа
- сколько действий нужно, чтобы дойти сюда с нуля
- что он делает после — magic moment редко последний шаг
Шаг 3. Спецификация на уровне сантехники
То, что нашлось, описывается конкретно, а не пожеланиями. Не «улучшить обработку ошибок», а: «при таймауте парсера показать сообщение X, оставить ссылку в очереди, повторить через Y минут, при третьей неудаче написать в лог Z и показать пользователю кнопку W».
Уровень детализации такой, чтобы по описанию можно было реализовать, не додумывая. Формулировка, допускающая додумывание, будет додумана иначе, чем ты имел в виду.
Шаг 4. Золотые артефакты — руками, до генератора
Прежде чем писать код, который что-то генерирует, напиши руками один-два образцовых результата. Идеальную заметку. Идеальный ответ. Идеальное письмо.
Это делается вручную по двум причинам. Пока образца нет, «хорошо» не определено, и генератор невозможно оценить. И написание образца само вскрывает требования, которых не было в плане: обычно выясняется, что для хорошего результата нужны данные, которые никто не собирался собирать.
Золотые артефакты становятся приёмочным критерием: генератор готов, когда его вывод сравним с ними.
Шаг 5. Отдай результат списком
- сцена, разобранная по шагам
- что из неё уже есть
- чего нет, со спецификацией на уровне сантехники
- золотые артефакты
- что осознанно не делаем сейчас
Чего не делать
- Не подменяй сцену списком фич. «Нужны уведомления» — это фича; «он не понимает, что обработка идёт, и уходит» — это сцена.
- Не бери сразу три сценария. Один, разобранный до конца, полезнее трёх поверхностных.
- Не описывай счастливый путь и на этом останавливайся: ошибочные ветки и есть последние 20%.
- Не считай генератор готовым, пока не с чем сравнить его вывод.
- Не превращай это в редизайн: скилл достраивает то, что задумано, а не придумывает другое.