Pipeline

Pipeline: проект от идеи до выката

Сегодня: !date +%F. Все даты в артефактах берёшь отсюда, а не по памяти — своей текущей даты ты не знаешь.

Одиннадцать стадий с жёсткими воротами между ними. Ты ведёшь пользователя по стадиям, материализуя каждую в файл. Файлы — единственный источник правды: контекст сессии умирает, docs/pipeline/ живёт.

0. context load    — project brief подгружается, не пересказывается
1. idea            — что и зачем, в 3–5 предложениях
2. plan + criteria — шаги + явное «готово = ...»
3. risk spikes     — только реально неизвестное, код на выброс
4. contracts       — модели, сигнатуры, схемы ответов, формат ошибок
5. vertical slice  — один сквозной путь end-to-end
6. tasks           — атомарные, у каждой свой критерий готовности
7. implementation  — по одной задаче за сессию
8. audit           — в свежем контексте: тесты + ручные проверки
9. feedback        — находки аудита → обратно в brief + decision log
10. release        — выкат: пред-запусковые проверки, доступы, бэкапы, откат

Стадии 0–9 — цикл разработки, он повторяется. Стадия 10 проходится не каждый круг, а перед реальной публикацией.

Артефакты

Всё в docs/pipeline/ в корне проекта:

Шаблоны — в references/templates.md. Детали по стадиям — в references/stages.md. Читай нужный раздел stages.md перед началом стадии, а не по памяти.

Правило ворот (нарушать нельзя)

В конце каждой стадии:

1. Запиши артефакт на диск.
2. Обнови state.md.
3. Покажи сжатую сводку: суть + что решили. Не пересказ файла.
4. Задай явный вопрос про переход и остановись. Следующую стадию не начинаешь, пока пользователь не сказал «да / дальше / поехали».

Исключение: пользователь явно сказал «не спрашивай, гони до конца». Тогда идёшь подряд, но артефакты всё равно пишешь и в конце показываешь их список.

Правило нулевой стадии

brief.md подгружается, не пересказывается. Прочитал — работай с этим знанием молча. Пересказ brief пользователю запрещён: он его писал. Максимум — одна строка «brief загружен: <проект>, стадия N, следующая задача T-xx».

Старт сессии

1. Есть docs/pipeline/state.md? → стадия 0: прочитай brief.md, state.md, и артефакт текущей стадии. Одна строка подтверждения → продолжай с зафиксированной стадии.
2. Нет? → новый проект: создай docs/pipeline/, разведай окружение (стадия 0), переходи к стадии 1.
3. Пользователь назвал стадию явно («давай контракты») — прыгай туда, но сначала прочитай артефакты предыдущих стадий. Не выдумывай контекст, которого не читал.

Проект, где код уже есть (brownfield)

Пайплайн написан под чистый лист. В существующем проекте стадии те же, но три из них работают наоборот — не проектируешь, а извлекаешь:

• 1 idea. Brief пишется по факту: что система делает сейчас, и отдельным разделом — что мы хотим изменить. Не переписывай замысел автора, ты его не знаешь.
• 4 contracts. Контракты вычитываются из кода: реальные сигнатуры, реальные модели, реальный формат конфига. Расхождение «как написано» и «как задумано» — находка, её в decisions.md, а не молчаливое «исправление».
• 5 vertical slice. Слайс уже существует. Вместо написания — запусти имеющийся сквозной путь и покажи вывод. Не запускается — это первая задача, а не повод идти дальше.

Скоуп при этом сужается до изменения: пайплайн ведём по той части системы, которую трогаем, а не по всему репозиторию. Полная инвентаризация чужого кода — отдельная работа, и её не делают «заодно».

Стадии (кратко; развёрнуто — в references/stages.md)

0. Context load. Повторная сессия: подгрузить brief + state молча. Новый проект: разведка инструментами — что в репо, версии рантаймов, git/CI/тесты, ОС-специфика. Не спрашивай пользователя о том, что можешь проверить сам.

1. Idea → brief.md. Вытащи суть вопросами пачкой (AskUserQuestion, не по одному). Кто пользователь, какую боль решаем, что считается успехом, что явно вне скоупа, жёсткие ограничения. Итог — 3–5 предложений, подтверждённых пользователем, плюс изученные внешние зависимости (доки, лицензии, ToS). Кладётся в brief.md.

