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

documentation-criteria — скилл для Claude Code: документы и установка

Скилл documentation-criteria для Claude Code определяет, какие документы нужны изменению и где их хранить. Агент подключает его при выборе объёма документации или создании и проверке технического документа.

MIT ★ 720 обновлён 2026-11-11

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

Что делает documentation-criteria

Скилл выбирает набор документов для изменения и задаёт порядок их подготовки. Он различает PRD, ADR, UI Spec, Design Doc и Work Plan: PRD фиксирует результат и критерии приёмки, ADR — долговременный технический выбор, а Work Plan — порядок задач и проверок.

Решение зависит от масштаба: небольшое изменение можно сразу реализовать, для среднего нужны Design Doc и Work Plan, для крупного сначала готовят PRD. UI Spec добавляется перед Design Doc, если решения по интерфейсу ещё открыты; ADR появляется перед ним для выбора, который требует сравнения вариантов и повлияет на будущую работу. Скилл проверяет существующие ADR и отличает такие решения от локальных изменений, которые следуют принятому дизайну.

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

  • выбрать документы для изменения по его масштабу
  • определить, нужен ли ADR для технического решения
  • решить, требуется ли отдельная спецификация интерфейса
  • задать порядок подготовки PRD, Design Doc и Work Plan

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

  • Определи, какие документы нужны для этого изменения.
  • Проверь, требует ли выбор хранилища отдельного ADR.
  • Оцени масштаб изменения и составь порядок подготовки документации.

Как установить documentation-criteria

1Через Skills CLI (Vercel)

npx skills add shinpr/claude-code-workflows --skill documentation-criteria -a claude-code

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

~/.claude/skills/documentation-criteria/SKILL.md

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

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

Вопросы о documentation-criteria

Как установить documentation-criteria в Claude Code?

Выполни npx skills add shinpr/claude-code-workflows --skill documentation-criteria -a claude-code. Файл скилла находится по пути ~/.claude/skills/documentation-criteria/SKILL.md.

Что делает documentation-criteria?

Скилл определяет, какие PRD, ADR, UI Spec, Design Doc и Work Plan нужны для изменения и в каком порядке их готовить. Он также задаёт место для каждого документа.

Когда documentation-criteria предлагает создать ADR?

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

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

SKILL.md · MIT
---
name: documentation-criteria
description: Determines which of PRD, ADR, UI Spec, Design Doc, and Work Plan a change requires, and where each is stored. Use when deciding documentation scope, or when creating or reviewing a technical document.
---

# Documentation Creation Criteria

This file holds the routing decision: which documents a change requires and where they live. What to write inside one is defined by its template, linked from Storage Locations.

## What Each Document Fixes

Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed.

- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it.

- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan.

- **UI Spec** — Records screen structure, transitions, component/state contracts, and visual acceptance before components exist, so decomposition is decided before implementation instead of per-component during it. Create one when those decisions remain open; reuse an approved UI Spec or go straight to the Design Doc when one evident repository-supported pattern already determines them. Technical implementation and API contracts belong to the Design Doc.

- **Design Doc** — Records the complete implementation design for the scope of the requirements: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. The same baseline turns anything written in it into planned and implemented work, so release execution, production operation, and other work outside the repository change stay out of it; a requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while the outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan.

- **Work Plan** — Fixes task order, dependencies, executable verification, and the earliest vertical proof point. Without it task order follows file layout rather than dependency, and integration risk moves to the end of the work. Design detail is referenced from the Design Doc rather than restated. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output.

## Creation Decision Matrix

| Structural Scale | Base Documents | Creation Order |
|------------------|----------------|----------------|
| Small | None | Direct implementation |
| Medium | Design Doc → Work Plan | Start with Design Doc |
| Large | PRD → Design Doc → Work Plan | Continue after PRD approval |

Build one path in this order:

1. Select the base path from Structural Scale.
2. Insert an applicable UI Spec immediately before the Design Doc.
3. One or more qualifying ADR decision points insert an ADR batch immediately before the Design Doc. A qualifying decision point sets the scale floor to Medium.

## Structural Scale

Classify the decision burden, not repository layout. File count is supporting evidence only.

| Scale | Structural condition |
|-------|----------------------|
| Small | One coherent outcome has one evident repository-supported implementation within one responsibility boundary and no unresolved durable choice |
| Medium | One coherent outcome coordinates across a boundary or requires investigation of a potentially durable choice |
| Large | Multiple independently valuable outcomes require separate design decisions |

A qualifying ADR decision point sets the floor at Medium because it creates a durable decision. One coherent outcome remains Medium when it crosses multiple layers; Large requires independently valuable outcomes with separate design decisions.

## ADR Decision Filters

Apply the Choice filter, then the Durability filter, to each technical topic inside the implementation scope. Apply them independently from Structural Scale, and check existing ADRs first.

1. **Choice requires judgment** — current requirements, accepted decisions, and representative repository evidence support at least two credible, materially distinct options whose selection requires comparison.
2. **Decision is durable** — choosing among those options materially changes responsibility, dependency direction, a shared contract, persistence, a technology dependency, reversibility, or lifecycle cost that future work must preserve or understand.

Create one ADR for each topic that passes both filters, and review the complete batch together. Treat choices as one decision point when they must be selected or reconsidered together; separate independently revisitable choices.

