Перейти к основному содержимому

Предложение по внедрению AI-кодинга и документации

Цели​

  1. Внедрение AI-ассистированной разработки.
  2. Создание полноценной документации для повышения эффективности разработки и выделения команды QA.

Почему Claude?​

  1. Агенты

Архитектура​

Структура репозиториев​

  • Разработчик может хранить структуру каталогов в любом каталоге своей машины.
  • Локальная структура каталогов разработчика идентична структуре проектов в GitLab.
  • Переменная окружения SPORTECO_WORKING_PATH на машине разработчика указывает на его корневой рабочий каталог. Устанавливается автоматически запуском скрипта и указанием пути до рабочего каталога.
Common/
├── documentation/     # Общая документация
│   ├── ai/            # Документация по AI
│   └── backend.md     # Архитектура backend
├── ai/
│   ├── agents/        # Описания AI-агентов
│   ├── proxy-agents/  # Шаблоны прокси-агентов
│   └── scripts/       # Скрипты управления агентами
Media/
├── documentation/     # Документация проекта Media
└── [сервисы]/
    └── .claude/agents/  # Прокси агентов
Scount/
├── documentation/     # Документация проекта Scount
└── [сервисы]/
    └── .claude/agents/  # Прокси агентов

AI-агенты​

  • Хранение: полные описания в Common/ai/agents/
  • Прокси-агенты: хранятся в Common/ai/proxy-agents/, ссылаются на полное описание агента из Common/ai/agents/, предназначены для копирования в сервисы и каталоги
  • Использование: прокси-агенты в .claude/agents/ каждого сервиса ссылаются на:
    • Полное описание агента из Common/ai/agents/
    • Общую документацию Common/documentation
    • Документацию проекта (например, Media/documentation)
    • Все пути в описаниях агентов строятся относительно SPORTECO_WORKING_PATH
    • Синхронизация: автоматическая через скрипты из Common/ai/scripts/
    • Типы агентов: backend, backend-review, frontend, frontend-review, qa, documentation

Документация​

Содержание​

  • Common
    • Корпоративные концепции разработки (backend/frontend)
    • Подходы к разработке, тестированию, документированию
    • Онбординг-материалы для новых сотрудников
  • Описания продуктов Media и Scount

Workflow​

Редактирование в Obsidian (или любом другом редакторе) ↓ Коммит в Git (контроль версий, история изменений) ↓ Автоматическое копирование в Docusaurus при коммите в master (с коммитом) ↓ Автоматическая сборка Docusaurus при коммите в master ↓ Автоматическая публикация Docusaurus в корпоративном контуре (доступ через VPN)

Преимущества​

  • Централизованное управление AI-агентами
  • Единый источник истины для документации
  • Контроль версий документации
  • Защита корпоративной информации
  • Упрощенный онбординг новых сотрудников

Подробнее (если полезно)​

  1. Разработчики хранят репозитории с кодом на своей машине в любом каталоге, но структура этого каталога полностью повторяет структуру GitLab. В переменные окружения на машине разработчика записывается переменная SPORTECO_WORKING_PATH, устанавливается скриптом.
  2. Структура каталогов: Common/, Common/documentation, Common/ai/, Common/ai/agents/, Common/ai/proxy-agents/, Common/ai/scripts/, Media/, Media/documentation, Scount/, Scount/documentation
  3. Разрабатываются хорошие описания агентов, хранятся в Common/ai/agents/. На машине разработчика в репозитории проекта (например, Media/ordering) в папку .claude/agents складываются прокси всех агентов, которые имеют минимальное описание и ссылаются на полное описание агента в Common/ai/agents/, а также на общую документацию Common/documentation и документацию проекта (например, Media/documentation).
  4. Агенты копируются во все сервисы скриптом из Common/ai/scripts/, при обновлении агентов - обновляются этим же скриптом.
  5. Агенты: backend, backend-review, frontend, frontend-review, analist, qa, documentation и т.д.
  6. В документации описываются принятые в компании концепции разработки бекенда и фронтенда, подходы к разработке, тестированию и документированию, документы для изучения новыми сотрудниками, а также подробное описание всех продуктов (Media, Scount).
  7. Документация редактируется в Obsidian и комитится в репозиторий. Так избегаем случайных изменений/потерь и имеем контроль и историю изменений документации.
  8. При коммите документация автоматически копируется в сборку Docusaurus и выкладывается в контуре компании. Доступ к документации - через VPN, т.к. это закрытая информация и содержит корпоративную тайну.