Files
repoctl/docs/guide.md
T

43 KiB
Raw Blame History

documentId, documentVersion, status, normative, language, machineSpecification, architectureSource
documentId documentVersion status normative language machineSpecification architectureSource
repository-stewardship-guide 0.2.0 draft false ru docs/specification.md docs/research/infrastructure-operations-architecture-options.md

Универсальная работа с репозиториями: руководство для человека

Модель называется Repository Stewardship: ответственное и долговременное ведение структуры, знаний, связей и способов работы репозитория. repoctl — её локальный командный интерфейс.

1. Коротко о результате

Каждый управляемый репозиторий получает:

  1. короткий машиночитаемый паспорт — ops/contract.yaml;
  2. индекс знаний — kdb/kdb.yaml;
  3. явные указатели на места реального результата работы — contentRoots;
  4. короткие точки входа CLAUDE.md и AGENTS.md;
  5. при необходимости — собственные безопасные operations и handlers.

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

Так получается «MCP-подобный» инструментарий без обязательного MCP server: репозитории уже предоставляют ресурсы, знания и операции через общий контракт, а CLI, Claude skills, другие агенты и будущий MCP становятся сменными интерфейсами.

Машинные поля и правила определены в specification.md. Этот документ объясняет ту же модель простым языком. Процедура подключения существующих репозиториев описана в adoption-runbook.md. Исходные архитектурные варианты и исследование сохранены в research/infrastructure-operations-architecture-options.md.

2. Главные принципы

2.1. Репозиторий сам описывает себя

Центральная база не должна вручную хранить копии сведений обо всех репозиториях. Каждый repository contract находится рядом с материалами, которые он описывает. Центральный каталог можно полностью перестроить.

2.2. Одинаков интерфейс, а не физическое дерево

LXD profiles могут оставаться в profiles-source/, Docker stacks — в каталогах стеков, код — в src/, а проектные результаты — в deliverables/.

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

2.3. Знание загружается по задаче

CLAUDE.md не превращается в энциклопедию. Пользовательская задача преобразуется в intent, например container.deploy. По intent выбираются только связанные темы KDB, документы, content roots и operations.

2.4. Потребитель формулирует потребность, провайдер реализует её

Antivirus знает, какой сервис ему нужен и как проверить его работу. LXD знает, как создать контейнер. Network знает, как предоставить сеть. Ни один из них не должен копировать authoritative configuration другого.

2.5. Сначала безопасная семантика, затем выполнение

Первая версия только обнаруживает, валидирует и выдаёт контекст. Затем добавляются единый handler protocol, Plan, approval, apply и evidence. MCP появляется последним как транспорт над уже проверенной моделью.

3. Общая архитектура

flowchart TB
    U["Пользователь"] --> A["Claude или другой AI-агент"]
    A --> E["CLAUDE.md / AGENTS.md / skill"]
    E --> R["repoctl"]

    R --> C["RepositoryContract"]
    R --> K["KnowledgeBase"]
    R --> G["Производный CatalogIndex"]

    C --> CR["contentRoots"]
    C --> O["operations"]
    C --> REL["requirements / capabilities / bindings"]
    K --> T["topics по intent"]
    T --> D["Markdown и vendor sources"]

    O -. "после L2" .-> H["Repo-local handlers"]
    H -. "domain API/CLI" .-> X["LXD / Docker / AD / Network / Monitoring"]

    R -. "после L3" .-> P["Plan / approval / RunEvidence"]
    R -. "опционально" .-> M["MCP adapter"]

Важное разделение:

  • contract и KDB принадлежат репозиторию;
  • catalog и context bundle вычисляются repoctl;
  • handler принадлежит своему техническому домену;
  • skill и MCP только помогают вызвать тот же интерфейс.

4. Минимальная структура репозитория

