Menú
Создание технической документации для нового проекта. Используй когда нужно создать PRD, SPEC, CLAUDE.md, ADR или подготовить документацию перед стартом разработки.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | project-docs |
| description | Создание технической документации для нового проекта. Используй когда нужно создать PRD, SPEC, CLAUDE.md, ADR или подготовить документацию перед стартом разработки. |
Стандарт создания технической документации для агентской разработки с Claude Code.
Этот skill используется на Шаге 0 — перед началом разработки, когда нужно:
НЕ начинай писать документацию, пока не проведёшь discovery. Цель — понять реальные потребности, не генерировать "правдоподобные" документы.
Перед созданием PRD задай заказчику:
Проблема и контекст:
Аудитория:
Scope и приоритеты:
Технический контекст:
Использование результата:
Техника: копай вглубь
| Когда заказчик говорит... | Спроси... |
|---|---|
| "Хочу автоматизировать X" | "Расскажи, как ты делаешь X сейчас? Что занимает больше всего времени?" |
| "Нужна интеграция с Y" | "Как ты используешь Y? Какие данные оттуда нужны?" |
| "Хочу красивый интерфейс" | "Покажи пример того, что считаешь красивым. Какие действия должны быть на виду?" |
Техника: конкретизируй
| Когда заказчик говорит... | Уточни... |
|---|---|
| "Быстро" | "Что значит быстро? 1 секунда? 10 секунд?" |
| "Много данных" | "Сколько примерно? 1000 записей? 1 миллион?" |
| "Популярный контент" | "Как определяем популярность? Лайки? Репосты? Порог?" |
Техника: выявляй приоритеты
После каждого этапа СТОП — покажи результат и получи подтверждение:
| Этап | Вопрос заказчику | Что может измениться |
|---|---|---|
| После PRD | "Правильно ли я понял цели и scope?" | Переформулировка целей, сужение scope |
| После SPEC | "Требования верны? Какой стек предпочитаете?" | Изменение FR, AC, приоритетов, ВЫБОР СТЕКА |
| После ADR-001 | "Зафиксированный стек устраивает?" | Корректировка технологий |
Не пропускай validation! Документация без валидации = документация на основе твоих предположений.
НИКОГДА не выбирай технологический стек самостоятельно.
Перед созданием ADR-001-tech-stack.md ОБЯЗАТЕЛЬНО:
Запрещено:
Исследования показывают: структурированные спецификации повышают качество генерируемого кода на 71%, а явные требования сокращают циклы доработки на 68%.
| Принцип | Описание |
|---|---|
| Разделение абстракций | PRD (зачем) → SPEC (что) → ADR (почему так) → Код (как) |
| Модульность | Маленькие файлы экономят токены контекстного окна |
| Отложенные решения | Детали реализации фиксируются в ADR, не в SPEC |
| Проверяемость | Каждое требование имеет acceptance criteria |
| Эксплицитность | AI нужны явные границы, примеры, ограничения |
| 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-* (почему выбраны конкретные решения)
Провести интервью по чеклисту выше.
Результат: понимание проблемы, аудитории, scope, ограничений.
1. docs/PRD.md — бизнес-цели, аудитория, scope
2. ⏸️ СТОП: показать заказчику, получить подтверждение
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. ⏸️ СТОП: "Зафиксированный стек устраивает?"
9. docs/decisions/ADR-002-*.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 для полного чеклиста.
См. директорию examples/ для полных примеров: