project-docs

name	project-docs
description	Создание технической документации для нового проекта. Используй когда нужно создать PRD, SPEC, CLAUDE.md, ADR или подготовить документацию перед стартом разработки.

Project Documentation Skill

Стандарт создания технической документации для агентской разработки с Claude Code.

Назначение

Этот skill используется на Шаге 0 — перед началом разработки, когда нужно:

• Трансформировать идею проекта в структурированную документацию
• Создать технические файлы-ориентиры для Claude Code
• Зафиксировать требования, ограничения и решения ДО написания кода

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

• Старт нового проекта
• Формализация существующей идеи
• Подготовка спецификации для передачи Claude Code

Процесс работы

Важно: Discovery First

НЕ начинай писать документацию, пока не проведёшь discovery. Цель — понять реальные потребности, не генерировать "правдоподобные" документы.

Чеклист discovery-вопросов

Перед созданием PRD задай заказчику:

Проблема и контекст:

• Какую проблему решаем? Почему это важно сейчас?
• Что происходит, если проблему не решить?
• Как проблема решается сейчас (если решается)?

Аудитория:

• Кто будет использовать? Их технический уровень?
• Какие у них ключевые потребности?

Scope и приоритеты:

• Каков минимальный scope для первой версии (MVP)?
• Какие функции критичны vs nice-to-have?
• Что точно НЕ нужно делать?

Технический контекст:

• Есть ли предпочтения по технологиям/стеку?
• Какие интеграции планируются?
• Есть ли ограничения (платформа, бюджет, сроки)?

Использование результата:

• Как будет использоваться? (CLI, API, интеграция)
• Какой формат вывода нужен?

Гайд по интервью

Техника: копай вглубь

Когда заказчик говорит...	Спроси...
"Хочу автоматизировать X"	"Расскажи, как ты делаешь X сейчас? Что занимает больше всего времени?"
"Нужна интеграция с Y"	"Как ты используешь Y? Какие данные оттуда нужны?"
"Хочу красивый интерфейс"	"Покажи пример того, что считаешь красивым. Какие действия должны быть на виду?"

Техника: конкретизируй

Когда заказчик говорит...	Уточни...
"Быстро"	"Что значит быстро? 1 секунда? 10 секунд?"
"Много данных"	"Сколько примерно? 1000 записей? 1 миллион?"
"Популярный контент"	"Как определяем популярность? Лайки? Репосты? Порог?"

Техника: выявляй приоритеты

• "Если бы можно было реализовать только одну функцию — какую?"
• "Что важнее: скорость работы или полнота данных?"

Validation Loops (ОБЯЗАТЕЛЬНО)

После каждого этапа СТОП — покажи результат и получи подтверждение:

Этап	Вопрос заказчику	Что может измениться
После PRD	"Правильно ли я понял цели и scope?"	Переформулировка целей, сужение scope
После SPEC	"Требования верны? Какой стек предпочитаете?"	Изменение FR, AC, приоритетов, ВЫБОР СТЕКА
После ADR-001	"Зафиксированный стек устраивает?"	Корректировка технологий

Не пропускай validation! Документация без валидации = документация на основе твоих предположений.

⚠️ Критичное правило: выбор технологий

НИКОГДА не выбирай технологический стек самостоятельно.

Перед созданием ADR-001-tech-stack.md ОБЯЗАТЕЛЬНО:

1. Проверь, указал ли пользователь стек на этапе Discovery
2. Если НЕТ или указан частично — спроси явно при валидации SPEC:
   • "Какой язык программирования предпочитаете?"
   • "Есть ли предпочтения по фреймворкам/библиотекам?"
3. Предложи варианты на основе требований из SPEC (если уместно)
4. Дождись ЯВНОГО ответа перед созданием ADR-001

Запрещено:

• Выбирать технологии "по умолчанию"
• Предполагать стек на основе типа проекта
• Создавать ADR-001 без явного согласования стека с пользователем

Философия

Документация как инструкция для AI

Исследования показывают: структурированные спецификации повышают качество генерируемого кода на 71%, а явные требования сокращают циклы доработки на 68%.

Ключевые принципы

Принцип	Описание
Разделение абстракций	PRD (зачем) → SPEC (что) → ADR (почему так) → Код (как)
Модульность	Маленькие файлы экономят токены контекстного окна
Отложенные решения	Детали реализации фиксируются в ADR, не в SPEC
Проверяемость	Каждое требование имеет acceptance criteria
Эксплицитность	AI нужны явные границы, примеры, ограничения

Что нужно AI vs людям

AI-агенты требуют	Люди предпочитают
Эксплицитные инструкции	Концептуальное понимание
Конкретные примеры I/O	Высокоуровневые обзоры
Чёткие границы и запреты	Гибкость интерпретации
Термины с определениями	Подразумеваемый контекст

Структура документации проекта

