<img src="../banner.png" width="100%" alt="pipeline-optimizer banner">

Русский — Официальная русская версия pipeline-optimizer.

Pipeline Optimizer / Project-Folder Optimizer (Русский)

6-шаговая реновация без несовместимостей — применима на двух уровнях:

Имя триггера	Область применения (область)	Пример
Pipeline optimizer	Целые пайплайны, стеки, структуры документации	Ваши тематические пайплайны, например, software/, research/, games/, система агентов
Project-folder optimizer	Отдельные папки проектов внутри пайплайна	Инструмент ПО, проект научной статьи, проект игры

Под пайплайном здесь понимается тематическая структура верхнего уровня, в которой несколько проектов сосуществуют в рамках общих конвенций (например, пайплайн ПО с правилами релизов, исследовательский пайплайн с процедурой публикации).

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

Когда применяется этот навык

Навык применяется, как только вас просят улучшить, перестроить или расширить существующую структуру — а не для создания с нуля (greenfield). Конкретные триггеры:

Уровень пайплайна (область: весь пайплайн):

• «Сделать пайплайн X лучше»
• «Оптимизировать стек»
• «Отремонтировать / обновить пайплайн ПО»
• «Консолидация документации в исследовательском пайплайне»
• Существенное вмешательство в тематический пайплайн, центральный _tools/ или системные компоненты

Уровень папки проекта (область: отдельная папка проекта):

• «Навести порядок / оптимизировать папку проекта X»
• «Улучшить структуру папки в Y»
• «Провести рефакторинг одного инструмента»
• «Унифицировать настройку проекта статьи»
• «Привести папку игрового проекта в соответствие со стандартом пайплайна»

Сквозные:

• «Перестроить X / интегрировать его в существующий Y»
• «Рефакторинг», «консолидация»
• «Унифицировать конвенции»
• «Интегрировать в существующую систему»

Метафора существующего фонда здания

Чтобы отремонтировать дом, сначала нужно знать, из чего он сделан (камень, дерево, пластик), для чего он предназначен (горный приют, кузница ПО) и где он уже выполняет свои функции. Та же дисциплина применима и к пайплайнам.

---

Порядок действий — 6 шагов (НЕ пропускать, НЕ менять порядок)

Шаг A — Обследование существующего фонда

Вопрос: Из чего сделан дом?

Область пайплайна (все корневые документы + инструменты + шаблоны):

• Полностью прочитать все корневые документы (а не только фрагменты / точки вставки)
• Проверить папки шаблонов (_templates/, _TEMPLATES/) и папки инструментов (_tools/)
• Файлы регламентов: например, GITHUB-POLICY.md, RELEASE-MANAGEMENT.md, QUALITY_RULES.md, NAMING-SYSTEM.md, процедуры публикаций, …
• Снимки состояния: например, PROJECT_STATUS.md, обзоры статуса, releases.json, файлы реестров
• Чек-листы: например, чек-листы релизов, чек-листы сборки/PDF
• Рабочие процессы (Workflows): AGENTS.md, GUIDE.md, SKILL.md
• Файлы извлеченных уроков: LESSONS_LEARNED.md, MEMORY.md, файлы состояния циклов

Область папки проекта (содержимое одного проекта + соответствующие конвенции пайплайна):

• Прочитать все markdown и управляющие файлы в папке проекта (README, CHANGELOG, TASKS/TODO, DONE, CONCEPT, план действий, заметки о доказательствах, …)
• Обследовать структуру кода: src/, tests/, конфигурацию сборки (pyproject.toml, requirements.txt, манифесты проектов, файлы инструментария, …)
• Учесть конвенции родительского пайплайна (например, для проекта ПО: политика GitHub, система наименований, управление релизами, шаблоны)
• Просканировать существующие инструменты/скрипты в проекте (_tools/, _scripts/, build_*.bat, скрипты START)
• Конфигурационные файлы: .gitignore, LICENSE, NOTICE, SECURITY.md, CODE_OF_CONDUCT.md

