Как я настроил общий AI-harness для команды разработки на Pi

Один Git-репозиторий с контекстом всей экосистемы, skills для рабочих инструментов и два интерфейса: терминал и Telegram.

Инженерная задача начинается со сбора контекста

Требования находятся в таск-трекере, код — в нескольких репозиториях, история изменений и pipelines — в GitLab, ошибки — в логах и мониторинге, данные — в PostgreSQL. Обычно разработчик знает, в какой системе искать нужную информацию и как связаны проекты и сервисы.

Чтобы агент мог делать то же самое, я создал отдельный репозиторий agent. В нём хранятся описания проектов, документация, настройки Pi и skills для внутренних CLI-интеграций.

Отдельный репозиторий agent

Рабочий каталог устроен так:

~/code/company/
├── agent/
│   ├── AGENTS.md
│   ├── README.md
│   ├── docs/
│   │   └── ecosystem/
│   └── .pi/
│       ├── settings.json
│       └── skills/
├── main-application/
├── infrastructure/
├── terraform/
├── telegram-bot/
├── analytics/
└── qa/

Pi запускается из agent/, а файловые и shell-инструменты обращаются к sibling repositories через ../.

В AGENTS.md находится карта проектов и общие правила:

Workspace for agents operating across the company ecosystem.

When a task relates to an ecosystem project:

1. Find the matching sibling repository.
2. Read its README and project documentation.
3. Check the ecosystem documentation when infrastructure is relevant.
4. Do not mutate repositories or infrastructure without explicit approval.

## Projects

- `../main-application` — main CRM and web application.
- `../infrastructure` — deployment configuration.
- `../terraform` — cloud infrastructure.
- `../telegram-bot` — notification service.
- `../analytics` — analytics and data pipelines.
- `../qa` — automated tests.

AGENTS.md задаёт роли проектов и общие правила. По задаче агент выбирает нужные sibling repositories и читает их документацию и код — cross-repo контекст без monorepo.

.pi/settings.json хранит общие настройки Pi и project extensions, которые команда получает вместе с репозиторием.

Контекст загружается по задаче

Постоянно передавать модели всю внутреннюю документацию нет необходимости. В стартовом контексте достаточно правил и карты возможностей.

При запуске:
  AGENTS.md
  имена и описания skills

При выборе skill:
  SKILL.md

При выполнении конкретной операции:
  нужный файл из references/

Во время работы:
  документация проекта
  код
  результаты CLI

Интеграции:

Упрощённый пример:

---
name: youtrack
description: Use for issue IDs, issue search, task creation and comments.
---

Use `yt`.

Pass credentials through environment variables:

    YOUTRACK_BASE_URL="$TEAM_YOUTRACK_URL" 
    YOUTRACK_TOKEN="$TEAM_YOUTRACK_TOKEN" 
    yt ...

For task creation, read `references/creating-task.md`.

SKILL.md содержит условия вызова, CLI и ограничения. Операционные инструкции находятся в references/:

youtrack/
├── SKILL.md
└── references/
    ├── reading-task.md
    └── creating-task.md

Так чтение задачи не загружает инструкцию по её созданию. Credentials остаются вне Git: skill называет environment variables, а runtime передаёт значения.

Какие сценарии получились

Ценность harness проявляется в задачах, где нужно связать несколько источников контекста.

При cross-repo работе агент перечисляет затронутые repositories, связи между MR и порядок merge.

Тот же harness в Telegram

Локальный Pi удобен разработчику в терминале. Для запросов из рабочего чата используется chat-assistant с тем же harness.

chat-assistant подключает agent как pinned Git submodule и клонирует repositories проектов во внутренний workspace. После review документации и skills обновляется revision submodule, поэтому локальный Pi и Telegram используют одну версию контекста.

CLI установлены в образ Gondolin и выполняются внутри sandbox. Бот работает только в разрешённых чатах, credentials имеют ограниченную область применения, production БД остаётся read-only, а изменяющие операции требуют подтверждения.