project/
├── CLAUDE.md                  # Точка входа для Claude Code
└── docs/
    ├── PRD.md                 # Бизнес-требования (зачем, для кого)
    ├── SPEC.md                # Функциональная спецификация (что)
    ├── api.md                 # Контракты интерфейсов
    ├── data-formats.md        # Форматы входных/выходных данных
    └── decisions/             # Architecture Decision Records
        ├── ADR-001-*.md
        └── ADR-002-*.md

Иерархия и связи

CLAUDE.md (точка входа, навигация)
    │
    └── docs/
         ├── PRD.md (зачем делаем, для кого, метрики успеха)
         │
         ├── SPEC.md (что делает система, acceptance criteria)
         │       │
         │       ├── api.md (CLI/REST контракты)
         │       └── data-formats.md (структуры данных)
         │
         └── decisions/
                 └── ADR-* (почему выбраны конкретные решения)

Порядок создания

Этап 0: Discovery

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

Этап 1: PRD + валидация

1. docs/PRD.md — бизнес-цели, аудитория, scope
2. ⏸️ СТОП: показать заказчику, получить подтверждение

Этап 2: SPEC + Tech Stack + валидация

3. docs/SPEC.md — функциональные требования с AC
4. docs/api.md — если есть CLI/API (детализация SPEC)
5. docs/data-formats.md — если сложные форматы (детализация SPEC)
6. ⏸️ СТОП: "Требования верны? Какой стек предпочитаете?"
   - Если стек НЕ указан на discovery — ОБЯЗАТЕЛЬНО спросить
   - Предложить варианты на основе требований
7. docs/decisions/ADR-001-tech-stack.md — ТОЛЬКО после явного согласования
8. ⏸️ СТОП: "Зафиксированный стек устраивает?"

Этап 3: Дополнительные ADR (при необходимости)

9. docs/decisions/ADR-002-*.md и далее — если есть другие архитектурные решения:
   - Выбор между паттернами
   - Компромиссы производительности
   - Интеграционные решения

Этап 4: CLAUDE.md (финальный)

10. CLAUDE.md — создать точку входа:
   - Технологический стек (на основе ADR)
   - Ключевые решения (ссылки на ADR)

Шаблоны

Шаблон	Назначение	Когда создавать
PRD.md	Бизнес-требования	После discovery (Этап 1)
SPEC.md	Функциональные требования	После валидации PRD (Этап 2)
API.md	Контракты интерфейсов	Если есть CLI/REST (Этап 2)
DATA-FORMATS.md	Форматы данных	Если сложные структуры (Этап 2)
ADR.md	Архитектурное решение	ADR-001-tech-stack обязателен (Этап 2), остальные по необходимости (Этап 3)
CLAUDE.md	Точка входа для агента	Последним, после ADR (Этап 4)

Уровни детализации

✅ Что ДОЛЖНО быть в документации

Элемент	Пример	Где
Бизнес-цели	"Сократить время обработки на 50%"	PRD
Метрики успеха	"WER < 10% для чистой речи"	PRD
Функциональные требования	"Поддержка форматов MP3, WAV, FLAC"	SPEC
Acceptance criteria	"GIVEN файл 1 час WHEN обработка THEN результат ≤30 мин"	SPEC
Нефункциональные требования	"RAM: 16 GB рекомендуется"	SPEC
Внешние контракты	CLI команды, флаги, коды ошибок	api.md
Форматы данных	JSON-схемы, примеры	data-formats.md
Глоссарий терминов	"Diarization — разделение по спикерам"	SPEC
Ограничения	"GPU обязателен", "Только batch-режим"	SPEC
Допущения	"Пользователь имеет базовые навыки CLI"	SPEC
Границы для AI	"НЕ модифицировать миграции БД"	CLAUDE.md

❌ Что НЕ ДОЛЖНО быть в спецификации

Элемент	Почему	Где фиксировать
Рабочий код	Это реализация	В коде
Имена классов/функций	Решается при разработке	В коде
Конкретные пути файлов	Решается при разработке	В коде
Выбор библиотек	Архитектурное решение	В ADR
Детали алгоритмов	Если не критичны для требований	В коде/ADR

Трассируемость

Требования должны прослеживаться от бизнес-целей до acceptance criteria:

PRD: Цель "Качественная транскрипция русской речи"
         ↓
SPEC: FR-1 "Транскрипция аудио с WER < 10%"
         ↓
SPEC: AC "GIVEN чистая русская речь WHEN транскрипция THEN WER < 10%"

Чеклист перед стартом разработки

См. checklist.md для полного чеклиста.

Минимальный набор

• CLAUDE.md создан и содержит контекст + ссылки на docs/
• docs/PRD.md определяет цели, аудиторию, scope, метрики
• docs/SPEC.md содержит все FR с acceptance criteria
• docs/decisions/ADR-001-tech-stack.md фиксирует технологический стек
• Критичные ограничения зафиксированы
• Глоссарий терминов заполнен (если есть специфика домена)

Примеры

См. директорию examples/ для полных примеров:

• stt-service/ — сервис транскрипции аудио