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

clarify-spec — скилл для Claude Code: что делает и как установить

Скилл clarify-spec устраняет маркеры неопределённости в спецификациях Swarm, опрашивая разработчика по одному вопросу за раз.

MIT ★ 539 обновлён 2026-10-29

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add ZaxbyHub/opencode-swarm --skill clarify-spec -a claude-code
Открыть на GitHub

Что делает clarify-spec

Протокол подключается архитектором Swarm при наличии маркеров [NEEDS CLARIFICATION] в действующей спецификации или по команде /swarm clarify. Скилл считывает единый источник требований — нативный .swarm/spec.md, OpenSpec или Spec-Kit. Кроме явных меток, алгоритм ищет размытые формулировки без метрик, пересекающиеся требования и нетестируемые критерии приёмки.

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

Если спецификация отсутствует или в проекте конфликтуют несколько источников, скилл откажется работать и потребует вызвать /swarm specify либо устранить неоднозначность.

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

  • закрыть маркеры [NEEDS CLARIFICATION] в действующей спецификации
  • выявить неизмеримые прилагательные и скрытые пограничные случаи в требованиях
  • зафиксировать решения пользователя без затирания исходных файлов OpenSpec или Spec-Kit
  • проверить формулировки спорных вопросов через агента-критика перед уточнением

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

  • /swarm clarify
  • Уточни спецификацию и разбери спорные требования
  • Разбери открытые маркеры clarification в текущем спеке

Как установить clarify-spec

1Через Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill clarify-spec -a claude-code

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

~/.claude/skills/clarify-spec/SKILL.md

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

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

Вопросы о clarify-spec

Как установить clarify-spec в Claude Code?

Выполните команду npx skills add ZaxbyHub/opencode-swarm --skill clarify-spec -a claude-code. Файл навыка сохранится по пути ~/.claude/skills/clarify-spec/SKILL.md.

Что делает скилл clarify-spec?

Он ведёт пошаговый опрос по неясным местам спецификации проекта, обращается к предметному агенту и сразу обновляет файл требований принятыми решениями.

Как скилл защищает неродные спецификации вроде OpenSpec?

Он запрещает создавать файл .swarm/spec.md, чтобы случайно не перекрыть сторонний источник. Изменения вносятся прямо в артефакты формата либо запрашивается материализация через /swarm sdd project.

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

SKILL.md · MIT
---
name: clarify-spec
description: >
  Full execution protocol for MODE: CLARIFY-SPEC -- resolving spec clarification markers and maintaining spec/planning alignment.
metadata:
  audience: swarm-plugin
---

# Clarify Spec Protocol

This protocol is loaded on demand by the architect runtime. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.

### MODE: CLARIFY-SPEC
Activates when: `/swarm sdd status` reports a **single resolved EFFECTIVE spec** (non-null) AND it contains `[NEEDS CLARIFICATION]` markers; OR user says "clarify", "refine spec", "review spec", or "/swarm clarify" is invoked; OR architect transitions from MODE: SPECIFY or MODE: BRAINSTORM with open markers.

`/swarm sdd status` reflects `readEffectiveSpecSync`, which returns **null** (NO effective spec) for: no sources at all, multiple competing sources (e.g. `openspec/` AND `.specify/`), multi-feature Spec-Kit without a selected feature, or any other unresolvable state. CLARIFY-SPEC does NOT activate in these null cases — tell the user: "No resolved effective spec exists. Disambiguate with `/swarm sdd project --source <source>` or `--feature <feature>`, or run `/swarm specify` to generate one first." and stop.

CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. Always consult `/swarm sdd status` to determine the effective spec source before proceeding.

