AI 26 июля 2026 г. 7 мин чтения

AI-харнесс: Markdown-хранилище знаний для ИИ агентов

Как я настроил Git-репозиторий с Markdown-файлами, который даёт AI-ассистентам контекст о моей инфраструктуре — и работает офлайн.

ai claude opencode self-hosted markdown knowledge-base homelab

Каждый раз, когда я начинаю новую сессию с ИИ агентом, одна и та же проблема. Агент ничего не знает о моём окружении. Он не знает, что я запускаю Docker на хомсервере, что ноутбуки подключены через mesh-VPN, или что я предпочитаю NixOS для повседневной работы. Приходится объяснять всё с нуля.

Я хотел систему, где агент уже знает моё окружение до первого вопроса. Не потому что он помнит наш прошлый разговор — он не помнит — а потому что читает структурированное хранилище знаний на диске.

Это то, что я называю AI-харнесс.

Суть идеи

Харнесс — это Git-репозиторий с Markdown-файлами. Ничего сложного. Он документирует мои устройства, инфраструктуру, проекты, плейбуки, ранбуки, конвенции и решения. На каждой машине, которой я пользуюсь, есть клон этого репозитория.

Когда я открываю ИИ агента — OpenCode, Claude Code, Codex, что угодно — он сначала читает один входной файл, а затем переходит к конкретным документам, которые нужны для текущей задачи.

Ключевая идея: Markdown-файлы — это источник правды. Всё остальное — эмбеддинги, векторный поиск, MCP-серверы — опционально. Если хомсервер оффлайн, агент всё равно работает. Он просто ищет по локальным файлам с помощью grep вместо семантического поиска.

                Forgejo
                   ▲
                   │
            git push/pull
                   │
        +----------+----------+
        |                     |
   Ноутбук A            Ноутбук B
        │                     │
        │                     │
  Локальный харнесс    Локальный харнесс
        │                     │
        └─────────┬───────────┘
                  │
             Хомсервер
       (опциональный индексинг,
        MCP, эмбеддинги)

Это значит:

На ноутбуке агент читает ~/Documents/vault/ai напрямую.
Когда хомсервер доступен, агенты могут использовать семантический поиск, эмбеддинги, MCP.
Когда он оффлайн — откатываются к поиску по локальным Markdown-файлам.

Структура каталогов

Вот как выглядит харнесс:

ai/
├── AI_CONTEXT.md              # Точка входа — читать первым
├── README.md                  # Обзор и конвенции
│
├── skills/                    # Переиспользуемые знания
├── devices/                   # Документация по устройствам
├── infrastructure/            # Сеть, сервисы, безопасность
├── playbooks/                 # Пошаговые процедуры
├── runbooks/                  # Руководства по устранению проблем
├── projects/                  # Контекст проектов
├── incidents/                 # Что сломалось и как починили
├── decisions/                 # Почему были сделаны технические решения
├── memory/                    # Предпочтения, конвенции
├── prompts/                   # Переиспользуемые AI-промпты
├── snippets/                  # Фрагменты кода
└── scratch/                   # Временные заметки

Каждый каталог имеет чёткую назначение. Не все они нужны. Начните с AI_CONTEXT.md, devices/, skills/ и memory/. Остальные добавляйте по мере необходимости.

Точка входа: AI_CONTEXT.md

Этот файл — оглавление. Он должен быть маленьким, сфокусированным и всегда загружаться первым.

# AI Context — Моя инфраструктура

## Текущий фокус

**Активные проекты:**
- my-api
- hermes-agent

**Текущая работа над инфраструктурой:**
- Миграция VPN-шлюза
- Очистка NFS

## Краткая справка — Устройства

| Устройство | ОС | Роль |
|------------|-----|------|
| Хомсервер | Arch | Основной сервер, Docker, хранилище |
| Ноутбук | NixOS | Основной рабочий, разработка |

## Карта документации

| Тема | Расположение |
|------|-------------|
| Инфраструктура | infrastructure/ |
| Устройства | devices/ |
| Навыки | skills/ |
| Плейбуки | playbooks/ |
| Проекты | projects/ |

