type: standard
layer: arch
object: service-files
aspect: trio
form: table
title: "Стандарт тройки файлов: AI.md + CLAUDE.md + README.md"
status: superseded
superseded_by: arch-platform-structure.md
version: 1.0.0
date: 2026-04-11
knowledge_level: У1
parent: arch-workspace-structure.md
deps:
- arch-workspace-structure.md
- arch-document-format.md
- arch-component-structure.md

Стандарт тройки файлов

Три служебных файла присутствуют в каждом важном узле платформы. Каждый обслуживает свою аудиторию. Этот стандарт определяет: когда создавать, в каком порядке, что писать, как перекрёстно ссылаться.

1. ТРИ ФАЙЛА — ТРИ АУДИТОРИИ

AI.md       = контекст для любого AI-агента (мастер-файл)
CLAUDE.md   = AI.md + специфичное для Claude Code CLI
README.md   = AI.md + объяснения для людей / GitHub

Отношения содержимого:

AI.md   ──extends──→  CLAUDE.md  (добавляет: команды, хуки, shortcuts)
AI.md   ──extends──→  README.md  (добавляет: объяснения, контекст)

AI.md — мастер. Если содержимое меняется в AI.md → обновить CLAUDE.md и README.md.

2. КОГДА СОЗДАВАТЬ

Место	AI.md	CLAUDE.md	README.md
Корень `$WORKSPACE`	✅ обязателен	✅ обязателен	✅ обязателен
7 компонентов (`arch/`, `projector/`, `projects/`, `infra/`, `system/`, `coder/`, `services/`)	✅ обязателен	✅ обязателен	✅ обязателен
Проект `projects/org/{домен}/{проект}/`	✅ обязателен	✅ обязателен	✅ обязателен
Агент `@{имя}.agent/`	✅ главный (=AI.md платформы)	✅ + Claude-специфичное	❌ не нужен
Сервис `@{имя}.service/`	❌	✅ обязателен	✅ если публичный
Вложенные папки (`scripts/`, `src/`, `css/`)	❌	❌	❌
Поддиректория проекта (`it/`, `biz/`)	❌	⚡ если есть нюансы	❌

Правило вложенных папок: тройку НЕ создавать глубже уровня компонента или проекта.

3. СОДЕРЖИМОЕ

AI.md

Лаконичный контекст — без лишних объяснений:

# {Имя папки} — Контекст

## ЧТО ЗДЕСЬ
{1-2 предложения: что это, зачем}

## СТРУКТУРА
{дерево важных файлов/папок с однострочными описаниями}

## ПРАВИЛА
{только специфичные для этого узла ограничения}

## ССЫЛКИ
{ключевые внешние зависимости}

CLAUDE.md

AI.md + дополнения для Claude Code:

{всё содержимое AI.md}

---

## НАВИГАЦИЯ (Claude Code)
{таблица: Тема → Путь/команда}

## КОМАНДЫ
{bash-команды для типовых операций}

## ХУКИ
{если есть особые hooks или настройки}

README.md

AI.md + объяснения для людей:

{всё содержимое AI.md}

---

## КАК ИСПОЛЬЗОВАТЬ
{шаги для человека без контекста платформы}

## ПРИМЕРЫ
{конкретные примеры}

## АРХИТЕКТУРНЫЕ РЕШЕНИЯ
{почему так, а не иначе — для onboarding}

4. ПОРЯДОК СОЗДАНИЯ

1. AI.md         ← создаётся первым (мастер-контент)
2. CLAUDE.md     ← extends AI.md + добавить команды
3. README.md     ← extends AI.md + добавить объяснения

Никогда не создавать CLAUDE.md или README.md без AI.md.

5. ПРАВИЛА СИНХРОНИЗАЦИИ

При изменении содержимого:

Что изменилось	Обновить
Структура папки / новые файлы	AI.md → CLAUDE.md → README.md
Команды Claude Code	только CLAUDE.md
Объяснения для людей	только README.md
Правила и ограничения	AI.md → CLAUDE.md + README.md
Ссылки на файлы	все три (если упомянуто в каждом)

Запрет: разнобой между AI.md, CLAUDE.md, README.md. Одно и то же правило — одинаково в трёх файлах.

6. СПЕЦИАЛЬНЫЙ СЛУЧАЙ: АГЕНТЫ

У агентов @{имя}.agent/ AI.md выполняет двойную роль:
- Платформенный контекст (как обычно)
- Определение роли агента (persona, rules, L-levels)

Структура AI.md агента:

---
extends: PolicyConfidentiality
class: AgentComponent
sentinel: enabled
---

# @{имя} — Агент

## РОЛЬ
{кто я, что делаю}

## УРОВНИ ОПЕРАЦИЙ
{L0-L4 что разрешено}

## ПРОТОКОЛ РАБОТЫ
{шаги, правила, ограничения}

## SENTINEL
{sentinel_hooks}

## КОНФИДЕНЦИАЛЬНО В ЭТОЙ ЗОНЕ
{специфичные данные этого агента}

7. ПРИЗНАКИ НАРУШЕНИЯ

⚠️  CLAUDE.md существует без AI.md → создать AI.md
⚠️  README.md существует без AI.md → создать AI.md
⚠️  AI.md обновлён, CLAUDE.md устарел → синхронизировать
⚠️  Тройка создана во вложенной папке → удалить (кроме исключений §2)
⚠️  CLAUDE.md содержит правила работы (не навигацию) → вынести в AI.md

8. СВЯЗАННЫЕ ДОКУМЕНТЫ

Родитель:
- arch-workspace-structure.md — §5 Служебные файлы

Связанные:
- arch-document-format.md — формат .md документов
- arch-component-structure.md — структура компонентов
- arch-agent-registry.md — реестр агентов