2. Plan + criteria → plan.md. 3–7 крупных шагов. К каждому — «готово = ...» в форме «дано → когда → тогда». Критерий проверяй вопросом «как я проверю это, не спрашивая мнения?». Нет ответа — переписывай. Отдельно — non-goals.

3. Risk spikes → spikes/. Только то, чего мы не знаем и что может обрушить план. Один спайк — один вопрос да/нет + факты. Код в spikes/ на выброс: не рефачить, прод-код его не импортирует. Ответы — в spikes/FINDINGS.md. Спайк убил допущение — возврат на стадию 2, это успех спайка, а не провал.

4. Contracts → contracts.md. Модели данных, публичные сигнатуры, схемы хранения и ответов, формат конфига, таксономия ошибок. Пиши как код, не прозой. Реализации нет — только формы. Проверка: по контрактам можно написать заглушки, и они состыкуются типами. Здесь же — секреты и окружение: какие ключи нужны, откуда берутся, что лежит в .env.example, что закрыто .gitignore. Ни один секрет в контракт не вписывается значением, только именем переменной.

5. Vertical slice. Один сквозной путь: вход → обработка → выход, реально работающий. Самый узкий из возможных, всё постороннее захардкожено. Реальные зависимости, не моки. Запусти и покажи вывод. Стадия не закрыта, пока слайс не отработал вживую. Сработало — сразу впиши в brief.md раздел «Как запускать» теми командами, которые только что отработали. Дальше по ним работают и будущие сессии, и аудитор на стадии 8.

6. Tasks → tasks.md. Атомарные: одна задача по объёму = один осмысленный коммит. У каждой — файлы, что делаем, DoD, зависимости. Порядок в файле = порядок выполнения.

7. Implementation. По одной задаче за сессию. Сделал → проверил DoD фактически (запуск/тест, не «выглядит правильно») → отметил [x] → отчёт в 1–3 строки → остановился и спросил. Задача разрослась — стоп, дроби в tasks.md, потом делай.

Правило трёх попыток. DoD не сходится после трёх заходов — прекрати чинить. Это не задача не решается, это задача поставлена неверно: не хватает знания (→ спайк, стадия 3), неверен контракт (→ стадия 4) или DoD непроверяем (→ стадия 6). Доложи пользователю, что перепробовал и какой из трёх случаев видишь. Четвёртая попытка тем же способом — самый дорогой способ потратить сессию.

8. Audit → audit.md. Субагент (Agent, general-purpose) со свежим контекстом. Он не видел, как писался код, — в этом смысл. Проверяет acceptance criteria запуском: тесты + ручные проверки. Промпт — по шаблону из references/stages.md. Сам аудит не проводишь.

9. Feedback. Находки аудита → обратно в brief.md (привести к тому, что построено) и в decisions.md (append-only, абсолютные даты). Оставшиеся дефекты — задачами в tasks.md. Следующий проход начинается со стадии 7, а не с 1.

10. Release → release.md. Только если проект реально куда-то выкатывается. Аудит проверял, что код делает обещанное; выкат проверяет, что он переживёт встречу с внешним миром: секреты, доступы, лимиты, бэкапы, откат. Прогоняется отдельными скиллами, а не по памяти: /launch-security для любого приложения с сервером или чужими данными, /launch-web для публичного сайта. Их отчёты ложатся в docs/launch/, находки P1 идут задачами в tasks.md и чинятся до выката, остальное — в бэклог. В release.md фиксируешь: что выкачено, куда, какой версией/коммитом, чем проверено после выката, как откатить и у кого доступы. Скиллы /launch-* вызывает пользователь — сам ты их не запускаешь, скажи одной строкой, что пора.

Роутинг: кто выполняет стадию

Модель главного цикла переключить изнутри нельзя — её задаёт пользователь через /model. Поэтому роутинг устроен так: мышление остаётся в главном цикле, рутина уходит субагентам, у которых модель прибита в их определении. Имена моделей живут там, а не здесь: скилл говорит про роли и переживает смену поколений моделей.

Стадия 7 — исполнитель задачи решается на стадии 6, не на бегу. У каждой задачи в tasks.md проставляй поле Исполнитель::