Qualifying durable choices include:

- introducing or replacing a technology, library, platform, storage model, or external dependency;
- changing ownership, dependency direction, a trust boundary, or a shared public contract when credible alternatives exist;
- replacing an accepted architecture decision with a different durable choice that passes both filters;
- choosing an irreversible or high-cost-to-reverse data or compatibility strategy.

A local contract, data-flow, state, or component change belongs in the Design Doc when it follows an accepted design, has one evident repository-supported implementation, or remains cheaply reversible. Counts of files, consumers, nesting levels, states, steps, and asynchronous operations are supporting evidence rather than ADR criteria. Only the qualifying decisions above create ADRs; generic technical concerns, operational possibilities, and rejected activities can only support that determination.

## Storage Locations

| Document | Path | Naming Convention | Template |
|----------|------|------------------|----------|
| PRD | `docs/prd/` | `[feature-name]-prd.md` | [prd-template.md](references/prd-template.md) |
| ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` | [adr-template.md](references/adr-template.md) |
| UI Spec | `docs/ui-spec/` | `[feature-name]-ui-spec.md` | [ui-spec-template.md](references/ui-spec-template.md) |
| UI Spec Assets | `docs/ui-spec/assets/{feature-name}/` | Prototype code files | - |
| Design Doc | `docs/design/` | `[feature-name]-design.md` | [design-template.md](references/design-template.md) |
| Work Plan | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | [plan-template.md](references/plan-template.md) |
| Task File | `docs/plans/tasks/` | `{plan-name}-task-{number}.md` | [task-template.md](references/task-template.md) |

*Note: Work plans are excluded by `.gitignore`

## References

Each template defines the content, structural elements, and diagram criteria for its document: [prd-template.md](references/prd-template.md), [adr-template.md](references/adr-template.md), [ui-spec-template.md](references/ui-spec-template.md), [design-template.md](references/design-template.md), [plan-template.md](references/plan-template.md), [task-template.md](references/task-template.md)

© shinpr · MIT · shinpr/claude-code-workflows

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

Все скиллы по теме «Тексты и документация» →
code-documentation MoizIbnYousaf Скилл code-documentation задаёт структуру README, API-справки, комментариев и архитектурных заметок, чтобы агент писал документацию по одному шаблону. CX Codex +1 571установок create-architecture-documentation davila7 Слэш-команда create-architecture-documentation для Claude, которая собирает документацию по архитектуре проекта: диаграммы, ADR и описание компонентов. CX Codex +1 6 136установок technical-specification aj-geddes Скилл technical-specification для Claude Code. Помогает агенту структурировать техспеки, PRD, ADR и RFC: собирает требования, архитектуру, критерии приёмки и схемы данных в единый документ до написания кода. CX Codex +1 816установок documentation-and-adrs addyosmani Скилл documentation-and-adrs для Claude Code фиксирует архитектурные решения и помогает находить устаревшую документацию. Подключается при изменении публичного API, выпуске функций и проверке соответствия документов коду. CX Codex +1 80 700установок documentation-patterns OrchestKit Скилл documentation-patterns для Codex даёт шаблоны README, ADR, OpenAPI-документации и changelog. Помогает оформлять документацию проекта и записывать архитектурные решения. CX Codex +1 150установок adr-documentation MadAppGang Скилл adr-documentation помогает фиксировать архитектурные решения, причины выбора и рассмотренные альтернативы. Пригодится при выборе технологий, паттернов или стратегии миграции. CX Codex +1 1установок

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

Весь набор →
llm-friendly-context Скилл llm-friendly-context для Claude Code правит промпты, хендоффы и отчёты, чтобы следующий агент видел входы, шаги и критерии успеха. CX Codex +1 ★ 720звёзд репо requirement-convergence Скилл requirement-convergence для Claude Code отделяет целевой результат изменений от предложенных требований и фиксирует исключения пользователя. Включается на этапе сбора требований до проектирования архитектуры. CX Codex +1 ★ 720звёзд репо work-planner Субагент work-planner для Claude Code превращает утверждённые Design Doc в план реализации с задачами, зависимостями и проверками. Запускается при запросе плана работ или планирования задач. CX Codex ★ 720звёзд репо typescript-rules Набор правил для фронтенд-разработки на React и TypeScript: типобезопасность, устройство компонентов, владение состоянием и обработка ошибок. CX Codex +1 ★ 720звёзд репо codebase-analyzer Субагент codebase-analyzer для Claude Code собирает факты о кодовой базе перед составлением Design Doc. Запускается по утверждённому PRD или списку требований для оценки повторного использования и рисков. CX Codex ★ 720звёзд репо code-verifier Субагент code-verifier для Claude Code сверяет утверждения в PRD, дизайн-документах и планах работ с кодом репозитория. Его запускают перед ревью документа, после реализации или для проверки описания существующей системы. CX Codex ★ 720звёзд репо scope-discoverer Субагент scope-discoverer разбирает кодовую базу на функциональные блоки и связи для обратного документирования. Помогает подготовить фундамент под PRD. CX Codex ★ 720звёзд репо ui-spec-designer Субагент ui-spec-designer для Claude Code превращает требования к интерфейсу в спецификацию экранов, состояний и компонентов. Запускается при проектировании фронтенда или запросе на разбиение UI на компоненты. CX Codex ★ 720звёзд репо

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

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