specsfy-03-specify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Montar a especificação única

构建统一规范文档

Modo de interação

交互模式

Modo de interação:

perguntas

. Antes de formular qualquer pergunta, leia e aplique o

Contrato de perguntas numeradas

.specsfy/Spec.md

Crie ou atualize o pacote

specs/draft/<NNNN>-<slug>/

, no qual

spec.md

é a única fonte normativa de todo o fluxo SDD. Somente o diretório recebe o número; mantenha o arquivo sempre como

spec.md

. Consolide descoberta, research, esclarecimentos, produto, plano técnico, modelo de dados, contratos, TDD, BDD, validações, tarefas, decisões e conclusão em três atos explícitos. Evidências externas consultadas vivem em

research/

; não gere

plan.md

research.md

data-model.md

tasks.md

, checklists ou uma segunda especificação.

交互模式：

提问式

。在提出任何问题之前，请阅读并应用

.specsfy/Spec.md

中的

编号提问协议

。

创建或更新

specs/draft/<NNNN>-<slug>/

包，其中

spec.md

是整个SDD流程的唯一规范性文件。仅目录使用编号；请始终将文件名保持为

spec.md

。将发现、调研（research）、澄清说明、产品需求、技术方案、数据模型、合同、TDD、BDD、验证、任务、决策及结论整合为三个明确的部分。查阅过的外部证据存放在

research/

目录下；请勿生成

plan.md

、

research.md

、

data-model.md

、

tasks.md

、清单或第二个规范文档。

Orquestrar a conversa

对话编排

Ao concluir esta etapa ou detectar trabalho de outra etapa, anuncie

Pendência detectada: <descrição> — ação: resolvendo nesta etapa

e resolva-a quando pertencer ao próprio escopo. Quando houver troca de responsabilidade, anuncie

Transição automática: $specsfy-03-specify → $<destino> — motivo: <motivo> — resultado esperado: <resultado>

e carregue imediatamente a skill de destino, sem pedir confirmação nem repetir o comando. Continue na mesma conversa. Depois de uma correção necessária a esta etapa, anuncie

Retomada automática: $<destino> → $specsfy-03-specify — pendência resolvida: <resultado>

e retome-a imediatamente. Reavalie o estado após cada handoff para evitar ciclos. Não peça confirmação para o handoff; ações sensíveis continuam exigindo autorização específica.

完成本阶段工作或发现其他阶段的待处理任务时，请告知

检测到待处理事项：<描述> — 操作：本阶段内解决

，并在属于当前范围的情况下予以解决。当需要移交职责时，请告知

自动流转：$specsfy-03-specify → $<目标> — 原因： <原因> — 预期结果：<结果>

，并立即加载目标skill，无需请求确认或重复命令。请在同一场对话中继续。对本阶段进行必要修正后，请告知

自动重启：$<目标> → $specsfy-03-specify — 已解决待处理事项： <结果>

，并立即重启本阶段。每次移交后重新评估状态，避免循环。移交无需请求确认；敏感操作仍需特定授权。

Preparar

准备工作

Resolva a raiz do projeto pelo diretório informado pelo usuário ou por
```
Path.cwd()
```
quando ele não informar outro. Não procure nem promova o destino para uma raiz Git.
Ao criar uma spec, resolva o diretório desta skill e execute antes de escrever:

bash

node <diretório-da-skill>/scripts/iniciar_spec.mjs \
  --title "<nome da especificação>" [--slug <slug>] [--root <raiz>]

Use o caminho absoluto impresso pelo script. Ele aloca o próximo ID local, prefere
```
.specsfy/templates/custom/Spec.md
```
, recorre ao template gerenciado
```
.specsfy/templates/Spec.md
```
e cria somente
```
specs/draft/<NNNN>-<slug>/spec.md
```
; nunca renomeie o arquivo para incluir o ID. Ao desenvolver este repositório, o script usa
```
skills/templates/Spec.md
```
como fallback; no projeto consumidor, template ausente exige
```
specsfy install
```
.
Ao atualizar, use o caminho da spec existente fornecido ou descoberto sob a raiz atual; não execute o inicializador novamente.
Leia a captura de origem em
```
specs/inbox/
```
, o item de backlog, o brief da refinamento do backlog, o pedido atual, a spec nesse caminho, seu
```
research/
```
e arquivos do repositório que revelem restrições reais.
Se não houver informação suficiente para identificar problema, ator e resultado, anuncie a pendência e carregue
```
$specsfy-02-backlog
```
para executar o ciclo. Retome esta skill ao final do ciclo e use o brief completo ou parcial produzido.
Leia
```
references/mcr-10.md
```
ao receber relato, história, transcrição ou especificação a refinar.

