Организация спецификаций на новом проекте

Эта схема для системного аналитика, который заводит репозиторий документации с нуля: продукт ещё не оброс десятками разрозненных файлов, и можно сразу договориться, что агент читает первым. Речь не про перенос чужого проекта и не про замену шаблонов артефактов из раздела 10. Речь про каркас, в котором эти артефакты лежат так, чтобы агент открывал два-три связанных файла, а не весь каталог.

Подход продолжает 11.10 Spec-Driven Development — спецификация как источник работы ИИ и 11.11 OpenSpec и Spec Kit — обзор и как ставить задачу агенту: спецификация живёт в репозитории. Здесь добавляется правило экономии контекста. Агент не угадывает устройство системы по длинной переписке. Он читает короткий бизнес-контекст, короткий системный контекст и граф спецификаций, а полный текст берёт только по связям текущей правки.

1. Когда схема уместна

Берите её, если одновременно верно следующее.

• Проект новый или документация ещё не разложена, и пути файлов можно выбрать сейчас.
• Спецификации пишет человек вместе с ИИ-агентом, и агент будет возвращаться к ним много раз.
• Есть несколько видов документов: процесс, метод API, схема данных, экран. Одного большого SRS уже мало.

Не натягивайте схему на архив, где имена, папки и уровень детализации уже закреплены процессом команды. Сначала договоритесь, какие файлы остаются источником истины. Иначе агент будет обновлять граф, а люди — старую папку.

Шаблоны самих документов берите из базы: 10.01.04 Шаблон спецификации REST API, 10.01.03 Шаблон спецификации БД сервиса, 10.01.08 Шаблон сквозной фичи (BPMN-процесс), 10.01.12 Шаблон нефункциональных требований (NFR), 10.01.09 Шаблон описания экранной формы и логики на FE. Каркас ниже говорит, куда их класть и что читать до записи. Он не подменяет разделы этих шаблонов.

2. Что читать до правки

Перед новой спецификацией или правкой существующей агент открывает четыре файла, в этом порядке.

1. docs/context/business.md — продукт, пользователь, границы первой версии.
2. docs/context/system.md — где лежат данные, какие системы рядом, как устроен вызов.
3. docs/context/spec-graph.md — карта спецификаций. Дальше открываются только файлы, на которые указывает текущая правка.
4. docs/conventions.md — куда класть файл, как называть, как рисовать диаграмму.

Содержание этих файлов в каждый документ не копируется. Спецификация метода ссылается на контекст, а не пересказывает его.

После записи, в том же проходе:

• узел и связи этой спецификации обновляются в spec-graph.md;
• новый устойчивый факт о продукте, пользователе или границе версии дописывается в business.md, в раздел «Накопленные факты»;
• новый устойчивый факт о хранении, соседней системе или способе вызова дописывается в system.md, в тот же по смыслу раздел;
• новое правило оформления одного вида документа остаётся в скилле этого вида. Правило для всех спецификаций дописывается в conventions.md.

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

3. Зачем это экономит токены

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

С картой путь короче.

flowchart LR
  agent["Агент"]
  business["Бизнес-контекст"]
  system["Системный контекст"]
  specGraph["Граф спецификаций"]
  spec["Связанная спецификация"]
  agent --> business
  agent --> system
  agent --> specGraph
  specGraph --> spec

Агент держит в контексте три короткие страницы и одну спецификацию, которую меняет. Вторую открывает, только если граф на неё ссылается. Полный текст соседнего сервиса не читается «на всякий случай».

Экономия держится на дисциплине, а не на длине промпта. Если после правки узел графа не обновлён, следующий заход снова ищет вслепую. Если бизнес-факт записан только в файле метода, следующий метод его не увидит и выдумает заново.

4. Куда класть документы

Имена файлов — латиница, kebab-case. Ссылки между документами — относительные ссылки Markdown. Один API-метод — один файл. Схема данных сервиса — один файл. Сквозной процесс не принадлежит одному сервису и не лежит в его папке.

flowchart TD
  docs[docs]
  context[context]
  services[services]
  feature["feature-architecture"]
  screens["frontend/screens"]
  templates[templates]
  docs --> context
  docs --> services
  docs --> feature
  docs --> screens
  docs --> templates
  context --> business["business.md"]
  context --> system["system.md"]
  context --> specGraph["spec-graph.md"]
  services --> api["service/api/verb-resource.md"]
  services --> erd["service/erd.md"]

Пустые скелеты четырёх входных файлов лежат ниже. Их копируют в новый репозиторий и заполняют фактами этого продукта. Чужой домен в скелет не подставляют.

Диаграммы в самих спецификациях оставьте теми, к которым привык шаблон базы. Для сквозного процесса это BPMN рядом с текстом, для схемы данных — DBML, для метода — последовательность вызовов. В графе диаграмма не дублируется: там только имя узла, путь и связи.

4.1. Асинхронный вызов

