design-docs — скилл для Claude Code: что делает и как установить
Ведёт design-доки проекта: домен, техспеку, behavior-спеку, реестр section-ID и changelog. Запускается по заголовку [MODE: DESIGN_DOCS ...].
MIT ★ 539 обновлён 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/design-docs/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/design-docs/
1Через Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a codex2Вручную: положить файлы
.agents/skills/design-docs/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a cursor2Вручную: положить файлы
.cursor/skills/design-docs/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .claude/skills/design-docs2Вручную: положить файлы
.github/skills/design-docs/SKILL.md1Через Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a gemini-cli2Командой платформы
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .claude/skills/design-docsВручную: положить файлы
.devin/skills/design-docs/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill design-docs -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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