Компактная семантика проекта для кодового агента: 4 файла вместо Confluence

⚡ Главное за 5 секунд - Автор предлагает обойтись без тяжёлой документации и собрать компактный слой контекста для кодового агента — всего четыре коротких файла. - Подход доступен как репозиторий с готовым мини-примером, моделирующим модуль недельной квоты. - Ограничение: метод рассчитан на небольшие проекты; для десятков команд или долгоживущего контекста автор советует смотреть в сторону OpenViking. ### 🔍 Что обнаружено В статье dgerasina от 25 сентября на Habr описывается SDD-практика в уменьшенном масштабе. Суть — дать агенту намерение, а не только код. В тестовом примере агент нашёл метод, добавил счётчик и написал тест, но не учёл, что лимит считается на пользователя, а отклонённая попытка не расходует квоту. Это произошло, потому что модель получила код, но не предметную семантику. Минимальный набор файлов выглядит так: - agent-context/index.md — навигация: куда идти с задачей определённого типа; - domain.md — термины и инварианты (например, «неделя начинается в понедельник в 00:00 UTC»); - contracts.md — публичные контракты, видимые внешнему вызывающему коду; - features/*.md — границы и критерии готовности конкретной фичи. Автор даёт фильтр: если утверждение можно без потери восстановить из исходника, не копируйте его в agent-context — достаточно пути в index.md. А вот инварианты вроде «отказ не расходует квоту» из кода надёжно не извлекаются, их должна записать знающая предметную область. Для агента предлагается короткий маршрут: сначала прочитать index.md, затем для задачи про лимиты — domain.md, contracts.md и features/weekly-limit.md, после чего открыть названные исходники и тесты. Критерии готовности нужно сопоставить с тестами, а публичный контракт не менять без обновления contracts.md. ### 💡 Почему это важно Практическая польза в том, что подход даёт агенту именно ту семантику, которой не хватает моделям: «зачем», «что нельзя сломать» и различия похожих терминов. Это снижает риск регрессий — вместо уверенного, но неверного изменения агент сначала сверится с инвариантами. Кроме того, набор файлов минимален, а правила PR просты: изменился публичный API — обновите contracts.md; появился инвариант — обновите domain.md и тест. Автоматизировать стоит только очевидное, например сравнение сгенерированного OpenAPI с закоммиченной схемой. ### 🧩 Контекст Автор подчёркивает, что не предлагает копировать весь workflow Spec Kit — только сделать намерение доступным агенту и связать его с тестами. Для маленького проекта достаточно этих файлов, и они не заменяют архитектурное ревью. Когда контекст живёт дольше одной фичи, появляется память между сессиями и много источников, автор рекомендует OpenViking — контекстную базу для агентов с виртуальной файловой системой. Но для пет-проекта ставить её ради двух тестов — «всё равно что позвать грузовой кран переставить табуретку». До этого момента можно обойтись без RAG и автономных оркестраторов.

🔗 Читать на habr.com