flowchart LR
    ROOT["repository root"] --> CONTRACT["ops/contract.yaml"]
    ROOT --> KDB["kdb/kdb.yaml"]
    ROOT --> AGENTS["AGENTS.md"]
    ROOT --> CLAUDE["CLAUDE.md"]
    ROOT --> DOCS["docs/"]
    ROOT --> OPS["ops/"]
    ROOT --> DOMAIN["domain-native content"]

    OPS --> HANDLERS["handlers/ — после L2"]
    OPS --> SCHEMAS["schemas/ — по необходимости"]
    OPS --> RUNS["runs/ — локальные планы и evidence"]

    DOMAIN --> EX1["profiles-source/"]
    DOMAIN --> EX2["stacks/"]
    DOMAIN --> EX3["src/"]
    DOMAIN --> EX4["deliverables/"]

Обязательная часть проста:

  • ops/contract.yaml — паспорт;
  • kdb/kdb.yaml — индекс знаний;
  • AGENTS.md — переносимые инструкции;
  • CLAUDE.md — вход для основного агента Claude.

Остальные каталоги создаются только при реальной необходимости.

5. Четыре типа репозиториев

flowchart TB
    R["Repository"] --> I["Infrastructure configuration"]
    R --> S["Service configuration"]
    R --> C["Software / code"]
    R --> P["Project / non-code"]

    I --> I1["desired state"]
    I --> I2["inventory / profiles / stacks"]
    I --> I3["observed state / evidence"]

    S --> S1["service definition"]
    S --> S2["policies / requirements"]
    S --> S3["acceptance / runbooks"]

    C --> C1["source"]
    C --> C2["tests / build"]
    C --> C3["packages / deployment"]

    P --> P1["deliverables"]
    P --> P2["sources / working"]
    P --> P3["decisions / archive"]
Тип За что отвечает Что особенно важно
Infrastructure configuration контейнеры, сеть, серверы, платформенная конфигурация разделить desired и observed state; иметь diff/plan/verify
Service configuration продуктовая конфигурация и правила эксплуатации сервиса владеть requirements и acceptance, не копировать provider configuration
Software/code исходники, тесты, сборка и выпуск следовать conventions своего ecosystem, явно отделить deployment artifacts
Project/non-code документы, исследования, планы и результаты явно назвать deliverables, sources и decisions

Организационный путь, уровень доступа и lifecycle не определяют тип. Например, репозиторий в Services/ может содержать software, а архивный инфраструктурный repository остаётся типом infrastructure-config.

6. Карта сущностей

