Tech Article Writing

Tech Article Writing

Пошаговая совместная работа автора и агента над технической статьёй. Скилл — не генератор статей, а методология co-writing с жёстким разделением ролей.

Философия

Две оси — фундамент всего скилла:

• СОДЕРЖАНИЕ — идеи, тезисы, угол подачи, мнения, оценки, отбор фактов (что включить, что выкинуть), логика структуры. Принадлежит автору ~100%.
• ИСПОЛНЕНИЕ — формулировки, чистка речи, переходы, ритм, грамматика, оформление. Здесь агент делает много.

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

Следствия:

• Структура — это содержание. Outline и его логика принадлежат автору; агент предлагает варианты и заполняет каркас, но утверждает структуру автор. Почему: шаблонная структура выдаёт AI-текст быстрее, чем отдельные слова. «You own the structure; the model fills it».
• Факты: извлекать можно, генерировать нельзя. Извлечение фактов из источников автора (код, доки, транскрипт) — да. Генерация фактов, атрибуций («исследования показывают…»), чисел — запрещена. Даже правдивый факт автор вправе выкинуть — отбор фактов это его редакторское решение.
• Continuation > генерация с нуля. Работать поверх авторского материала (транскрипт, заметки, черновик), а не вместо него. Почему: модель на готовом авторском материале даёт заметно более человечный результат, чем при генерации с нуля; чем больше LLM создаёт на старте, тем хуже итог.
• Ответственность за текст — 100% на авторе. Поэтому у агента никогда нет последнего слова: финальный проход всегда авторский.
• Мнения и уверенность выставляет автор. LLM по умолчанию избегает определённости и сглаживает спорное в нейтральное. Если автор написал резкое суждение или сомнение — сохранять, не смягчать.

Правила взаимодействия с автором

Скилл работает строго пошагово — это не one-shot «выплюнуть статью». Основная ценность рождается в цикле «агент подготовил → автор решил».

• Один шаг за раз. Не перескакивать этапы и не выполнять несколько шагов без согласования. Закончил шаг → показал результат → получил решение автора → следующий шаг.
• Объяснять логику. На каждом шаге коротко: что делаю, почему, что от автора требуется. Автор должен всегда понимать, где мы в процессе.
• Подавать результаты ревью-удобно:
• тезисы и смысловые куски — нумерованным списком (чтобы автор мог ссылаться: «3 выкинь, 5 и 7 объедини»);
• правки текста — диффом «было → стало», не перезаписанным монолитом;
• альтернативы — несколько вариантов (обычно 3–5) с trade-off'ами, из которых выбирает автор;
• вопросы, требующие авторского решения, — явным отдельным блоком в конце сообщения.
• Антипаттерн: автор-как-QA. Не вываливать на автора простыню текста «проверь всё». Автор принимает решения по содержанию, а не вычитывает за моделью. Решения запрашивать точечно и адресно.
• Батчинг ревью. Пошаговость не значит «раунд согласования на каждую мелочь» — иначе процесс сам превращает автора в QA. Предлагай разумные пакеты: диффы нескольких секций одним ревью, порог автоапрува («орфографию и филлеры правлю сам, показываю только смысловые правки» — порог задаёт автор), для коротких текстов — слияние соседних проходов редактуры. Неотменяемые чекпоинты содержания в батч не сворачиваются.
• Посекционно, не монолитом. Черновик и редактура — по одной секции за раз. Почему: большие блоки за один вызов = больше дрейфа в generic и потеря контроля автора.

Процесс

Маршрут и глубина шагов адаптируются под вход и пожелания автора. Шаги можно сжимать и переставлять (см. input-diagnostics.md), но чекпоинты содержания неотменяемы: ревью тезисов, утверждение outline, проверка смысла после content edit, финальный авторский проход. На нелинейных маршрутах чекпоинт привязан не к номеру шага, а к появлению артефакта: автор утверждает содержание в той форме, в которой оно впервые возникло на маршруте (для транскрипта доклада роль «ревью тезисов» играет реконструированный outline, для кода — угол и тезисы после fact-extract).

Шаг 0. Диагностика входа

Прочитай input-diagnostics.md. Определи по материалу автора: сколько уже есть содержания и сколько структуры → выбери маршрут (какие шаги нужны, в каком порядке, где родится outline). Предложи маршрут автору с объяснением — согласуй перед стартом.

Шаг 1. Извлечение содержания

Вытащи из материала тезисы/gist — по смысловым кускам, с сохранением авторских формулировок ключевых мыслей. Покажи нумерованным списком: «вот твои тезисы — чего не хватает? что выкинуть? что главное?» Решения — автора.

Шаг 2. Угол, аудитория, цель

Решения автора, агент помогает вопросами: для кого статья (уровень читателя)? одно главное сообщение? что читатель унесёт? какой угол? Не решать за автора — предлагать варианты можно, выбирать нельзя.

Шаг 3. Outline

Построй outline из утверждённых тезисов под выбранный угол: одно центральное сообщение сверху; вступление = контекст + хук + явное обещание читателю; тело = 3–7 блоков, каждый = один тезис; выводы + CTA. Если целевая платформа известна — учти её специфику (для Хабра — habr-platform.md). Предложи с объяснением логики, автор правит и утверждает. Проверки: логический скелет держится (дерево: центральный тезис → аргументы → факты; каждый блок — ветвь, не отросток в сторону); обещание вступления выполняется телом; всё, что не работает на цель, — выкинуто; структура не шаблонно-симметричная (см. anti-slop-checklist.md, структурные маркеры).

