type: concept
title: Агенты и модули
status: active
version: 3.0.0
date: 2026-04-09
knowledge_level: У0

Агенты и модули

Вытекает из: PLATFORM.md
Связан с: ROLES.md

Концепция

Платформа строится из модулей. Внутри модуля живут агенты —
определения ролей для Claude Code. Модуль — это контейнер процесса,
агент — исполнитель роли внутри этого процесса.

Этот документ фиксирует разницу между пятью понятиями:
компонент, модуль, агент, AI.md, CLAUDE.md.

Пять понятий

Понятие	Форма	Что это	Пример
Компонент	папка верхнего уровня	Один из шести слоёв платформы	`project/`, `infra/`
Модуль	`@name.type/`	Автономная функциональная единица	`@projector.module/`
Агент	`{name}.ai.md`	Определение роли для Claude Code	`intake.ai.md`
AI.md	файл `AI.md`	Служебный контекст папки для AI	`@it.domain/AI.md`
CLAUDE.md	файл `CLAUDE.md`	Навигатор для Claude Code CLI	`project/CLAUDE.md`

Правило вложенности

компонент/
└── @модуль.тип/
    ├── CLAUDE.md          ← навигатор: куда идти
    ├── AI.md              ← контекст модуля для AI
    ├── {роль1}.ai.md      ← агент: роль 1
    ├── {роль2}.ai.md      ← агент: роль 2
    └── …

Агент всегда живёт внутри модуля. Отдельно стоящих .ai.md
вне @name.type/ — не бывает.

Что такое агент

Агент — это файл {name}.ai.md, который:

Определяет роль внутри процесса модуля (планировщик, исполнитель, рецензент…).
Содержит инструкции для Claude Code: что делает, чем не занимается, какие входы/выходы.
Активируется в сессии Claude Code, когда оператор переключается на эту роль.

Агент ≠ процесс, ≠ контейнер, ≠ человек. Это роль в сессии Claude Code.

Пример: @projector.module/ содержит агентов
intake.ai.md, researcher.ai.md, analyst.ai.md, designer.ai.md —
четыре роли одного процесса проектирования.

Что такое модуль

Модуль @name.type/:

Реализует один процесс (проектирование, деплой, тестирование…).
Содержит 1–N агентов — роли внутри этого процесса.
Имеет собственный CLAUDE.md и AI.md.
Автономен: может быть перенесён целиком в другой компонент.

Типы модулей фиксируются в У1-стандарте standards/naming/.
Наиболее частые: .module, .domain, .agent, .service.

AI.md и CLAUDE.md — не агенты

Файл	Для кого	Содержит
`CLAUDE.md`	Claude Code CLI (автозагрузка)	Навигатор: что в папке, куда идти
`AI.md`	Любая AI-сессия (ручная загрузка)	Контекст: правила работы с этой папкой
`{name}.ai.md`	Claude Code при активации роли	Определение роли (агент)

AI.md и CLAUDE.md — не определяют роль. Они описывают место,
в котором роль работает.

Семь модулей платформы

Каркас платформы образуют семь модулей в четырёх слоях:

arch/     @architect            analyst, writer, reviewer
project/  @projector.module     intake, researcher, analyst, designer
project/  @manager.module       planner, coordinator, controller
project/  @tester.module        planner, executor, reporter
domains/  @it.domain            dispatcher
infra/    @executor.module      provisioner, deployer, monitor
infra/    @support.module       incident, patcher, updater

Связи между модулями и процессы — в ROLES.md.

Пример: @projector.module

project/
└── @projector.module/
    ├── CLAUDE.md           ← навигатор модуля
    ├── AI.md               ← контекст процесса проектирования
    ├── intake.ai.md        ← роль: приём заявки (фаза 0)
    ├── researcher.ai.md    ← роль: исследование (фазы 1–2)
    ├── analyst.ai.md       ← роль: анализ (фазы 3–4)
    └── designer.ai.md      ← роль: проектирование (фазы 5–6)

Один модуль = один процесс = несколько ролей.
Claude Code активирует нужного агента в зависимости от фазы.

Пример: @it.domain и coder-стеки

@it.domain — диспетчер, а не исполнитель кода.
Он не содержит знаний о конкретных стеках. При получении задачи
определяет стек и передаёт в соответствующий модуль-стек:

domains/
├── @it.domain/              ← диспетчер
│   ├── CLAUDE.md
│   └── dispatcher.ai.md
│
├── @drupal.coder/           ← база знаний стека Drupal
│   ├── CLAUDE.md
│   ├── AI.md
│   └── coder.ai.md
│
├── @fastapi.coder/          ← база знаний стека FastAPI
│   └── …
│
└── @vue.coder/              ← база знаний стека Vue
    └── …

Это реализация эволюции v2 (см. ROLES.md).

Принципы

Агент всегда внутри модуля. Нет .ai.md вне @name.type/.
Один модуль — один процесс. Не смешивать проектирование и деплой.
Роли не дублируют друг друга. Если две роли делают одно и то же — это одна роль.
Контекст и определение разделены. AI.md описывает место, .ai.md — роль.
CLAUDE.md — только навигация. Никаких правил поведения внутри.

Ссылки

PLATFORM.md — шесть слоёв платформы (родитель)
ROLES.md — семь модулей и связи между ними
standards/naming/ — У1: именование модулей и агентов
standards/structure/ — У1: структура @name.type/
standards/format/format-ai-files.md — У1: формат AI.md / CLAUDE.md / .ai.md