935 lines
43 KiB
Markdown
935 lines
43 KiB
Markdown
---
|
||
documentId: repository-stewardship-guide
|
||
documentVersion: 0.2.0
|
||
status: draft
|
||
normative: false
|
||
language: ru
|
||
machineSpecification: docs/specification.md
|
||
architectureSource: 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](specification.md). Этот документ объясняет ту же модель простым языком. Процедура подключения существующих репозиториев описана в [adoption-runbook.md](adoption-runbook.md). Исходные архитектурные варианты и исследование сохранены в [research/infrastructure-operations-architecture-options.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. Общая архитектура
|
||
|
||
```mermaid
|
||
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. Минимальная структура репозитория
|
||
|
||
```mermaid
|
||
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. Четыре типа репозиториев
|
||
|
||
```mermaid
|
||
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. Карта сущностей
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```text
|
||
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 — связь между объектами:
|
||
|
||
```text
|
||
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.
|
||
|
||
```mermaid
|
||
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 с конкретным реализованным ресурсом.
|
||
|
||
Например:
|
||
|
||
```text
|
||
Antivirus requirement
|
||
→ lxd://drweb/dwcp
|
||
```
|
||
|
||
Binding принадлежит provider repository. Он появляется после выбора или создания target и становится active только после verification и acceptance.
|
||
|
||
### 9.6. Acceptance
|
||
|
||
Проверки, доказывающие, что задача consumer решена.
|
||
|
||
LXD может подтвердить, что контейнер запущен и имеет правильный профиль. Только Antivirus может подтвердить, что базы обновляются и control plane действительно работает.
|
||
|
||
```mermaid
|
||
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
|
||
|
||
```mermaid
|
||
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 должна быть указана честно.
|
||
|
||
```mermaid
|
||
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.
|
||
|
||
Пример: развернуть контейнер для антивируса.
|
||
|
||
```mermaid
|
||
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-команды:
|
||
|
||
```text
|
||
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](adoption-runbook.md), поэтому процедура переносима между 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 само по себе.
|
||
|
||
```mermaid
|
||
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`.
|
||
|
||
```mermaid
|
||
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`
|
||
|
||
```mermaid
|
||
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 существующего репозитория
|
||
|
||
```mermaid
|
||
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.
|
||
|
||
```mermaid
|
||
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](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](https://backstage.io/docs/features/software-catalog/) | descriptor хранится рядом с repository content, catalog является проекцией |
|
||
| Bootstrap и обновление стандартной части | [Backstage Software Templates](https://backstage.io/docs/features/software-templates/), [Copier updates](https://copier.readthedocs.io/en/stable/updating/) | typed inputs, preview, template version, migrations |
|
||
| Desired/observed state и reconciliation | [OpenGitOps](https://opengitops.dev/), [Kubernetes API conventions](https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md) | декларативность, разделение spec/status, conditions и observed revision |
|
||
| Requirements и capabilities | [Crossplane composite resources](https://docs.crossplane.io/latest/composition/composite-resources/), [Score](https://docs.score.dev/docs/) | отделение потребности consumer от реализации provider |
|
||
| Operations и workflows | [OpenAPI](https://spec.openapis.org/oas/latest.html), [Arazzo](https://spec.openapis.org/arazzo/latest.html) | стабильные operation IDs, schemas, dependencies, outputs и success criteria |
|
||
| Claude и переносимые agent instructions | [Claude memory](https://code.claude.com/docs/en/memory), [AGENTS.md](https://agents.md/) | короткий постоянный entrypoint и on-demand подробности |
|
||
| Опциональный transport | [MCP server primitives](https://modelcontextprotocol.io/specification/2025-06-18/server/index) | resources, tools и prompts как адаптеры над общей моделью |
|
||
| KDB и provenance | [Data Package](https://specs.frictionlessdata.io/guides/data-package/), [W3C PROV](https://www.w3.org/TR/prov-o/), [Diátaxis](https://diataxis.fr/) | human/machine index, происхождение знания и типы документации |
|
||
| Repository security | [OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md), [SLSA provenance](https://slsa.dev/spec/v1.2/provenance), [SPDX](https://spdx.github.io/spdx-spec/v3.0.1/scope/) | ownership, protected changes, integrity и supply-chain provenance |
|
||
| Domain-native content roots | [Flux repository layouts](https://fluxcd.io/flux/guides/repository-structure/), [Terraform module structure](https://developer.hashicorp.com/terraform/language/modules/develop/structure), [Docker Compose project directory](https://docs.docker.com/reference/cli/docker/compose/) | стандартное место результата задаётся доменом, а contract только объявляет его |
|
||
|
||
Уникальная часть нашей модели — сочетание intent-based KDB routing, typed content roots, consumer-owned acceptance, provider-owned bindings и immutable cross-repository Plan. Внешние практики подтверждают отдельные элементы, но не дают эту комбинацию целиком.
|
||
|
||
## 21. Итоговая модель одной фразой
|
||
|
||
```mermaid
|
||
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** — разные интерфейсы над одной моделью.
|