^ Стандартизация знаний и правил организации для AI

Careti разработан таким образом, чтобы AI точно понимал и соблюдал правила и стандарты кодирования вашей команды. Благодаря этой системе AI функционирует как полноценный член команды, понимающий контекст проекта, а не просто как инструмент генерации кода.

Почему важна синхронизация знаний?

Ситуация	Обычные AI-инструменты	Careti
Соблюдение правил команды	Не знает правил	✅ Автоматически распознает файлы правил
Контекст проекта	Каждый раз требует объяснений	✅ Постоянная память
Согласованность кода	Разные стили у каждого инструмента	✅ Поддерживает стандарты команды
Оптимизация ролей	Нет	✅ Раздельные документы для AI и человека

Основная концепция 1: Архитектура с двумя директориями

Careti признает, что документы для AI и для людей служат разным целям. Для решения этой задачи используются две директории:

your-project/
├── .agents/                    # Для AI (English, оптимизировано по токенам)
│   ├── context/               # Системные правила
│   │   ├── agents-rules.json  # Основной файл правил (SoT)
│   │   └── ai-work-index.yaml # Индекс работ
│   ├── workflows/             # Task workflows
│   │   └── atoms/             # Повторно используемые блоки
│   ├── skills/                # AI-навыки
│   └── hooks/                 # Обработчики событий (hooks)
│
├── .users/                     # Для людей (родной язык, подробные описания)
│   ├── context/               # Контекст проекта (Markdown)
│   ├── workflows/             # Руководства по workflow
│   └── skills/                # Руководства по навыкам
│
└── AGENTS.md                   # Точка входа для AI

Почему они разделены?

Категория	.agents/ (Для AI)	.users/ (Для людей)
Язык	English (эффективные токены)	Родной язык
Формат	JSON/YAML (структурированный)	Markdown (читаемый)
Цель	Обеспечение детерминированного поведения	Предоставление подробных объяснений
Целевая аудитория	AI agents	Разработчики / Члены команды

Оптимизация токенов: Файлы в .agents/ написаны на English, чтобы передать тот же смысл с использованием меньшего количества токенов. Это позволяет эффективно использовать context window и снижает затраты.

Основная концепция 2: Система атомарных знаний (Atomic Knowledge)

Careti использует подход Atomic Knowledge. Вместо одного массивного документа знания разбиваются на минимальные единицы (Atoms) и комбинируются по мере необходимости.

Как это работает

1. Анализ задачи: AI читает ai-work-index.yaml для определения типа задачи.
2. Загрузка Workflow: Читается только соответствующий файл workflow.
3. Композиция атомов знаний: Загружаются только те атомы, на которые ссылается workflow.
4. Выполнение задачи: Выполняет задачу, используя скомбинированные знания.

Пример

.agents/workflows/
├── code-review.md             # Workflow для code review
├── feature-implementation.md  # Workflow для реализации фич
└── atoms/                     # Повторно используемые блоки
    ├── tdd-cycle.md           # Цикл TDD
    ├── naming-conventions.md  # Соглашения об именовании
    └── document-changes.md    # Документирование изменений

Преимущество: Вместо постоянной загрузки всех правил AI выборочно загружает только те правила, которые необходимы для текущей задачи, экономя токены.

Основная концепция 3: Расположение и приоритет правил

Careti использует папку .agents/context/ как единый источник правил. Это гарантирует, что AI будет следовать единым стандартам во всем проекте.

Расположение правил

Тип	Расположение	Назначение
Правила Workspace	.agents/context/	Правила конкретного проекта
Область директории	AGENTS.md	Применяются только к конкретным папкам
Глобальные правила	Documents/Careti/Rules	Применяются ко всем проектам
Workflows	.agents/workflows/	Загрузка по требованию

Почему важна стандартизация?

Проблема	Решение
Правила разбросаны в нескольких местах	Управление в одном месте
Возникают конфликты правил	Четкий порядок приоритетов
AI пропускает правила	Гарантированная автоматическая загрузка

Основная концепция 4: Синхронизация знаний внутри организации

Используя submodules, вы можете делиться правилами и знаниями между несколькими проектами во всей вашей организации.

Паттерн репозитория организации

