type: standard
aspect: format
title: "PROJECT DOCUMENTATION — Стандарт документации проектов"
version: 1.0.0
date: 2026-02-19
status: active

PROJECT DOCUMENTATION — Стандарт документации проектов

Версия: 1.0.0
Дата: 2025-12-21
Статус: active

НАЗНАЧЕНИЕ

Стандарт организации документации для изолированных проектов с навигацией.

ПРИНЦИПЫ

Принцип	Описание
Изоляция	Проект видит только свои документы
Навигация	Двусторонняя навигация INDEX ↔ документ
Относительные ссылки	Внутри проекта — только относительные пути
Единая структура	Все проекты следуют одному шаблону

СТРУКТУРА ПРОЕКТА

Минимальная структура

project-name/
├── INDEX.md           ← Оглавление проекта (обязательно)
├── PROJECT.md         ← Полное описание проекта
├── CLAUDE.md          ← Контекст для Claude
└── README.md          ← Описание для пользователей (опционально)

Расширенная структура

project-name/
├── INDEX.md
├── PROJECT.md
├── CLAUDE.md
├── README.md
├── docs/              ← Дополнительная документация
│   ├── API.md
│   ├── DEPLOYMENT.md
│   └── ARCHITECTURE.md
├── design/            ← Проектирование
│   ├── VISION.md
│   ├── MVP.md
│   └── ROADMAP.md
└── _shared/           ← Общие данные
    └── MASTER.md

ОБЯЗАТЕЛЬНЫЕ ФАЙЛЫ

1. INDEX.md

Назначение: Оглавление и точка входа в документацию проекта

Обязательные элементы:

# Project Name — Оглавление

**Тип:** {business|saas|infrastructure}
**Статус:** {design|development|production}
**Версия:** X.Y.Z

[← Назад к Parent Project](../INDEX.md)

---

## 📖 ОСНОВНЫЕ ДОКУМЕНТЫ

| Документ | Описание |
|----------|----------|
| [PROJECT.md](PROJECT.md) | **Полное описание проекта** |
| [CLAUDE.md](CLAUDE.md) | Контекст для Claude |

---

## 📊 О ПРОЕКТЕ

{Краткое описание проекта — 1-2 абзаца}

---

## 🔗 СВЯЗИ

- **Родительский проект:** [Parent](../INDEX.md)
- **Связанные проекты:**
  - [Project A](../project-a/INDEX.md)
  - [Project B](../project-b/INDEX.md)

---

**Обновлено:** YYYY-MM-DD

[← Назад к Parent Project](../INDEX.md)

Правила:

Заголовок H1: # Project Name — Оглавление
Метаданные: тип, статус, версия
Навигация вверху и внизу: [← Назад к ...](...)
Таблица основных документов
Краткое описание проекта
Секция "Связи" с родительским и связанными проектами

2. PROJECT.md

Назначение: Полное техническое описание проекта

Обязательные элементы:

# Project Name — Описание

**Тип:** {business|saas|infrastructure}
**Модель:** {описание бизнес-модели}
**Статус:** {design|development|production}
**Версия:** X.Y.Z

[← Назад в оглавление](INDEX.md) | [Parent Project](../INDEX.md)

---

## СУТЬ ПРОЕКТА

{Детальное описание}

---

## ЦЕЛЕВАЯ АУДИТОРИЯ

{Описание ЦА}

---

## ТЕХНОЛОГИИ

{Tech stack}

---

## ROADMAP

{План развития}

---

**Версия:** X.Y.Z
**Статус:** {текущий статус}

[← Назад в оглавление](INDEX.md) | [Parent Project](../INDEX.md)

Правила:

Навигация вверху: [← Назад в оглавление](INDEX.md) | [Parent](../INDEX.md)
Навигация внизу: та же самая
Только относительные ссылки внутри проекта
Абсолютные http-ссылки только для внешних ресурсов

3. CLAUDE.md

Назначение: Контекст проекта для Claude (краткая справка)

Обязательные элементы:

# Project Name — Контекст проекта

**Тип:** {business|saas|infrastructure}
**Статус:** {design|development|production}
**Версия:** X.Y.Z

[← Назад в оглавление](INDEX.md) | [Parent Project](../INDEX.md)

---

## О ПРОЕКТЕ

{Краткое описание — 1-2 абзаца}

---

## СТРУКТУРА

