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, интеграция)
• • Какой формат вывода нужен?

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

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

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

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

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

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

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

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

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

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

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

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

Запрещено:

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

Философия

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

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

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

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

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

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)

Шаблоны

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

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

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

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

Требования должны прослеживаться от бизнес-целей до 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/ — сервис транскрипции аудио