Смысл в маршрутизации, а не в документации. Скажите агенту, где искать, а не что всё делает.

Системный промпт

Здесь большинство людей ошибаются. Они пишут промпты вроде “прочитай всё под ai/.” Это тратит контекст и замедляет работу.

Вместо этого научите агента навигации:

У тебя есть доступ к моему AI-харнессу в ~/Documents/vault/ai.

Не предполагай, что ты уже знаешь моё окружение.
Получай информацию из харнесса, когда это уместно.

## Стратегия загрузки контекста

Начни с AI_CONTEXT.md.
Определи, какие дополнительные документы релевантны.
Загружай только файлы, необходимые для текущей задачи.

## Порядок поиска

1. AI_CONTEXT.md
2. Документация проекта
3. Навыки (skills)
4. Плейбуки или ранбуки
5. Устройства
6. Инфраструктура
7. Решения (decisions)
8. Память (memory)

## Рабочие принципы

Предпочитай поиск догадкам.
Если нужной информации нет — спроси, а не придумывай.
При модификации инфраструктуры сначала проверь плейбуки.

## Уровни уверенности

ВЫСОКАЯ — Информация получена напрямую из харнесса.
СРЕДНЯЯ — Выведена из нескольких документов харнесса.
НИЗКАЯ — Общие знания (в харнессе нет релевантной информации).

Никогда не выдавай информацию с НИЗКОЙ уверенностью
как часть моего окружения.

## Улучшение знаний

После завершения значимой работы подумай, стоит ли
обновить харнесс. Предлагай обновления, но не изменяй
харнесс без явной просьбы.

Заметьте: нигде не написано “прочитай весь харнесс.” Написано “ищи в нём.” Это огромная разница.

Как это работает на практике

Вы пишете:

Настрой NFS на моём ноутбуке.

Агент:

Читает AI_CONTEXT.md
Видит devices/ и skills/ в карте документации
Загружает skills/nfs-management/SKILL.md
Загружает devices/<ноутбук>.md для деталей конкретного устройства
Проверяет playbooks/setup-nfs-arch-laptop.md, если существует
Отвечает с контекстом из вашего реального сетапа

Вы пишете:

Задеплой my-api.

Агент автоматически находит:

projects/my-api/state.md — обзор проекта
playbooks/ — процедуры деплоя
skills/docker-containers/ — паттерны Docker

Без того чтобы вы упоминали хоть один из них.

Три уровня

Я думаю о харнессе как о трёхъярусной системе:

Уровень 1 — Всегда доступен. Markdown-файлы плюс grep. Без сети, без сервера. На каждой машине, потому что это просто клон Git. Возможности: ripgrep, поиск по имени файла, чтение Markdown. Справляется с 80% случаев.

Уровень 2 — Приятный бонус. Хомсервер предоставляет MCP-сервер, который оборачивает ripgrep и возвращает куски вместо целых файлов. Лучшая маршрутизация, меньше токенов. Если оффлайн — ничего не ломается.

Уровень 3 — Будущее. Семантический поиск с эмбеддингами. Хорош для абстрактных вопросов вроде “какие паттерны я использую для Docker-сети?” Стройте это только когда Уровни 1 и 2 недостаточны.

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

Советы, которые сделали работу лучше

Держите AI_CONTEXT.md маленьким. Думайте о нём как о маршрутизаторе, а не о документации. Точка входа в 50 страниц противоречит самой идее.

Добавьте секцию Current Focus. Обновляйте её периодически с активными проектами и приоритетами. Это смещает поиск агента к тому, над чем вы реально работаете.

Используйте правило рефлексии. Скажите агенту: после завершения значимой работы спросите себя “будет ли полезно Будущему Мне это запомнить?” Если да — предложите заметку. Каждый разговор улучшает вашу документацию.

Задайте порядок поиска. Скажите агенту точно, какие директории проверять и в каком порядке. Это предотвращает блуждание по десяткам файлов.

