archspec — шпаргалка по прогону Sonnet 4.6

Репозитории: archspec · bench · freelance-marketplace

Где что лежит

task_4_with_sonnet_4_6 — это OpenSpec, не archspec.

Пайплайн

Скиллы: sync / init · investigate · implement

1. init → SERVICE_MAP

• Сканер находит в Go-коде endpoints, зависимости, хранилища, топики.
• Оператора спрашивают о том, чего в коде нет: имя и владелец, responsibilities, invariants, идемпотентность, SLA.
• Коммиты: task-service · config-service · остальные 10
• Пример: task-service/docs/SERVICE_MAP.yaml

YAML и JSON. YAML — сам контракт, его правят руками. .servicemap/schema.json — копия JSON Schema для подсказок в IDE; валидация идёт по схеме внутри плагина.

2. investigate → archplan

Четыре вопроса модели (скриншоты, 144943–145320):

Второй раунд — Open Questions в плане (160905, 161901): worker_id из JWT, city_id обязателен, ноль кандидатов → match.exhausted.

• archplan в ветке
• ревью плана

Оба файла плана закоммичены только последним коммитом ветки, истории правок по коммитам нет.

3. implement → контракты, coding plan, код

Восемь фаз, буквы — из SKILL.md. Идут строго по порядку.

Пять проходов фазы E — каждый ловит класс багов, который проходит при зелёных тестах:

• Wiring — в main.go нет nil вместо зависимостей, адреса клиентов совпадают с портами сервисов.
• Emission — у каждого объявленного события есть место публикации на всех путях.
• Threading — новое поле доходит от публичного входа до всех потребителей и сидов.
• Dedup — ключ дедупликации ставится не раньше побочных эффектов; повторная попытка не глотается как дубликат.
• Evidence — каждое требование задачи → file:line → тест.

Артефакты прогона Sonnet:

• коммит контрактов — первый в прогоне
• coding plan
• заметки по реализации

Edge cases: когда и как

1. investigate, шаг 8a. Каждый риск становится записью edge_cases[] в YAML-патче archplan. Имя теста придумывается сразу.
2. implement, фаза B «Сначала контракты». Патч попадает в SERVICE_MAP.yaml вместе с тестами-заглушками.
3. implement, фаза D «Реализация». Заглушки наполняются по TDD.

Запись — ровно три обязательных поля:

edge_cases:
  - id: EC-002
    description: "DeclineOffer with wrong worker_id must return PERMISSION_DENIED"
    test: "services/task-service/usecase/task_decline_test.go::TestEC002_WrongWorkerDeclines"

Заглушка из первого коммита:

func TestEC002_WrongWorkerDeclines(t *testing.T) {
	t.Skip("not yet implemented")
}

Заглушка с t.Skip проходит все автоматические проверки. От забытых заглушек защищают только Definition of Done и независимое ревью (фаза G). Подробнее: VALIDATION_RULES.md.

Edge cases в task_3: task-service · matching-service · notification-service. В task_2 их нет: init секцию не создаёт.

Что ещё записывается в SERVICE_MAP

Edge cases — лишь одна из секций. Ниже реальные записи из прогона Sonnet (ветка task_3) и из спецификации. Полный формат: SERVICE_MAP_SPEC.md.

Где лежат edge cases прогона

В контрактах 12 записей из 15: EC-011, EC-012 и EC-013 есть в archplan и в тестах, но в YAML не попали.

Инварианты сервиса — service.invariants

Что всегда верно внутри одного сервиса. Свободный текст, автоматикой не проверяется. Пример: task-service:25.

invariants:
  - "every write goes through the outbox"
  - "task can only be declined by its currently assigned worker (AssignedWorkerID must match)"
  - "offer.declined is not emitted when reassignment_count >= 3; task.failed is emitted instead"
  - "task.Status transitions: open → assigned (via match.found), assigned → open (via offer.declined), assigned/open → failed"

Инварианты между сервисами — consistency.cross_service_invariants

Что должно сходиться на стыке сервисов. Пример: matching-service:108.

cross_service_invariants:
  - "every task.created eventually produces exactly one match.found OR one match.exhausted (never both, never neither)"
  - "offer.declined with attempt N produces exactly one match.found (attempt N+1) or one match.exhausted, never both"
  - "match.found for attempt > 0 carries client_id so notification-service can notify the client"

