К основному содержанию
скилл CX Codex

contract-first-agents — скилл для Claude Code: координация агентов

Скилл contract-first-agents для Claude Code задаёт общий контракт перед запуском параллельных агентов, затем проверяет результат и предлагает исправить ошибки. Используется в задачах, части которых должны состыковаться.

MIT ★ 138 обновлён 2026-09-03

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add happycapy-ai/Happycapy-skills --skill contract-first-agents -a claude-code
Открыть на GitHub

Что делает contract-first-agents

Сначала руководитель команды описывает модули, имена экспортов, интерфейсы, общие типы и зависимости. Полный контракт передаётся каждому рабочему агенту вместе с его заданием, чтобы параллельные результаты опирались на одни и те же соглашения. Контракт сохраняется в ~/.claude/teams/{team-name}/contract.md.

После завершения работы руководитель проверяет синтаксис, импорты, имена и полноту экспортов. Если проверка находит ошибки, отдельный агент исправляет только перечисленные проблемы, не перестраивая результат. Для одиночной задачи или независимых заданий без связей между результатами протокол предлагает обойтись без контракта; для работы с несколькими агентами он добавляет этап подготовки общего документа.

Какие задачи решает

  • согласовать интерфейсы модулей до параллельной разработки
  • распределить связанные части проекта между агентами
  • сверить импорты с экспортами после объединения результатов
  • исправить найденные ошибки без повторной генерации всей работы

Примеры запросов агенту

  • Разбей эту задачу на связанные модули и подготовь контракт для команды агентов.
  • Создай общий контракт, затем параллельно поручите агентам реализацию модулей.
  • Проверь объединённый результат по контракту и исправь только обнаруженные несоответствия.

Как установить contract-first-agents

1Через Skills CLI (Vercel)

npx skills add happycapy-ai/Happycapy-skills --skill contract-first-agents -a claude-code

2Вручную: положить файлы

~/.claude/skills/contract-first-agents/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/contract-first-agents/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о contract-first-agents

Как установить contract-first-agents в Claude Code?

Выполните npx skills add happycapy-ai/Happycapy-skills --skill contract-first-agents -a claude-code. Файл скилла устанавливается по пути ~/.claude/skills/contract-first-agents/SKILL.md.

Что делает contract-first-agents?

Он задаёт порядок координации команды: общий контракт перед запуском рабочих агентов, параллельное выполнение и проверка объединённого результата. При найденных проблемах отдельный агент вносит точечные исправления.

Когда протокол предлагает пропустить контракт?

Для задач одного агента, независимых заданий без перекрёстных ссылок и исследований, которым не нужна интеграция результатов.

Исходный текст

SKILL.md · MIT
---
name: contract-first-agents
description: "Contract-First Map-Reduce coordination protocol for native TeamCreate multi-agent teams. Wraps TeamCreate, Task (teammates), SendMessage with an upfront shared contract phase that eliminates 75% of integration errors. Based on 400+ experiment research proving 52.5% quality improvement over naive coordination."
version: 1.0.0
author: HappyCapy Research
triggers:
  - contract first agents
  - contract first team
  - coordinated agents
  - multi agent contract
  - team with contract
  - optimal team coordination
  - contract-first
---

# Contract-First Map-Reduce Agent Coordination

> Wraps native TeamCreate/Task/SendMessage with a proven 4-phase protocol
> that eliminates 75% of integration errors in multi-agent tasks.

## Research Basis

Based on 400+ controlled experiments comparing 7 coordination strategies:
- **Naive multi-agent**: 0.571 composite quality score
- **Contract-First Map-Reduce**: 0.871 composite quality score (+52.5%)
- The contract alone accounts for the ENTIRE quality improvement
- Validated across 2-64 agent configurations

## The Protocol

### Phase 1: CONTRACT GENERATION (Team Lead, ~5% of time)

Before spawning ANY worker agent, the team lead MUST create a Contract Document.

**The Contract Document must contain:**

