Skip to content

documentation-system.md

Latest commit

 

History

History
63 lines (49 loc) · 6.87 KB

documentation-system.md

File metadata and controls

63 lines (49 loc) · 6.87 KB
Raw

Система Спецификаций Проекта

Этот документ определяет эталонную структуру документации (specs/) для проектов, использующих CodeMemory. Цель этой структуры — быть легко читаемой как для человека, так и для LLM, обеспечивая быструю навигацию без раздувания контекста.

6-Слойная Архитектура

Документация строго разделена на 6 слоев, от бизнеса к коду:

  1. product/ (Что и Зачем): Миссия, глоссарий, границы скоупа (v1). Здесь нет технической реализации.
  2. domain/ (Данные): Форма данных, сущности (Entities), связи в БД. (Без описания жизненного цикла и runtime-состояний).
  3. features/ (Функции): Детальное описание крупных функциональных блоков (например, RAG, Wizard, Admin UI). Каждая фича — в своей папке с обязательным README.md (картой фичи).
  4. system/ (Кросс-функциональное): Инфраструктура, внешние сервисы, протоколы API, контракты, развёртывание.
  5. code/ (Разработка): Правила написания кода, конвенции, дизайн-система.
  6. meta/ (Будущее): Идеи, отложенные задачи.

Помимо шести слоёв в корне спеки живут два сквозных артефакта: RULES.md (реестр инвариантов, ниже) и specs/user-stories/ — User Stories, которые по своей природе пересекают слои и поэтому не помещаются ни в один (см. ниже).

RULES.md — Глобальный реестр инвариантов

В корне спецификаций (или в code/) должен лежать файл RULES.md. Это машиночитаемый индекс критических архитектурных правил проекта.

  • Зачем: LLM загружает этот файл на старте сессии (указано в CLAUDE.md). Это даёт ей жёсткие рамки до погружения в детали.
  • Формат: Таблица с ID, кратким описанием правила и ссылкой на деталь. (Пример: [R-API-01] Все ответы API через ApiResponse::make() -> system/api.md)

Функциональная Карта и User Stories

Для предотвращения "слепых зон" (когда LLM меняет бэкенд, но забывает про UI или очереди), спецификации должны явно описывать потоки выполнения.

Functional Map (Справочник связей)

В features/<feature>/README.md должны быть описаны кросс-модульные связи.

  • Не просто: "Есть очередь обработки".
  • А как поток: "При загрузке (Admin UI) -> Создается Document (Domain) -> Диспатчится IngestionJob (Features/Ingestion)".

User Stories — сквозной дом specs/user-stories/

User Story в нашей модели двухуровневая (см. user-stories.md): бизнес-поведение плюс system_reaction — что крутится под капотом. Из-за system_reaction история несёт техническую реализацию и потому не помещается в слой product/, который по определению без неё. Поэтому истории живут в собственном верхнеуровневом доме specs/user-stories/, сквозном по слоям (бизнес + системная реакция) — это снимает противоречие слоя product/.

  • Формат: Актор делает Действие -> Ожидаемый Результат (изменения в UI, БД, отправка событий).
  • Истории описывают наблюдаемое поведение, помогая модели понять, какие слои затронет её изменение.

Идентичность по ID, раскладка свободная

Истории устроены identity-first — так же, как заметки Code Memory (короткий ID, ссылка по ID, путь не несущий):

  • ID, не путь. У истории короткий стабильный глобально-уникальный ID; имя файла — <id>-<slug>.md (ID как префикс, <slug> — kebab от goal для читабельности). Все ссылки — по ID, никогда по пути; резолв ссылки — glob **/<id>-*.md.
  • Свободная переставляемая раскладка. Внутри specs/user-stories/ структура свободная (по фиче, механизму, пакетам) и реорганизуемая без поломки ссылок — путь не несущий. Это снимает и проблему пустых папок под сквозную историю, и угадывание «правильной» иерархии заранее.

Практики оформления под LLM

  1. Машиночитаемый Frontmatter: Каждый .md файл должен содержать YAML блок (статус, доменные сущности, теги), чтобы LLM могла быстро понять релевантность файла без полного парсинга.
  2. Один файл — одна тема: Лимит ~150-250 строк. Разросшиеся документы режутся на логические части.
  3. Не дублируй то, что есть в коде: Каталоги маршрутов, полные схемы таблиц или точные сигнатуры интерфейсов не должны быть в спеке. Модель должна читать их из исходников.
  4. Явное выделение Инвариантов: В тексте спецификаций жёсткие правила выделяются в отдельную секцию ## Инварианты (Must Hold), чтобы модель могла легко извлечь их при поиске.