Как устроен embedded-tech-spec

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

Путь от исходных данных к проверенному ТЗ

исходные данные документ связи требований проверка

1. Исходные данные

Метод формирования записывается в реквизиты: с нуля, по коду или приведение к целевой реализации.

Код модуля

текущее поведение для обратной разработки

Журналы и архитектура

логи загрузки, планы, описание платформы

Ответы заказчика

решения по открытым вопросам каждой ревизии

template.md

шаблон нового документа ревизии 1.0

TECHNICAL_SPECIFICATION_<МОДУЛЬ>.md

2. Документ: порядок частей фиксирован

Разделы 1–2 и приложения — информативные, остальные — нормативные.

Реквизиты и ревизии

история ревизий, блоки изменений, новейший сверху

Введение и описание

соглашения документа, контекст, границы, ограничения платформы

Требования

предметные разделы, жизненный цикл и API, интерфейсы, нефункциональные

Верификация

тест-кейсы TC-NN, матрица прослеживаемости, допущения и вопросы

Приложения

константы, раскладки, расхождения с кодом, примеры

3. Один номер связывает требование, код и тест

Если номер сдвинуть, ссылки из кода и тестов станут ложными.

Пункт ТЗ

одно проверяемое утверждение

5.3.10. setValue ДОЛЖЕН …

ссылка

Код

комментарий у реализации

// ТЗ 5.3.10

ссылка

Тест-кейс

проверка методом A, T, I или D

TC-22

строка

Матрица

требование → реализация → проверка

4. Механическая проверка

Скрипт не понимает смысла, но ловит типовые ошибки перенумерации и выпуска ревизий.

check_spec.py

разбирает Markdown-файл ТЗ

python3 scripts/check_spec.py ТЗ.md --strict

находит

Замечания

повторы номеров, ссылки в пустоту, требования вне матрицы, пункты без маркера, ревизии без блока изменений

затем

Чтение глазами

однозначно ли требование и проверяемо ли указанным методом

Цикл новой ревизии

ОтветыКаждый ответ заказчика переносится в требование, а не только в таблицу вопросов.

ПометкиНовый или изменённый пункт получает (р.X.Y); исключённый остаётся с номером.

ИсторияРеквизиты, строка истории, блок «Изменения ревизии X.Y» над прежними.

ВопросыЗакрытые меняют статус и ссылаются на пункты с решением, новые добавляются.

ПроверкаТест-кейсы, матрица, константы и расхождения с кодом, затем check_spec.py.

Из чего состоит пункт требования

5.3.10. setValue ДОЛЖЕН вернуть ошибку для ключа
вне области. `[U]` (р.1.6)

Часть	Смысл
`5.3.10.`	раздел, подраздел, пункт; номер постоянный
`ДОЛЖЕН`	модальность: ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, МОЖЕТ
`[R]` `[N]` `[U]`	происхождение: из кода, новое, уточнение
`(р.1.6)`	ревизия, в которой пункт создан или изменён

Правила, которые держат документ

номера пунктов и тест-кейсов не переиспользуются и не сдвигаются;
у требования есть граница и метод проверки: «не более 200 мс, замер на оборудовании»;
предположенное — в допущения, неизвестное — в открытые вопросы, а не додумывается;
одно требование живёт в одном месте, другие места на него ссылаются;
проверенное и непроверенное различаются явно: «проверено симуляцией», «эскиз».

Эталон — ТЗ ревизии 1.8 на подсистему параметров во Flash-эмуляции EEPROM, около 2000 строк (references/example-eeprom.md).

Насколько проверено

Проверяется в CI репозитория

check_spec.py на шаблоне и на эталонном ТЗ: ошибок нет

Ещё не проверено

смысловая проверка требований — только чтением; скрипт её не заменяет

Описание навыка (SKILL.md), шаблон и проверка · версия 0.1