Specification в Kavor: один раз продумайте тщательно, затем реализуйте лучше
Specification превращает намерение в долговечный контракт, который люди и CodingAgents могут читать, обсуждать, реализовывать и проверять без зависимости от памяти одной беседы.
Она может определять архитектуру, интеграцию, моделирование домена, feature, модуль или ограниченный набор исправлений. Объём меняется, ответственность — нет: объяснить, что должно стать истинным до признания работы завершённой.
Источник истины — файл
Содержимое Specification живёт в Markdown внутри Workspace. Файл принадлежит вам: открывайте его в Kavor, редактируйте другими инструментами, версионируйте в Git и позволяйте CodingAgents читать напрямую.
Kavor хранит вокруг источника только операционные метаданные: identity, status и outputs. Frontmatter сохраняет identity, позволяющий отслеживать Specification после перемещения или переименования файла.
Не редактируйте вручную поля frontmatter, которыми управляет Kavor. Пишите контракт в теле, а identity и lifecycle обновляйте операциями продукта.
Пишите сами или вместе с CodingAgent
Можно начать вручную или в соавторстве с CodingAgent. Для сложной темы полезна сессия, сфокусированная на планировании, и более высокая способность к рассуждению до начала реализации.
Хороший начальный prompt:
Проведи со мной интервью по теме X, чтобы написать Specification Y. Раздели проверенные факты, решения, допущения, non-goals, сценарии отказа и наблюдаемые критерии приёмки. Не считай документ Ready, пока остаются решения, способные изменить подход.
Более тщательное мышление здесь уменьшает переделки, потери контекста и неоднозначность реализации. Но это не гарантирует меньшую стоимость: плохая Specification остаётся плохой, даже если она длинная или написана дорогой моделью.
Минимальный контракт, способный направлять работу
Полезная Specification обычно содержит:
- контекст и текущую проблему;
- цель и определение успеха;
- non-goals, ограничивающие область;
- решения и ограничения;
- выбранный подход, если он уже определён;
- наблюдаемые критерии приёмки;
- значимые сценарии отказа и риски;
- открытые вопросы;
- ссылки на код, ADRs, issues или другие Specifications.
Если в Workspace есть лучшая конвенция, фиксированный ритуал не нужен. Но документ должен отделять решение от гипотезы и позволять оценить результат без восстановления исходной беседы.
Lifecycle — ориентир, а не украшение
Kavor использует пять состояний:
| Состояние | Практическое значение |
|---|---|
| Draft | Проблема ещё исследуется, обсуждается или решается. |
| Ready | В контракте достаточно информации для безопасного начала реализации. |
| In progress | Работа, разрешённая Specification, выполняется. |
| Blocked | Конкретное условие препятствует значимому прогрессу. |
| Done | Цель достигнута, и требуемой контрактом работы не осталось. |
Status намеренно advisory. Kavor не превращает checkboxes Markdown в собственную систему и не доказывает сам, что все критерии выполнены. Для Done всё равно нужны свидетельства и суждение.
Надёжная практика — разделять авторство, реализацию и проверку. CodingAgent-соавтор может разъяснять контракт, другой его реализует, независимый Reviewer сравнивает результат с критериями.
Организуйте несколько Specification roots
Workspace может хранить Specifications в нескольких папках. Это полезно, когда проект уже разделяет решения по продукту, инженерии, операциям или модулям, либо единственная root стала неудобной.
Откройте Workspace Settings и используйте Specification roots, чтобы добавлять, удалять и менять порядок папок. Roots должны быть:
- относительными к каталогу Workspace;
- упорядоченными;
- уникальными и непересекающимися;
- не более 32 на Workspace.
Первая root — Primary, куда по умолчанию попадают новые Specifications. Изменение порядка меняет назначение по умолчанию, но не перемещает существующие файлы. Удаление root тоже не удаляет файлы. Specifications вне настроенных roots исчезают из активного списка и возвращаются после повторного добавления root.
При нескольких roots панель Specifications группирует сначала по root, затем по реальным папкам filesystem. Canvas не создаёт параллельную таксономию: организацией остаётся ваша файловая структура.
Простая структура roots
docs/ общие решения и контракты продукта
specs/ реализуемые features и интеграции
marketing/ кампании и редакционные эксперименты
operations/ обслуживание и операционные изменения
Не создавайте roots только для сокращения списка. Используйте их, когда каждая папка представляет долговечную и понятную людям и агентам границу.
Что Specification получает в графе
Specification принимает две прямые Connections:
- Specification + CodingAgent делает контракт достижимым для агента и позволяет lifecycle и outputs. Connection
может содержать
specification_read_only. - Specification + Terminal экспортирует канонический абсолютный путь Markdown через переменную окружения, настроенную на Connection.
Другие CodingAgents того же компонента тоже достигают Specification по действующим путям. Не нужно повторять прямую Connection для каждого участника, если только это не делает топологию понятнее или паре не нужен отдельный Guardrail.
Три задачи, оправдывающие Specification
Архитектурная основа
Запишите инварианты, разрешённые зависимости, границы безопасности, стратегию миграции и проверяемые критерии. Этот документ направляет последующие features без повторного открытия основы каждым агентом.
Feature с независимой реализацией и проверкой
Spec Writer исчерпывает решения и переводит контракт в Ready. Implementer работает по нему. Reviewer проверяет поведение, сбои и свидетельства. Outputs связывают commits и другие результаты с работой.
Ограниченная серия исправлений
Когда у нескольких дефектов общая причина или поверхность, Specification может определить ожидаемое поведение, точный набор исправлений и регрессионные тесты. Бесконечный список bugs без общей границы уже не является контрактом.
Практический граф
Spec Writer — Specification — Implementer — Reviewer
│
Terminal
Spec Writer фиксирует решения. Implementer выполняет только контракт Ready. Reviewer сравнивает результат и критерии. Terminal предоставляет свидетельства. Решение считать работу Done остаётся за человеком.
Чего избегать
- Выходить из Draft из-за объёма текста, не разрешив решения, меняющие подход.
- Объединять анализ, Specification, реализацию и проверку в одной сессии ради удобства.
- Писать «работает правильно» или «имеет хорошую производительность» без наблюдаемого результата.
- Редактировать управляемый Kavor frontmatter как обычный текст.
- Считать status автоматическим доказательством качества или завершения.
- Создавать пересекающиеся roots или несколько roots без долговечной границы.
- Оставлять единственное важное решение в беседе, которую не найдёт следующий участник.
Перед переводом в Ready
Проверьте: ясны ли проблема, цель и non-goals; разделены ли факты, решения и гипотезы; учтены ли важные сценарии отказа; проверяемы ли критерии приёмки; поймёт ли Implementer допустимую область изменений; сможет ли Reviewer оценить результат, не наследуя рассуждения автора; закрыты ли вопросы, способные изменить решение.
Хорошая Specification не пытается предсказать каждую строку кода. Она снимает достаточно неоднозначности, чтобы исполнение и проверка были независимыми, проверяемыми и восстанавливаемыми.
Продолжите в Как замкнуть первый loop в Kavor, выберите участников в CodingAgents и роли или откройте матрицу Connections.