# Spec Writer

> Проектный документ в файл, три режима: spec (проблема, цели, архитектура, ADR-решения, риски), plan (фазы, оценки, зависимости) и brief (записка для руководства без кода и терминов). Используй когда пользователь просит «составь план для реализации пунктов из ROADMAP», «разложи это в SPEC/PLAN», «напиши спеку», «tech spec», «design doc», «запроектируй фичу», «аналитическая записка». Только документ, ничего не исполняет: нарезать на агентские куски — agent-workflow (режим decompose); документация по существующему коду — docs-generator; пакет от виртуальной команды по сырому входу — sage.

- Skill: `goldenprofile/spec-writer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add goldenprofile/spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldenprofile/spec-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: goldenprofile (https://skillmd.com/u/goldenprofile)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goldenprofile/spec-writer

---


# Spec Writer

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

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

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

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

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

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

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

Принципы:
- **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](references/templates.md) (§ Spec).
Скелет разделов:

1. Резюме (TL;DR) · 2. Проблема и контекст (текущая ситуация, бизнес-потребность) ·
3. Цели и анти-цели · 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](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](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 для руководства, детали для инженеров