\```
project-name/
├── INDEX.md
├── PROJECT.md
└── ...
\```

---

## ТЕКУЩИЙ ЭТАП

**Фаза:** {текущая фаза}
**Следующий шаг:** {что делать дальше}

---

## БЫСТРЫЕ ССЫЛКИ

| Документ | Путь |
|----------|------|
| Полное описание | [PROJECT.md](PROJECT.md) |
| Родительский проект | [Parent](../INDEX.md) |

---

## СВЯЗИ

- **Родительский:** [Parent Project](../INDEX.md)
- **Связанные:** [Project A](../project-a/INDEX.md)

---

**Версия:** X.Y.Z

[← Назад в оглавление](INDEX.md) | [Parent Project](../INDEX.md)

Правила:

Максимально краткий (1-2 экрана)
Только ключевая информация для быстрого понимания
Навигация вверху и внизу

Уровень	Формат ссылки	Пример
Внутри проекта	Относительная	`[PROJECT.md](PROJECT.md)`
Родительский проект	Относительная вверх	`[Parent](../INDEX.md)`
Соседний проект	Относительная через parent	`[Project A](../project-a/INDEX.md)`
Внешний ресурс	Абсолютная http	`[Docs](http://docs.0kt.ru/...)`

Шаблоны навигации

В начале документа:

[← Назад в оглавление](INDEX.md) | [Parent Project](../INDEX.md)

В конце документа:

[← Назад в оглавление](INDEX.md) | [Parent Project](../INDEX.md)

В INDEX.md:

[← Назад к Parent Project](../INDEX.md)

URL СТРУКТУРА

Формат URL для docs.0kt.ru

http://docs.0kt.ru/projects/{parent-project}/{sub-project}/INDEX.md

Примеры:

content-factory (экосистема):
http://docs.0kt.ru/projects/content-factory/INDEX.md

contentpro (подпроект):
http://docs.0kt.ru/projects/content-factory/contentpro/INDEX.md

PROJECT.md:
http://docs.0kt.ru/projects/content-factory/contentpro/PROJECT.md

Относительные vs Абсолютные

Контекст	Использовать
Ссылка внутри проекта	Относительная: `[doc](file.md)`
Ссылка на соседний проект	Относительная: `[proj](../other/INDEX.md)`
Ссылка для пользователя (копировать)	Абсолютная: `http://docs.0kt.ru/...`

ИЗОЛЯЦИЯ ПРОЕКТОВ

Принцип изоляции

Проект НЕ ДОЛЖЕН ссылаться напрямую на документы других проектов своего уровня.

Правильно:

Связанные проекты:
- [CreatorHub](../creatorhub/INDEX.md)  ← только на INDEX.md

Неправильно:

Связанные проекты:
- [CreatorHub API](../creatorhub/docs/API.md)  ← прямая ссылка в чужой проект

Исключение: Родительские проекты могут ссылаться на любые документы дочерних проектов.

ПРИМЕРЫ

Пример 1: Экосистема с подпроектами

content-factory/              ← Экосистема
├── INDEX.md                  ← Оглавление экосистемы
├── ECOSYSTEM.md              ← Описание экосистемы
├── CLAUDE.md                 ← Контекст экосистемы
│
├── contentpro/               ← Подпроект 1
│   ├── INDEX.md              ← Оглавление contentpro
│   ├── PROJECT.md
│   └── CLAUDE.md
│
├── creatorhub/               ← Подпроект 2
│   ├── INDEX.md              ← Оглавление creatorhub
│   ├── PROJECT.md
│   └── CLAUDE.md
│
└── core-services/            ← Подпроект 3
    ├── INDEX.md              ← Оглавление core-services
    ├── PROJECT.md
    └── CLAUDE.md

URLs:

Экосистема:
http://docs.0kt.ru/projects/content-factory/INDEX.md

ContentPro:
http://docs.0kt.ru/projects/content-factory/contentpro/INDEX.md

CreatorHub:
http://docs.0kt.ru/projects/content-factory/creatorhub/INDEX.md

Core Services:
http://docs.0kt.ru/projects/content-factory/core-services/INDEX.md

Пример 2: Standalone проект

my-project/
├── INDEX.md
├── PROJECT.md
├── CLAUDE.md
└── docs/
    ├── API.md
    └── DEPLOYMENT.md

Навигация в API.md:

# API Documentation

[← Назад в оглавление](../INDEX.md)

---

{содержимое}

---

[← Назад в оглавление](../INDEX.md)

ПРОВЕРКА ДОКУМЕНТАЦИИ

Checklist

[ ] INDEX.md существует
[ ] INDEX.md содержит навигацию вверху и внизу
[ ] INDEX.md содержит таблицу документов
[ ] PROJECT.md существует
[ ] PROJECT.md содержит навигацию вверху и внизу
[ ] CLAUDE.md существует
[ ] CLAUDE.md содержит навигацию вверху и внизу
[ ] Все ссылки внутри проекта — относительные
[ ] Ссылки на родительский проект работают
[ ] Ссылки на соседние проекты ведут только на INDEX.md
[ ] Нет прямых ссылок в документы других проектов

Автоматическая проверка

# Проверка существования обязательных файлов
test -f INDEX.md && echo "✓ INDEX.md" || echo "✗ INDEX.md"
test -f PROJECT.md && echo "✓ PROJECT.md" || echo "✗ PROJECT.md"
test -f CLAUDE.md && echo "✓ CLAUDE.md" || echo "✗ CLAUDE.md"

# Проверка навигации в INDEX.md
grep -q "← Назад" INDEX.md && echo "✓ Navigation in INDEX.md" || echo "✗ No navigation"

# Проверка навигации в PROJECT.md
grep -q "← Назад в оглавление" PROJECT.md && echo "✓ Navigation in PROJECT.md" || echo "✗ No navigation"

Томография документации

Для глубокого анализа документации проекта используйте Томографию документации.

Когда применять:
- Перед переходом из фазы design → implementation
- Перед презентацией инвесторам
- При передаче проекта новой команде
- Периодически для крупных проектов (раз в квартал)

Что проверяет:
- Полноту каждого документа (оценка в %)
- Согласованность данных между документами (финансы, метрики, описания)
- Правильность последовательности (от абстрактного к конкретному)
- Возможность составить логичные треки чтения для разных ролей

Результат: Отчёт TOMOGRAPHY.md с выявленными проблемами и рекомендациями по исправлению.

МИГРАЦИЯ СУЩЕСТВУЮЩИХ ПРОЕКТОВ

Шаги миграции

Создать INDEX.md
- Использовать шаблон из этого стандарта
- Добавить список всех существующих документов
Добавить навигацию в PROJECT.md
- В начало: [← Назад в оглавление](INDEX.md) | [Parent](../INDEX.md)
- В конец: та же самая строка
Добавить навигацию в CLAUDE.md
- В начало и конец: навигация как в PROJECT.md
Добавить навигацию в другие документы
- В начало каждого: [← Назад в оглавление](INDEX.md)
- В конец: та же самая строка
Проверить ссылки
- Заменить абсолютные ссылки на относительные (внутри проекта)
- Убрать прямые ссылки в документы других проектов

СВЯЗАННЫЕ СТАНДАРТЫ

CODE_DATA_SEPARATION.md — Разделение кода и данных
CODE_LIBRARY.md — Библиотека компонентов
PROJECT_BOOTSTRAP.md — Bootstrap нового проекта
DOCUMENTATION_TOMOGRAPHY.md — Томография документации проекта

Версия: 1.0.0
Обновлено: 2025-12-21
Статус: active

PROJECT DOCUMENTATION — Стандарт документации проектов

НАЗНАЧЕНИЕ

ПРИНЦИПЫ

СТРУКТУРА ПРОЕКТА

Минимальная структура

Расширенная структура

ОБЯЗАТЕЛЬНЫЕ ФАЙЛЫ

1. INDEX.md

2. PROJECT.md

3. CLAUDE.md

НАВИГАЦИЯ

Правила навигации

Шаблоны навигации

URL СТРУКТУРА

Формат URL для docs.0kt.ru

Относительные vs Абсолютные

ИЗОЛЯЦИЯ ПРОЕКТОВ

Принцип изоляции

ПРИМЕРЫ

Пример 1: Экосистема с подпроектами

Пример 2: Standalone проект

ПРОВЕРКА ДОКУМЕНТАЦИИ

Checklist

Автоматическая проверка

Томография документации

МИГРАЦИЯ СУЩЕСТВУЮЩИХ ПРОЕКТОВ

Шаги миграции

СВЯЗАННЫЕ СТАНДАРТЫ