القائمة
Создание технической документации для нового проекта. Используй когда нужно создать PRD, SPEC, CLAUDE.md, ADR или подготовить документацию перед стартом разработки.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف 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/ для полных примеров: