escribir-contrato

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Escribir contrato

编写契约

Goal

目标

Producir el único documento que leen el TESTER y el DEV: lo que la HU tiene que hacer vista desde afuera, con la precisión suficiente para que dos agentes que no se ven lleguen al mismo resultado. El contrato fija lo observable; lo interno queda libre para el DEV.

Esta skill no construye nada. Escribe, pregunta y se detiene.

产出 TESTER 和 DEV 唯一会阅读的文档：从外部视角描述 HU 必须做什么，其精确程度应确保两个互不沟通的 Agent 能够得到相同结果。契约固定可观测行为；内部实现则由 DEV 自由决定。

此 skill 不构建任何内容。 它只负责编写、提问并停止。

Input

输入

La HU — desde Jira vía MCP si está conectado, o el archivo/enlace indicado. Si tiene puntos abiertos sin resolver, detenerse: se escalan antes de escribir el contrato.
```
TECH-DESIGN.md
```
— la sección y los criterios de aceptación que corresponden a esta HU.
```
adrs/
```
— solo los ADRs de historia de esta HU (y los transversales que condicionan su interfaz, ej. estilo de API).
```
AGENTS.md
```
— convenciones del proyecto.
Contratos anteriores en
```
contratos/
```
— para no contradecir nombres ya fijados.

HU — 如果已连接，则通过 MCP 从 Jira 获取；或使用指定的文件/链接。如果存在尚未解决的开放问题，则停止：在编写契约之前先将其升级处理。
```
TECH-DESIGN.md
```
— 与此 HU 对应的章节和验收标准。
```
adrs/
```
— 仅使用此 HU 的故事 ADR，以及会影响其接口的横向 ADR，例如 API 风格。
```
AGENTS.md
```
— 项目约定。
```
contratos/
```
中的既有契约 — 避免与已经固定的名称发生冲突。

Workflow

工作流

Armar el paquete de contexto: HU + ADRs que aplican + sección del TDD. Nada más. Listar qué entró al paquete y por qué.
Identificar la interfaz observable por la que se usa la funcionalidad (una ruta HTTP, una pantalla, un comando, un evento…). El contrato se escribe sobre esa interfaz.
Por cada escenario Gherkin y cada criterio de aceptación del TDD, derivar los casos:
- entrada exacta (ruta, parámetros, formato);
- salida exacta por caso (status, datos, texto visible, efecto persistente);
- errores (qué entrada inválida produce qué respuesta).
Fijar los nombres que no se negocian: rutas, campos, mensajes visibles, formatos. Son los que el TESTER verificará textualmente.
Anotar el origen de cada línea (escenario Gherkin, criterio del TDD, ADR). Una línea sin origen es una decisión nueva: se marca
```
DECISIÓN PROPUESTA
```
y entra en la lista de preguntas para el humano. Nunca se presenta como si viniera de la HU.
Declarar qué queda fuera del contrato (todo lo interno: estructura, nombres de funciones, consultas) → libertad del DEV.

Guardar

contratos/CONTRATO-<HU>.md

con

assets/contrato-template.md

, versión

v1

Detenerse. Presentar el contrato y las preguntas al humano. No invocar a nadie.

组装上下文包： HU + 适用的 ADR + TDD 相关章节。不包含其他内容。列出哪些内容进入了上下文包，以及纳入的原因。
确定使用该功能的可观测接口（HTTP 路由、页面、命令、事件等）。契约围绕该接口编写。
针对每个 Gherkin 场景和 TDD 的每项验收标准推导出用例：
- 精确输入（路由、参数、格式）；
- 每个用例的精确输出（状态、数据、可见文本、持久化效果）；
- 错误（哪种无效输入会产生哪种响应）。
固定不可协商的名称： 路由、字段、可见消息和格式。这些内容将由 TESTER 进行文本核验。
标注每一行的来源（Gherkin 场景、TDD 标准、ADR）。任何没有来源的行都是一项 新决策：应标记为
```
DECISIÓN PROPUESTA
```
，并加入面向人工的问题列表。绝不能将其表述为来自 HU。
声明不属于契约的内容（所有内部实现：结构、函数名称、查询等）→ DEV 拥有实现自由。

保存

contratos/CONTRATO-<HU>.md

，使用

assets/contrato-template.md

模板，版本为

v1

。

停止。 向人工展示契约和问题。不得调用任何人。

Versionado

版本管理

Cuando durante el ciclo aparece un hueco (lo reporta el TESTER, el DEV o el veredicto):

se formula la pregunta al humano;
con la respuesta, se edita el contrato, se sube la versión (
```
v2
```
,
```
v3
```
…) y se agrega una fila al changelog (qué cambió, por qué, quién lo aprobó);
el LEAD avisa a TESTER y DEV de la nueva versión.

当执行周期中出现缺口时（由 TESTER、DEV 或验证结果报告）：

向人工提出问题；
收到答复后，编辑契约、升级版本（
```
v2
```
、
```
v3
```
……），并向 changelog 添加一行记录（更改了什么、为什么更改、由谁批准）；
LEAD 将新版本通知给 TESTER 和 DEV。

Constraints

约束

No se completa con suposiciones lo que la HU no dice: se pregunta.
No se describe implementación interna en el contrato.
No se contradice un nombre fijado en un contrato anterior sin decirlo explícitamente.
No se publica nada.

HU 未说明的内容不得通过假设补全：必须提问。
契约中不得描述内部实现。
不得与既有契约中已经固定的名称冲突，除非明确说明冲突。
不得发布任何内容。