org-context/                      # Общий репозиторий организации (Git)
├── .agents/                      # AI-контекст
│   ├── context/                  # Правила и политики организации
│   │   ├── conventions.md        # Соглашения о разработке
│   │   ├── tech-stack.md         # Технологический стек
│   │   └── security-policy.md    # Политика безопасности
│   └── workflows/                # Определения workflow
│       ├── code-review.md
│       └── release-process.md
│
├── .users/                       # Документация для пользователей (зеркальная)
│   ├── context/
│   │   ├── dev-standards.md      # Подробное руководство
│   │   └── tech-stack.md
│   └── workflows/
│       └── code-review-guide.md
│
└── AGENTS.md                     # Точка входа для AI в организации

Подключение как Submodule

# Добавление контекста организации как submodule
git submodule add git@github.com:your-org/org-context.git

your-project/
├── .agents/                # Правила проекта
├── .users/                 # Документация пользователя проекта
├── org-context/            # ← Submodule (правила организации)
│   ├── .agents/
│   └── .users/
└── AGENTS.md

4-уровневое слияние правил

Уровень 1: Глобальный (на уровне пользователя)
    ~/.agents/                    # Личные правила AI

Уровень 2: Организация
    org-context/.agents/          # AI-контекст организации

Уровень 3: Проект
    {project}/.agents/            # AI-правила проекта

Уровень 4: Локальный (для конкретной директории)
    {project}/packages/{pkg}/
    └── AGENTS.md                 # Переопределение для конкретной директории

Приоритет слияния: Локальный > Проект > Организация > Глобальный

Примеры использования

# Все задачи возможны в одном проекте:

# Задача по кодированию
"Refactor this function"
→ Обращается к правилам в .agents/context/ для выполнения задачи

# Вопрос по политике компании
"What's the remote work policy?"
→ Читает org-context/.users/policies/remote-work.md и дает ответ

# Руководство по workflow
"How do I do code review?"
→ Ссылается на org-context/.users/workflows/code-review-guide.md

Быстрый старт: команда /init

Если в вашем проекте нет стандартной структуры, вы можете сгенерировать ее автоматически с помощью команды /init.

# В чате Careti
/init

Эта команда:

• Создает структуру папок .agents/ и .users/
• Предоставляет шаблоны правил по умолчанию
• Никогда не перезаписывает существующие файлы (безопасно)

Миграция существующих проектов

Если у вас есть файлы правил в других местах, переместите их в .agents/context/.

your-project/
├── .agents/
│   ├── context/          # Файлы правил
│   │   └── coding.md     # например, Стандарты кодирования
│   └── workflows/        # Workflows (опционально)
└── AGENTS.md             # Корневые инструкции (опционально)

Ключевые преимущества

1. Настоящее партнерство

AI и разработчики общаются на основе одних и тех же документов, что исключает недопонимание.

2. Эффективность токенов

• Экономия токенов благодаря файлам в папке .agents/, написанным на English
• On-Demand Loading загружает только необходимые правила

3. Согласованность на уровне организации

Все проекты используют одни и те же правила организации через submodules.

4. Прозрачность

Разработчики могут четко видеть, как работает AI, через папку .agents/.

5. Согласованность команды

• Все члены команды используют одни и те же правила
• Надежность AI — никогда не пропускает правила
• Контроль версий — отслеживание истории изменений правил
• Гибкая область действия — выбор уровня проекта/папки/глобального уровня

Полное сравнение с Cline

Параметр	Cline	Careti
Обмен знаниями	Один файл (plain text)	Atomic Knowledge System
Эффективность	Всегда загружает все правила	On-Demand Loading
Разделение ролей	Нет	Разделение на AI и человека
Bootstrap	Ручная настройка	Автоматическое создание структуры через /init
Обмен в организации	Нет	Поддержка паттерна submodule
Приоритет правил	Неясный	Четкое 4-уровневое слияние

С чего начать

Способ 1: Автоматическая инициализация (рекомендуется)

# В чате Careti
/init

Способ 2: Ручная настройка

1. Создайте папку .agents/context/ в корне проекта
2. Напишите правила в файлах Markdown
3. Начните чат с Careti

Подробные рекомендации по написанию правил см. в документации Careti Rules Feature.

Связанная документация

• Careti Rules Feature - Руководство по написанию правил
• Document Reading Tools - AI напрямую читает документы
• Image Tools - Генерация и анализ изображений с помощью AI