Если метод не отдаёт результат сразу, в его файле должно быть видно три вещи: какой идентификатор получает вызывающая сторона, какие статусы бывают у операции, кто опрашивает результат. Идентификатор и статусы задаются один раз в регламенте. Файл метода показывает их на диаграмме последовательности и не копирует общее описание опроса в каждый документ.

Не вводите в отдельном методе свой набор статусов, если регламент уже назвал общий. Если клиент ходит не в исполнителя операции, а в свой сервис, файл метода описывает этот обход: что видит клиент и что сервис делает сам.

5. Скелеты четырёх файлов

5.1. Бизнес-контекст

# Бизнес-контекст
 
## Продукт
 
<что делает продукт одним абзацем>
 
## Пользователь
 
<кто вызывает систему и зачем>
 
## Границы
 
<что входит в первую версию и что сознательно остаётся снаружи>
 
## Накопленные факты
 
- <устойчивый факт о продукте, пользователе или границе>

5.2. Системный контекст

# Системный контекст
 
## Хранение
 
<где сервис хранит свои данные и чего в своей базе нет>
 
## Смежные системы
 
<система — что у неё спрашивают или что ей отдают>
 
## Паттерн вызова
 
<синхронный вызов, очередь или операция с последующим опросом>
 
## Накопленные факты
 
- <устойчивый факт о хранении, соседней системе или вызове>

5.3. Граф спецификаций

# Граф спецификаций
 
## Назначение
 
Карта документов. Агент открывает спецификацию, только если на неё есть связь у текущей правки.
 
## Узлы
 
| Узел | Путь | Вид |
| --- | --- | --- |
| <короткое имя> | <путь от корня репозитория> | процесс \| метод \| схема \| экран \| контекст |
 
## Связи
 
| От | К | Зачем |
| --- | --- | --- |
| <узел> | <узел> | <что один документ берёт у другого> |
 
## Порядок чтения
 
1. `docs/context/business.md`
2. `docs/context/system.md`
3. Этот файл. Дальше — только строка из «Связи».
4. `docs/conventions.md`, если пишется новый документ.

5.4. Регламент

# Регламент спецификаций
 
Текст документов — на русском. Имена файлов — латиница, kebab-case. Ссылки — относительные.
 
## Куда класть спецификацию
 
| Вид | Путь |
| --- | --- |
| API-метод | `docs/services/<service>/api/<verb>-<resource>.md` |
| Схема данных сервиса | `docs/services/<service>/erd.md` |
| Сквозной процесс | `docs/feature-architecture/<process>.md` |
| Экран | `docs/frontend/screens/<screen>.md` |
 
Один метод — один файл. Сквозной процесс не лежит внутри папки сервиса.
 
## Имена и ссылки
 
Файл называет действие и сущность: `post-certificate-request.md`, не `api.md`. В спецификации нет копии бизнес-контекста и системного контекста: на них стоит ссылка.
 
## Диаграммы
 
- Процесс: текст и диаграмма в одном комплекте, шаги пронумерованы.
- Метод: диаграмма последовательности в файле метода.
- Схема данных: одна схема на сервис.
 
## Асинхронная операция
 
Запуск возвращает идентификатор операции. Статусы общие: операция выполняется, завершилась успешно, завершилась с ошибкой. Файл метода показывает, кто опрашивает результат, и не копирует сюда таблицу статусов заново.
 
## Накопленные правила
 
- <правило, которое верно для всех спецификаций этого репозитория>

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

6. Пример: заявка на справку

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

Узлы:

Связи:

flowchart LR
  process["Заказ справки"]
  method["Создать заявку"]
  storage["Заявки"]
  process -->|"шаг вызывает метод"| method
  method -->|"пишет строку"| storage

Агент, которому поручили поправить тело ответа метода, читает бизнес-контекст, системный контекст и граф, затем открывает post-certificate-request.md. Файл процесса он открывает, только если меняется шаг, а не поле ответа. Схему открывает, если в ответе появилось поле, которого нет в хранении.

В бизнес-контекст попадает факт «справку заказывает сотрудник о себе». В системный — «заявка хранится в базе сервиса заявок». Номер поля в JSON остаётся в файле метода.

7. Как это делает наставник базы

Наставник не держит раскладку в памяти модели. Если вы собираете документацию нового проекта, он открывает эту статью и скилл spec-greenfield: скелеты четырёх файлов и проверка, что в графе есть назначение, узлы, связи и порядок чтения.

Дальше документ собирается своим скиллом базы, а не вторым форматом поверх этого каркаса:

• метод — spec-rest-api;
• схема данных — spec-db-schema;
• сквозной процесс — spec-bpmn-process;
• нефункциональные требования — spec-nfr.

Если четыре файла каркаса в проекте уже есть, скилл документа читает их до записи и обновляет узел графа после. Шаблон статьи при этом не подменяется.

Поиск скилла идёт через инструменты наставника: search_skills, затем get_skill и get_skill_template. Нет скилла — наставник так и говорит, а не собирает оглавление из общих знаний.