Spec Writer

Spec Writer

Пишет проектные документы трёх типов как самостоятельные Markdown-файлы, которые читаются как человеческая документация: Spec (спецификация), Plan (план реализации) и Brief (аналитическая записка для руководства). Навык только пишет документ — он ничего не исполняет, не правит код проекта и не делает коммитов.

Когда какой режим использовать

Если пользователь просит и спеку, и план — делай оба документа, сначала spec, потом plan (plan ссылается на spec).

Аудитория и контекст

Навык заточен под три аудитории:

Принципы:

• Spec — это в первую очередь для тебя. Документ должен помочь самому продумать решение до того, как начнёшь писать код.
• Пиши так, чтобы агент понял. Если spec пойдёт в Claude Code — он должен содержать достаточно контекста, чтобы агент не гадал.
• Для руководства — отдельный формат. Не отправляй CEO техническую спеку. Пиши brief: проблема, решение, сроки, риски — на языке бизнеса.

Инструменты

Работа идёт штатными инструментами ассистента над файлами проекта:

Навык не исполняет код проекта, не запускает тесты, не делает коммитов и не правит исходники. Read/Glob/Grep нужны только чтобы изучить проект перед написанием документа.

Путь сохранения

Определи каталог для документов один раз, дальше передавай инструментам абсолютные пути. Порядок разрешения:

1. Переменная окружения SPEC_WRITER_DIR, если задана.
2. Путь, который явно указал пользователь.
3. Дефолт: docs/specs/ в корне проекта (создай каталог, если его нет). Вне git-репозитория — сохраняй в текущую рабочую папку или уточни путь.

Никогда не передавай инструментам строку $SPEC_WRITER_DIR буквально — сначала разверни её в реальный путь.

Имя файла: YYYY-MM-DD-<slug>-<type>.md, где <type> — spec, plan или brief (например 2026-06-23-email-notifications-spec.md). Slug — короткий, kebab-case, латиницей.

Дата

Документы датируются и именуются по дате. Перед записью любого файла бери сегодняшнюю реальную дату из контекста сессии (харнесс сообщает текущую дату). Не переиспользуй дату из примера или предыдущего документа и не угадывай год — это типовая ошибка. При необходимости получить дату в терминале: date +%F (bash) или Get-Date -Format yyyy-MM-dd (PowerShell).

Общие правила для всех режимов

1. Сначала изучи. Если проект существует — посмотри структуру, ключевые файлы, архитектуру (Glob/Grep/Read). Не пиши документ в вакууме.
2. Задавай уточняющие вопросы только если информация критична и ты не можешь заполнить пробел сам. Не больше 3-5 вопросов за раз.
3. Пиши на языке пользователя. Если пользователь пишет по-русски — документ на русском (технические термины — на языке проекта).
4. Сохраняй по правилам раздела «Путь сохранения».
5. Не выполняй код. Ты только пишешь документ — никаких коммитов, правок в проекте, запуска тестов.
6. После сохранения дай краткое резюме: что за документ, где лежит, ключевые решения.

Режим 1: Spec (спецификация)

Назначение

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

Шаблон спеки

Полный шаблон — в references/templates.md (§ Spec). Скелет разделов:

1. Резюме (TL;DR) · 2. Проблема и контекст (текущая ситуация, бизнес-потребность) ·
2. Цели и анти-цели · 4. Предлагаемое решение (обзор архитектуры, ключевые решения в формате ADR-lite «контекст → варианты → выбор → обоснование → последствия», модель данных, API/интерфейсы) · 5. Альтернативы (отклонённые) · 6. Риски и смягчение (таблица) · 7. Открытые вопросы · 8. Критерии готовности (чекбоксы).

Процесс написания спеки

1. Собери контекст: прочитай описание пользователя, изучи кодовую базу (если проект существует).
2. Выяви пробелы: что неясно? Если пробелов >3 и они критичны — задай уточняющие вопросы.
3. Сформируй документ по шаблону выше. Секции, которые неприменимы — пропускай (не пиши «N/A», просто не включай).
4. Проверь сам:
   • TL;DR понятен без чтения остального? ✓
   • Каждое решение объяснено (контекст, альтернативы, обоснование)? ✓
   • Риски перечислены конкретно (не «может не работать», а «может не работать при нагрузке >1000 RPS потому что ...»)? ✓
5. Сохрани по правилам раздела «Путь сохранения».

Режим 2: Plan (план реализации)

Назначение

Взять спеку (или описание проекта) и разложить на фазы реализации с оценками, зависимостями и рисками. Это не микро-таски TDD — это план уровня «неделя/фаза», понятный команде.

