convez.ai
SkillDesign & UIIntermediário
jade-666

Design Brief Builder

jade-666/design-brief-builder

Converte requisitos vagos em briefs estruturados para agentes de design

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que transforma requisitos vagos em arquivos de restrições estruturados para agentes de IA. Elimina ambiguidades de design antes da execução, compatível com Claude Code, Cursor e Codex, reduzindo retrabalho através de briefs bem definidos em Markdown.

Instalação

$npx convez-ai jade-666/design-brief-builder

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v1.0.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Documentar requisitos de design antes de agentes iniciarem trabalho
  • Resolver conflitos entre múltiplas fontes de input (PRD, protótipos, brand)
  • Definir constraints de sistema de design para evitar componentes desalinhados
  • Padronizar prioridades e escopo em revisões incrementais

Veredito

Endereça um problema real em workflows com agentes de design — formalizar restrições antes da execução reduz retrabalho significativo. Arquitetura de 4 camadas (Goal, Structure, Constraints, Reference) é sólida e well-documented, com benchmarks mostrando consistência entre agentes.

README

A tradução para o português deste README ainda está na fila.

Design Brief Builder

Stop your AI agent from guessing your design. Turns vague requests into structured constraint files that eliminate rework — before a single line of code runs. Works with Claude Code, Cursor, Codex, and beyond.

npm version Benchmark Score License


Why it exists

AI agents are increasingly capable at design work, but most problems happen before they start — conflicts in the requirements, unresolved priorities, and unstated boundaries all get carried straight into execution.

Anyone who has used an agent for design has hit problems like these:

ProblemWhat it looks like
Vague goalThe agent doesn't know what the page should accomplish, so it invents its own success criteria
Conflicting inputsThe PRD and the prototype screenshot disagree; the agent just picks one at random
Missing constraintsNo design-system boundaries, so the agent invents components that don't fit the existing system
Ambiguous priorities"Minimal but information-complete" — when two requirements conflict, the agent decides on its own
Unclear scopeDuring an incremental revision, the agent touches modules it was never supposed to change
Omitted statesOnly the happy path gets built; empty / error / loading states are all missing

The common root cause: there is no structured step that nails down the constraints before the agent starts.

Design Brief Builder is that step.


What it does

Whatever the input looks like — a one-line request, several conflicting documents, or a partial revision of a live system — DBB produces the same structure:

┌──────────────────────────────────────────────────────────────────┐
│ 4-LAYER DESIGN BRIEF                                             │
│   • Goal         core users · use context · success criteria     │
│   • Structure    full page list · per-page states · gaps filled  │
│   • Constraints  brand rules · prohibitions · order · priorities │
│   • Reference    style refs · extraction dims · exclusions       │
└──────────────────────────────────────────────────────────────────┘
                                  │  written to
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│ DESIGN_BRIEF.md                                                  │
│   Read-only intent layer — untouched during execution            │
└──────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│ CLAUDE.md / AGENTS.md / .cursorrules                             │
│   Execution constraints — one per agent, append-only             │
└──────────────────────────────────────────────────────────────────┘

Every ambiguity and conflict is resolved before the agent starts — nothing is left to the agent's own judgment.


When to use it

The more of these conditions hold, the more value DBB adds:

  • More than one input source — designer, PM, brand team, and PRD all say different things; conflicts must be resolved before execution rather than left to the agent to pick at random
  • A clear "do not touch" exists — redesigns, incremental iterations, existing systems: boundaries matter more than goals, and the agent needs to know where the no-go zones are
  • Output needs staged review — not a one-shot delivery; key checkpoints must be confirmed before continuing
  • Constraints come from external files — design systems, brand guidelines, DESIGN.md: they need to be referenced correctly, not overwritten or rewritten

