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

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

Ведёт design-доки проекта: домен, техспеку, behavior-спеку, реестр section-ID и changelog. Запускается по заголовку [MODE: DESIGN_DOCS ...].

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

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

Что делает design-docs

Скилл описывает полный протокол режима DESIGN_DOCS. Архитектор подгружает его, когда команда design-docs выдаёт заголовок [MODE: DESIGN_DOCS ...], и дальше работа идёт в репозитории собираемого проекта: domain.md с сущностями и инвариантами, technical-spec.md со слоями и контрактами, behavior-spec.md в формате Given/When/Then, design-changelog.md и каталог reference/ для всего языкового.

Из заголовка берутся out (по умолчанию docs), lang (по умолчанию auto) и флаг update; при update=false в хвосте нужен текст с описанием системы. Сами доки пишет субагент docs_design. Номера секций D-###, S-###, B-###, R-### присваиваются один раз и при синхронизации не переезжают, реестр лежит в reference/traceability.json, у каждой секции есть футер со ссылками на FR.

Нормативный текст в трёх основных файлах остаётся без имён фреймворков и библиотек — всё такое уходит в reference/. Включается скилл только при design_docs.enabled: true в opencode-swarm.json: без этого агента docs_design просто нет, и протокол встанет на первом шаге.

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

  • сгенерировать доменную модель и техспеку для нового проекта
  • синхронизировать доки с кодом после фазы разработки
  • держать стабильные section-ID между перегенерациями
  • связать разделы доков с требованиями FR из спеки
  • разложить языковые детали в reference/, не засоряя нормативный текст

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

  • Прогони design-docs с out=docs и update=false: опиши сервис бронирования билетов.
  • Синхронизируй docs/ с изменениями этой фазы, правились src/orders/.
  • Проверь, что в technical-spec.md нет имён фреймворков, и допиши запись в design-changelog.md.

Как установить design-docs

1Через Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a claude-code

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

~/.claude/skills/design-docs/SKILL.md

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

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

Вопросы о design-docs

Как установить design-docs в Claude Code?

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

Что делает design-docs?

Ведёт структурированные design-доки проекта: домен, техспеку, поведение, changelog и reference/. Работает по заголовку [MODE: DESIGN_DOCS ...], который выдаёт команда design-docs.

Что нужно, чтобы скилл заработал?

Включённый design_docs.enabled: true в opencode-swarm.json, иначе субагента docs_design нет. Если в проекте лежит .swarm/spec-staleness.json, сначала разберитесь со спекой, иначе запись упрётся в SPEC_DRIFT_BLOCK.

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