Определите уровни уверенности. Это предотвращает классическую ошибку AI — уверенно выдавать выдуманные детали об окружении, которых нет в харнессе.

Git даёт бонусы. Поскольку на каждой машине есть клон репозитория, агенты могут использовать git grep, ripgrep, поиск по имени файла — всё это удивительно эффективно даже без эмбеддингов.

Где подходит RAG

Всё, что я описал выше, технически является примитивной RAG-системой. Ручная маршрутизация вместо эмбеддингов — но паттерн тот же: запрос на вход, релевантные куски на выходе, LLM генерирует ответ.

Разница в том, как происходит поиск.

Сейчас:

Вопрос
      │
      ▼
AI_CONTEXT.md (маршрутизация)
      │
      ▼
grep / ripgrep / find
      │
      ▼
Чтение 3-5 файлов
      │
      ▼
LLM отвечает

Классический RAG:

Вопрос
      │
      ▼
Эмбеддинг запроса → векторный поиск по схожести
      │
      ▼
Возврат релевантных кусков
      │
      ▼
LLM отвечает

Преимущество RAG — работа с абстрактными вопросами. “Какие паттерны я использую для Docker-сети?” сложно ответить с помощью grep, потому что ответ может быть разбросан по skills, devices и infrastructure. Эмбеддинги находят связанный контент по смыслу, а не только по ключевым словам.

Но вот в чём дело — мой харнесс маленький. Около 65 файлов, vielleicht 30-50k токенов. Простая комбинация ripgrep, структуры каталогов и AI_CONTEXT.md отлично работает на этом масштабе. RAG добавляет сложность (модели эмбеддингов, векторные базы, пайплайны индексинга), которая пока не оправдана.

План — добавить RAG, когда харнесс вырастет до сотен файлов или когда вопросы начнут требовать семантического понимания, которое не может обеспечить поиск по ключевым словам. Архитектура построена так, что добавление RAG позже не потребует переписывания — просто направьте индексатор на тот же Git-репозиторий и позвольте ему строить эмбеддинги при коммите.

Архитектура, к которой я стремлюсь:

              Obsidian
                  │
                  ▼
               Git Push
                  │
                  ▼
             AI Harness
                  │
     ┌────────────┴────────────┐
     │                         │
Поиск по файлам         Индекс эмбеддингов
(rg/find)                (sqlite-vec)
     │                         │
     └────────────┬────────────┘
                  │
           Движок поиска
                  │
                  ▼
               OpenCode
                  │
                  ▼
                Claude

Движок поиска выбирает лучший метод: точное имя файла для известных файлов, ripgrep для текстового поиска, семантический поиск для абстрактных вопросов, метаданные для поиска по тегам, обход графа для переходов между документами. AI_CONTEXT.md остаётся маршрутизатором, сужающим пространство поиска до того, как RAG вообще запустится.

Ключевая идея: RAG — это не замена харнесса. Это стратегия поиска, которая стоит перед теми же Markdown-файлами. Формат данных остаётся стабильным, а механизм поиска эволюционирует.

Чего стоит избегать

Не превращайте харнесс в монолит. Каждый файл должен покрывать одну тему. Если файл становится длинным — разделите его.

Не загружайте всё. Смысл в избирательной загрузке. Пять файлов, а не пятьдесят.

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

Не привязывайте к одному инструменту. Markdown универсален. Если вы перейдёте с OpenCode на Claude Code или что-то другое, хранилище знаний остаётся тем же. Меняется только системный промпт.

Почему такая архитектура

Это философия Unix, применённая к AI-контексту:

Знания — это просто Markdown в Git-репозитории.
Продвинутые сервисы (MCP, векторный поиск, индексинг) — опциональные улучшения.
Любая машина с клоном репозитория может отвечать на вопросы с помощью обычного поиска по файлам.

Вы никогда не привязаны к конкретному AI-инструменту. Используете ли вы Claude Code, Codex CLI, OpenCode или что-то другое — все они работают из одного локального хранилища знаний.

В этом весь смысл. Знания живут в файлах, а не в сервисе. Сервис просто делает их быстрее для поиска.