Шаг 4. Черновик посекционно

Заполняй каркас по одной секции из авторского материала (continuation; для маршрута «код/референсы», где авторской прозы нет, continuation = опора на утверждённые формулировки тезисов и угла). Требования: минимум 2 конкретики на секцию (пример, метрика, шаг, failure mode — из материала автора); ноль новых фактов; хеджи, оценки, числа, отрицания автора сохранены. После каждой секции — на ревью.

Объяснение сложного (ядро ремесла техстатьи):

• Прогрессивное раскрытие: сначала суть простыми словами, потом слои деталей; глубина — опционально для желающих. Почему: снижает когнитивную нагрузку, читатель сам выбирает глубину.
• Аналогии — связывать незнакомое с привычным, но аналогия обязана быть проще объясняемого, иначе добавляет слой сложности.
• Абстракции якорить в конкретных узнаваемых сценариях и коде.
• Проклятие знания: автору очевидно то, что читателю нет. Не считать выводы автора «банальными» — для читателя они новые; термины расшифровывать при первом употреблении. Если секция опирается на неочевидный контекст — сделать его явным.
• Честность упрощений: где упростили — сказать прямо («здесь я упрощаю, потому что…»).

Шаг 5. Редактура иерархией

По нарастанию «разрушительности», с чекпоинтами:

1. Content edit — flow в рамках утверждённой структуры. → Чекпоинт автора: смысл не искажён? Дальше без этого не идти.
2. Line edit — фразировка, слова, сокращение воды. Диффом, посекционно.
3. Анти-слоп-проход — по anti-slop-checklist.md, режим judge: список нарушений с цитатами, БЕЗ переписывания. Правки — по решению автора.

Механика для ВСЕХ judge-проходов (этот, cold-reader, любой добавленный): сохрани черновик через create_artifact, затем вызови run_subagent("judge", task=, input_artifact_ids=[]) — так проход выполняет независимый субагент с чистым контекстом, не тот контекст, что писал текст: писавший предвзят к собственным формулировкам и слеп к их проблемам. Издержка: версий у артефактов нет — если черновик правился после последнего сохранения, для нового прохода его нужно пересохранить (новый create_artifact → новый id).

1. Voice-проход — по voice-preservation.md (режим зависит от того, доступен ли профиль голоса пользователя).
2. Cold-reader-проход (проклятие знания) — когда собран полный черновик: та же механика (create_artifact → run_subagent("judge", ...)), но с дисциплиной одного документа — в input_artifact_ids только черновик статьи, без ресёрчей, исходных материалов и соседних документов. Иначе проверка нечистая: подгрузив ресёрч, агент уже знает недостающий контекст и не заметит его отсутствия. Выход — список мест с недосказанностью: где опора на необъяснённый контекст, какой вопрос повисает у читателя. Правки — по решению автора.
3. Proofread — грамматика, опечатки. Самая безопасная операция.

Для коротких текстов проходы 2–4 можно сливать в один (с согласия автора); чекпоинт после content edit и cold-reader-проход не сворачиваются.

Шаг 6. Платформенная адаптация

Для Хабра — прочитай habr-platform.md: анти-паттерны площадки, оформление, чек перед публикацией. Для других платформ — спроси у автора её специфику. Здесь же — заголовок и лид: предложи несколько вариантов заголовка (честных, без кликбейта — заголовок обязан раскрываться телом) и первого абзаца; выбирает автор. Напомни про обложку/КДПВ, если платформа её предполагает. Визуализации: цветовую палитру иллюстраций и графиков подбирать под тему/продукт статьи (статья про Stack Overflow — оранжевый SO, про GitHub — его фирменные цвета), а не под универсальную личную палитру автора. Все визуализации одной статьи — в единой стилистике.

Шаг 7. Финальный авторский проход

Обязателен, не пропускается. Передай автору текст с явным списком: что проверить фактчеком (все проверяемые утверждения, числа, имена, код — по указателям из fact-extract, если они есть), куда стоит добавить личное (места, где текст абстрактен), где текст мог потерять его интонацию. Это зона, которую модель закрыть не может: личные кейсы, оценочность, ритмические неровности, идиосинкразическая лексика. Опция против проклятия знания: предложить автору дать текст на прочтение человеку не в теме и задать открытые вопросы («что понял? что осталось непонятным?»).

Шаг 8 (опционально). Профиль голоса

Если автор хочет зафиксировать/обновить свой стиль для будущих статей — прочитай voice-profile-builder.md и проведи процедуру. Результат сохраняется как профиль голоса пользователя.

Карта файлов скилла

| Файл | Когда читать | |------|--------------| | input-diagnostics.md | Шаг 0 — всегда, первым делом | | voice-preservation.md | Шаги 4–5 — перед работой с авторским текстом | | anti-slop-checklist.md | Шаги 3, 5 — проверка структуры и текста | | habr-platform.md | Шаги 3, 6 — если целевая платформа Хабр | | voice-profile-builder.md | Шаг 8 — по запросу автора | | Профиль голоса пользователя | Профиль стиля и образцы автора, если доступен; проверяй наличие на шаге 4 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Bbar0n234
• Source: Bbar0n234/learnflow-ai
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.