erDiagram
    REPOSITORY ||--|| REPOSITORY_CONTRACT : publishes
    REPOSITORY ||--o| KNOWLEDGE_BASE : owns
    REPOSITORY_CONTRACT ||--o{ CONTENT_ROOT : declares
    REPOSITORY_CONTRACT ||--o{ OPERATION : exposes
    REPOSITORY_CONTRACT ||--o{ CAPABILITY : provides
    REPOSITORY_CONTRACT ||--o{ REQUIREMENT : requires
    REPOSITORY_CONTRACT ||--o{ BINDING : records
    KNOWLEDGE_BASE ||--o{ TOPIC : routes
    KNOWLEDGE_BASE ||--o{ KNOWLEDGE_DOCUMENT : indexes
    TOPIC }o--o{ KNOWLEDGE_DOCUMENT : selects
    REQUIREMENT }o--o{ CAPABILITY : matches
    BINDING }o--|| REQUIREMENT : fulfills
    OPERATION ||--o| HANDLER : implemented_by
    INTENT }o--o{ TOPIC : selects
    INTENT }o--o{ OPERATION : selects
    PLAN ||--o{ OPERATION : orders
    RUN_EVIDENCE }o--|| PLAN : proves

Дальше сущности объясняются в том порядке, в котором они встречаются при работе.

7. Сущности: от входа в репозиторий до понимания задачи

7.1. Репозиторий

Отдельная область ответственности и отдельный источник истины.

Примеры:

  • Infra/LXD отвечает за контейнеры и LXD profiles;
  • Services/Antivirus отвечает за требования и правила приёмки антивируса;
  • software repository отвечает за код;
  • project repository отвечает за результаты проекта.

7.2. RepositoryContract

Короткий машиночитаемый паспорт репозитория в ops/contract.yaml.

Он отвечает на вопросы:

  • что это за репозиторий;
  • кто его владелец;
  • где лежит результат работы;
  • что он предоставляет и что требует;
  • какие операции публично разрешены;
  • где находится его KDB.

Контракт не заменяет документацию. Это оглавление, интерфейс и граница ответственности.

7.3. Metadata

Стабильное имя, отображаемое название, владельцы, labels и annotations.

Стабильное имя вроде infra-lxd важнее физического пути. Репозиторий можно переместить, не меняя ссылки в requirements и bindings.

7.4. Repository type

Один из четырёх функциональных типов. Он определяет хорошие практики организации, но не заставляет использовать одно дерево каталогов.

7.5. Lifecycle

Текущее состояние репозитория:

  • production;
  • active;
  • experimental;
  • stub;
  • archive;
  • external.

Lifecycle помогает агенту не принять эксперимент или архив за production source.

7.6. ContentRoot

Явный указатель на место, где лежит настоящий результат работы.

Content root имеет:

  • стабильный ID;
  • роль;
  • путь;
  • природу данных (authority);
  • политику записи;
  • при необходимости selector.

Например, profiles-source/ может быть source, а profiles/ — generated mirror. Оба содержат YAML, но обращаться с ними нужно по-разному.

7.7. Authority

Объясняет природу содержимого:

  • source — первоисточник;
  • generated — автоматически созданное;
  • observed — полученное из runtime;
  • mirror — копия другого источника;
  • evidence — историческое доказательство.

8. Сущности: от пользовательского запроса до нужного знания

8.1. Intent

Краткое имя цели пользователя, а не техническая команда.

Например, запрос:

Разверни новый контейнер LXD для антивируса.

преобразуется в intent:

container.deploy

Intent помогает выбрать репозитории, темы KDB и операции. В нём нет hostname, пароля или shell-команды.

8.2. CatalogIndex

Производная телефонная книга репозиториев.

Она позволяет найти:

  • какой repository предоставляет LXD containers;
  • где находится Antivirus;
  • какие requirements ещё не имеют bindings;
  • какие repositories являются архивными.

Каталог можно удалить и пересобрать из contracts.

8.3. Entity и relation

Entity — объект каталога: repository, capability, requirement, binding или operation.

Relation — связь между объектами:

Antivirus requires LXD container
LXD provides LXD container
Binding fulfills Antivirus requirement

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

8.4. KnowledgeBase

Машиночитаемый индекс знаний в kdb/kdb.yaml.

KDB не обязана содержать весь текст. Она хранит:

  • темы;
  • соответствующие intents;
  • машиночитаемые constraints и facts;
  • ссылки на Markdown;
  • сведения о vendor sources;
  • provenance и freshness.

8.5. Topic

Тематический маршрут знаний.

Например:

  • container-deployment;
  • network-attachment;
  • profile-management;
  • backup-and-restore.

Для container.deploy агент получает первые нужные темы, но не читает всю документацию про backup, clustering и обновление платформы.

8.6. KnowledgeDocument

Конкретный Markdown, YAML, PDF, HTML snapshot, runbook или внешний URL.

Один документ может использоваться несколькими topics. Поэтому documents хранятся единым реестром, а topics ссылаются на их IDs.

8.7. Provenance

Ответ на вопрос «откуда это известно»:

  • исходный URL;
  • vendor;
  • версия;
  • дата получения;
  • hash локальной копии;
  • способ проверки.

Provenance отделяет официальную vendor information от локального правила и от наблюдаемого runtime fact.

8.8. Freshness

Ответ на вопрос «можно ли ещё доверять этим данным».

Если срок проверки истёк, информация не удаляется. Она помечается stale, а агент перед важным действием должен обновить или проверить её.

8.9. ContextBundle

Минимальный пакет контекста, который repoctl сформировал для одного intent.

Он содержит только:

  • краткое описание contract;
  • нужные content roots;
  • подходящие operations;
  • выбранные topics и documents;
  • warnings о stale или missing information.
flowchart LR
    Q["Запрос пользователя"] --> I["Intent"]
    I --> C["Contract operations"]
    I --> T["KDB topics"]
    C --> B["ContextBundle"]
    T --> B
    B --> A["Небольшой контекст агента"]

    ALL["Весь репозиторий и вся KDB"] -. "не загружаются" .-> A

Это основной механизм экономии времени и токенов.

9. Сущности: взаимодействие репозиториев

9.1. Consumer

Репозиторий, которому что-то нужно.

В примере с антивирусом consumer — Services/Antivirus. Он знает требования продукта и критерии успешности.

9.2. Provider

Репозиторий, предоставляющий техническую возможность.

В примере:

  • LXD предоставляет контейнер;
  • Network предоставляет сетевое подключение;
  • Monitoring предоставляет наблюдаемость.

9.3. Capability

Тип возможности провайдера.

Пример: compute.lxd-container означает «этот repository умеет предоставлять управляемые LXD containers». Это ещё не конкретный контейнер.

9.4. Requirement

Потребность consumer repository.

Antivirus может потребовать:

  • 4 CPU;
  • 8 GiB memory;
  • подключение к services network;
  • определённые acceptance operations.

Requirement принадлежит Antivirus, потому что LXD не должен угадывать потребности продукта.

9.5. Binding

Связь requirement с конкретным реализованным ресурсом.

Например:

Antivirus requirement
→ lxd://drweb/dwcp

Binding принадлежит provider repository. Он появляется после выбора или создания target и становится active только после verification и acceptance.

9.6. Acceptance

Проверки, доказывающие, что задача consumer решена.

LXD может подтвердить, что контейнер запущен и имеет правильный профиль. Только Antivirus может подтвердить, что базы обновляются и control plane действительно работает.

flowchart LR
    S["Service consumer"] --> R["Requirement"]
    P["Infrastructure provider"] --> C["Capability"]
    R --> M{"Совместимы?"}
    C --> M
    M -->|"да"| B["Binding to concrete target"]
    B --> V["Provider verification"]
    V --> A["Consumer acceptance"]
    A -->|"успех"| ACTIVE["Active binding"]

10. Сущности: безопасное выполнение

10.1. Operation

Публично объявленное действие репозитория.

Примеры:

  • container.inspect;
  • container.plan;
  • container.apply;
  • container.verify;
  • knowledge.validate.

Operation сообщает назначение, intent, фазу, effect, risk, schemas, preconditions и канонический handler.

10.2. Handler

Единственная исполняемая реализация operation.

Это может быть Python, PowerShell, shell, Terraform или Ansible. Важно не средство, а то, что handler лежит в одном каноническом месте и ограничен своим доменом.

Skill не копирует handler. Claude не конструирует произвольные команды, если существует operation.

10.3. Effect и risk

Effect описывает, что операция способна изменить:

  • read-only;
  • local-write;
  • external-write;
  • disruptive;
  • destructive.

Risk показывает серьёзность возможных последствий: low, medium, high, critical.

Effect и risk нужны для автоматического выбора approval policy.

10.4. Preconditions

Проверяемые условия до запуска:

  • contract валиден;
  • знания не stale;
  • target входит в разрешённую область;
  • revision не изменилась;
  • binding существует;
  • approval относится к текущему plan.

При нарушении precondition операция останавливается, а не «пробует всё равно».

11. Desired, observed, status и drift

flowchart LR
    G["Git desired state"] --> D["Diff"]
    R["Runtime observed state"] --> D
    R --> S["Immutable snapshot"]
    S --> D
    D --> DRIFT{"Drift exists?"}
    DRIFT -->|"нет"| READY["Ready condition"]
    DRIFT -->|"да"| PLAN["Plan or warning"]
    PLAN -. "только после approval" .-> APPLY["Apply"]
    APPLY --> VERIFY["Verify"]
    VERIFY --> R

11.1. Desired state

То, что должно быть. Хранится в authored files в Git.

11.2. Observed state

То, что фактически обнаружено в LXD, Docker, AD, Network или другой системе. Всегда имеет время наблюдения и provenance.

11.3. Snapshot

Неизменяемая историческая копия observed state. Snapshot полезен для diff, plan, расследования и rollback, но не является desired state.

11.4. Status и condition

Status — краткое производное состояние сущности.

Condition — отдельный стандартизованный факт, например:

  • ContractValid=True;
  • KnowledgeFresh=False;
  • DriftDetected=True;
  • Ready=Unknown.

Condition содержит reason, message, observed revision и время.

11.5. Drift

Разница между desired и observed state. Наличие drift не даёт автоматического разрешения на исправление: иногда нужен только warning, иногда — новый Plan.

12. Plan, apply и доказательство результата

12.1. Plan

Неизменяемое описание точных будущих изменений.

Plan фиксирует:

  • intent;
  • Git revisions;
  • snapshots;
  • targets;
  • порядок operations;
  • effects и risks;
  • checkpoints;
  • verification;
  • rollback;
  • собственный hash.

12.2. Revision и plan hash

Revision указывает точную версию входных данных. Plan hash идентифицирует точный план.

Если после планирования contract, desired state или важный snapshot изменился, старое approval больше не должно разрешать apply.

12.3. Approval

Разрешение конкретного пользователя на конкретный plan hash и targets. Approval не является общим разрешением «делать любые изменения в LXD».

12.4. Apply

Выполняет сохранённый Plan. Он не должен заново придумывать операции или расширять scope.

12.5. Checkpoint

Промежуточная остановка и проверка. Следующий шаг выполняется только после успешного результата предыдущего provider change и его проверки.

12.6. Verify

Проверяет технический результат provider. Успешный exit code apply ещё не доказывает правильность состояния.

12.7. Run и RunEvidence

Run — одно конкретное выполнение workflow.

RunEvidence — структурированное доказательство:

  • какой plan выполнялся;
  • кем и когда;
  • какие шаги прошли;
  • что проверил provider;
  • прошла ли consumer acceptance;
  • какой target был создан;
  • что было redacted.

12.8. Reconcile и rollback

Reconcile повторно сравнивает desired и observed state и решает, нужен ли warning или новый Plan.

Rollback восстанавливает предыдущее состояние либо выполняет компенсирующее действие. Не все изменения полностью обратимы, поэтому невозможность rollback должна быть указана честно.

stateDiagram-v2
    [*] --> Describe
    Describe --> Inspect
    Inspect --> Validate
    Validate --> Diff
    Diff --> Plan: change required
    Diff --> Verify: no change required
    Plan --> AwaitApproval: write effect
    Plan --> Apply: local safe operation
    AwaitApproval --> Apply: approved plan hash
    AwaitApproval --> [*]: denied or stale
    Apply --> Verify
    Verify --> Accepted: provider and consumer checks pass
    Verify --> Rollback: failed and rollback available
    Verify --> Reconcile: drift remains
    Rollback --> Verify
    Reconcile --> Inspect
    Accepted --> [*]

13. Workflow

Workflow связывает несколько operations ради пользовательского результата. Он координирует репозитории, но не копирует реализации handlers.

Пример: развернуть контейнер для антивируса.

sequenceDiagram
    actor User as Пользователь
    participant Agent as Claude
    participant Repoctl as repoctl
    participant AV as Services/Antivirus
    participant LXD as Infra/LXD
    participant Runtime as LXD runtime

    User->>Agent: Разверни контейнер для антивируса
    Agent->>Repoctl: context(intent=container.deploy)
    Repoctl->>AV: Read contract and selected KDB topics
    Repoctl->>LXD: Read contract and selected KDB topics
    AV-->>Repoctl: Requirement and acceptance operation
    LXD-->>Repoctl: Capability and provider operations
    Repoctl-->>Agent: ContextBundle and relation graph

    Agent->>Repoctl: inspect and build Plan
    Repoctl->>Runtime: Read observed state
    Runtime-->>Repoctl: Snapshot
    Repoctl-->>User: Exact Plan, risk and plan hash
    User->>Repoctl: Approve plan hash

    Repoctl->>LXD: Apply provider step
    LXD->>Runtime: Create or update container
    Runtime-->>LXD: Result
    LXD-->>Repoctl: Provider verification
    Repoctl->>AV: Run consumer acceptance
    AV-->>Repoctl: Acceptance passed
    Repoctl-->>Agent: Active binding and RunEvidence
    Agent-->>User: Container deployed and verified

Cross-repository workflow не является атомарной транзакцией. Безопасность достигается immutable Plan, последовательными checkpoints, verification, acceptance и evidence.

14. Интерфейсы для агентов и людей

14.1. repoctl

Общий диспетчер. Он не заменяет LXD, Docker, Git, Terraform или Ansible.

MVP-команды:

repoctl init
repoctl adopt
repoctl validate
repoctl discover
repoctl describe
repoctl context

14.2. AGENTS.md

Короткая переносимая инструкция: что это за repository, где contract, как получить контекст и какие safety rules обязательны.

14.3. CLAUDE.md

Главный runtime entrypoint, потому что основной агент — Claude. Он импортирует AGENTS.md и содержит только Claude-specific дополнения.

14.4. Skill

Удобная команда или инструкция для типового intent, например repository-adoption или repo-handoff. Skill выбирает нужную операцию, но не реализует её заново. Для adoption источником истины остаётся runbook, поэтому процедура переносима между Claude и другими агентами.

14.5. Adapter

Тонкий слой для конкретного harness: Claude skill, Codex skill, IDE command, CI job или MCP tool.

14.6. MCP

Будущий сетевой transport. Он публикует те же contracts, context bundles и operations. Добавление MCP не меняет владельца данных и не даёт write permission само по себе.

flowchart TB
    CORE["Contract + KDB + repo-local handlers"] --> CLI["repoctl CLI"]
    CORE --> CLAUDE["Claude adapter"]
    CORE --> OTHER["Other agent adapter"]
    CORE --> CI["CI validation"]
    CORE -. "позже" .-> MCP["MCP server"]

    CLI --> SAME["Одинаковая семантика"]
    CLAUDE --> SAME
    OTHER --> SAME
    CI --> SAME
    MCP --> SAME

15. Простая первая версия

Первая версия намеренно read-only вне явно подтверждённых init и adopt --mode apply.

flowchart LR
    A["Phase A: schema/parser"] --> B["Phase B: validate/discover/describe/context"]
    B --> C["Phase C: bootstrap, adoption and template lineage"]
    C --> D["Phase D: LXD + Antivirus pilots"]
    D --> E["Phase E: operation ABI and Plan"]
    E --> F["Scoped apply and optional MCP"]

15.1. Что реализуем сейчас

  • parser для RepositoryContract и KnowledgeBase;
  • validation;
  • безопасную работу с repo-relative paths;
  • discovery и производный catalog;
  • describe без чтения всей KDB;
  • context с exact intent routing и budget;
  • bootstrap четырёх repository types;
  • adoption существующих репозиториев через assess → plan → apply → verify;
  • compatibility index для legacy KDB без массовой конвертации;
  • template ID/version/revision;
  • генерацию AGENTS.md и CLAUDE.md;
  • YAML и JSON output;
  • тестовые fixtures.

15.2. Что оставляем на следующий этап

  • единый ABI для существующих handlers;
  • фактический вызов operations;
  • immutable Plan hashing;
  • approvals;
  • apply;
  • RunEvidence storage;
  • continuous reconciliation;
  • MCP server.

При этом IDs, envelope и связи уже совместимы с этими расширениями.

16. Предлагаемая внутренняя структура repoctl

flowchart TB
    CLI["cli"] --> MODEL["model"]
    CLI --> COMMANDS["commands"]
    COMMANDS --> VALIDATE["validation"]
    COMMANDS --> DISCOVERY["discovery"]
    COMMANDS --> CATALOG["catalog"]
    COMMANDS --> CONTEXT["context selection"]
    COMMANDS --> BOOTSTRAP["templates/bootstrap"]
    COMMANDS --> ADOPTION["adoption"]

    VALIDATE --> IO["YAML/JSON I/O"]
    DISCOVERY --> IO
    CATALOG --> MODEL
    CONTEXT --> MODEL
    BOOTSTRAP --> MODEL
    ADOPTION --> MODEL

    MODEL --> SCHEMA["versioned schemas"]

Модули должны оставаться независимыми:

  • model не знает о CLI;
  • discovery ничего не исполняет;
  • catalog только агрегирует contracts;
  • context выполняет детерминированный выбор;
  • bootstrap сначала строит preview/diff;
  • adoption сохраняет существующие authoritative paths и сначала строит assessment/plan;
  • будущий runner добавляется отдельно и не расширяет права read-only команд.

17. Bootstrap нового и adoption существующего репозитория

sequenceDiagram
    actor User as Пользователь
    participant Init as repoctl init
    participant Template as Template registry
    participant Repo as New repository
    participant Validate as Validator

    User->>Init: type, name, owner, lifecycle
    Init->>Template: Load trusted template version
    Template-->>Init: Skeleton and defaults
    Init-->>User: Preview files and optional SSH recommendation
    User->>Init: Confirm local write
    Init->>Repo: Write contract, KDB and entrypoints
    Init->>Validate: Validate generated repository
    Validate-->>User: Findings and final diff

Bootstrap предлагает, но не навязывает:

  • уникальный SSH deploy key для repository-scoped automation;
  • read-only доступ по умолчанию;
  • отдельное безопасное место private key вне Git;
  • CODEOWNERS/branch policy;
  • type-specific content roots.

Он обязательно записывает происхождение шаблона, чтобы стандартную часть можно было обновить позднее.

Для существующего репозитория используется другая операция — repoctl adopt. Она не раскладывает старый repository как новый шаблон, а сначала картографирует уже существующие источники истины, agent instructions, KDB и штатные места результата.

По умолчанию adoption добавляет overlay и ничего не переносит. Если владелец отдельно просит упорядочить дерево, используется именованная normalization recipe. Например, documents-to-content-root оставляет в корне README.md, AGENTS.md и CLAUDE.md, переносит только подтверждённые длинные документы и одновременно переписывает contract, KDB, frontmatter и Markdown links.

flowchart LR
    EXISTING["Существующий repository"] --> ASSESS["Assess: только чтение"]
    ASSESS --> PLAN["Plan: contract, roots, KDB adapter"]
    PLAN --> REVIEW{"Владелец согласен?"}
    REVIEW -->|нет| REFINE["Уточнить классификацию"]
    REFINE --> PLAN
    REVIEW -->|overlay| APPLY["Apply: только metadata layer"]
    REVIEW -->|normalize| NORMALIZE["Approved recipe and rename map"]
    NORMALIZE --> APPLY
    APPLY --> VERIFY["Validate and verify"]
    VERIFY --> PILOT["Добавить в catalog как pilot"]

Подробные правила, включая legacy KDB и существующие CLAUDE.md/AGENTS.md, находятся в adoption-runbook.md.

18. Проверки MVP

Минимальный тестовый набор должен включать:

Область Позитивный тест Негативный тест
Contract четыре repository types неизвестный type
Paths repo-relative path ../outside и absolute path
IDs уникальные stable IDs duplicate repository/content/topic IDs
KDB routing exact intent selects expected topics нерелевантные topics не загружаются
Freshness current verified source expired source создаёт warning
Catalog воспроизводимая пересборка duplicate repository name
Relations requirement находит capability unresolved requirement создаёт warning
Security harmless metadata secret-shaped fields и shell string
Context budget deterministic truncation тихое усечение без warning запрещено
Agent entrypoint Claude imports portable instructions длинная копия KDB в CLAUDE.md
Adoption legacy layout объявлен без перемещения перезапись существующего KDB или domain content

19. Как измерять пользу

Цель — не просто создать новые YAML-файлы. Пользу нужно измерять на реальных задачах.

Рекомендуемые метрики:

  • время до первой правильной команды;
  • количество файлов, прочитанных до начала работы;
  • tokens/bytes загруженного repository context;
  • количество повторных объяснений структуры пользователем;
  • доля stale knowledge, обнаруженного до действия;
  • доля operations с успешным verify;
  • количество несовместимых или orphan bindings;
  • количество разных копий одного handler;
  • время onboarding нового repository;
  • время обновления repository template.

Для проверки достаточно нескольких одинаковых сценариев до и после внедрения:

  1. найти LXD profiles;
  2. подготовить новый container для Antivirus;
  3. найти все Docker stacks;
  4. проверить monitoring configuration;
  5. начать работу в незнакомом software repository;
  6. найти deliverables и sources в project repository.

20. Как модель связана с внешними практиками

Эта схема не копирует один конкретный продукт. Она соединяет несколько зрелых подходов, оставляя их независимыми от выбранного agent harness.

Наша часть Близкая внешняя практика Что заимствовано
Repo-local contract и производный catalog Backstage Software Catalog descriptor хранится рядом с repository content, catalog является проекцией
Bootstrap и обновление стандартной части Backstage Software Templates, Copier updates typed inputs, preview, template version, migrations
Desired/observed state и reconciliation OpenGitOps, Kubernetes API conventions декларативность, разделение spec/status, conditions и observed revision
Requirements и capabilities Crossplane composite resources, Score отделение потребности consumer от реализации provider
Operations и workflows OpenAPI, Arazzo стабильные operation IDs, schemas, dependencies, outputs и success criteria
Claude и переносимые agent instructions Claude memory, AGENTS.md короткий постоянный entrypoint и on-demand подробности
Опциональный transport MCP server primitives resources, tools и prompts как адаптеры над общей моделью
KDB и provenance Data Package, W3C PROV, Diátaxis human/machine index, происхождение знания и типы документации
Repository security OpenSSF Scorecard, SLSA provenance, SPDX ownership, protected changes, integrity и supply-chain provenance
Domain-native content roots Flux repository layouts, Terraform module structure, Docker Compose project directory стандартное место результата задаётся доменом, а contract только объявляет его

Уникальная часть нашей модели — сочетание intent-based KDB routing, typed content roots, consumer-owned acceptance, provider-owned bindings и immutable cross-repository Plan. Внешние практики подтверждают отдельные элементы, но не дают эту комбинацию целиком.

21. Итоговая модель одной фразой

flowchart LR
    REQUEST["Что хочет пользователь"] --> INTENT["Intent"]
    INTENT --> CONTRACT["Кто отвечает и что умеет"]
    INTENT --> KDB["Что нужно знать"]
    CONTRACT --> ROOTS["Где лежит результат"]
    CONTRACT --> RELATIONS["Кто от кого зависит"]
    CONTRACT --> OPERATIONS["Что разрешено сделать"]
    KDB --> CONTEXT["Минимальный нужный контекст"]
    ROOTS --> CONTEXT
    RELATIONS --> CONTEXT
    OPERATIONS --> CONTEXT
    CONTEXT --> PLAN["Что именно изменится"]
    PLAN --> RESULT["Проверенный результат и evidence"]

В коротком виде:

  • Contract — кто мы и как с нами работать;
  • Intent — чего хочет пользователь;
  • KDB — что нужно знать для этой цели;
  • ContentRoot — где находится реальный результат;
  • Requirement — что нужно consumer;
  • Capability — что умеет provider;
  • Binding — какой конкретный target удовлетворил requirement;
  • Operation — что разрешено сделать;
  • Handler — как это технически выполняется;
  • Plan — какие точные изменения подтверждаются;
  • RunEvidence — чем доказан итог;
  • repoctl / skill / MCP — разные интерфейсы над одной моделью.