Product Docs

Репозиторий продуктовой, функциональной, UI, API и технической документации команды разработки.

Документация создаётся и поддерживается преимущественно AI-агентами и при этом остаётся полностью читаемой людьми.

Пошаговый workflow сотрудника — от постановки задачи до коммита, с примерами промптов — WORKFLOW.md.

Назначение

Это не хранилище Markdown-файлов, а формализованная система ведения требований:

Product Context → Product Documentation → Requirements → UI/API → Technical Specification → Review

Система обеспечивает:

• предсказуемую структуру документов;
• traceability между требованиями (FR/BR/NFR/UI/API/ADR);
• минимизацию дублирования через cross-reference;
• защиту от «придуманных» AI требований (FACT / ASSUMPTION / TBD);
• масштабирование на большую команду и много сервисов.

Архитектура документации

docs/
├── product/        # Глобальный продуктовый контекст: overview, vision, glossary,
│                   # personas, roles, business-rules, non-functional-requirements
├── features/       # Документация по фичам: одна директория = одна feature
│                   # (внутри api/ и model/ — файл на метод и на сущность)
├── changes/        # Change proposals: изменения утверждённых документов
│                   # (+ archive/ применённых и отклонённых)
├── architecture/   # Архитектура системы, доменная модель данных (data-model/) и ADR
├── api/            # Глобальные API-соглашения и документация сервисов (services/)
└── ai/             # Справочные материалы для AI: рекомендуемые external skills

templates/          # Шаблоны документов (source of truth для структуры);
rules/              # Глобальные правила для AI и людей (стиль, ID, ссылки, guardrails)
schemas/            # Стандарт метаданных, ID и простые YAML-схемы
scripts/            # Локальные автоматические проверки документации
.gigacode/skills/   # Agent Skills для работы с документацией (GigaCode CLI)
.gigacode/commands/ # Команды /feature-* и /change-*: сборка feature и change proposal
.gigacode/rules/    # Базовые правила поведения агента GigaCode
GIGACODE.md         # Entry point GigaCode CLI: импорты .gigacode/rules/
services/           # Локально подключённые репозитории сервисов (не коммитятся)

Ключевое правило: глобальный контекст не копируется в feature — feature ссылается на docs/product/, docs/architecture/, docs/api/.

Типы документов

Тип	Файл	Отвечает на	Содержит
Product	product.md	WHAT + WHY	Проблема, цель, пользователи, сценарии, scope
Requirements	requirements.md	Ожидаемое поведение	FR-XXX, BR-XXX, NFR-XXX, acceptance criteria
Model	model/	Какие данные	Индекс и файл на сущность: поля, связи, дельта существующих
UI	ui.md	Поведение интерфейса	UI-XXX, экраны, состояния, валидация
API	api/	Контракт взаимодействия	Индекс и файл на метод: API-XXX, request/response, errors
Technical	technical.md	HOW	Решение, компоненты, data flow, миграции
ADR	decisions/adr-XXX-*.md	WHY (техническое решение)	Контекст, решение, альтернативы, последствия

Уровни не смешиваются: product не содержит деталей реализации, technical не переопределяет требования.

Жизненный цикл документации

Каждый документ имеет статус в YAML frontmatter:

draft → review → approved → deprecated

• draft — создан, не проверен;
• review — на проверке (в т.ч. skill documentation-review);
• approved — утверждён, является source of truth;
• deprecated — устарел, хранится для истории; его требования не действуют.

Изменение утверждённых документов

Содержательное изменение approved-документа (добавление/изменение/удаление требований) вносится через change proposal в docs/changes/<change-name>/: proposal с дельтами требований утверждает человек, затем изменения применяются к целевым документам, а proposal архивируется. MINOR-правки и правки draft/review-документов идут обычным процессом. Правило порога — CONTRIBUTING.md, структура и жизненный цикл — docs/changes/README.md, процесс — skill change-management, команды — /change-propose и /change-apply.

Проверка документации

Локальная валидация без внешних зависимостей (нужен только Node.js >= 18):

node scripts/validate-docs.mjs

Скрипт проверяет:

• битые относительные ссылки, включая якоря и регистр путей;
• дубликаты requirement ID в пределах scope (feature / global);
• некорректный формат ID (FR-01, FR-001a, FR-XXX, fr-001);
• ссылки на несуществующие FR/BR/NFR/UI/API/ADR ID;
• отсутствующий или невалидный YAML frontmatter (правила — из schemas/);
• title и H1 не на русском языке;
• неизвестные типы документов;
• базовую структуру Markdown (rules/markdown.md) и состав feature-директорий.

Формат ошибок: файл:строка [КОД] сообщение. Exit code 0 — проверки пройдены, 1 — найдены ошибки. Запускается перед коммитом и пригоден для CI.

Source of truth

Приоритет источников информации определён в AGENTS.md (раздел «Source of truth») — единственном месте, где живёт этот список.

• Requirements описывают требуемое поведение.
• Исходный код в services/ описывает текущую реализацию.
• Расхождение между ними — сигнал для явной пометки, а не для автоматического «исправления» требований под код.

Как добавить новую feature

1. Создать директорию docs/features/<feature-name>/ (kebab-case).
2. Скопировать нужные шаблоны из templates/ (не все файлы обязательны — см. docs/features/README.md).
3. Заполнить product.md (WHAT + WHY), затем requirements.md, затем model/ (если feature вводит или меняет сущности), затем ui.md / api/, затем technical.md. В model/ и api/ — по одному файлу на сущность и на метод.
4. Присвоить требованиям ID по стандарту schemas/README.md.
5. Связать документы cross-reference (UI-004 → FR-012).
6. Прогнать review (skill documentation-review).

Для комплексной работы использовать skill documentation-orchestrator (см. AGENTS.md).

Как AI работает с документацией

Обязательный порядок для AI-агента:

1. Прочитать AGENTS.md — entry point и routing по skills.
2. Прочитать rules/ — особенно rules/ai-guardrails.md.
3. Перед изменением документа — прочитать связанные документы (product, requirements, ui, api, technical той же feature).
4. Неизвестную информацию помечать TBD, предположения — ASSUMPTION. Придумывать факты запрещено.
5. Сохранять существующие requirement ID, не переиспользовать удалённые.
6. После изменений обновлять cross-reference и запускать review.

GigaCode CLI: entry point GIGACODE.md подключает базовые правила .gigacode/rules/, skills читаются из .gigacode/skills/.

Рекомендуемые external skills

Помимо собственных skills (.gigacode/skills/), существуют внешние Agent Skills из реестра skills.sh, которые можно использовать как концептуальные ориентиры:

• prd-development — разработка PRD;
• user-story — формулирование user stories;
• documentation — общие практики ведения документации;
• api-documentation-generator — генерация API-документации;
• architecture-decision-records — ведение ADR.

Ключевое правило: source of truth — локальные .gigacode/skills/*/SKILL.md; внешние skills носят справочный характер, репозиторий не имеет runtime dependency от skills.sh. Соответствие ориентиров локальным skills и команды установки — в docs/ai/external-skills.md.

services/

services/ предназначена для локального подключения (clone/symlink) репозиториев сервисов, чей исходный код AI может анализировать при написании технической документации.

• Содержимое services/ не попадает в этот Git-репозиторий (см. .gitignore).
• Коммитится только services/README.md.
• Код в services/ — source of truth только для текущей реализации, не для требований.