根据用户指定的目录或默认使用
```
Path.cwd()
```
确定项目根目录。请勿查找或将目标目录设为Git根目录。
创建规范文档时，确定本skill的目录并在编写前执行：

bash

node <skill目录>/scripts/iniciar_spec.mjs \
  --title "<规范文档名称>" [--slug <slug>] [--root <根目录>]

使用脚本输出的绝对路径。脚本会分配下一个本地ID，优先使用
```
.specsfy/templates/custom/Spec.md
```
模板，若无则使用官方维护的
```
.specsfy/templates/Spec.md
```
模板，仅创建
```
specs/draft/<NNNN>-<slug>/spec.md
```
；切勿重命名文件以包含ID。开发本仓库时，脚本会使用
```
skills/templates/Spec.md
```
作为备选；在消费项目中，若缺少模板则需执行
```
specsfy install
```
。
更新规范文档时，使用用户提供的或在当前根目录下发现的现有规范文档路径；请勿再次执行初始化脚本。
读取
```
specs/inbox/
```
中的原始收集内容、待办事项条目、待办事项梳理简报、当前请求、该路径下的规范文档、其
```
research/
```
目录以及仓库中揭示实际限制的文件。
若信息不足以识别问题、角色和结果，请告知待处理事项并加载
```
$specsfy-02-backlog
```
执行循环。循环结束后重启本skill，并使用生成的完整或部分简报。
在接收待梳理的报告、用户故事、转录内容或规范文档时，请阅读
```
references/mcr-10.md
```
。

Aplicar o MCR-10

应用MCR-10标准

Preserve a formulação original e identifique finalidade, ator e resultado.
Analise termos ambíguos, equivalências terminológicas e derivações.
Use substância, quantidade, qualidade, relação, lugar, tempo, posição, posse, ação e afecção como lentes adaptativas, não como questionário.
Distinga cada declaração da pessoa de inferência, hipótese, decisão, conflito ou questão aberta produzida durante a análise.
Se existir lacuna aplicável, carregue
```
$specsfy-02-backlog
```
para executar o ciclo sem limite e retome esta skill ao final do ciclo. Se a pessoa escolher
```
avançar
```
, aplique a confirmação e o registro definidos no contrato central. Mantenha
```
Status: Draft
```
e
```
Definition Gate: Pending
```
quando restarem pontos aplicáveis; não promova a spec a
```
Defined
```
e não reabra o mesmo ciclo nesta retomada.
Recombine decisões em afirmações com sujeito, condição, ação e efeito observável; derive regras, histórias, Gherkin, limites e falhas.
Registre o resultado nas seções existentes de
```
spec.md
```
; não gere relatório MCR separado nem copie a referência para o pacote da fatia.

保留原始表述，并明确目的、角色和结果。
分析模糊术语、术语等价性及衍生含义。
以实体、数量、质量、关系、地点、时间、位置、所属、动作和影响作为适应性分析视角，而非问卷。
区分分析过程中产生的个人陈述、推论、假设、决策、冲突或开放性问题。
若存在适用的信息缺口，请加载
```
$specsfy-02-backlog
```
执行无限制循环，循环结束后重启本skill。若用户选择
```
继续
```
，请应用中心协议中定义的确认和记录规则。当仍有适用要点未解决时，请保持
```
状态：草稿（Draft）
```
和
```
定义闸门：待处理（Pending）
```
；请勿将规范文档升级为
```
已定义（Defined）
```
，且本次重启中请勿重复相同循环。
将决策重组为包含主语、条件、动作和可观察效果的陈述；推导规则、用户故事、Gherkin用例、边界和故障场景。
将结果记录在
```
spec.md
```
的现有章节中；请勿生成单独的MCR报告，也请勿将参考内容复制到功能包中。

