architect/standards/arch-ai-models.md

arch-ai-models — Стандарт работы с AI на платформе

Раздел: architect/standards/
Связан с: architect/ai/

Два типа AI

Тип Определение Документация
runtime Модель на которой платформа работает — ведёт сессии, пишет код, управляет architect/ai/runtime/<модель>/
connector Модель к которой платформа подключается через API architect/ai/connectors/<модель>/

Структура документации каждой модели

Каждая модель (runtime или connector) имеет папку в architect/ai/ со следующими файлами:

Файл Назначение
README.md Что это, статус, ссылки
MODEL.md Описание модели: возможности, стоимость, когда использовать
CHANGES.md История изменений конфигурации
SETUP.md Как настроить и подключить

Правила конфигурации (runtime)

Где хранить настройки

Файл Что хранить Запрещено
/root/.claude/settings.json (глобальный, внутри контейнера) outputStyle, model, theme, env, плагины —
.claude/settings.json (проектный, git) только permissions, hooks ❌ outputStyle, model, theme
Хост вне контейнера ничего из AI-настроек ❌

Где хранить стиль (output style)

Единственный источник — git:

.claude/output-styles/default.md   ← только здесь

/root/.claude/output-styles/ — не создавать. При пересборке контейнера удалять если появилась.

Именование стилей

Два типа установки runtime-модели

Тип 1: прямо на сервер Тип 2: в контейнере
Как запускается Claude Code прямо на хосте Claude Code в Docker-контейнере
settings.json /root/.claude/settings.json /root/.claude/settings.json (volume)
Стиль воркспейс или глобальный только воркспейс (git)
Секреты переменные окружения хоста .env + bind-mount secrets/
Обновление git pull вручную entrypoint при каждом старте
Пример сервер 91.x (dev-pro-eu) сервер 155 (aipd)
Документация infra/@сервер/ai.md infra/@сервер/ai.md + entrypoint.sh

Опции для Типа 1 (прямо на сервер)

/root/.claude/settings.json:
  outputStyle: default
  model: sonnet | opus | haiku
  alwaysThinkingEnabled: true/false
  env:
    CLAUDE_SERV: <имя сервера>

Опции для Типа 2 (в контейнере)

Хост:
  .env:
    GIT_TOKEN=...
    ANTHROPIC_API_KEY=...

docker-compose.yml:
  volumes:
    - claude-auth:/root/.claude/     ← settings, credentials
    - claude-workspace:/opt/...      ← воркспейс (git)
    - ./secrets:/run/secrets/        ← резервные копии
  environment:
    - CLAUDE_SERV=<имя>
    - MODEL=sonnet|opus|haiku        ← опционально

entrypoint.sh (автоматически):
  git pull                           ← свежий стиль из git
  /root/.claude/settings.json        ← outputStyle, model, env
  rm -rf /root/.claude/output-styles ← чистка старых файлов
  .claude.json восстановить          ← из volume

Стандарт развёртывания нового сервера

Хост:
├── .env                 ← GIT_TOKEN, ANTHROPIC_API_KEY (никогда не в git)
└── docker-compose.yml   ← volumes, bind-mounts

↓ docker compose up

Entrypoint автоматически:
1. git clone/pull → /opt/claude-workspace     ← стиль из git
2. /root/.claude/settings.json                ← outputStyle, model, env
3. rm -rf /root/.claude/output-styles/        ← удалить если есть старый
4. восстановить .claude.json из volume

Результат: работает без ручных шагов, без переподключения.

Документация на уровне инфры

Каждый сервер где работает AI имеет в своей папке infra/ файл ai.md:

infra/@<имя>.server/
└── ai.md     ← какая модель, пути к конфигам, env переменные

Формат ai.md:

# AI на сервере <имя>

## Runtime
| Модель | Контейнер | Конфиг |
|--------|-----------|--------|
| Claude Code | claude | /opt/platform/claude/ |

## Настройки
- outputStyle: default
- model: sonnet
- Стиль: /opt/claude-workspace/.claude/output-styles/default.md