mcp-integration

name	mcp-integration
description	Когда какой MCP-инструмент звать и в каком порядке — gate ritual, recording discipline, action tools для всех агентов разработки.
type	mandatory
domain	development
owners	["architect","conductor","devops","product_manager","reviewer","senior_full_stack","tester","ux_ui_designer"]
gates	["PM","UX","ARCH","DEV","REV","OPS","TEST","RG"]
tech	["mcp"]
topic	["general"]
triggers	["record_decision","request_decision","classify_gate","start_task","advance_gate","submit_artifact","list_skills","get_skill","load_role","MCP","code-ai MCP","gate flow"]
related	["karpathy-guidelines","code-review-checklist","adr-log"]
budget_lines	250
schema_version	1
license	MIT

MCP Integration

Правила работы с code-ai MCP-сервером для всех агентов разработки. Когда какой инструмент звать, в каком порядке, что записывать, какие ошибки не совершать.

Если сервер MCP в .mcp.json не зарегистрирован — fall back на чтение файлов с пометкой report_exception. Не молчи.

---

1. Когда применять

Триггеры: любая задача в development-домене, которая проходит через gates (PM/UX/ARCH/DEV/REV/OPS/TEST/RG). То есть — почти любая.

Вывод: инструмент вызван корректно, его результат использован в текущей фазе, при необходимости записан через record_decision или submit_artifact.

---

2. Что такое code-ai MCP

Локальный MCP-сервер (stdio transport) с 26 инструментами. Состояние хранит в .code-ai/state/ (JsonlStore — append-only, файлы decisions.jsonl, exceptions.jsonl, artifacts/<task>.jsonl). MempalaceStore — опциональное зеркало, не источник истины.

Сервер регистрируется инсталлятором (.mcp.json пишется автоматически на --target=claude). Если инсталлятор не отработал — записи можно делать вручную в .code-ai/state/, но MCP-инструменты предпочтительнее: они валидируют ввод через zod.

---

3. Группа 1 — Навигация (4 инструмента)

list_skills — получить полный список скилов домена с фронтматтером. Зови в начале задачи чтобы понять что у тебя есть. Парсер пермиссивный — пропускает скилы со сломанным фронтматтером (см. run_drift_audit если что-то ожидалось но не появилось).

get_skill — получить SKILL.md по имени. Используй вместо ручного чтения файла — get_skill даёт фронтматтер уже распарсенным и тело markdown отдельно.

load_role — получить профиль агента (промпт + список скилов которые он может звать). Зови первым делом когда задача попадает к тебе на роль.

regenerate_manifest — пересборка manifest.json после правок скилов. Зови когда добавил/удалил/переименовал скилл.

Порядок при старте задачи: load_role → list_skills → выбираешь нужные → get_skill по каждому.

---

4. Группа 2 — Gate flow (6 инструментов)

Это ритуал прохождения gate. Каждый gate обязан пройти эти шаги в порядке.

start_task — создать прогон с явным режимом (full/bugfix/hotfix) и его начальным гейтом. Единственный путь создания — звать первым; current_gate задачу больше не создаёт.

classify_gate — классифицируешь задачу перед началом работы над gate. Возвращает auto_resolve (зелёный путь, артефакт всё равно нужен для аудита), fork (нужно решение пользователя — запросишь через request_decision) или exception (автоматическая проверка упала — пишешь breakdown в exceptions).

request_decision — запрашиваешь решение у пользователя. Создаёт ADR-PENDING-* в decisions.jsonl. Должен быть вызван перед record_decision если решение требует одобрения пользователя. Не молчи и не выбирай сам — это нарушение karpathy-guidelines §1.

current_gate — где сейчас находится задача. Полезно когда context потерялся или ты переключился между задачами.

advance_gate — продвинуть задачу в следующий gate. Только после того как все artefacts текущего gate submitted и sign_off проставлен.

sign_off — подпись текущего gate. Sign_off без предыдущего submit_artifact — anti-pattern (см. §8). Сначала результат, потом подпись. Кто подписывает — по sign_off_policy гейта: user-гейты (PM/UX/ARCH/RG) требуют signer="user" — ОСТАНОВИСЬ и запроси подпись у пользователя, по одному гейту, без батчинга, и не начинай следующий gate пока текущий не подписан; исполнительские (DEV/REV/OPS/TEST, policy=either) можно подписать как signer="mcp" при выполненном DoD. Машина отвергнет mcp-подпись user-гейта.

Канонический ритуал gate: start_task (создать прогон с режимом, один раз) → current_gate (понять где ты) → classify_gate → если fork: request_decision → ждёшь → record_decision → продолжаешь → submit_artifact → verify_claim (где применимо) → sign_off → advance_gate.

---

5. Группа 3 — Действия (15 инструментов)

Инструменты которые что-то делают в проекте. Каждый отвечает на один DoD-вопрос.

run_tests — vitest/jest/pytest wrapper. Зови когда DoD говорит "тесты зелёные". Возвращает numPassedTests, numFailedTests, failureMessages. Используется в verify_claim для claim_type=tests_pass.

check_lint — проверка линтером. Возвращает clean: true/false плюс список lint-failures. DoD claim_type lint_clean.

build — tsc или эквивалент. Парсит TSxxxx ошибки. DoD claim_type build_succeeds.

apply_diff — применить git diff из стдина. Чище чем ручная правка через много вызовов Edit/Write — особенно для много-файловых патчей.

git_commit — закоммитить (с путями или -a). Использует tempfile для сообщения — heredoc с кавычками ненадёжен на Windows.

run_drift_audit — найти расхождения между скилами на диске и AGENTS.yaml/manifest.json. Парсер пермиссивный — видит сломанные скилы (в отличие от list_skills который их пропускает).

e2e_playwright — запуск Playwright. Браузеры по умолчанию не качаются (.npmrc skip flag) — поставь вручную если нужно.

docker_compose — обёртка над docker compose (up/down/ps/logs). Skip-ается если Docker daemon не запущен.

dependency_supply_chain — npm audit --json парсер. Возвращает уязвимости с severity. DoD claim_type no_critical_vulns.

verify_claim — мета-инструмент. Принимает claim_type (tests_pass / lint_clean / build_succeeds / no_critical_vulns / e2e_passes / docker_runs / custom), зовёт нужный action tool, возвращает structured verdict. custom пока stub — для него человеческая верификация (см. DEV-103).

audit_budget_compliance — проверка нарушений бюджета файлов: declared_budget > schema_max (ловит latent bugs schema rejection — пример DEV-107 RoleFrontmatter) и actual_lines > declared_budget. По всем agent.md + SKILL.md в указанном домене (RU + EN). Зови периодически или перед крупными правками agent.md / SKILL.md.

audit_bilocale_parity — проверка паритета локалей RU/EN: спаривает каждый agent.md / SKILL.md с парой в другой локали и репортит declared_mismatch (разный budget_lines), actual_mismatch (разное число строк — ловит дрейф как у design-intake в DEV-114) и orphan (файл есть только в одной локали). Read-only. Зови перед/после правок, затрагивающих одну локаль.

aggregate_run_metrics — фундамент данных Аудитора. Считает сухую статистику по агентам (через гейт→роль из pipeline.yaml) и воркфлоу (mode) из леджера завершённых прогонов (.code-ai/state/audit/runs.jsonl): first-try rate, переработки, откаты, срабатывания предохранителя, исключения, разбивка классификаций. min_runs (по умолч. 3) — защита от малой выборки. Read-only, только числа — суждение за агентом-Аудитором.

propose_change — записать предложение Аудитора (черновик правки агента/скила) как pending-запись в локальный склад (.code-ai/state/audit/proposals.jsonl). Несёт change_kind (edit_minor/add_asset/destructive → уровень риска), обоснование, evidence, threshold_met и инлайн-черновик. Чистый surfacing — ассет не трогает; инертно до одобрения/применения (item 4b).

list_proposals — список предложений Аудитора (новые сверху), фильтры status/risk/domain. Read-only.

review_proposal — авторизовать переход статуса предложения (approve/reject для pending; пометить approved как applied) + обязательный отчёт. Применяет матрицу автономии + тумблер из .code-ai/config.json: decided_by='auditor_auto' может одобрить только low/additive и только при ВЫКЛЮЧЕННОМ гейте; destructive (high) и включённый гейт — всегда через user. Авто-добавление нового скила проходит дедуп-проверку: при пересечении с существующим скилом уходит к user, а не добавляется само. Только авторизация — сама запись в ассет это отдельный шаг submit_artifact/edit (см. next_step).

render_diff — отрендерить unified-diff (например вывод git diff) в цветную HTML-страницу ревью (по файлам, с номерами строк) в системный TEMP. Возвращает путь + file:// URL для открытия в браузере. Зови на REV-гейте, чтобы показать изменения кода на ревью. Только информационный вывод — файл в TEMP (стирается при перезагрузке), проект не засоряет.

---

6. Группа 4 — Запись решений (6 инструментов + 1 служебный)

record_decision — записать ADR-решение в decisions.jsonl. Только после request_decision если решение требует участия пользователя. Если решение mechanical (signer=mcp) — можно напрямую, но укажи signer: "mcp" явно.

recent_decisions — последние N решений (фильтры по domain/signer/since). Используй чтобы понять контекст текущей задачи.

audit_trail — полный аудит-трейл задачи: все decisions + artifacts + exceptions в хронологическом порядке. Зови перед sign_off чтобы убедиться что ничего не забыл.

submit_artifact — отправить артефакт текущего gate (например spec.md, ADR draft, design doc). Без этого нельзя делать sign_off.

list_artifacts / get_artifact — посмотреть что уже отправлено в задаче. Используй чтобы не дублировать.

report_exception — записать exception (gate-check failed). Не используй вместо честного фикса — exception это «я попробовал, не вышло, причина X, нужен fork» а не «обходной путь».

Запись хранится в JsonlStore (append-only). Никаких "переписать" — только новая запись с invalidates: <prev_id> через kg_invalidate если факт устарел.

---

7. Канонические ритуалы

Ритуал A — "Получил задачу"

1. load_role          (понять что я умею)
2. list_skills        (что есть в домене)
3. current_gate       (где задача)
4. get_skill <name>   (для каждого релевантного скила)
5. classify_gate      (начать gate ritual)

Ритуал B — "Закрываю gate"

1. verify_claim       (для каждого DoD claim_type где есть автоматический check)
2. submit_artifact    (artefacts gate'а)
3. audit_trail        (последняя проверка — всё ли на месте)
4. sign_off           (подпись)
5. advance_gate       (переход)

Ритуал C — "Архитектурное решение"

1. request_decision   (создаёт ADR-PENDING-*)
2. (ждёшь одобрения пользователя)
3. record_decision    (финализирует ADR с signer=user)
4. apply_diff         (применяешь изменения единым патчем если возможно)
5. git_commit         (commit с adr_id в сообщении)

---

8. Anti-patterns

1. record_decision без request_decision для решений, требующих одобрения пользователя — нарушает governance, ломает audit trail.
2. advance_gate без sign_off — gate остаётся «не подписан», следующий агент не понимает что готово.
3. apply_diff без git_commit — изменения висят в working tree, следующая сессия их потеряет или примет за свои.
4. Ручной парсинг SKILL.md вместо get_skill — пропустишь фронтматтер-валидацию, словишь latent-баг (см. DEV-103 list_skills lesson).
5. report_exception вместо честного фикса — exception для «дальше решит пользователь», не для «я обошёл».
6. Зов MCP когда сервер не зарегистрирован без graceful fallback — silent failure хуже честного «MCP unavailable, fell back to file read».

---

9. DoD

• gate ritual пройден полностью (classify → action → submit → sign_off → advance)
• все artefacts submitted через submit_artifact
• все decisions записаны через record_decision (с request_decision где нужно одобрение пользователя)
• exceptions записаны честно через report_exception (если были)
• verify_claim вызван для каждого DoD-claim'а с автоматическим check'ом
• commit с MCP-связанными изменениями делается одним batch'ем (apply_diff → git_commit)