Антипаттерн: Использование grep -l "<keyword>" для поиска точек вставки и вставка туда кода без понимания контекста файла.

Результат: Инвентаризационная заметка со всеми соответствующими конвенциями, инструментами и шаблонами в выбранной области.

Шаг B — Определение назначения

Вопрос: Для чего существует дом?

Явно сформулируйте назначение в 1–2 предложениях.

Примеры для пайплайнов:

Пайплайн	Назначение
Пайплайн ПО	Разрабатывать, тестировать и выпускать настольные приложения + веб-инструменты в магазины/GitHub
Исследовательский пайплайн	Писать научные статьи, рецензировать их, публиковать в репозиториях/серверах препринтов
Игровой пайплайн	Разрабатывать игры и публиковать их на целевой платформе
Система агентов	Система LLM для оркестрации мультиагентных систем

Примеры для папок проектов:

Папка проекта	Назначение
software/PlannerApp	Настольное приложение для планирования, коммерческое, приватный репозиторий
research/CosmologyModel	Серия статей по моделированию + численные расчеты
games/SortingChaos	Игра-сортировка, стадия альфа, прогрессия уровней

Назначение направляет каждое вмешательство — меры, которые не служат назначению, отбрасываются.

Шаг C — Набросок идеальной картины

Вопрос: Как выглядел бы идеальный дом для этих целей?

• Набросайте его с собственной точки зрения (кратко, макс. 10 пунктов)
• Привлеките сравнение с лучшими практиками (например, стек Vercel для SaaS, стек scientific-python для исследований)
• Не погружайтесь в детализацию оптимизации — достаточно концептуального наброска верхнего уровня

Результат: 5–10 пунктов «идеального состояния пайплайна»

Шаг D — Анализ разрывов + план

Четыре вопроса для каждого пайплайна:

1. Что уже есть в доме? — Даже если решено иначе, чем в идеале, но функционально эквивалентно. Пример: В идеале написано «pip-licenses для лицензий третьих сторон». Реальность: кастомный скрипт-генератор оборачивает его → функционально эквивалентно, вмешательство не требуется.

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

3. Что является нефункциональным? — Мертвый код, устаревшие конвенции, неиспользуемые инструменты.

4. Что измеримо улучшило бы функции? — Конкретные вмешательства с ожидаемой пользой.

→ На основе этого формируется конкретный план:

• Что создается заново?
• Что расширяется?
• Что демонтируется/удаляется?
• Что остается без изменений (важно назвать!)

Результат: Таблица плана с колонками Вмешательство / Существующее / Мера / Обоснование

Шаг E — Эмпирическая работа

Не планируйте только сверху вниз — собирайте проблемные места (pain points):

• Известные баги: баг-трекер, файлы TASKS/TODO/DONE
• История ошибок: файлы извлеченных уроков, логи исправления багов, реестры проверок
• Сбои автоматизации: «Что мне всегда приходится делать вручную?»
• Интервью с пользователем: спросите конкретно — проблемные места, пожелания, обходные решения
• Самотестирование: пройдите по пайплайну (создайте новый проект, запустите сборку, сымитируйте релиз) — где происходит сбой?

Эмпирически найденные проблемные места определяют приоритеты плана из шага D.

Шаг F — Повторные тесты после реализации

• Поручите свежим субагентам (не обремененным контекстом реновации) пройти по измененному рабочему процессу
• Измеримые значения «до/после»: время настройки, частота ошибок, количество ручных шагов, время сборки
• Проверка на отсутствие регрессии: работают ли существующие процессы после изменений?
• Если нет измеримого улучшения или возникла регрессия: откатите изменения или скорректируйте план

Антипаттерны (запрещено)