```markdown
# === SHARED CONTRACT: [Project Name] ===

## 1. MODULE MANIFEST
For EVERY module/section an agent will produce:
- Exact filename
- Purpose (1 sentence)
- ALL exported names (exact spelling, exact case)

## 2. INTERFACE DEFINITIONS
For EVERY cross-module reference:
- Exact function/class name
- Exact parameter names and types
- Exact return type
- Source module -> consuming module(s)

## 3. SHARED TYPES
For EVERY data structure shared across modules:
- Exact field names and types
- Validation rules
- Serialization format

## 4. STYLE GUIDE
- Naming: snake_case for functions/variables, PascalCase for classes
- Indentation: [N] spaces
- Docstrings: [Google/NumPy/Sphinx] style on all public functions/classes
- Error handling: exact exception types
- Import convention: "from module import Name"
- Language-specific conventions

## 5. DEPENDENCY MAP
- Which modules import from which
- Execution order constraints (if any)
- Shared state / global configuration

## 6. SECTION BOUNDARIES
For EACH section assigned to an agent:
- What it must produce (exact deliverables)
- What it imports from other sections (exact names)
- What it exports for other sections (exact names)
- How it connects to adjacent sections (transitions, API calls, imports)
```

**Contract Quality Checklist:**
- [ ] Every exported name is spelled out exactly
- [ ] Every cross-module import has a matching export
- [ ] Style guide is specific (not "be consistent" but "use snake_case")
- [ ] Shared types have exact field names and types
- [ ] No ambiguity - an agent reading only the contract can produce correct code

### Phase 2: PARALLEL EXECUTION (Worker Agents)

Spawn worker agents using the Task tool with `team_name` parameter. Each worker's prompt MUST include:

```
[FULL CONTRACT TEXT - every worker gets the COMPLETE contract]

---

YOUR ASSIGNMENT: [Specific section/module]

You are Agent [N] of [Total]. You are producing [section name].

CRITICAL INSTRUCTIONS:
1. Follow the contract EXACTLY. Do not deviate from specified names, types, or conventions.
2. Your section will be merged with outputs from other agents working in parallel.
3. Use ONLY the exported names specified in the contract when referencing other modules.
4. Do NOT rename, reorganize, or "improve" the interface - follow the contract.
5. Write your output to: [exact file path]
```

**Spawn all workers in parallel** using a single message with multiple Task tool calls.

### Phase 3: AUTOMATED VALIDATION (Team Lead or Script)

After all workers complete, the team lead validates the merged output:

```python
# Validation checks (in priority order):
1. Syntax validity    - Can the output be parsed? (ast.parse, eslint --no-fix, etc.)
2. Import resolution  - Do all imports match actual exports?
3. Name consistency   - Is the naming convention uniform throughout?
4. Completeness       - Are all contracted exports present?
5. Style consistency  - Indent, docstrings, error handling patterns
6. Cross-references   - Do function calls use correct signatures?
```

Save validation results. If all pass -> done. If issues found -> Phase 4.

### Phase 4: TARGETED FIX (Fixer Agent, only if needed)

Spawn ONE fixer agent that receives:
- The merged output
- The specific validation errors (exact line numbers, exact issues)
- The original contract

**The fixer ONLY fixes the specific issues found. It does NOT regenerate or restructure.**

## Implementation with Native Tools

```python
# Step 1: Create team
TeamCreate(team_name="my-project", description="Building X with contract-first protocol")

# Step 2: Team lead generates the contract
# Save contract to a shared file: ~/.claude/teams/{team-name}/contract.md

# Step 3: Spawn workers with full contract in their prompts
Task(
    name="worker-auth",
    team_name="my-project",
    subagent_type="general-purpose",
    prompt=f"""
    {FULL_CONTRACT_TEXT}

    YOUR ASSIGNMENT: auth module
    Write to: /workspace/project/auth.py
    Follow the contract exactly.
    """
)
# ... spawn all workers in parallel

# Step 4: After workers complete, validate
# Team lead reads all output files and runs validation checks

# Step 5: If issues found, spawn fixer
Task(
    name="fixer",
    team_name="my-project",
    subagent_type="general-purpose",
    prompt=f"""
    Fix these specific issues in the merged output:
    {VALIDATION_ERRORS}

    Original contract: {CONTRACT}
    Do NOT restructure. Only fix the specific issues listed.
    """
)

# Step 6: Cleanup
SendMessage(type="shutdown_request", recipient="worker-auth")
# ... shutdown all workers
TeamDelete()
```

## When to Use This Protocol

**ALWAYS use for:**
- Any task requiring 3+ agents
- Tasks producing code that must interoperate
- Large document generation (multiple sections that reference each other)
- Any task where agents produce outputs that will be merged