• субагент — рутина: boilerplate, тесты по готовому контракту, CLI-обвязка, парсинг по описанной схеме, механические правки. Отдаёшь субагенту pipeline-task.
• главный цикл — задача трогает архитектуру, требует решений или диалога с пользователем. Делаешь сам. Если сомневаешься — главный цикл: делегирование не бесплатно, субагент заново поднимает контекст, и на неоднозначной задаче это дороже, чем сделать самому.

Что сказать пользователю про его сторону: на стадиях 2 и 4 держать самую сильную доступную модель, на 7 при пачке рутины — можно переключиться на быструю. Актуальные имена он видит в /model, там же есть комбинированные режимы «планирование сильной, исполнение быстрой». Говори это один раз на воротах нужной стадии, не напоминай каждое сообщение.

Стиль кода — действует на всех стадиях

Комментарии

Комментарий объясняет почему, а не что. Что делает код — видно из кода.

Пиши комментарий, только если он несёт знание, которого в коде нет:

• неочевидное внешнее ограничение («у OLX private_business возвращает 200 и молча не фильтрует — рабочий параметр owner_type»)
• причина обходного пути и что сломается без него
• откуда взялось магическое значение (ссылка на спайк, тикет, замер)
• намеренный отказ от очевидного решения и его причина

Не пиши никогда:

# Увеличиваем счётчик на единицу
counter += 1

# Функция для получения объявлений
def get_listings(...):

# ---------- ХЕЛПЕРЫ ----------

Это шум: он повторяет код, устаревает первым и приучает не читать сам код. Докстринги — только там, где неочевидны контракт, единицы измерения или побочные эффекты. Тривиальной функции докстринг не нужен. Докстринг, пересказывающий имя функции ("""Сколько спать до следующего опроса""" над seconds_until_next), — чистый шум.

Измеримые ориентиры (словесного «подгоняй под окружающий код» на практике не хватает):

• Комментариев в файле — примерно 5–8% от строк кода. Выше 12% — почти наверняка объяснение самого себя, а не кода.
• Над одиночным вызовом — не больше одной строки комментария. Три строки обоснования над одной строкой кода — это сообщение коммита, а не комментарий.
• Разброс плотности между файлами одного проекта — признак поломки. Если в одном модуле 25%, а в другом 3%, значит, комментировался ход мыслей: гуще там, где дольше думал.

Проверяй себя вопросом: «это знание или мой мыслительный процесс?» Про чужой API, про грабли, про причину неочевидного выбора — знание, оставляй. Про то, как ты пришёл к решению, — процесс, выкидывай.

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

Не пересказывай общеизвестное. «Зависимости отдельным слоем, чтобы не пересобирались» в Dockerfile, «индекс ускоряет выборку» у CREATE INDEX — это знает всякий, кто читает такой файл. Правило действует и вне кода: YAML, Dockerfile, конфиги — там та же норма.

В файле без комментариев не начинай их расставлять.

Git

• Не указывай себя в авторах или контрибьюторах. Никаких Co-Authored-By, Generated with, упоминаний модели в теле коммита или PR. Автор — пользователь.
• Сообщение коммита — о сути изменения, в стиле, уже принятом в репозитории (посмотри git log, прежде чем писать первый коммит).
• Коммитишь и пушишь только по явной просьбе. «Одна задача = один коммит» из стадии 6 — это мера размера задачи, а не разрешение коммитить самому: задача должна быть такой, чтобы её изменения складывались в один осмысленный коммит.
• Закрыв задачу на стадии 7, в отчёте одной строкой предложи готовое сообщение коммита. Пользователь коммитит сам или говорит «коммить». Молчание — не согласие.
• Перед первым коммитом проверь, что в индекс не попали .env, ключи, дампы и мусор сборки. Секрет, попавший в историю, чистится ротацией ключа, а не git rm.

Как себя вести внутри стадии

• Не забегай вперёд. На контрактах не пиши реализацию, на плане не пиши контракты. Самая частая поломка пайплайна — «я тут заодно уже накидал».
• Не выдумывай факты. Не знаешь, как ведёт себя внешний сервис или библиотека — это спайк (стадия 3) или веб-поиск, а не догадка в brief.
• Решения фиксируй сразу черновой строкой, на стадии 9 соберёшь в decisions.md.
• Артефакты — на языке пользователя, код и идентификаторы — по-английски.