Антипаттерн	Ущерб	Противоядие
Поиск точек вставки вместо чтения документации	Параллельные стандарты	Шаг A в полном объеме
Перенос «лучших практик из X» 1:1	Несовместимость	Шаг D сравнивает функционально
Создание нового файла без проверки конвенций	Дублирование (например, NOTICE.md ↔ THIRD_PARTY_LICENSES.txt)	Шаг A + шаг D
Планирование сверху вниз без эмпирики	Решение не попадает в проблемную точку	Шаг E до финализации плана
Отсутствие тестирования собственных изменений	Необнаруженная регрессия	Шаг F со свежим агентом
«Уточнить позже» при неясном статусе	Пользователь обнаружит конфликт позже	При сомнениях снова пройдите шаг D вместе с пользователем

Практический пример — инцидент с NOTICE.md

Задача: Реализовать улучшения пайплайнов в нескольких тематических пайплайнах (ПО, исследования, игры).

Ошибка: Шаг A пропущен — искались только точки вставки вместо прочтения полных файлов регламентов.

Последствие: Файл NOTICE.md был внедрен как «новый файл лицензий» в 7 файлах, хотя THIRD_PARTY_LICENSES.txt + кастомный генератор лицензий (обертка над pip-licenses) уже были установлены и задокументированы в политике GitHub пайплайна (обязательные файлы + чек-лист лицензий). Во всех проектах ПО уже присутствовали файлы THIRD_PARTY.

Обнаружение: Только после вопроса пользователя («Я практически уверен, что у нас уже было управление правами»).

Исправление: Файл NOTICE.md удален из шаблона проекта, 6 других файлов скорректированы, сделана ссылка на существующий генератор лицензий вместо pip-licenses.

Урок: Если бы шаг A был выполнен в полном объеме, конфликт был бы обнаружен до записи файлов.

Практические правила

1. Для «улучшения пайплайна» сначала читайте столько же, сколько пишете.
2. Никаких новых стандартов без доказательства того, что существующего стандарта нет.
3. Используйте существующие инструменты/обертки вместо создания новых параллельных.
4. «Механическое наращивание» обычно хуже, чем «расширение существующего».
5. Откат при конфликте всегда лучше, чем поддержка двух параллельных стандартов.

Чек-лист завершения

Перед тем как доложить о завершении реновации пайплайна:

• Шаг A: прочитаны все соответствующие корневые документы?
• Шаг B: назначение пайплайна сформулировано в 1–2 предложениях?
• Шаг C: набросана идеальная картина (5–10 пунктов)?
• Шаг D: проведен анализ разрывов с таблицей (что остается / что расширяется / что добавляется / что удаляется)?
• Шаг E: проверена эмпирика (баги, уроки, самотестирование, интервью с пользователем)?
• План согласован с пользователем?
• Шаг F: протестировано со свежим субагентом — улучшение измеримо?
• Не внедрены ли параллельные стандарты?
• При конфликтах: выполнен ли откат или честно учтены расхождения?

Оптимальная структура папки проекта (для оптимизатора папки проекта)

Когда навык применяется к одной папке проекта, следующая комбинированная рекомендация служит идеальным ориентиром (шаг C):

Стандарт Anthropic (Claude Code)

