Как собрать семантику проекта для кодового агента и не открыть филиал Confluence

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

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

Это не обязательно проблема модели. Я дала ей код, но не дала намерение.

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

Что здесь называется семантикой

Код отвечает на вопрос “как сейчас сделано”. Хуже он отвечает на вопросы “зачем”, “что нельзя сломать” и “какие два похожих слова означают разные вещи”.

Под семантикой проекта я имею в виду небольшой слой договоренностей:

• словарь предметной области;

• инварианты, которые должны пережить рефакторинг;

• публичные контракты;

• границы конкретного изменения.

Это похоже на Spec-Driven Development, но в уменьшенном масштабе. Документация GitHub Spec Kit описывает SDD как процесс, в котором намерение фиксируется до реализации и уточняется в несколько шагов [1]. Я не предлагаю копировать весь workflow. Для маленького проекта достаточно сделать намерение доступным агенту и связать его с тестами.

Минимальный набор файлов

Положите рядом с кодом такую структуру:

agent-context/  index.md  domain.md  contracts.md  features/    weekly-limit.md

Это не документация “на всякий случай”. У каждого файла одна работа. Если файл не помогает выбрать исходники или принять решение, он кандидат на удаление, а не на еще один подраздел.

В мини-примере есть все четыре файла, тесты и готовая инструкция для агента. Он моделирует модуль с недельной квотой.

# domain.md- Недельный лимит считается на пользователя, не на API-ключ и не на IP-адрес.- Отклоненная из-за лимита попытка не расходует квоту.- Неделя начинается в понедельник в 00:00 UTC.

Эти три строки полезнее для агента, чем еще один пересказ app/limits.py. Первая задает границу агрегации, вторая — поведение на отказе, третья — правило времени. Все три должны быть проверяемы тестами.

Как собрать контекст за вечер

Начинать с генерации документации моделью не стоит. Иначе быстро получится аккуратный пересказ package-lock.json, который никому не нужен. Я бы посмотрела пять вещей:

1. точку входа и дерево модулей;

2. файл зависимостей и команду запуска тестов;

3. публичный API или CLI;

4. две-три показательные интеграционные проверки;

5. последнюю нетривиальную фичу в истории изменений.

Из них можно собрать навигацию, имена модулей и внешний контракт. Но смысл правила “отказ не расходует квоту” из кода надежно не извлекается. Его должна записать та, кто знает предметную область.

Фильтр простой: если предложение можно без потери восстановить из исходника, не копируйте его в agent-context. Дайте путь к модулю в index.md. Если после рефакторинга утверждение все еще обязано быть верным, ему место в domain.md или в спецификации фичи.

Как этим пользуется агент

Не отправляйте весь репозиторий в первый запрос. Контекстное окно — не склад, куда нужно запихнуть все коробки перед переездом. Дайте агенту короткий маршрут:

Перед изменением прочитай agent-context/index.md.Для задачи про лимиты прочитай domain.md, contracts.md иfeatures/weekly-limit.md, затем открой названные там исходники и тесты.Сначала сопоставь каждый критерий готовности с тестом. Если критерию нетсоответствия, добавь или измени тест. Публичный контракт не меняй безобновления contracts.md.

Польза не в волшебном промпте. Маршрут заставляет сначала прочитать правила, а потом ограничивает поиск нужной частью репозитория. Если агент предлагает поменять тип результата, он видит, что это уже не локальная правка.

Что стоит автоматизировать, а что нет

Для маленького проекта достаточно двух правил в PR:

• изменился публичный API — обновите contracts.md;

• появился или изменился инвариант — обновите domain.md и тест.

Автоматизировать имеет смысл только очевидное: например, сравнение сгенерированного OpenAPI с закоммиченной схемой. Не стоит ставить CI, который требует переписать документацию после переименования переменной. Иначе контекст станет ритуалом, который все обходят с выражением лица человека, обновляющего пароль в корпоративном VPN.

Спецификацию разовой фичи после merge можно удалить. Если в ней остался постоянный инвариант, перенесите его в domain.md или contracts.md. Spec Kit тоже не предписывает единую судьбу артефактам спецификации после изменения требований [2].

Где этот подход заканчивается

Четыре файла не заменят архитектурное ревью, не сделают код агента безопасным и не разрешат конфликтующие требования. Они также перестанут быть удобными, если десятки команд одновременно меняют один репозиторий.

Здесь уже можно смотреть в сторону OpenViking. Это контекстная база для агентов, которая объединяет знания, память и skills в виртуальной файловой системе. В ней агент сначала читает короткий abstract каталога, затем overview и только потом исходные материалы. Идея близка к нашему index.md, но масштаб другой: вместо четырех файлов появляются сервер, индексация и отдельный слой хранения контекста [3].

Для pet-проекта я бы не ставила OpenViking только ради того, чтобы агент нашел два теста. Это все равно что позвать грузовой кран переставить табуретку. Но когда контекст живет дольше одной фичи, у агента есть память между сессиями, а источников уже много, такая система становится осмысленным следующим шагом.

Но до этого момента необязательно начинать с RAG, графа зависимостей и автономного оркестратора, который героически оркестрирует два Markdown-файла. Сначала стоит ответить на один вопрос: сможет ли новый человек за десять минут понять, что прочитать перед изменением лимита? Если нет, агенту тоже придется гадать, только быстрее.

Чек-лист первой версии

• [ ] index.md ведет от типа задачи к исходникам и тестам.

• [ ] domain.md содержит только термины и инварианты.

• [ ] contracts.md фиксирует внешне наблюдаемое поведение.

• [ ] У активной фичи есть критерии готовности и границы задачи.

• [ ] Каждый важный критерий покрыт тестом.

• [ ] В PR есть вопрос: изменился ли контракт или инвариант?

Этого достаточно, чтобы агент получил не “весь проект”, а его рабочую модель. А дальше инструменты стоит добавлять только там, где четырех файлов правда не хватает.

Источники

1. GitHub Spec Kit: What is Spec-Driven Development?

2. GitHub Spec Kit: Development notes

3. OpenViking: Context Database for AI Agents