Escrever

编写规范

Grave sempre em
```
<raiz>/specs/draft/<NNNN>-<slug>/spec.md
```
; o ID pertence ao diretório e o arquivo permanece exatamente
```
spec.md
```
.
Use
```
<raiz>/specs/draft/<NNNN>-<slug>/research/
```
somente para cópias, snapshots, contratos, schemas, exemplos e notas de proveniência realmente consultados. Não coloque código de produção, testes ou documentos normativos nesse diretório.
Ao pesquisar uma API ou documentação externa, armazene a evidência permitida em
```
research/
```
e indexe caminho, origem, versão/data, licença e impacto em
```
Artefatos de pesquisa armazenados
```
. Se licença ou termos impedirem a cópia, armazene metadados, URL, data de acesso, checksum/versão quando disponível e notas próprias, sem reproduzir conteúdo protegido.
Fora de
```
spec.md
```
e
```
research/
```
, não crie outra entrada no pacote da feature.
Ao promover
```
specs/backlog/<NNNN>-<slug>.md
```
, registre esse caminho na spec e atualize o item para
```
Status: Promoted
```
com o caminho da spec criada. O backlog preserva proveniência, mas deixa de governar o comportamento.
Ao derivar diretamente de
```
specs/inbox/<data-hora>-<slug>.md
```
, registre o caminho na spec e preserve a captura sem alteração. A análise inicial é contexto, não requisito confirmado.
Preserve o cabeçalho como uma tabela Markdown de duas colunas,
```
Campo
```
e
```
Valor
```
; não converta seus metadados em linhas
```
**Campo**: valor
```
.
Na tabela, declare
```
ID
```
como
```
SPEC-NNNN
```
e
```
Slug
```
como
```
<NNNN>-<slug>
```
e mantenha o slug igual ao diretório pai.
Preserve exatamente os três atos e as 18 seções do template resolvido:
```
.specsfy/templates/custom/Spec.md
```
quando existir ou
```
.specsfy/templates/Spec.md
```
caso contrário.
Substitua o conteúdo editorial restante do modelo durante o refinamento; não deixe seus exemplos ou placeholders na spec promovida para
```
Defined
```
.
Ao atualizar, edite o arquivo existente e preserve IDs e decisões ainda válidas.
Numere novos itens sem reutilizar ou renumerar IDs removidos:
- histórias:
```
US-001
```
  ;
- requisitos funcionais:
```
FR-001
```
  ;
- requisitos não funcionais:
```
NFR-001
```
  ;
- cenários de aceite:
```
AC-001
```
  ;
- decisões:
```
DEC-001
```
  .
Escreva cada requisito como comportamento verificável.
Escreva cada cenário com Given/When/Then e associe-o a pelo menos um requisito.
Defina no mínimo três
```
AC
```
distintos para a feature inteira e para cada
```
US
```
,
```
FR
```
e
```
NFR
```
. Conte cobertura somente quando o
```
AC
```
declarar o ID em
```
**Cobre**
```
; use caminho feliz, variação/regra crítica e falha ou limite material para ampliar contexto sem duplicar cenários equivalentes.
Inclua fora de escopo, erros, limites, segurança e acessibilidade quando relevantes.
Mantenha a seção técnica concreta o bastante para permitir tarefas com caminhos de arquivo, sem confundir escolha interna com resultado do usuário.
Registre defaults reversíveis em
```
Suposições
```
; peça esclarecimento apenas quando opções plausíveis mudarem materialmente escopo, dados, segurança, UX ou testes.
Não deixe placeholders, exemplos do template,
```
TBD
```
,
```
TODO
```
ou marcadores de clarificação em um arquivo marcado como
```
Defined
```
.
Mantenha tarefas futuras na seção
```
14. Tarefas
```
; skills posteriores atualizam a mesma seção, nunca outro arquivo.
Use os metadados
```
Definition Gate
```
,
```
Plan Gate
```
e
```
Delivery Gate
```
para expressar prontidão sem criar relatórios separados.