**SKIP the contract for:**
- Completely independent tasks (no cross-references)
- Single-agent tasks
- Research/exploration tasks (no integration needed)

## Key Principles

1. **The contract IS the coordination** - review phases add <5% value if contract is good
2. **Every agent gets the FULL contract** - not just their section's part
3. **Specific beats general** - "use snake_case" beats "be consistent"
4. **Parallel beats sequential** - contract enables parallel work; pipelines sacrifice speed for marginal gain
5. **Targeted fixes beat regeneration** - fix specific issues, don't redo entire sections
6. **10+ agents need validation** - probability of ANY error increases with agent count

© HappyCapy Research · MIT · happycapy-ai/Happycapy-skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
k2f-contract suzheng Скилл k2f-contract собирает NDA, MSA, SOW и SaaS-договоры из ваших условий в подписной вид. Юрист всё равно нужен. CX Codex +1 556установок Jobly — Agent-to-Agent Contract Marketplace jobly Jobly — Agent-to-Agent Contract Marketplace — MCP-сервер для Claude Code размещает контракты между агентами, принимает предложения и сдачу работы, поддерживает споры через escrow и JOOBs. CX Codex +1 2 218установок contract-review claude-office-skills Скилл contract-review находит риски в договорах, проверяет структуру документов и готовит правки для торга. Пригодится перед подписанием соглашений об оказании услуг, NDA и трудовых контрактов. CX Codex +1 5 700установок contract-helper aaron-he-zhu Скилл contract-helper составляет шаблон договора с инфлюенсером и разбирает условия уже полученного соглашения. Он включается для оформления сделки, согласованной в принципе. CX Codex +1 1 100установок contract-and-proposal-writer Alireza Rezvani Скилл contract-and-proposal-writer для Claude Code готовит договоры, предложения, SOW, NDA и MSA в Markdown с учётом юрисдикции. Создаёт черновики клиентских документов для последующей конвертации в DOCX. CX Codex +1 747установок material-contract-schedule официальный anthropics Скилл material-contract-schedule формирует Schedule 3.X существенных договоров для сделок M&A по данным дью-дилидженса. Применяет критерии соглашения о покупке и форматирует список под требования договора. CX Codex +1 644установок

Из того же набора41

Весь набор →
agent-0-repo-qualifier Субагент agent-0-repo-qualifier проверяет репозитории на GitHub до того, как вы начнёте искать в них задачи: живость проекта, отзывчивость мейнтейнера, барьеры вроде CLA. Отдаёт список прошедших дальше по цепочке. CX Codex ★ 138звёзд репо agent-7-pr-creator Субагент agent-7-pr-creator проверяет изменения, готовит коммиты и описание, затем создаёт pull request через gh. Он работает после субагентов 4, 5 и 6. CX Codex ★ 138звёзд репо agent-1-issue-scout Субагент agent-1-issue-scout для Claude, который ищет в отобранных GitHub-репозиториях свободные «good first issue» и отдаёт одну выбранную задачу следующему агенту цепочки. CX Codex ★ 138звёзд репо html-over-markdown Скилл html-over-markdown создаёт автономные HTML-файлы с диаграммами, сетками и интерактивом вместо Markdown для отчётов, планов и разборов кода. CX Codex +1 ★ 138звёзд репо agent-9-status-monitor Субагент agent-9-status-monitor для Claude, который следит за открытыми пул-реквестами: ловит мержи, закрытия, новые ревью и падения CI, обновляет историю и шлёт алерты соседним агентам роя. CX Codex ★ 138звёзд репо generate-image Скилл generate-image для Claude Code генерирует иллюстрации по тексту и редактирует готовые изображения через AI Gateway API. Подключает модели Gemini, Seedream и GPT-Image. CX Codex +1 ★ 138звёзд репо agent-0-strategic-planner Субагент agent-0-strategic-planner оценивает GitHub-задачи и выбирает те, что обещают пользу пользователям. Он пригодится для планирования осмысленных вкладов в проекты с открытым исходным кодом. CX Codex ★ 138звёзд репо claude-code-templates Скилл ставит и настраивает CLI claude-code-templates: каталог агентов, слэш-команд, MCP-серверов, хуков и шаблонов проектов для Claude, плюс мониторинг сессий. CX Codex +1 ★ 138звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой