Оптимизация эффективности каждого этапа OpenSpec с помощью разных агентов: практическое резюме HagiCode

8 мая 2026 г.

Участие ИИ

ИИ помогал в написании, редактировании или проверке этой страницы.

Внимательно оценивайте важные детали и при необходимости сверяйте критические решения с первоисточниками.

Оптимизация эффективности каждого этапа OpenSpec с помощью разных агентов: практическое резюме HagiCode

Универсальные промпты не могут справиться с конкретными потребностями различных этапов разработки. Благодаря агентам, специфичным для каждого этапа, и параметризованной системе шаблонов, ИИ может генерировать высококачественный контент на каждом этапе.

Предыстория

OpenSpec — это система разработки, управляемая предложениями, которая управляет созданием, рассмотрением и реализацией технических предложений через структурированный рабочий процесс. Сама идея неплохая, но на практике мы обнаружили, что единый универсальный ИИ-промпт имеет очевидные проблемы.

На этапе explore отсутствует привязка к контексту, и ИИ при исследовании легко отклоняется от объёма предложения; качество генерации артефактов нестабильно, design.md не содержит визуальных элементов, proposal.md не содержит таблицы изменений кода, а tasks.md даже содержит операции Git, которые не должны там быть; границы ответственности размыты, неясно, какой контент должен содержать каждый тип документа; промпты не обладают гибкостью и не могут динамически регулировать поведение ИИ в зависимости от разных сценариев.

Эти проблемы напрямую влияют на эффективность рабочего процесса OpenSpec и качество вывода. На самом деле, другого пути нет, кроме как самостоятельно изменять шаблоны промптов. Эта статья — запись того времени.

О HagiCode

Решение, описанное в этой статье, основано на нашем практическом опыте в проекте HagiCode. HagiCode — это кодовый помощник на основе ИИ, и в процессе разработки мы активно используем рабочий процесс OpenSpec для управления техническими предложениями. Стратегия многоуровневых агентов, описанная в этой статье, — это именно решение по оптимизации, которое мы вывели из практического использования.

Если вы считаете это решение ценным, значит, наша инженерная практика неплохая — сам HagiCode заслуживает внимания.

Анализ рабочего процесса OpenSpec

Система OpenSpec содержит несколько основных этапов, каждый из которых имеет свои специфические цели и ограничения. Понимание границ ответственности этих этапов — основа для разработки эффективной стратегии агентов.

┌─────────────────────────────────────────────────────────────────────┐
│                     Этапы рабочего процесса OpenSpec                │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │ Explore  │ -> │   New    │ -> │    FF    │ -> │  Apply   │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │ Archive  │    │   Sync   │    │ Verify   │    │  Status  │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
└─────────────────────────────────────────────────────────────────────┘

Цели каждого этапа совершенно разные: этап Explore требует исследовательской позиции, сосредоточенной на сборе информации; этап New фокусируется на анализе требований и проектировании решений; этап FF создаёт артефакты пакетно в порядке зависимостей; этап Apply преобразует предложения в реальный код. Очевидно неразумно использовать один и тот же шаблон промпта для управления этими совершенно разными задачами.

Архитектура системы промптов

OpenSpec использует шаблонную систему промптов, что обеспечивает техническую основу для многоуровневых агентов. Файлы шаблонов используют формат .hbs (Handlebars/Scriban), в сочетании с файлами метаданных .json для определения параметров и правил проверки, поддерживая двуязычность (китайский и английский).

Ключевой элемент дизайна — это перечисление PromptScenario, которое определяет сценарии промптов для разных этапов:

public enum PromptScenario
{
    OpenspecV1Explore,      // Этап исследования
    OpenspecV1New,          // Создание предложения
    OpenspecV1Ff,           // Быстрая генерация
    OpenspecV1Apply,        // Применение изменений
    OpenspecV1Archive       // Архивация
}

Каждый сценарий имеет соответствующий независимый файл шаблона, например openspec-v1-explore.zh-CN.hbs и openspec-v1-ff.zh-CN.hbs, что позволяет внедрять специфичные для каждого этапа ограничения и рекомендации.

Параметризованная загрузка промптов

Реализация динамической инъекции параметров — это ядро всей системы. FilePromptProvider отвечает за загрузку промптов на основе сценария и параметров:

public async Task<string> GetOpenspecV1FfPromptAsync(
    string changeName,
    string changeDescription,
    string locale = "en-US",
    string? planningDirectionInstructions = null,
    CancellationToken cancellationToken = default)
{
    var parameters = new Dictionary<string, object>
    {
        { "planningDirectionInstructions",
          ResolvePlanningDirectionInstructions(locale, planningDirectionInstructions) }
    };

    if (!string.IsNullOrWhiteSpace(changeName))
    {
        parameters["changeName"] = changeName;
    }

    return await GetPromptWithParametersAsync(
        PromptScenario.OpenspecV1Ff,
        locale,
        cancellationToken,
        parameters);
}

Эта конструкция позволяет нам динамически внедрять параметры во время выполнения, такие как changeName и planningDirectionInstructions, без необходимости изменять сами файлы шаблонов.

Динамическая конфигурация направления планирования

HagiCode реализует гибкую систему направлений планирования, позволяющую пользователям выбирать разные направления для каждой генерации. Каждое направление имеет независимый ID, описание и фрагмент промпта:

public static class ProposalPlanningDirections
{
    private static readonly ProposalPlanningDirectionDefinition[] Catalog =
    [
        new(
            ExploreId,
            "Explore mode",
            DefaultEnabled: true,
            EnglishPromptFragment:
            "- Explore mode: add an explicit exploration pass...",
            ChinesePromptFragment:
            "- 探索模式：在定稿工件之前增加明确的探索阶段..."),
        // ... change-map, flowchart, prototype, architecture, sequence
    ];

    public static NormalizedProposalPlanningDirections Normalize(
        bool? enableExploreMode,
        IReadOnlyList<PlanningDirectionOptionDto>? planningDirections)
    {
        // Объединение конфигурации по умолчанию и пользовательской конфигурации
    }
}

Поддерживаемые направления включают: explore (режим исследования), change-map (карта изменений), flowchart (блок-схема взаимодействия), prototype (UI-прототип), architecture (архитектурная диаграмма), sequence (временная диаграмма API). Пользователи могут свободно включать/выключать эти направления, и система динамически генерирует соответствующие блоки инструкций промпта.

В шаблонах Handlebars условные операторы используются для внедрения этих инструкций:

{{#if planningDirectionInstructions}}
## Направления планирования этой генерации

{{{planningDirectionInstructions}}}
{{/if}}

Чёткие ограничения области содержимого

Самое важное улучшение — это чёткое определение ограничений области содержимого для разных типов документов, особенно для tasks.md. Мы добавили строгие ограничения в промпт:

### Ограничения области содержимого tasks.md

При создании артефакта `tasks.md` необходимо соблюдать следующие ограничения области содержимого:

**Обязательно включить**：
- Задачи бизнес-логики (реализация кода, разработка функций)
- Задачи технической реализации (интеграция компонентов, разработка API)
- Задачи тестирования (модульные тесты, интеграционные тесты)
- Задачи документации (обновление документации, добавление комментариев)

**Запрещено включать**：
- Операции фиксации Git (git add, git commit, git push)
- Рабочие процессы управления версиями
- Операции развертывания и публикации

Использование нормативного языка (MUST/SHALL), а не рекомендательного, гарантирует, что ИИ строго поймёт эти ограничения. Для proposal.md и design.md мы также чётко определили границы их ответственности: proposal.md должен включать таблицу изменений кода и UI-прототипы (когда есть изменения UI), а design.md должен включать архитектурные диаграммы и диаграммы потока данных.

Привязка контекста на этапе исследования

Проблема этапа Explore легче всего упустить из виду — при исследовании ИИ может полностью отклониться от объёма предложения. Мы решаем эту проблему, усиливая промпт:

## Принципы выполнения Explore

- **Не нужно писать документы** — результаты исследования не нужно сохранять как отдельный документ
- **Передача информации** — после завершения исследования собранная информация будет передана на этап создания Proposal
- **Важнее всего размышления** — ценность исследования заключается в сборе информации, а не в создании документов

## Связь с созданием Proposal

Этап Explore происходит после создания предложения и до написания кода проекта. После завершения исследования
система направит вас на создание или заполнение файла `proposal.md`, и собранная информация будет служить основой для содержимого предложения.

Так чётко определяется позиция этапа Explore: это предварительный шаг сбора информации, а не независимый этап создания документов. Поняв это, ИИ может больше сосредоточиться на исследовании знаний, связанных с предложением.

Руководство по внедрению

Если вы хотите применить это решение в HagiCode, выполните следующие действия:

1. Определите направления планирования: определите ID направления, состояние по умолчанию и фрагменты промпта в ProposalPlanningDirections.cs
2. Параметризация шаблонов: используйте условные операторы и инъекцию переменных в шаблонах .hbs
3. Проверка вывода: при включении определённого направления проверяйте, содержит ли соответствующий артефакт ожидаемое содержимое
4. Тестирование границ: проверяйте, что при отключении направления соответствующее содержимое не генерируется и не влияет на другие направления

Следует отметить, что изменения шаблонов должны быть синхронизированы с upstream, а структура китайских и английских шаблонов должна быть согласованной. Рендеринг направлений планирования должен завершаться на уровне микросекунд, чтобы избежать влияния на производительность.

Заключение

Оптимизация эффективности рабочего процесса OpenSpec заключается в понимании разнообразных потребностей разных этапов. Благодаря агентам, специфичным для каждого этапа, параметризованным шаблонам и чётким ограничениям содержимого, мы позволяем ИИ генерировать высококачественный контент на каждом этапе.

Это решение было проверено на практике в HagiCode — не только улучшилось качество документов, но и уменьшился объём ручного редактирования. Если ваша команда также использует аналогичный рабочий процесс, управляемый предложениями, надеюсь, этот опыт будет вам полезен.

На самом деле, это просто разбиение проблемы на части. У каждого этапа есть свои особенности, используйте правильный метод, и проблема станет простой.

Справочные материалы

• Адрес проекта HagiCode: github.com/HagiCode-org/site
• Официальный сайт HagiCode: hagicode.com
• Видео демонстрации официальной версии: www.bilibili.com/video/BV1z4oWB3EpY/
• Установка в один клик: docs.hagicode.com/installation/docker-compose
• Быстрая установка для Desktop: hagicode.com/desktop/

---

Если эта статья вам помогла:

• Поставьте лайк, чтобы больше людей увидели
• Приходите на GitHub и поставьте звёздочку
• Посетите официальный сайт, чтобы узнать больше
• Посмотрите видео демонстрации, чтобы узнать о полных функциях
• Установите в один клик и начните пользоваться

Открытое бета-тестирование уже началось, добро пожаловать на установку и пробу!

AI-перевод

Эта страница переведена с оригинала на упрощённом китайском языке с помощью ИИ.

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

Открыть оригинал на упрощённом китайском

Tags:

• OpenSpec
• AI
• Agent
• Инженерия промптов
• HagiCode
• Оптимизация рабочих процессов

Управление многоязычными метаданными Steamworks: от ручного обслуживания к структурированному рабочему процессу

Практика ускорения P2P-дистрибуции desktop-приложений: полная интеграция от потребительской стороны до стороны публикации