Идемпотентность endpoint’а — api.endpoints[].idempotency

Проверяется линтером AI-001: если required: true, в хендлере должен быть ключ. Пример: matching-service:37.

- name: FindMatch
  protocol: gRPC
  idempotency:
    required: true
    key_source: "field: task_id"
    storage: "in-memory dedup store (CreatePendingIfAbsent mutex guard)"

Поведение при отказе зависимости — dependencies.downstream.sync[]

Таймаут, ретраи и что делать, если сосед недоступен. Пример: matching-service:74.

- service: geo-service
  timeout: "3s"
  retries: 0
  fallback: "if geo-service call fails, log warning and use worker_id as stable secondary sort"
  on_failure: "degraded (geo tie-breaking skipped, not propagated)"

События и способ записи — events, consistency.write_path

Какие топики сервис публикует и читает, и атомарна ли запись с публикацией. Проверяются DEP-001, AI-002 (outbox) и AI-009 (необъявленное событие).

events:
  published:
    - topic: match.exhausted
      contract: "not-documented"
      version: 1
  consumed:
    - topic: offer.declined
      contract: "not-documented"
      expected_version: 1
consistency:
  write_path:
    pattern: outbox

not-documented и not-measured — долговые маркеры: поле заполнено честно, а не выдумано.

Конкурентность — concurrency

Стратегия записи агрегата; при optimistic линтер AI-003 ищет проверку версии.

concurrency:
  aggregates:
    - name: MemoryMatch
      write_strategy: optimistic

Необязательные секции

В прогоне Sonnet их нет; примеры из спецификации.

Исключение без причины, ADR или срока блокирует коммит (DET-010…014). Подробнее: EXCEPTIONS.md.

Проверки: где и чем

Два слоя: детерминированные скрипты (git-хуки, правила DET-*) и аудит кода против контракта (Go-линтеры, правила AI-*). В investigate и implement к ним добавляется ревью самой моделью. Все правила: VALIDATION_RULES.md.

Investigate — проверяется план

Скриптов нет, всё делает модель по SKILL.md:

• Clarify gate (шаг 3) — чек-лист неоднозначностей, на каждую незакрытую задаётся вопрос.
• Self-review (шаг 9) — перечитывает диаграмму и YAML-патч по списку анти-паттернов.
• Plan review (шаг 9c) — независимый ревьюер: APPROVED или REVISE, максимум три раунда.

Implement — контракт, потом код против контракта

Фазы расписаны выше, в разделе 3.

Go-линтеры: идемпотентность · outbox · оптимистичные блокировки · проглоченные ошибки · лишние вызовы · необъявленные события

Commit — pre-commit hook

Запускает run_all_checks.py; коммит блокируется только на BLOCK.

Когда срабатывает: на каждом git commit — и у человека, и у модели в фазах B, D, H implement. Те же проверки первым шагом запускает /archspec:validate (фаза F).

Push — pre-push hook

Запускает run_all_pushchecks.py, проверяет весь диапазон коммитов против origin/main.

Когда срабатывает: на git push. Implement сам не пушит, так что это происходит после фазы H, когда пушит человек.

• check_drift.py — заново генерирует диаграммы и ARCHITECTURE.md из YAML и сравнивает побайтно: ловит забытый /archspec:sync и ручную правку.
• check_contract_changes.py — DET-006 и DET-008 по всем коммитам сразу.

Оба хука ставит install_hooks.sh во время /archspec:init.

Реальную блокировку дают только хуки. /archspec:validate и /archspec:check-architecture формируют отчёт; чинить BLOCK и перезапускать обязана модель.

Как устроены питоновские проверки

Обычные скрипты без ИИ. Читают YAML как данные и сравнивают его со схемой, с прошлой версией из git и с заново сгенерированными файлами. Go-код сервиса не читают.

На чём построено

Зависимости: requirements.txt. Обёртки над git: _git.py.

Каркас: run_all_checks.py берёт staged-файлы, вызывает run(staged) у каждой проверки и собирает находки (_finding.py). Код возврата 1 — только при BLOCK.

Четыре приёма

Четвёртый приём работает, потому что генерация детерминирована: один YAML всегда даёт один и тот же вывод.

Отдельные случаи