1. Read the **effective spec** resolved by `/swarm sdd status` (native `.swarm/spec.md` OR OpenSpec `openspec/` OR Spec-Kit `.specify/` — read the resolved spec FIRST before making any changes).
2. Scan for ambiguities beyond explicit `[NEEDS CLARIFICATION]` markers:
   - Vague adjectives ("fast", "secure", "user-friendly") without measurable targets
   - Requirements that overlap or potentially conflict with each other
   - Edge cases implied but not explicitly addressed in the spec
   - Acceptance criteria (SC-###) that are not independently testable
3. Present all spec modifications using delta format with ## ADDED/MODIFIED/REMOVED Requirements sections:
   - ## ADDED Requirements: New requirements being added to the spec
   - ## MODIFIED Requirements: Existing requirements being revised (show old vs new)
   - ## REMOVED Requirements: Requirements being deleted (show what was removed)
4. Delegate to `the active swarm's sme agent` for domain research on ambiguous areas before presenting questions.
5. Present questions to the user ONE AT A TIME (max 8 per session):
   - Offer 2–4 multiple-choice options for each question
   - Mark the recommended option with reasoning (e.g., "Recommended: Option 2 because…")
   - Allow free-form input as an alternative to the options
6. After each accepted answer, write the resolution to the **resolved effective source** (source-aware write-back):
    - **NATIVE effective spec** (`.swarm/spec.md` exists): update `.swarm/spec.md` with the resolution directly.
    - **NON-NATIVE effective spec** (openspec/specify-only, NO native `.swarm/spec.md`): do NOT write `.swarm/spec.md` — this would silently shadow the non-native source. Instead:
      - (a) If the resolved source supports in-place edits (e.g., OpenSpec sections), update the source artifacts directly.
      - (b) If no in-place edit path exists, ask the user: "The effective spec lives in `<source>`. To persist this resolution as a native spec, run `/swarm sdd project` first to materialize one, or I can stop here. Proceed?" — if the user consents to project, materialize via `/swarm sdd project` then write `.swarm/spec.md`; otherwise stop.
      - (c) If neither (a) nor (b) applies, stop and tell the user the clarification cannot be auto-written to a non-native source without a projection step.
    - Replace the relevant `[NEEDS CLARIFICATION]` marker or vague language with the accepted answer.
    - If the answer invalidates an earlier requirement, update it to remove the contradiction.
7. Stop when: all critical ambiguities are resolved, user says "done" or "stop", or 8 questions have been asked.
8. Report a ## Clarification Summary: total questions asked, requirements added/modified/removed, remaining open ambiguities (if any), and suggest next step (`PLAN` if spec is clear, or continue clarifying).

CLARIFY-SPEC RULES:
- FR-ID increment rule: When adding new requirements, find the highest existing FR-ID and increment from there (FR-001 → FR-002). Never reuse or skip FR-IDs.
- One question at a time — never ask multiple questions in the same message.
- Do not modify any part of the spec that was not affected by the accepted answer.
- Always write the accepted answer back to the resolved effective source before presenting the next question. Never write `.swarm/spec.md` in a non-native (openspec/specify-only) repo — see step 5 source-aware write-back rule.
- Max 8 questions per session — if limit reached, report remaining ambiguities and stop.
- Do not create, overwrite, or shadow the spec file — only refine what exists. In non-native (openspec/specify-only) repos, never silently materialize a `.swarm/spec.md` that would shadow the effective source.

### Scoped Funnel Protocol (CLARIFY-SPEC only)

CLARIFY-SPEC handles **already-surfaced** `[NEEDS CLARIFICATION]` markers and spec ambiguities — it does not perform open-ended discovery of new uncertainties. The full four-stage clarification funnel (inventory, classify, consult critic, surface) described in the clarify skill applies to MODE: CLARIFY and MODE: PLAN, not here.

However, before surfacing each marker question to the user, CLARIFY-SPEC MUST:

1. **Consult `critic_sounding_board`** with the candidate marker question and surrounding spec context to check whether the question wording can be improved or the item can be resolved from existing context.
2. **Apply the Overconfidence guard:** If the critic supplies a `RESOLVE` verdict with a default answer, but that default is not directly supported by user request, spec, or recorded context, classify the item as `user_decision` rather than `self_resolved`.
3. **Apply always-surface protection:** If the marker belongs to an always-surface category (scope boundaries, destructive behavior, security/privacy, backward compatibility, breaking API changes, new dependencies, deprecations, cross-platform impact, cost/performance tradeoffs, user-visible UX, rollout strategy, QA gates), the item MUST NOT receive `UNNECESSARY`/`DROP` from the critic — override to `APPROVED`/`ASK_USER`.

Critic verdict mapping (`SoundingBoardVerdict`): `UNNECESSARY`→DROP, `RESOLVE`→RESOLVE, `REPHRASE`→REPHRASE, `APPROVED`→ASK_USER.

This scoped protocol is lighter than the full funnel because CLARIFY-SPEC starts from known markers rather than open uncertainty inventory, but it still protects against overconfident self-resolution and premature dropping of important questions.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

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

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
deep-clarify chrono-meta Скилл deep-clarify для Claude Code проясняет расплывчатую задачу и превращает её в спецификацию. Запускается по просьбе уточнить направление или подготовить требования. CX Codex +1 ★ 33звёзд репо speckit.clarify Chat2AnyLLM Команда speckit.clarify находит неясные места в спецификации фичи и задаёт до 5 целевых вопросов, чтобы заполнить пробелы перед планированием. CX Codex +1 ★ 117звёзд репо ns-spec-driven nextstage-brasil Скилл ns-spec-driven для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode, который ведёт доставку фичи по формальной спецификации. CX Codex +1 208установок spec codewithmukesh Скилл spec превращает сырую идею фичи в письменную спецификацию с критериями приёмки. Задаёт вопросы раундами, пока не закроет все пробелы. CX Codex +1 3 900установок cursor-spec-interviewer stark-ai-de Скилл cursor-spec-interviewer для Claude Code, Codex, Cursor и других агентных платформ превращает размытый запрос в согласованную спецификацию реализации с критериями приёмки. CX Codex +1 2 700установок om-app-spec-writing open-mercato Скилл om-app-spec-writing формирует бизнес-архитектуру приложения, модель домена, сценарии с расчётом ROI и фазы запуска до написания кода. Блокирует реализацию до приёмки App Spec. CX Codex +1 1 000установок

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

Весь набор →
design-docs Ведёт design-доки проекта: домен, техспеку, behavior-спеку, реестр section-ID и changelog. Запускается по заголовку [MODE: DESIGN_DOCS ...]. CX Codex +1 ★ 539звёзд репо orchestrating-subagents Скилл orchestrating-subagents для Claude Code задаёт правила декомпозиции задач: выбор моделей для ролей, параллельный запуск исследователей и независимую приёмку кода ревьюерами. CX Codex +1 ★ 539звёзд репо commit-pr Скилл commit-pr ведёт работу с коммитами и pull request: от подготовки публикации до проверки CI и завершения PR. Он пригодится при выпуске изменений по GitHub issue. CX Codex +1 ★ 539звёзд репо contributing Скилл contributing проводит агента по всему циклу пул-реквеста в репозитории opencode-swarm: ветка, формат коммитов, фрагмент release notes, локальные проверки и шаблон описания. CX Codex +1 ★ 539звёзд репо pre-phase-briefing Скилл pre-phase-briefing собирает контекст перед фазой проекта, проверяет прошлые ретроспективы и сверяет план с реальным состоянием кодовой базы. CX Codex +1 ★ 539звёзд репо rust-crate-ci Скилл rust-crate-ci для правки Rust-крейта runners/swarm-sandbox-runner: задаёт порядок локальных проверок и разбирает ошибки Windows, которые видит только CI. CX Codex +1 ★ 539звёзд репо clarify Скилл clarify разбирает неясные требования через четырёхэтапную воронку с проверкой критиком и готовит пакет решений без лишних вопросов. CX Codex +1 ★ 539звёзд репо editing-skills Скилл editing-skills помогает менять SKILL.md в opencode-swarm, не нарушая правила зеркалирования, публикации и проверки расхождений. Загрузите его перед редактированием скиллов в этом репозитории. CX Codex +1 ★ 539звёзд репо

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

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