Жизненный цикл спецификации
Осознанно выбирай место и жизненный цикл
Спецификация должна находиться там, где выполняющие работу люди и агенты могут её просматривать, находить и обновлять. Подходящих мест может быть несколько:
| Место | Когда полезно | Главный компромисс |
|---|---|---|
| Задача или трекер проектов | Обсуждение, назначение исполнителей и согласование происходят вместе с работой над выпуском | Может быть отделено от истории кода и офлайн-инструментов |
| RFC или проектный документ в репозитории | Важны версионирование рядом с кодом и ревью средствами репозитория | Может выглядеть авторитетным после того, как поведение уже изменилось |
| Общий документ или система знаний | Важны межфункциональное ревью и развитые средства совместной работы | Доступ, версионирование и извлечение агентом могут быть слабее |
Выбирай исходя из процесса ревью, контроля доступа, версионирования, прослеживаемости, доступа агентов и ожидаемого срока жизни, а не универсального варианта по умолчанию.
Жизненный цикл подчиняется тому же правилу. Спецификацию поставки можно закрыть после реализации. RFC может остаться исторической записью о решении. Спецификация протокола или политики может продолжать определять поведение и требовать обновления вместе с кодом. Какую бы модель ты ни выбрал, явно назови действующий авторитетный источник и правило обновления, чтобы агентам не приходилось угадывать между противоречащими описаниями.
Когда реализация становится эксплуатационным источником истины, выполни явную передачу полномочий:
- Закрепи проверяемое поведение в коде, типах, валидации, конфигурации и тестах.
- Держи неочевидные локальные обоснования рядом с кодом, если от них зависят будущие изменения.
- Сохраняй более общие решения или отвергнутые альтернативы в подходящей долговечной записи, если они всё ещё важны.
- Архивируй, закрывай, обновляй или удаляй спецификацию в соответствии с её предполагаемым жизненным циклом.
Так разрешается намеренное дублирование без навязывания одного места для всех видов знаний. Глава «Код, удобный для агентов» объясняет, как сделать эксплуатационные ограничения восстанавливаемыми при исследовании кода.
Главные выводы
- Место и жизненный цикл — проектные решения. Явно обозначай авторитетный источник, правила обновления и будущую передачу полномочий.
- Жизненный цикл следует цели спецификации. Спецификация поставки закрывается после реализации; RFC может остаться исторической записью; спецификация политики продолжает жить вместе с кодом.
- Передавай полномочия осознанно. Когда реализация становится эксплуатационным источником истины, закрепи проверяемое поведение в коде, держи обоснования рядом с кодом, а более общие решения сохраняй там, где они ещё имеют значение.