ИЕРАРХИЯ CLAUDE.md

Версия: 1.0.0
Дата: 2026-02-01

ПРИНЦИП

Каждая папка = дочерний класс, наследует контекст родителя.

НИКАКОГО ХАРДКОДИНГА — все данные через наследование или кеш.

УРОВНИ ИЕРАРХИИ

WORKSPACE ($WORKSPACE)
    ↓
ORG (projects/*)
    ↓
PROJECT (projects/org/name)
    ↓
BLOCK (projects/org/name/block)
    ↓
VERSION (projects/org/name/block/v1)

1. WORKSPACE Level

Путь: $WORKSPACE/CLAUDE.md

Содержит:
- Общие правила работы
- Структура workspace
- Глобальные инструменты
- Стандарты и процессы

НЕ содержит: Данные конкретных проектов.

Пример:

# WORKSPACE: Claude Workspace

## Назначение
Рабочее пространство для всех проектов.

## Структура
- `architect/` — методология
- `system/` — платформа
- `projects/` — все проекты

## Стандарты
- [Context Blocks](architect/standards/CONTEXT_BLOCKS.md)
- [Процессы](architect/standards/processes/)

## Инструменты
- cache-resolver
- claude-loader

2. ORG Level

Путь: $WORKSPACE/projects/CLAUDE.md

Содержит:
- Список организаций
- Общие данные организаций
- Шаблоны проектов

Наследует: WORKSPACE

Пример:

---
extends: ../CLAUDE.md
---

# ORG: Projects

## Организации
- `org/` — бизнес-проекты
- `internal/` — внутренние инструменты

## Стандарты организации
- Структура проектов
- Naming conventions

3. PROJECT Level

Путь: projects/org/{PROJECT_NAME}/CLAUDE.md

Содержит:
- Описание проекта
- Credentials (БД, API ключи)
- Структура блоков
- Ссылка на ROADMAP.md

Наследует: ORG → WORKSPACE

Пример:

---
extends: ../CLAUDE.md

# Кеширование данных проекта
project:
  name: {PROJECT_NAME}
  type: ecommerce

credentials:
  database:
    host: localhost
    name: {PROJECT_NAME}_db
    user: {PROJECT_NAME}_user

  api:
    url: https://api.{PROJECT_NAME}.ru

  ozon:
    seller_id: 12345
    client_id: xxx
    # API key в .credentials.md
---

# ПРОЕКТ: Pirotehnika

## Назначение
E-commerce платформа для пиротехники.

## Блоки

- `auth/` — авторизация JWT
- `orders/` — управление заказами
- `sync/` — синхронизация с OZON
- `shared/` — общие данные

## Роадмап

См. [ROADMAP.md](./ROADMAP.md)

## Документы для подгрузки

При работе с проектом:
1. Этот CLAUDE.md (контекст проекта)
2. ROADMAP.md (план)
3. CONTEXT_BLOCKS.md (карта блоков)
4. Конкретный блок: `{block}/CLAUDE.md`

## Проверка проекта

### Критерии готовности
- [ ] Все блоки completed
- [ ] Интеграционные тесты пройдены
- [ ] Документация актуальна

### Тесты
```bash
pytest tests/integration/

---

### 4. BLOCK Level

**Путь:** `projects/org/{PROJECT_NAME}/auth/CLAUDE.md`

**Содержит:**
- Описание блока
- Границы (что делает / не делает)
- Интерфейс (API)
- Зависимости (другие блоки)
- Кеш данных из родителя
- Стадии/версии
- Проверка корректности

**Наследует:** PROJECT → ORG → WORKSPACE

**Пример:**
```markdown
---
extends: ../CLAUDE.md

# Что нужно из родителя
include:
  - credentials
  - api.url

# Кеш из других блоков
cache:
  shared:
    $ref: ../shared/api.yaml#auth_endpoints

# Метаданные блока
block:
  id: auth
  type: CODE
  status: completed
  version: v2
---

# КОНТЕКСТБЛОК: Auth

## Назначение
JWT авторизация и валидация токенов.

## Границы

**ЧТО ДЕЛАЕТ:**
- Генерация JWT токенов
- Валидация токенов
- Проверка прав доступа

**ЧТО НЕ ДЕЛАЕТ:**
- Регистрация пользователей → [registration] блок
- Хранение паролей → [users] блок

## Структура

- `v1/` — первая версия (deprecated)
- `v2/` — текущая версия (активная)
- `code/` → symlink на v2/code
- `tests/` — тесты

## Интерфейс

```python
def validate_token(token: str) -> bool:
    """Проверяет JWT токен."""
    pass

def generate_token(user_id: int) -> str:
    """Генерирует JWT токен."""
    pass

Зависимости

Какие документы подгрузить при работе с блоком:
1. Этот CLAUDE.md (контекст блока)
2. Shared API — endpoints
3. Project credentials — секреты
4. v2/CLAUDE.md — текущая версия (детали)

Стадии/Версии

v1 (2025-12-01) — базовая реализация
v2 (2026-01-15) — текущая, рефакторинг
v3 (план) — OAuth интеграция

Текущая: v2

Роадмап блока

✅ v1 базовая реализация
✅ v2 рефакторинг
⏳ v3 OAuth (в плане)

Проверка корректности

Критерии готовности

[ ] Все функции реализованы
[ ] Тесты пройдены (100%)
[ ] Type checking (mypy) пройден
[ ] Документация обновлена
[ ] Интеграция с [orders] работает

Тесты

Запуск:

pytest tests/test_auth.py -v

Критерии:
- Coverage ≥ 90%
- Все edge cases покрыты
- Performance: validate_token < 10ms

Ссылка на тесты:
tests/test_auth.py

Как удостовериться

Запустить юнит-тесты:
bash pytest tests/test_auth.py
Проверить интеграцию:
bash pytest tests/integration/test_auth_flow.py
Валидация токена вручную:
bash python3 -m auth.cli validate TOKEN
Метрики:
- Response time < 10ms
- Success rate > 99.9%

Кеш данных (resolved)

# Из ../CLAUDE.md#credentials
credentials:
  database:
    host: localhost
    name: {PROJECT_NAME}_db
  api:
    url: https://api.{PROJECT_NAME}.ru

# Из ../shared/api.yaml#auth_endpoints
endpoints:
  login: POST /auth/login
  logout: POST /auth/logout
  validate: POST /auth/validate

---

### 5. VERSION Level

**Путь:** `projects/org/{PROJECT_NAME}/auth/v2/CLAUDE.md`

**Содержит:**
- Детали конкретной версии
- Изменения от предыдущей
- Статус (active/deprecated)
- Код этой версии

**Наследует:** BLOCK → PROJECT → ORG → WORKSPACE

**Пример:**
```markdown
---
extends: ../CLAUDE.md

version:
  number: v2
  status: active
  date: 2026-01-15
  deprecated: null
---

# VERSION: Auth v2

## Изменения от v1

- Рефакторинг на async/await
- Добавлен refresh token
- Улучшена производительность (3x)

## Статус

**ACTIVE** — текущая рабочая версия.

## Содержимое

- `code/` — исходный код v2
- `tests/` — тесты v2

## Обратная совместимость

✅ API совместим с v1
✅ Миграция не требуется

## Проверка

```bash
pytest v2/tests/

---

## ПРАВИЛА НАСЛЕДОВАНИЯ

### 1. extends:

Каждый дочерний CLAUDE.md указывает родителя:

```yaml
---
extends: ../CLAUDE.md
---

2. include:

Какие секции нужны из родителя:

---
extends: ../CLAUDE.md
include:
  - credentials
  - api_endpoints
---

3. cache:

Кеш данных из других файлов:

---
cache:
  shared:
    $ref: ../shared/api.yaml#endpoints
  auth:
    $ref: ../auth/CLAUDE.md#interface
---

4. resolved:

Скомпилированный кеш (auto-generated):

---
resolved:
  credentials:
    database: {PROJECT_NAME}_db
  endpoints:
    login: POST /auth/login
---

КОМПИЛЯЦИЯ КОНТЕКСТА

Команда

claude-loader compile auth/CLAUDE.md

Процесс

Читает auth/CLAUDE.md
Видит extends: ../CLAUDE.md
Читает родителя рекурсивно (до WORKSPACE)
Извлекает секции из include:
Разрешает $ref из cache:
Генерирует resolved: секцию
Возвращает СКОМПИЛИРОВАННЫЙ документ со ВСЕМ контекстом

Результат

ОДИН файл содержит:
- Контекст WORKSPACE (стандарты)
- Контекст ORG (организация)
- Контекст PROJECT (credentials, API)
- Контекст BLOCK (интерфейс, зависимости)
- Кеш из других блоков

= ВЕСЬ НУЖНЫЙ КОНТЕКСТ для решения задачи.

ШАБЛОН УНИВЕРСАЛЬНОГО CLAUDE.md

---
# Наследование
extends: ../CLAUDE.md

# Секции из родителя
include:
  - credentials
  - api_endpoints

# Кеш внешних данных
cache:
  dependency_name:
    $ref: ../path/to/file.yaml#section

# Метаданные (опционально)
meta:
  level: workspace|org|project|block|version
  type: CODE|DOCS|OPS|DESIGN|CONTENT|TEST
  status: planned|in_progress|completed|deprecated

# Скомпилированный кеш (auto-generated, не редактировать)
resolved:
  # Здесь данные после компиляции
---

# {LEVEL}: {Name}

## Назначение

{одно предложение — что делает}

## Структура / Блоки / Содержимое

{что внутри}

## Зависимости

Какие документы подгрузить:
- [Name](path/to/CLAUDE.md)
- [File](path/to/file.yaml)

## Роадмап / Стадии

{план или ссылка на ROADMAP.md}

## Проверка корректности

### Критерии готовности
- [ ] Критерий 1
- [ ] Критерий 2

### Тесты
```bash
{команда запуска тестов}

Как удостовериться

Шаг 1
Шаг 2

Кеш / Интерфейс / Данные

{специфичное для уровня}

---

## ИНСТРУМЕНТЫ

### claude-loader

**Компиляция:**
```bash
claude-loader compile auth/CLAUDE.md > auth/COMPILED.md

Чтение с компиляцией:

claude-loader read auth/CLAUDE.md
# Возвращает скомпилированный контекст

Обновление кеша:

claude-loader update auth/CLAUDE.md
# Обновляет resolved: секцию

Валидация

claude-loader validate auth/CLAUDE.md
# Проверяет:
# - extends: указан правильно
# - $ref: разрешаются
# - include: секции существуют в родителе

ЧЕКЛИСТ СОЗДАНИЯ CLAUDE.md

[ ] Указан extends: (кроме WORKSPACE)
[ ] Указан include: (что нужно из родителя)
[ ] Указан cache: (внешние зависимости)
[ ] Описано назначение (1-2 предложения)
[ ] Перечислена структура/блоки
[ ] Указаны зависимости (какие документы подгрузить)
[ ] Есть проверка корректности (критерии + тесты)
[ ] Проверен claude-loader validate

ТИПЫ КОНТЕКСТБЛОКОВ

Тип	Описание	Пример
CODE	Исходный код, функции	auth/, orders/
DOCS	Документация	specs/, guides/
OPS	Операции, скрипты	deploy/, backup/
DESIGN	Дизайн, макеты	ui/, mockups/
CONTENT	Контент, тексты	articles/, pages/
TEST	Тесты	tests/, integration/

СТАТУСЫ БЛОКОВ

Статус	Описание
planned	Запланирован, не начат
in_progress	В разработке
completed	Готов, работает
deprecated	Устарел, не использовать

ПРАВИЛО ВЕРСИОНИРОВАНИЯ

Структура версий

block/
├── v1/           ← первая версия (deprecated)
├── v2/           ← текущая версия (active)
├── v3/           ← следующая версия (planned)
├── code/         ← symlink → v2/code
├── tests/        ← тесты текущей версии
└── CLAUDE.md     ← описание блока

Активная версия

Symlink code/ всегда указывает на активную версию:

ln -sf v2/code code

Миграция версий

Создать новую папку v3/
Скопировать код из v2/
Внести изменения
Обновить тесты
Переключить symlink: ln -sf v3/code code
Обновить CLAUDE.md (version: v3, status: active)
Пометить v2/CLAUDE.md (status: deprecated)

ПРИМЕРЫ ПОЛНЫХ ИЕРАРХИЙ

Пример 1: Проект Pirotehnika

$WORKSPACE/
├── CLAUDE.md                           [WORKSPACE]
└── projects/
    ├── CLAUDE.md                       [ORG]
    └── org/
        └── {PROJECT_NAME}/
            ├── CLAUDE.md               [PROJECT]
            ├── ROADMAP.md
            ├── CONTEXT_BLOCKS.md
            ├── auth/
            │   ├── CLAUDE.md           [BLOCK]
            │   ├── v1/
            │   │   └── CLAUDE.md       [VERSION]
            │   ├── v2/
            │   │   └── CLAUDE.md       [VERSION]
            │   ├── code/ → v2/code
            │   └── tests/
            ├── orders/
            │   ├── CLAUDE.md           [BLOCK]
            │   └── code/
            └── shared/
                ├── CLAUDE.md           [BLOCK]
                └── api.yaml

Пример 2: Внутренний инструмент

$WORKSPACE/
└── projects/
    └── internal/
        └── monitoring/
            ├── CLAUDE.md               [PROJECT]
            ├── alerts/
            │   └── CLAUDE.md           [BLOCK]
            └── metrics/
                └── CLAUDE.md           [BLOCK]

СВЯЗЬ С ДРУГИМИ СТАНДАРТАМИ

Стандарт	Связь
CONTEXT_BLOCKS.md	Концепция контекстблоков
PROJECT_BOOTSTRAP.md	Создание проекта с CLAUDE.md
QUESTIONS.md	Словарь терминов для CLAUDE.md
PROTOCOL.md	Протокол работы с документами

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

Шаг 1: Оценка

Проверить текущую структуру:

tree projects/org/{PROJECT_NAME} -L 2

Шаг 2: Создать иерархию

Создать PROJECT CLAUDE.md:
bash touch projects/org/{PROJECT_NAME}/CLAUDE.md
Заполнить по шаблону (PROJECT Level)
Создать BLOCK CLAUDE.md для каждой папки:
bash touch projects/org/{PROJECT_NAME}/auth/CLAUDE.md touch projects/org/{PROJECT_NAME}/orders/CLAUDE.md
Заполнить по шаблону (BLOCK Level)

Шаг 3: Компиляция

claude-loader validate projects/org/{PROJECT_NAME}/auth/CLAUDE.md
claude-loader compile projects/org/{PROJECT_NAME}/auth/CLAUDE.md

Шаг 4: Тестирование

Проверить что все $ref разрешаются:

claude-loader update projects/org/{PROJECT_NAME}/auth/CLAUDE.md

BEST PRACTICES

1. Минимальное дублирование

НЕ копировать данные из родителя — использовать include: и cache:.

Плохо:

# auth/CLAUDE.md
credentials:
  database:
    host: localhost  # дублирование из PROJECT

Хорошо:

# auth/CLAUDE.md
include:
  - credentials  # взять из родителя

2. Явные зависимости

Всегда указывать какие документы нужны для работы:

## Зависимости

1. [Project credentials](../CLAUDE.md#credentials)
2. [Shared API](../shared/api.yaml)
3. [Orders interface](../orders/CLAUDE.md#interface)

3. Проверяемость

Каждый блок должен иметь:
- Критерии готовности
- Команды для тестирования
- Метрики успеха

4. Версионирование

Никогда не удалять старые версии
Держать deprecated версии для истории
Symlink code/ на активную версию

5. Документация изменений

В VERSION CLAUDE.md указывать:
- Что изменилось от предыдущей версии
- Почему изменили
- Обратная совместимость (да/нет)

FAQ

Q: Нужно ли каждой папке иметь CLAUDE.md?

A: Не обязательно. Только для:
- Логических блоков (auth, orders)
- Версий (v1, v2)
- Проектов

Служебные папки (utils/, helpers/) могут не иметь.

Q: Можно ли кешировать данные из других проектов?

A: Да, через cache: и $ref:

cache:
  shared_lib:
    $ref: ../../internal/library/api.yaml#functions

Q: Как обновить resolved: секцию?

A: Автоматически:

claude-loader update auth/CLAUDE.md

Или вручную при компиляции — resolved: генерируется на лету.

Q: Что если родитель изменился?

A: Перекомпилировать:

claude-loader update auth/CLAUDE.md

Или Claude автоматически загрузит свежий при чтении.

Q: Можно ли несколько extends?

A: Нет, только один прямой родитель. Но родитель сам extends следующего → получается цепочка.

ROADMAP СТАНДАРТА

v1.0 (2026-02-01) — текущая

✅ Базовая иерархия (5 уровней)
✅ Правила наследования
✅ Шаблоны CLAUDE.md
✅ Примеры

v1.1 (план)

[ ] Инструмент claude-loader (реализация)
[ ] Автоматическая валидация в pre-commit hook
[ ] Генератор CLAUDE.md по шаблонам

v2.0 (план)

[ ] Cross-project dependencies
[ ] Автоматическая генерация CONTEXT_BLOCKS.md
[ ] Интеграция с NocoDB (метаданные блоков)

ССЫЛКИ

Context Blocks — концепция контекстблоков
Project Bootstrap — создание проектов
Questions Standard — словарь терминов
YAML Frontmatter — формат
OpenAPI $ref — синтаксис ссылок

Версия: 1.0.0
Автор: Claude Opus 4.5
Дата создания: 2026-02-01