Spec writer

Spec Writer

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

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

Режим	Что на входе	Что на выходе
Spec	Идея, проблема, размытое описание фичи	Структурированная спецификация: проблема, цели, архитектура, решения, риски
Plan	Готовая спека (или описание проекта)	План реализации: фазы, оценки, зависимости, контрольные точки
Brief	Спека или описание проблемы	Короткая записка для руководства: проблема, решение, сроки, риски. Без кода и терминов.

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

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

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

Аудитория	Что важно	Формат
Сам разработчик (solo)	Ясность мышления, фиксация решений, передача агенту	Spec + Plan
CEO / руководство	Бизнес-смысл, сроки, риски, никакого кода	Brief
AI-агенты (Claude Code, OpenCode, Hermes)	Однозначность, полный контекст, явные шаги	Spec (полная) или Plan (если spec уже есть)

Принципы для solo-разработчика:

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

Инструменты

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

Операция	Инструмент
Прочитать существующий код/доку	Read
Найти файлы по имени/маске	Glob (например **/*.py, **/models.py)
Найти по содержимому	Grep (regex, фильтр glob)
Создать документ	Write
Точечная правка документа	Edit
Дата, git, slug (терминал)	Bash (POSIX) или PowerShell
Подтянуть внешний контекст по URL	WebFetch (опционально)

Навык не исполняет код проекта, не запускает тесты, не делает коммитов и не правит исходники. 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-уведомлений) во всех трёх режимах.

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

• clarify-prompt — превращает размытые описания в промты для AI-агента. Используй для подготовки конкретной задачи агенту; spec-writer — для проектного документа человеку/команде.
• docs-generator — README, ADR, docstrings, синхронизация CLAUDE.md/AGENTS.md. Это справочная документация по существующему коду; spec-writer проектирует то, чего ещё нет (spec/plan), либо объясняет бизнесу (brief).
• harness-engineering — обвязка проекта для агентов; spec/plan хорошо ложатся в проектную документацию и Definition of Done.
• code-archaeologist / codebase-express — изучение незнакомого проекта перед написанием спеки (раздел «текущая ситуация»).
• 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 для руководства, детали для инженеров