Файл/папка	Функция
CLAUDE.md (корень)	Автоматически загружается Claude Code, инструкции для конкретного проекта
.claude/settings.json	Разрешения, переменные окружения, выбор модели (фиксируется в git)
.claude/settings.local.json	Локальные переопределения (НЕ фиксировать в git, добавить в .gitignore)
.claude/commands/*.md	Пользовательские слэш-команды
.claude/agents/*.md	Пользовательские субагенты
.claude/skills/<name>/SKILL.md	Навыки проекта

Ваш собственный шаблон документации проекта (рекомендуется)

Если вы поддерживаете собственный шаблон документации проекта (например, в <your-workspace>/_templates/project-docs/), выгодно использовать три профиля развертывания. Пример разделения: MINIMAL предоставляет базовый набор сессии из 7 корневых файлов (AGENTS.md, CLAUDE.md, README.md, START.md, STATE.md, TODO.md, DONE.md) плюс _tools/. STANDARD добавляет CHANGELOG.md, DECISIONS.md и PATTERNS.md. FULL расширяет набор до 14 корневых файлов и дополнительно включает ARCHITECTURE.md, WORKFLOWS.md, TOOLS.md, GLOSSARY.md, а также workflows/ и .github/.

→ Используйте такой шаблон в качестве основы для новых проектов (копирование вместо создания вручную).

Дополнения, специфичные для пайплайна (примеры)

В зависимости от пайплайна поверх добавляются другие обязательные файлы — типичные шаблоны:

• Проект ПО: LICENSE, CODE_OF_CONDUCT.md, SECURITY.md, CONTRIBUTING.md, THIRD_PARTY_LICENSES.txt (сгенерированный), pyproject.toml/requirements.txt, запись в центральном реестре релизов пайплайна. → Если доступно: использовать шаблон cookiecutter пайплайна.
• Исследовательский проект: концептуальный документ, план действий, план публикаций, папки архива/источников/результатов/данных (_archive/, _sources/, _results/, _data/), paper/ для LaTeX. Для проектов доказательств: файл заметок с цепочкой доказательств и статусом.
• Игровой проект: манифест проекта и файлы инструментария движка (например, для Roblox/Rojo: default.project.json, rokit.toml, wally.toml, selene.toml), документ дизайна игры, src/{server,client,shared}/ по конвенции движка.

Полная подробная справка

→ См. references/optimal-project-structure.md в этой папке навыка (на немецком языке). Содержит:

• Пример settings.json (схема Anthropic)
• Обязательные записи в .gitignore
• Антипаттерны (чему НЕ место в папках проектов)
• Рекомендуемые рабочие процессы по типам пайплайнов (ПО/исследования/игры)
• Конвенция заголовков YAML для файлов документации
• Эскиз автопроверки

Связанные навыки (когда использовать вместо этого?)

Навык	Когда использовать
project-onboarding	Интеграция ВНЕШНЕГО существующего репозитория в вашу систему
Project bootstrapper (если доступен)	Создание НОВОГО проекта в существующем пайплайне (с нуля, без перестройки)
Pipeline bootstrapper (если доступен)	Создание СОВЕРШЕННО НОВОГО пайплайна (редкий случай)
System onboarding (если доступен)	Настройка нового компьютера

pipeline optimizer отвечает за реновацию, а не за новое строительство или интеграцию. Если в вашей коллекции навыков есть индекс навыков, найдите в нем соответствующие навыки типа bootstrapper.

Перекрестные ссылки

• Подробная справка: references/optimal-project-structure.md (в папке этого навыка)
• Документация Anthropic Claude Code: https://docs.claude.com/en/docs/claude-code
• Если доступно: глобальные пользовательские правила (например, раздел «реновации» в вашем ~/CLAUDE.md) и описания стека конкретных пайплайнов

Выбор области применения: пайплайн vs. папка проекта

Если неясно, какая область имеется в виду, уточните до выполнения шага A:

Признак	Область применения
«Улучшить весь пайплайн ПО»	Пайплайн
«Навести порядок в папке инструмента X»	Папка проекта
«Синхронизировать центральный реестр релизов»	Пайплайн (центральный ресурс)
«Провести рефакторинг AssetBuilder в игре Y»	Папка проекта
«Внедрить конвенцию проверок в рамках всего пайплайна»	Пайплайн
«Создать файл проверки в проекте Z»	Папка проекта

При области папки проекта дополнительно всегда кратко проверяйте конвенции родительского пайплайна (расширенный шаг A), чтобы вмешательство оставалось совместимым с пайплайном.

---

История изменений

1.2.0 (2026-06-13)

• Первая публикация в библиотеке навыков: личные пути, конкретные названия пайплайнов/проектов и ссылки на приватные навыки заменены общими примерами; сама процедура (6 шагов, антипаттерны, практический пример, чек-листы) оставлена без изменений

1.1.1 (2026-06-01) и ранее

• Внутренние версии (приватный каталог навыков, до публикации)