SKILL.md · MIT
---
name: design-docs
description: >
  Full execution protocol for MODE: DESIGN_DOCS — generate or sync structured,
  language-agnostic design docs (domain.md, technical-spec.md, behavior-spec.md,
  reference/) for the project under build, with a stable section-ID registry and
  a design changelog. Loaded on demand by the architect when the design-docs
  command emits a [MODE: DESIGN_DOCS ...] signal (issue #1080).
metadata:
  audience: swarm-plugin
---

# Design-Doc Generation & Sync Protocol

Generate or maintain the project's structured design documentation. The work is delegated to the `docs_design` agent (a design-doc-author role variant of the docs agent). This mode authors a fixed set of version-controlled docs in the **target project repo** (NOT under `.swarm/`). It does NOT modify source code, does NOT call `declare_scope`, and does NOT touch `.swarm/spec.md`, `CHANGELOG.md`, or `docs/releases/pending/*`.

### MODE: DESIGN_DOCS

## Step 0 — Parse Header

Parse the `[MODE: DESIGN_DOCS ...]` header to extract:
- `out`: output directory, project-relative (default `docs`)
- `lang`: target language for `reference/` docs, or `auto` (default `auto`)
- `update`: boolean — `true` = sync existing docs to current code/spec; `false` = generate fresh
- the trailing free text = the system description (required when `update=false`)

If the header is malformed, report the error and stop.

## Step 1 — Preconditions

1. Confirm `design_docs.enabled` is true (the `docs_design` agent only exists when enabled). If it is not, tell the user to set `design_docs.enabled: true` in `opencode-swarm.json` and stop.
2. If a spec-staleness block is active (`.swarm/spec-staleness.json` present), resolve/acknowledge spec staleness FIRST — otherwise design-doc writes may be blocked by the guardrail, which emits `SPEC_DRIFT_BLOCK`. Do not blindly retry on `SPEC_DRIFT_BLOCK`.
3. Read `.swarm/spec.md` if present — it is the authoritative requirements source (FR-### IDs). The design docs must be consistent with it.
   Run `/swarm sdd status` to resolve the effective spec before reading.

## Step 2 — Index Existing State (always)

Have the `docs_design` agent (or `doc_scan`) index `<out>/` to discover any existing design docs. If `<out>/reference/traceability.json` exists, it is the section-ID registry — load it. Existing section IDs MUST be preserved on regeneration.

## Step 3 — Generate or Sync

Dispatch the **`docs_design`** agent (the active swarm's `docs_design` — never the standard `docs` agent) with:
- `TASK`, `MODE` (generate|sync), `OUT_DIR`, `LANGUAGE`
- For sync: `FILES CHANGED` and `CHANGES SUMMARY` from the current phase/diff
- `SKILLS: file:.swarm/bundled-skills/design-docs/SKILL.md` (this skill)

The agent owns exactly these files under `<out>` and creates NOTHING else:

```
<out>/
├── domain.md              # 100% language-agnostic. Entities in neutral notation
│                          #   (field: type-class), domain invariants. ZERO framework
│                          #   names in normative text. Section IDs: D-###
├── technical-spec.md      # Language-agnostic architecture: layers, dependency rules,
│                          #   contract SHAPES (inputs→outputs→error-kinds), algorithms,
│                          #   invariants. + the traceability table. Section IDs: S-###
├── behavior-spec.md       # 100% language-agnostic Given/When/Then specs. IDs: B-###
├── design-changelog.md    # Keep-a-Changelog log of design-doc changes (NOT release notes)
└── reference/             # ALL [INCIDENTAL] language/framework-specific material here.
    ├── reference-impl.md  #   Exact signatures, CLI strings, SQL, code. Mapped to
    │                      #   spec sections by ID. Section IDs: R-###
    ├── idiom-notes.md     #   "Here is how the reference solved X" — examples only.
    └── traceability.json  #   Machine-readable section-ID registry (source of truth)
```

## Step 4 — Invariants the docs MUST satisfy

- **Language-agnostic normative text**: `domain.md`, `technical-spec.md`, and `behavior-spec.md` contain ZERO framework/library/language names in normative content. All such material lives ONLY in `reference/`.
- **Version header** on every doc:
  `<!-- design-doc: <name>  version: <phase-or-counter>  generated: <ISO-8601>  spec-hash: <8 chars> -->`
- **Stable section IDs**: assigned once, never renumbered. `D-###` domain, `S-###` technical-spec, `B-###` behavior-spec, `R-###` reference. On sync, reuse every existing ID; mint new IDs only for genuinely new sections.
- **Traceability footer** ending each section: `> Traceability: FR-012, FR-013 | invariant: <id-or-none>`.
- **traceability.json** kept in sync: `{ "schema_version": 1, "sections": [ { "section_id", "doc", "title", "spec_frs": [], "invariants": [], "code_anchors": [] } ] }`. `technical-spec.md` renders a human-readable mirror table `| Doc Section | Spec FR | Invariant | Code anchors |`.
- **design-changelog.md**: append one entry per generate/sync under `## [Unreleased]` (Added/Changed/Removed), e.g. `- <ISO date> phase <N>: <sections touched> (<FR refs>)`. This file is SEPARATE from release-please artifacts — never edit `CHANGELOG.md` or `docs/releases/pending/*` here.

## Step 5 — Verify & Report

1. Confirm the agent created/updated only the allowed files and `traceability.json` is consistent with the docs.
2. Confirm no normative doc names a framework (spot-check) and every section has an ID + traceability footer.
3. Report `UPDATED` / `ADDED` / `REMOVED` / `SUMMARY` back to the user.

## Notes on the PHASE-WRAP sync path

During PHASE-WRAP, the deterministic design-doc drift check (`runDesignDocDriftCheck`) writes `.swarm/doc-drift-phase-N.json`. If the verdict is `DOC_STALE` and `design_docs.enabled`, dispatch `docs_design` in **sync** mode for the affected sections only, then append a design-changelog entry. This is advisory and non-blocking — never block phase completion on design-doc lag.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

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

Все скиллы по теме «Тексты и документация» →
writing-design-docs riekelt Скилл writing-design-docs для Claude Code задаёт структуру RFC и архитектурных предложений: вывод, цели и не-цели, карточки Why & What и проверку на неопределённости. CX Codex +1 26 900установок merge-docs serpro69 Скилл merge-docs для Claude Code объединяет дизайн, план реализации и список задач из двух проработок одной фичи в один набор документов. Решает расхождения по коду проекта. CX Codex +1 ★ 155звёзд репо rfc-generator patricio0312rev Скилл rfc-generator собирает RFC по техническому предложению: проблема, решение, альтернативы, риски и план внедрения по готовому шаблону, а не с чистого листа. CX Codex +1 294установок design-reviewer serpro69 Субагент design-reviewer проверяет проектные спецификации и планы задач без контекста прошлых обсуждений. Помогает найти противоречия и технические риски до написания кода. CX Codex ★ 155звёзд репо egm-drift-report официальный google Скилл egm-drift-report для Claude Code сверяет дизайн-документы и README с кодом. Запускается по явному запросу на поиск расхождений или проверку согласованности файлов в каталоге. CX Codex +1 583установок propagate-design-change Donchitos Скилл propagate-design-change для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode находит ADR (architecture decision records), которые устарели после правки GDD, и разбирает каждый. CX Codex +1 638установок

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

Весь набор →
commit-pr Скилл commit-pr проверяет код перед пушем, создаёт конвенциональные коммиты и оформляет PR-описание. Включается при подготовке изменений к отправке. CX Codex +1 ★ 539звёзд репо test-file-split Скилл test-file-split разбивает разросшийся тест-файл на части по блокам describe(), когда тот подходит к лимиту в 500 строк или уже перевалил его. CX Codex +1 ★ 539звёзд репо fork-pr-operations Скилл fork-pr-operations инструктирует агента по работе с пулл-реквестами из форков: одобрение воркфлоу в GitHub Actions, безопасный rebase и сверка актуальности проверок CI. CX Codex +1 ★ 539звёзд репо parallel-work-check Скилл parallel-work-check для Claude Code сравнивает локальное состояние существующей ветки с удалённым и проверяет новые коммиты. Помогает заметить параллельные изменения до начала правок. 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звёзд репо clarify-spec Скилл clarify-spec устраняет маркеры неопределённости в спецификациях Swarm, опрашивая разработчика по одному вопросу за раз. CX Codex +1 ★ 539звёзд репо

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

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