始终写入
```
<根目录>/specs/draft/<NNNN>-<slug>/spec.md
```
；ID属于目录，文件名始终保持为
```
spec.md
```
。
仅将实际查阅过的副本、快照、合同、Schema、示例和来源说明存放在
```
<根目录>/specs/draft/<NNNN>-<slug>/research/
```
中。请勿将生产代码、测试用例或规范性文档放入该目录。
调研外部API或文档时，请将允许的证据存储在
```
research/
```
中，并在
```
已存储的调研 artifacts
```
章节中索引路径、来源、版本/日期、许可证和影响。若许可证或条款禁止复制，请存储元数据、URL、访问日期、可用的校验和/版本及自有注释，请勿复制受保护的内容。
除
```
spec.md
```
和
```
research/
```
外，请勿在功能包中创建其他条目。
推进
```
specs/backlog/<NNNN>-<slug>.md
```
时，请在规范文档中记录该路径，并将条目更新为
```
状态：已推进（Promoted）
```
及创建的规范文档路径。待办事项保留来源信息，但不再管控行为。
直接从
```
specs/inbox/<日期-时间>-<slug>.md
```
衍生时，请在规范文档中记录该路径，并保留原始收集内容不做修改。初始分析仅作为上下文，而非已确认的需求。
保留标题为两列Markdown表格，列名为
```
字段
```
和
```
值
```
；请勿将元数据转换为
```
**字段**：值
```
格式的行。
在表格中，将
```
ID
```
声明为
```
SPEC-NNNN
```
，
```
Slug
```
声明为
```
<NNNN>-<slug>
```
，并保持slug与父目录一致。
严格保留解析后的模板中的三个部分和18个章节：优先使用
```
.specsfy/templates/custom/Spec.md
```
，若无则使用
```
.specsfy/templates/Spec.md
```
。
梳理过程中替换模板的剩余编辑内容；请勿将模板中的示例或占位符保留在升级为
```
已定义（Defined）
```
的规范文档中。
更新时，请编辑现有文件并保留仍有效的ID和决策。
为新条目编号时请勿重用或重新编号已删除的ID：
- 用户故事：
```
US-001
```
  ；
- 功能需求：
```
FR-001
```
  ；
- 非功能需求：
```
NFR-001
```
  ；
- 验收场景：
```
AC-001
```
  ；
- 决策：
```
DEC-001
```
  。
每条需求均需编写为可验证的行为描述。
每个场景均需使用Given/When/Then格式，并关联至少一条需求。
为整个功能及每个
```
US
```
、
```
FR
```
和
```
NFR
```
定义至少三个不同的
```
AC
```
。仅当
```
AC
```
在
```
**覆盖**
```
中声明ID时才算作覆盖；使用正常流程、关键规则/变体、故障或实质性边界来扩展上下文，避免重复等效场景。
相关时请包含范围外内容、错误、边界、安全和可访问性说明。
技术章节需足够具体，以便提供带文件路径的任务，但请勿将内部选择与用户结果混淆。
将可逆默认值记录在
```
假设
```
章节中；仅当合理选项会实质性改变范围、数据、安全、UX或测试时才请求澄清。
标记为
```
已定义（Defined）
```
的文件中请勿保留占位符、模板示例、
```
TBD
```
、
```
TODO
```
或澄清标记。
将未来任务保留在
```
14. 任务
```
章节中；后续skills将更新同一章节，请勿创建其他文件。

使用元数据

定义闸门（Definition Gate）

、

计划闸门（Plan Gate）

和

交付闸门（Delivery Gate）

来表达就绪状态，无需创建单独报告。

Respeitar specs já aprovadas

尊重已获批的规范文档

Se a spec já obteve

Definition Gate: Passed

e a pessoa pedir para adicionar, remover, corrigir ou mudar algo, anuncie a pendência e carregue automaticamente

$specsfy-update-spec

. Essa skill classifica o impacto, atualiza a fonte normativa e invalida somente os gates afetados. Retome esta skill apenas se a mudança retornar a spec ao estado de definição inicial.

若规范文档已获得

定义闸门：通过（Passed）

