architect/projects/project-structure-standard/PROJECT.md

type: system-project
domain: standards
name: project-structure-standard
status: active
phase: 1
created: 2026-03-26
updated: 2026-03-26
template: BASE

project-structure-standard — Стандарт структуры папки проекта

Единый стандарт: какие файлы должны быть в любой папке проекта платформы.

Текущая версия: draft
Целевая версия: v1.0.0

Проблема

Нет единого стандарта структуры папки проекта:
- Разные проекты имеют разные файлы (CLAUDE.md есть, AI.md нет, README нет)
- Шаблоны не систематизированы (BASE, @biz-example разрозненны)
- Нет описания рантайм-файлов (task.yaml, CACHE.yaml)
- Иерархия шаблонов не задокументирована

Архитектурные решения

6 файлов проекта

project/
├── README.md          ← Что это (для людей)
├── AI.md              ← Инструкции для AI-агентов (роль, алгоритм, правила)
├── CLAUDE.md          ← Контекст для Claude (краткий, ссылки вверх)
├── PROJECT.tpl.md     ← Шаблон заполнения проекта
├── PROJECT.data.md    ← Данные о проекте (метаданные)
└── PROJECT.md         ← Документ проекта (заполнен по шаблону)

Смысл каждого файла

Файл Читает Пишет Назначение
README.md Человек Человек Обзор: что это, зачем, как начать
AI.md AI Человек Полные инструкции для AI-агентов
CLAUDE.md Claude Человек Краткий контекст: ссылки вверх + текущий шаг
PROJECT.tpl.md Человек + AI Человек Шаблон: структура документа проекта
PROJECT.data.md AI AI + Человек Данные: ссылки, метрики, зависимости
PROJECT.md Человек + AI AI + Человек Итоговый документ (заполнен по шаблону)

Рантайм файлы

Файл Читает Пишет Назначение
task.yaml Claude Claude Текущие задачи, шаг, состояние
CACHE.yaml Claude Claude Сжатый контекст для рекурсивных вызовов

task.yaml — оперативное состояние исполнения:

current:
  step: N
  action: "что делаем"
done: [список завершённых]
next: [список следующих]
decisions: [принятые решения]

CACHE.yaml — кэш для COMPRESS/DECOMPRESS:

context:
  project: название
  phase: N
  decisions: [ключевые решения]
  files_changed: [список изменённых файлов]
  dependencies: {имя: версия/хэш}
compressed_at: 2026-03-26T10:00:00

Наследование CLAUDE.md

CLAUDE.md (корень workspace)
    ↓ наследует
architect/CLAUDE.md
    ↓ наследует
architect/projects/CLAUDE.md
    ↓ наследует
architect/projects/{project}/CLAUDE.md

Каждый уровень:
- Указывает parent: в frontmatter
- Добавляет только специфичный для уровня контекст
- Ссылается на AI.md для полных инструкций

Иерархия шаблонов

architect/templates/
├── BASE/              ← Базовые шаблоны (применяются ко всем)
│   ├── README.md         ← шаблон README
│   ├── AI.md             ← шаблон инструкций AI
│   ├── CLAUDE.md         ← шаблон контекста
│   ├── PROJECT.tpl.md    ← шаблон документа проекта
│   └── PROJECT.data.md   ← шаблон данных
│
├── @biz-example/      ← Для бизнес-проектов (расширяет BASE)
├── @it-example/       ← Для IT-проектов (расширяет BASE)
└── system-project/    ← Для системных проектов (расширяет BASE)

Принцип: каждый шаблон расширяет BASE, не заменяет.

Карта документов

Документ Что создать Статус
architect/standards/structure/PROJECT_STRUCTURE_STANDARD.md Нормативный документ стандарта ⏳
architect/templates/BASE/README.md Шаблон README ⏳
architect/templates/BASE/AI.md Шаблон AI-инструкций ⏳
architect/templates/BASE/CLAUDE.md Шаблон контекста ⏳
architect/templates/BASE/PROJECT.tpl.md Шаблон проекта ⏳
architect/templates/BASE/PROJECT.data.md Шаблон данных ⏳

Роадмап

Фаза 1 — v1.0.0 ⏳ (2026-03-26)

Фаза 2 — v1.1.0 (будущее)

Связанные проекты