Core features

  • Platform-agnostic — not tied to any agent runtime. Claude Code, Cursor, Codex: one Brief process, each agent takes its own execution file
  • Pre-execution governance — requirements are diagnosed and constraints locked down before the agent acts, rather than patched after the output
  • Intent / execution separation — DESIGN_BRIEF.md is a read-only archive; constraint decisions are written only into the execution files, and the two never pollute each other
  • Checkpoint review chain — execution pauses at branching points to wait for human confirmation; review conclusions are appended to the execution files instead of relying on conversation memory
  • Change-boundary protection — edits affect only the current stage and never pollute already-approved pages

How it works

┌──────────────────────────────────────────────────────────────────┐
│ STEP 1  ·  Six-dimension diagnosis                               │
│   Scan the request, label KNOWN / VAGUE / MISSING                │
│   Ask at most 5 questions                                        │
└──────────────────────────────────────────────────────────────────┘
                                  │  user answers
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│ STEP 2  ·  Generate the 4-layer Brief                            │
│   Goal · Structure · Constraints · Reference                     │
└──────────────────────────────────────────────────────────────────┘
                                  │  user confirms
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│ STEP 3  ·  Write project files                                   │
│   DESIGN_BRIEF.md (read-only)                                    │
│   + CLAUDE.md / AGENTS.md / .cursorrules                         │
└──────────────────────────────────────────────────────────────────┘
                                  │  start execution
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│ STEP 4  ·  Execution                                             │
│   Force a stop at each Checkpoint                                │
│   Resume only after "approved, continue"                         │
│   Edits affect only the current stage                            │
└──────────────────────────────────────────────────────────────────┘

The Brief is a read-only intent layer; the execution files are an append-only decision layer. The two are physically separate.


Benchmark

Fully tested across 3 agent environments and 8 real-world scenarios.

Scoring dimensions (0–3 each, 9 max): diagnostic accuracy · question restraint · Brief usability

CaseScenarioScore range
TC-AMinimal input (one line, no attachments)9
TC-BConflicting inputs (multiple sources with contradictions)8–9
TC-CMissing goal (prototype present, no business goal)9
TC-DConflicting constraints (mutually contradictory design requirements)8–9
TC-EComplex B2B system (multi-role · operation order · misclick prevention)8–9
TC-FIncremental iteration (partial revision of a live system)8–9
TC-GExternal design-spec reference (DBB × DESIGN.md)9
TC-HMid-flight requirement change (handling changes after the Brief is locked)Pending

Score ranges reflect DBB's performance band across different agent environments. Full three-way benchmark (with per-case analysis) → evaluation/benchmark.md


Quick start

One-command install (recommended)

# Choose the install target interactively
npx design-brief-builder

# Or target directly
npx design-brief-builder claude    # Claude Code (global)
npx design-brief-builder project   # current project's .claude/skills
npx design-brief-builder cursor    # Cursor
npx design-brief-builder codex     # Codex

Manual install

The skill is a folder (SKILL.md + references/) — copy the whole thing into your client's skills directory. Don't copy SKILL.md alone, or the references will break.

cp -R design-brief-builder ~/.claude/skills/    # Claude Code (global)
cp -R design-brief-builder ~/.cursor/skills/    # Cursor
cp -R design-brief-builder ~/.agents/skills/    # Codex

After installing, start a new session and call /design-brief-builder explicitly.


Repository structure

.
├── README.md
├── package.json                        # npm package manifest (npx install entry)
├── bin/
│   └── install.js                      # npx one-command installer
├── design-brief-builder/               # ← copy this whole folder when installing
│   ├── SKILL.md                        # core file (process definition)
│   └── references/
│       ├── brief-template.md           # 4-layer Brief template
│       ├── execution-file-template.md  # execution-file template
│       └── diagnosis-guide.md          # detailed six-dimension diagnosis criteria
└── evaluation/                         # benchmark archive
    ├── benchmark.md                    # full 3-agent × 8-scenario benchmark records
    └── test-cases.md                   # 8 standard test cases (v2)

License

MIT © Marker Utron Studio

Ver o original no GitHub

Bom para

Relacionados