，且用户要求添加、删除、修正或修改内容，请告知待处理事项并自动加载

$specsfy-update-spec

。该skill会分类影响、更新规范性文件，并仅使受影响的闸门失效。仅当修改将规范文档恢复到初始定义状态时，才重启本skill。

Preservar rastreabilidade

保留可追溯性

Para cada

FR

NFR

, aponte no mínimo três cenários

AC

e mantenha o método de verificação explícito dos NFRs. Para cada história, identifique os requisitos que entregam seu valor e ao menos três

AC

. Use os mesmos IDs mais tarde nos casos TDD e na seção 14.

对于每个

FR

和

NFR

，需关联至少三个

AC

场景，并明确NFR的验证方法。对于每个用户故事，需识别交付其价值的需求及至少三个

AC

。后续在TDD用例和第14章节中使用相同的ID。

Controlar research

管控调研内容

Antes do planejamento, carregue somente as evidências indexadas e valide claims com:

bash

node .agents/skills/specsfy-03-specify/scripts/load_research.mjs \
  specs/<estado>/<NNNN>-<slug>/spec.md

Para pesquisa material, registre
```
R-ID
```
, criticalidade, claim, veredito, confiança, evidência local e orçamento na seção 2. Claim
```
critical
```
ainda não verificado bloqueia o handoff; claim refutado permanece registrado. IDs devem ser únicos, gasto não pode superar o limite e a âncora Markdown citada precisa existir no arquivo local.

规划前仅加载已索引的证据，并通过以下命令验证声明：

bash

node .agents/skills/specsfy-03-specify/scripts/load_research.mjs \
  specs/<状态>/<NNNN>-<slug>/spec.md

对于重要调研，请在第2章节中记录
```
R-ID
```
、关键程度、声明、裁决、可信度、本地证据和预算。未验证的
```
critical
```
级声明会阻止移交；已被反驳的声明仍需保留记录。ID必须唯一，开销不得超过限制，引用的Markdown锚点需存在于本地文件中。

Autovalidar

自我验证

Enquanto o arquivo estiver em Draft, execute a validação estrutural intermediária:

bash

node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md --allow-draft

Corrija falhas estruturais em no máximo três ciclos. A skill

specsfy-04-validate

faz a revisão semântica, registra o resultado na seção 13 e promove

Definition Gate: Passed

Status: Defined

. Até lá, mantenha

Status: Draft

Definition Gate: Pending

e relate decisões bloqueantes.

当文件处于草稿状态时，执行中间结构验证：

bash

node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs specs/<状态>/<NNNN>-<slug>/spec.md --allow-draft

最多用三个周期修正结构错误。

specsfy-04-validate

skill会进行语义审核，将结果记录在第13章节，并将

定义闸门：通过（Passed）

和

状态：已定义（Defined）

升级。在此之前，请保持

状态：草稿（Draft）

、

定义闸门：待处理（Pending）

并报告阻塞性决策。

Relatar

报告

Informe:

caminho
```
specs/<estado>/<NNNN>-<slug>/spec.md
```
;
caminhos de research armazenados ou a declaração de que não houve fonte externa;
status;
contagem de
```
US
```
,
```
FR
```
,
```
NFR
```
e
```
AC
```
;
suposições relevantes;
transição automática para
```
$specsfy-04-validate
```
, com motivo e resultado esperado.

请告知：

规范文档路径
```
specs/<状态>/<NNNN>-<slug>/spec.md
```
；
已存储的调研路径或无外部来源的声明；
状态；
```
US
```
、
```
FR
```
、
```
NFR
```
和
```
AC
```
的数量；
相关假设；
自动流转至
```
$specsfy-04-validate
```
的信息，包括原因和预期结果。

Especialistas sob demanda

按需调用专家

Leia references/specialists.md quando requisitos, NFRs, dados ou decisões técnicas exigirem conhecimento especializado. Registre o requisito na spec e proponha carregar o especialista. Se ele não estiver instalado, peça autorização específica antes de instalar.

当需求、NFR、数据或技术决策需要专业知识时，请阅读references/specialists.md。在规范文档中记录需求，并提议加载专家skill。若未安装该skill，请在安装前请求特定授权。