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

> 2026-09-26 · AI Release · @ai_release1

> #кодовые #семантика #spec-driven #документация #ИИ

### ⚡ Главное за 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 и автономных оркестраторов.

[Источник](https://habr.com/ru/articles/1086842/)