Шаблон плана

Полный шаблон — в references/templates.md (§ Plan). Скелет разделов:

1. Обзор · 2. Фазы реализации (для каждой: цель, задачи-чекбоксы, зависимости, критерий завершения, оценка в часах/днях) · 3. График зависимостей (ASCII или текст: что параллелится) · 4. Оценки — сводная таблица с буфером · 5. Риски и зависимости (внутренние/внешние) · 6. Что НЕ входит в план · 7. Контрольные точки.

Процесс написания плана

1. Загрузи контекст: прочитай spec-документ или описание от пользователя. Если спеки нет — сначала предложи написать спеку.
2. Разбей на фазы по принципу: каждая фаза — доставляемая ценность (можно задеплоить/показать), а не просто «сделали модель».
3. Оцени каждую фазу в часах или днях. Если не хватает данных — укажи диапазон («3-5 дней») и пометь как предварительную оценку.
4. Выяви зависимости между фазами и внешние блокирующие факторы.
5. Сохрани по правилам раздела «Путь сохранения».

Режим 3: Brief (аналитическая записка для руководства)

Назначение

Короткий документ (1-2 страницы) для не-технического руководителя. Никакого кода, никаких Django/Celery/Redis — только бизнес-смысл. CEO должен понять: в чём проблема, что мы делаем, сколько займёт, какие риски.

Когда использовать

• Пользователь явно просит: «напиши для CEO», «аналитическая записка», «executive summary»
• Ты написал spec и пользователь говорит «а теперь кратко для руководства»
• Пользователь описывает проблему и говорит «нужно показать CEO»

Шаблон brief

Полный шаблон — в references/templates.md (§ Brief). Скелет разделов: Суть (2-3 предложения без терминов) · Проблема (конкретно, что теряем) · Что предлагаю (в терминах бизнеса, 3-5 пунктов) · Сроки и ресурсы · Риски (2-3 честных) · Альтернативы (показать, что решение продумано) · Итог (одно предложение).

Правила для brief

1. Никакого кода. Вообще. Даже названий фреймворков — только если без них никак.
2. Один уровень детализации. Не углубляйся. Если CEO захочет деталей — он спросит.
3. Конкретные цифры где возможно. Не «часть пользователей», а «~30%». Не «быстро сделаем», а «3-4 дня».
4. Проблема → Решение → Сроки. Именно в этом порядке. CEO читает сверху вниз.
5. Объём: 1-2 страницы. Если больше — ты пишешь спеку, а не brief.

Быстрая дизамбигуация

• «Напиши спеку» / «tech spec» / «design doc» / «запроектируй фичу» → Режим 1 (Spec)
• «План разработки» / «implementation plan» / «разбей на фазы» → Режим 2 (Plan)
• «Для CEO» / «аналитическая записка» / «executive summary» / «кратко для руководства» → Режим 3 (Brief)
• «ADR» / «запиши решение» как самостоятельный документ → секция 4.2 спеки или отдельный ADR
• «И спеку, и план» → сначала Spec, потом Plan (plan ссылается на spec)

Примеры

См. references/example-spec.md, references/example-plan.md и references/example-brief.md — сквозной пример (система email-уведомлений) во всех трёх режимах.

Связанные навыки

• sage — координатор виртуальной команды: сырой вход → пакет документов (summary, discussion, design/runbook). spec-writer пишет один spec/plan/brief, когда тип документа уже ясен.
• agent-workflow — превращает размытые описания в промты для AI-агента. Используй для подготовки конкретной задачи агенту; spec-writer — для проектного документа человеку/команде.
• docs-generator — README, ADR, docstrings, синхронизация CLAUDE.md/AGENTS.md. Это справочная документация по существующему коду; spec-writer проектирует то, чего ещё нет (spec/plan), либо объясняет бизнесу (brief).
• harness-engineering — обвязка проекта для агентов; spec/plan хорошо ложатся в проектную документацию и Definition of Done.
• codebase-recon / codebase-recon — изучение незнакомого проекта перед написанием спеки (раздел «текущая ситуация»).
• django-audit / python-project-audit — если спека касается существующего Django/Python-проекта, помогут наполнить раздел «текущая ситуация» фактами.

Best practices (на чём основан)

• Amazon Kiro /spec: структура Problem → Goals → Design → Risks
• ADR (Architecture Decision Records): формат «контекст → решение → последствия» (Michael Nygard, 2011)
• RFC-культура: открытые вопросы, явные анти-цели, «что не входит»
• Google Design Docs: TL;DR для руководства, детали для инженеров