• check_pragmas.py — регулярное выражение по комментариям archspec:ignore: требует причину после --.
• check_graph_consistency.py и check_architecture.py — собирают все SERVICE_MAP.yaml монорепы и сверяют сервисы между собой: несогласованные зависимости, события без читателя. Только предупреждения.
• scan_go.py — не проверка, а сканер для /archspec:init: регулярные выражения по Go-исходникам и proto-файлам. Находки подтверждает оператор.

Чего питон не делает

• Не проверяет код против контракта. Это делают Go-линтеры на стандартных go/parser и go/ast.
• Не читает содержимое ADR: достаточно, что файл в docs/adr/ добавлен в коммит.
• Не заглядывает в тесты: проверяется только существование файла, поэтому заглушка с t.Skip проходит.

Freelance-marketplace: схема и ловушки

12 Go-сервисов: gRPC между сервисами, NATS для событий, transactional outbox. Задача бенчмарка — «умное переназначение»: фрилансер отклонил оффер → подобрать следующего, максимум 3 раза, иначе задача failed. В неё заложено восемь ловушек, полный текст: task.md.

Как система работает до задачи

Сплошная стрелка — синхронный gRPC, пунктир — событие через NATS. Под именем сервиса — его ответственность, по responsibilities из SERVICE_MAP.yaml.

flowchart TD
    C([клиент]) -->|"HTTP POST /api/v1/tasks"| GW["<b>api-gateway</b><br/>единая точка входа,<br/>своего состояния нет"]
    GW -->|CreateTask| TS["<b>task-service</b><br/>хранит задачи и их статусы,<br/>публикует task.created"]
    TS -.->|"task.created (outbox)"| MS["<b>matching-service</b><br/>подбирает исполнителя:<br/>навыки → кандидаты → рейтинг"]
    MS -->|AnalyzeText| SA["<b>skill-analyzer</b><br/>достаёт из текста задачи навыки,<br/>уровень, категорию, срочность"]
    MS -->|SearchBySkills| WF["<b>worker-facade</b><br/>собирает данные воркера<br/>из трёх сервисов в один ответ"]
    MS -->|"GetAverageRating, в цикле"| RS["<b>review-service</b><br/>отзывы и средний<br/>рейтинг воркера"]
    MS -.->|"match.found (outbox)"| NS["<b>notification-service</b><br/>шлёт офферы и уведомления,<br/>отсекает дубли событий"]
    NS -->|оффер| W([фрилансер])
    subgraph FACADE [за фасадом]
        WP["<b>worker-profile</b><br/>имя, навыки,<br/>город, контакты"]
        PF["<b>portfolio-service</b><br/>портфолио, поиск по навыкам,<br/>выполненные задачи"]
        VS["<b>verification-service</b><br/>проверка<br/>личности воркера"]
    end
    WF --> WP
    WF --> PF
    WF --> VS
    GEO["<b>geo-service</b><br/>города, регионы, часовые пояса,<br/>расстояние между городами"]
    CFG["<b>config-service</b><br/>feature-флаги"]

geo-service и config-service в базовом коде никем не вызываются.

Что добавляет задача и где ловушки

Цифры — номера ловушек из таблицы ниже. Стрелка с крестом — путь, которым идти нельзя.

flowchart TD
    W([фрилансер]) -->|"отказ от оффера"| GW[api-gateway]
    GW -->|"DeclineOffer — 7"| TS[task-service]
    TS -.->|"offer.declined — 7, 8"| MS[matching-service]
    MS --x|"повторный AnalyzeText — 2, 3"| SA[skill-analyzer]
    MS -->|"GetWorkersBatch — 4"| WF[worker-facade]
    MS --x|"напрямую — 1"| WP[worker-profile]
    WF --> WP
    MS -->|"рейтинг — 6"| RS[review-service]
    WF --x|"рейтинг через фасад — 6"| RS
    MS -->|"GetDistancesBatch по city_id — 5"| GEO[geo-service]
    MS -.->|"match.found — 8"| NS[notification-service]
    MS -.->|"кандидаты кончились"| TS
    TS -.->|"task.failed — 8"| NS
    NS -->|"уведомление"| C([клиент])

Ловушка → где в коде

Ссылки ведут на базовую ветку task_2 — то состояние, которое видела модель.

Ловушка 8 — самая частая: match_id выдаётся один на задачу, поэтому второе и третье match.found при переназначении notification-service глотает как дубликаты.