setup-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: setup-project

Você configura, uma vez por repositório, os contratos que o resto do pipeline lê em runtime. Sem eles as outras skills param com erro — de propósito, para falhar alto em vez de adivinhar.

O output são os arquivos abaixo. Os três primeiros são o contrato que o resto do pipeline lê; o restante é o que faz o PR chegar decidível sem abrir o diff.

arquivo de instruções — três seções curtas:
```
## Issue Tracker
```
,
```
## Commands
```
,
```
## Fluxo
```
docs/agents/issue-tracker.md
— o detalhe pesado (comandos do tracker, tabela de labels)

docs/agents/architecture.md
— o mapa do código que

to-spec

to-tickets

implementer

e revisor leem (Parte 5)

docs/agents/review-rules-projeto.md
— critérios deste projeto e os caminhos extras de risco (Parte 6). Sempre criado.
.github/pull_request_template.md
— as seções Como foi testado, Risco e Como desfazer (Parte 7)

.github/workflows/ci.yml
— os gates de

## Commands

e, em projeto Node,

npm audit

(Parte 7)

Qual é o arquivo de instruções:

AGENTS.md

na raiz — o formato que a maioria das ferramentas de agente lê. Se o repo já tem

CLAUDE.md

e não tem

AGENTS.md

, use o

CLAUDE.md

existente em vez de criar um segundo arquivo.

Ferramenta que não lê
AGENTS.md
sozinha: crie o ponteiro — não basta avisar, porque sem ele a seção

## Fluxo

nunca entra no contexto. Descubra a ferramenta pela pasta onde as skills do pipeline foram instaladas. Skills em

.claude/skills/

→ é o Claude Code: crie

CLAUDE.md

na raiz com a linha

@AGENTS.md

, ou acrescente essa linha ao

CLAUDE.md

existente se ela faltar. Outra ferramenta com arquivo próprio → a mesma ideia, na convenção dela. Informe o que criou.

O arquivo de instruções entra no contexto de toda conversa — mantê-lo enxuto importa. O detalhe fica isolado num arquivo que só quem precisa vai ler.

Sete partes, nesta ordem.

O que você pergunta, e o que não. O dono do repositório pode não ler código. Pergunte só decisões de processo: qual tracker, qual vocabulário de labels, qual o limiar do

## Fluxo

. O que é técnico — comandos do tracker, script

clean

, mapa do código, critérios de review — você decide, grava e informa em uma linha, sem pedir aprovação de rascunho.

你每个仓库只需配置一次 pipeline 在运行时读取的契约。缺少这些契约，其他 skills 会故意报错——宁可明确失败，也不要猜测。

输出为下列文件。前三个是 pipeline 其余部分在运行时读取的契约；其余文件用于让 PR 无需打开 diff 也能做出决策。

指令文件——三个简短章节：
```
## Issue Tracker
```
、
```
## Commands
```
、
```
## Fluxo
```
docs/agents/issue-tracker.md
——详细配置（tracker 命令、labels 表）
docs/agents/architecture.md
——供
```
to-spec
```
、
```
to-tickets
```
、
```
implementer
```
和 reviewer 读取的代码地图（第 5 部分）
docs/agents/review-rules-projeto.md
——本项目的标准以及额外的风险路径（第 6 部分）。始终创建。
.github/pull_request_template.md
——包含“如何测试”“风险”和“如何回滚”的章节（第 7 部分）
.github/workflows/ci.yml
——包含
```
## Commands
```
中的 gates；对于 Node 项目，还包含
```
npm audit
```
（第 7 部分）

**哪个是指令文件：**根目录下的

AGENTS.md

——这是大多数 Agent 工具都会读取的格式。如果仓库已有

CLAUDE.md

但没有

AGENTS.md

，则使用现有的

CLAUDE.md

，不要创建第二个文件。

**无法自行读取

AGENTS.md

的工具：**创建指针——仅作提醒不够，因为没有指针，

## Fluxo

章节就永远无法进入上下文。通过 pipeline 的 skills 安装目录判断所用工具。如果 skills 位于

.claude/skills/

，则说明是 Claude Code：在根目录创建

CLAUDE.md

并写入

@AGENTS.md

这一行；如果已有

CLAUDE.md

但缺少该行，则追加进去。对于使用自有文件的其他工具，也采用相同思路，但遵循其自身约定。说明你创建了什么。

指令文件会进入每次对话的上下文，因此保持精简很重要。详细内容应隔离到单独文件中，只让确实需要的人读取。

以下七个部分必须按此顺序处理。

**该询问什么，不该询问什么。**仓库所有者可能不读代码。只询问流程决策：使用哪个 tracker、使用什么 labels 词汇表、

## Fluxo

的阈值是什么。技术事项——tracker 命令、

clean

script、代码地图、review 标准——由你决定、记录并用一行说明，无需请求用户批准草稿。

Portabilidade dos comandos — regra dura

命令可移植性——硬性规则

O pipeline roda em Bash e em PowerShell. Todo comando que você documentar — e todo comando que outra skill lê daqui — tem que rodar nos dois:

Nada de composição de shell:
```
||
```
,
```
&&
```
,
```
$(...)
```
,
```
2>/dev/null
```
, pipe,
```
VAR=...
```
. Quando um passo depende do resultado do anterior, documente como passos separados: "rode X, leia a saída, use-a em Y".
Corpo de issue, comentário e PR vai por
--body-file <arquivo>
, nunca
```
--body "..."
```
. Markdown tem crase, aspas,
```
$
```
,
```
!
```
e
```
&
```
, e escapar isso inline quebra de jeitos diferentes em cada shell. O arquivo fica em
```
.scratch/
```
.

pipeline 同时运行于 Bash 和 PowerShell。你记录的所有命令，以及其他 skills 从此处读取的所有命令，都必须能在两者中运行：

禁止 shell 组合：
```
||
```
、
```
&&
```
、
```
$(...)
```
、
```
2>/dev/null
```
、pipe、
```
VAR=...
```
。当一个步骤依赖前一步的结果时，应将其记录为独立步骤：“运行 X，读取输出，在 Y 中使用它”。
Issue、评论和 PR 正文必须通过
--body-file <arquivo>
传入，绝不能使用
```
--body "..."
```
。Markdown 中可能包含反引号、引号、
```
$
```
、
```
!
```
和
```
&
```
，内联转义这些字符会在不同 shell 中以不同方式破坏命令。文件放在
```
.scratch/
```
中。

O modelo de artefatos

产物模型

Independente do tracker, a hierarquia é sempre a mesma — muda só como ela é materializada:

Conceito	Gerado por	GitHub / Linear	Markdown local
Spec — um objetivo inteiro	`to-spec`	Issue	Arquivo no nível da feature
Ticket — uma fatia vertical da spec	`to-tickets`	Sub-issue daquela issue	Arquivo em `issues/` dentro da pasta da feature

Com tracker real, a issue é canônica.

to-spec

to-tickets

também deixam uma cópia de trabalho em

.scratch/<slug>/

, que é ignorada pelo git — serve para organizar e reler a unidade em curso sem uma chamada de rede a cada leitura. Cópia de trabalho não é fonte de verdade: divergiu, vale a issue, e

.scratch/

pode ser apagado a qualquer momento sem perda.

Com markdown local, o arquivo em

.scratch/

é a própria fonte de verdade, e nada é publicado.

Em nenhum dos dois modos existe uma segunda cópia versionada no repo. Documentação de spec commitada em

docs/

diverge da issue e depois ninguém sabe qual vale.

无论使用哪种 tracker，层级结构始终相同，区别仅在于如何具体实现：

概念	生成方	GitHub / Linear	本地 Markdown
Spec——一个完整目标	`to-spec`	Issue	feature 目录下的文件
Ticket——spec 的一段纵向切片	`to-tickets`	该 Issue 的 Sub-issue	feature 目录内 `issues/` 下的文件

使用真实 tracker 时，Issue 是唯一事实来源。

to-spec

和

to-tickets

还会在被 git 忽略的

.scratch/<slug>/

中留下工作副本，用于组织并重新读取当前工作单元，而无需每次读取都发起网络请求。工作副本不是事实来源：如果发生分歧，以 Issue 为准；

.scratch/

可随时删除，不会造成损失。

使用本地 Markdown 时，

.scratch/

中的文件本身就是唯一事实来源，不会发布任何内容。

无论采用哪种模式，仓库中都不会存在第二份受版本控制的副本。将 spec 文档提交到

docs/

后，一旦它与 Issue 分歧，后续就没人能判断哪一份有效。

O que o arquivo de instruções guarda — regra canônica

指令文件保存什么——规范规则

O arquivo de instruções não guarda fato que envelhece.

O critério não é o tamanho da seção — é se aquela informação envelhece sozinha. Decisão estável fica; fato que muda a cada PR vira ponteiro.

Tipo de informação	Envelhece?	Onde mora
Como o pipeline roda neste repo ( `## Issue Tracker` , `## Commands` , `## Fluxo` )	não	arquivo de instruções
Como o deploy funciona; o resumo do design system que precede toda tarefa de UI	não	arquivo de instruções, curto, com ponteiro para o documento completo
O que o produto é, e quais são os requisitos	sim	`docs/prd.md` — o arquivo de instruções aponta
Estado atual do código: módulos, seams, invariantes	sim	`docs/agents/architecture.md` — o arquivo de instruções aponta
O que já foi construído, quantas telas existem, o que falta	sim	não mora em lugar nenhum: é o histórico do git e o quadro de issues

Por que a regra existe: fato que muda a cada PR ("este repositório ainda não tem código", "o produto é uma landing de guias grátis") apodrece sozinho, e o arquivo de instruções não tem dono que o mantenha. Misturado com decisão estável, ele acaba descrevendo um produto que não existe mais e contradizendo o PRD real.

Ao gravar ou reconfigurar: se você encontrar uma seção

## Status

## Product

ou equivalente descrevendo o que já existe no código, substitua por um ponteiro e mova o conteúdo para o documento que tem dono.

指令文件不保存会自行过时的信息。

判断标准不是章节长度，而是该信息是否会自行变旧。稳定的决策可以保留；每次 PR 都会变化的事实则应改为指针。

信息类型	会过时吗？	存放位置
pipeline 如何在此仓库中运行（ `## Issue Tracker` 、 `## Commands` 、 `## Fluxo` ）	否	指令文件
deploy 如何运行；每项 UI 任务之前都要阅读的 design system 摘要	否	指令文件，简要记录并指向完整文档
产品是什么，以及有哪些需求	是	`docs/prd.md` ——由指令文件指向
代码当前状态：模块、seams、不变量	是	`docs/agents/architecture.md` ——由指令文件指向
已经构建了什么、有多少页面、还缺少什么	是	不存放在任何固定位置：这些信息属于 git 历史和 Issue 看板

**设置该规则的原因：**每次 PR 都会变化的事实（例如“这个仓库目前还没有代码”“产品是一个免费指南的 landing page”）会自行失效，而指令文件没有专人维护。将这些事实与稳定决策混在一起，最终只会描述一个已经不存在的产品，并与真实 PRD 冲突。

写入或重新配置时，如果发现

## Status

、

## Product

或同类章节正在描述代码中已经存在的内容，请将其替换为指针，并把内容移动到有明确维护者的文档中。

Parte 1 — Issue tracker

第 1 部分——Issue Tracker

1. Explorar antes de perguntar

1. 先探索，再询问

Antes de fazer qualquer pergunta, levante o estado atual do repositório:

```
git remote -v
```
— há remote? Aponta para GitHub, GitLab, ou outro host?
```
AGENTS.md
```
ou
```
CLAUDE.md
```
na raiz — já existe uma seção
```
## Issue Tracker
```
? Se sim, essa é uma reconfiguração, não um setup do zero.
```
docs/agents/issue-tracker.md
```
— já existe, mesmo que a seção no arquivo de instruções tenha sido apagada? Sinal de configuração anterior a recuperar ou substituir.
```
.scratch/
```
— já existem pastas de feature aqui? Sinal de que uma convenção de markdown local já está em uso, mesmo sem registro formal.

进行任何询问之前，先查明仓库当前状态：

```
git remote -v
```
——是否配置了 remote？是否指向 GitHub、GitLab 或其他 host？
根目录中的
```
AGENTS.md
```
或
```
CLAUDE.md
```
——是否已经存在
```
## Issue Tracker
```
章节？如果存在，说明这是重新配置，而不是从零 setup。
```
docs/agents/issue-tracker.md
```
——即使指令文件中的章节已被删除，该文件是否仍然存在？这是需要恢复或替换的旧配置线索。
```
.scratch/
```
——这里是否已经存在 feature 目录？这说明即使没有正式记录，也已经在使用本地 Markdown 约定。

2. Propor um default inferido, não abrir um menu em branco

2. 提出推断出的默认值，不要打开空白菜单

Com base na exploração, lidere com a recomendação e deixe o usuário aceitar em uma palavra ou trocar:

Se o remote aponta para GitHub → proponha GitHub Issues
Se não há remote configurado, ou
```
.scratch/
```
já está em uso → proponha Markdown local
Caso contrário, apresente as opções sem assumir: GitHub Issues (via
```
gh
```
), Markdown local, Linear (via MCP), Jira, Outro / customizado

Se já existir configuração anterior (seção no arquivo de instruções ou

docs/agents/issue-tracker.md

), pergunte primeiro se é reconfiguração ou se deve manter a atual — não pule direto para a proposta de default.

根据探索结果主动给出推荐，让用户用一个词接受，或进行替换：

如果 remote 指向 GitHub，推荐 GitHub Issues
如果没有配置 remote，或者已经在使用
```
.scratch/
```
，推荐 本地 Markdown
否则，在不预设的情况下给出选项：GitHub Issues（通过
```
gh
```
）、本地 Markdown、Linear（通过 MCP）、Jira、其他／自定义

如果已有旧配置（指令文件中的章节或

docs/agents/issue-tracker.md

），先询问这是重新配置，还是应该保持当前配置；不要直接跳到默认推荐。

3. Configurar de acordo com o tracker escolhido

3. 根据所选 tracker 进行配置

GitHub Issues

Confirme autenticação:
```
gh auth status
```
Confirme remote:
```
git remote -v
```
. Se não houver remote, pare e instrua a rodar o Bootstrap do
```
to-prd
```
primeiro.
A spec vira uma issue; cada ticket vira uma sub-issue daquela issue, usando a relação nativa do GitHub.

⚠️ O
gh
não tem comando nativo de sub-issue (verificado na 2.88.1: nem
gh issue create
nem
gh issue edit
têm flag de parent). O vínculo é feito pela API GraphQL, com a mutation
addSubIssue
. Documente os comandos abaixo literalmente — sem eles,
to-tickets
publica issues soltas e o
implement
não acha os tickets da spec.

Comandos a documentar (com placeholders

{...}

bash

undefined

确认身份认证：
```
gh auth status
```
确认 remote：
```
git remote -v
```
。如果没有 remote，请停止并指导用户先运行 to-prd 的 Bootstrap。
Spec 变成一个 Issue；每个 Ticket 变成该 Issue 的 Sub-issue，使用 GitHub 的原生关系。

⚠️
gh
没有原生的 sub-issue 命令（已在 2.88.1 中确认：
gh issue create
和
gh issue edit
都没有 parent flag）。关联通过 GraphQL API 的
addSubIssue
mutation 完成。请逐字记录以下命令——缺少它们，
to-tickets
就会发布彼此独立的 Issues，而
implement
将找不到 spec 对应的 tickets。

需要记录的命令（使用

{...}

作为占位符）：

bash

undefined

Criar spec — devolve a URL da issue no stdout

gh issue create --title "{title}" --body-file {arquivo} --label "{label}"

Node ID da spec (necessário para vincular sub-issues)

gh issue view {spec-number} --json id -q .id

Criar ticket — devolve a URL do ticket no stdout; leia-a e use no passo seguinte

gh issue create --title "{title}" --body-file {arquivo} --label "{label}"

Vincular o ticket como sub-issue da spec

gh api graphql -f query=' mutation($parent:ID!, $url:String!) { addSubIssue(input:{issueId:$parent, subIssueUrl:$url}) { clientMutationId } }' -f parent={spec-node-id} -f url={ticket-url}

Listar os tickets de uma spec (com o corpo, de onde sai o ## Blocked by)

gh api graphql -f query=' query($owner:String!, $repo:String!, $num:Int!) { repository(owner:$owner, name:$repo) { issue(number:$num) { subIssues(first:50) { nodes { number title state body labels(first:10){ nodes{ name } } } } } } }' -f owner={owner} -f repo={repo} -F num={spec-number}

Ver o pai (a spec) de um ticket — sem pai, parent vem null

gh api graphql -f query=' query($owner:String!, $repo:String!, $num:Int!) { repository(owner:$owner, name:$repo) { issue(number:$num) { parent { number title } } } }' -f owner={owner} -f repo={repo} -F num={ticket-number}

Listar por label / ver / editar labels

gh issue list --label "{label}" gh issue view {number} gh issue edit {number} --add-label "{label}" --remove-label "{label}"

Fechar (ticket aprovado)

gh issue close {number} --reason completed


`addSubIssue` aceita `subIssueUrl` no lugar do node ID do filho — por isso a URL que o `gh issue create` devolve serve direto, sem uma segunda consulta. O agente a lê do stdout e a passa no comando seguinte; não há variável de shell no meio.

**Bloqueio entre tickets não usa relação nativa**, mesmo o GitHub tendo uma. A fonte única é a seção `## Blocked by` do corpo de cada ticket: funciona igual em qualquer tracker, e uma fonte só não diverge. Por isso a query de tickets traz o `body`.

gh issue close {number} --reason completed


`addSubIssue` 接受 `subIssueUrl`，因此可以直接使用 `gh issue create` 返回的 URL，无需再次查询。Agent 读取 stdout，并在下一条命令中传入；中间不使用 shell 变量。

**Tickets 之间的阻塞关系不使用原生关系**，即使 GitHub 提供了这种能力。唯一来源是每个 Ticket 正文中的 `## Blocked by` 章节：它适用于所有 tracker，而且单一来源不会产生分歧。因此，查询 tickets 时必须获取 `body`。

Markdown local (

.scratch/

)

本地 Markdown（

.scratch/

）

Uma pasta por feature:
```
.scratch/{feature-slug}/
```
Spec — no nível da feature:
```
.scratch/{feature-slug}/spec.md
```
. Corpo conforme o
```
<spec-template>
```
que vive dentro da skill
```
to-spec
```
.
Tickets — um nível abaixo, em
```
issues/
```
:
```
.scratch/{feature-slug}/issues/{NN}-{slug}.md
```
, numerados a partir de
```
01
```
em ordem de dependência (bloqueadores primeiro). Corpo conforme o
```
<local-ticket-template>
```
que vive dentro da skill
```
to-tickets
```
.
O nível
```
issues/
```
existe para separar tickets da spec, não para agrupar — o agrupamento já é a pasta da feature.
Adicione
```
.scratch/
```
ao
```
.gitignore
```
se ainda não estiver. É espaço de trabalho da sessão, não documentação do projeto.
Comandos a documentar (usando as ferramentas do agente em vez de shell):
- Criar spec: escrever
```
.scratch/{feature-slug}/spec.md
```
- Criar ticket: escrever
```
.scratch/{feature-slug}/issues/{NN}-{slug}.md
```
- Listar: buscar
```
\*\*Status:\*\* {label}
```
  em
```
.scratch/*/issues/*.md
```
- Ver: ler o arquivo correspondente
- Editar label: editar o campo
```
**Status:**
```
  no corpo do arquivo
- Fechar: editar o campo
```
**Status:**
```
  para
```
closed
```
- Vincular ticket à spec: gravar o ticket em
```
issues/
```
  dentro da pasta da spec
- Listar tickets da spec: ler
```
.scratch/{feature-slug}/issues/*.md
```
- Ver pai: a spec é
```
.scratch/{feature-slug}/spec.md
```
  , na mesma pasta do ticket

⚠️ Sem orquestração AFK neste modo. A skill
implement
gerencia estado por labels num tracker real; de
.scratch/
ela só lê a cópia de trabalho da SPEC, nunca o
**Status:**
dos tickets. Markdown local serve para trabalho conduzido por você, consumido na própria sessão. Avise o usuário disso ao confirmar a escolha.

每个 feature 一个目录：
```
.scratch/{feature-slug}/
```
Spec——位于 feature 层级：
```
.scratch/{feature-slug}/spec.md
```
。正文遵循
```
to-spec
```
skill 内的
```
<spec-template>
```
。
Tickets——位于下一级
```
issues/
```
中：
```
.scratch/{feature-slug}/issues/{NN}-{slug}.md
```
，从
```
01
```
开始编号，并按依赖顺序排列（阻塞项在前）。正文遵循
```
to-tickets
```
skill 内的
```
<local-ticket-template>
```
。
```
issues/
```
层级用于将 Tickets 与 Spec 区分开，而不是用于分组；分组已经由 feature 目录完成。
如果
```
.gitignore
```
中尚未包含
```
.scratch/
```
，则添加。该目录是会话工作空间，不是项目文档。
需要记录的命令（使用 Agent 工具而非 shell）：
- 创建 Spec：写入
```
.scratch/{feature-slug}/spec.md
```
- 创建 Ticket：写入
```
.scratch/{feature-slug}/issues/{NN}-{slug}.md
```
- 列出：在
```
.scratch/*/issues/*.md
```
  中查找
```
\*\*Status:\*\* {label}
```
- 查看：读取对应文件
- 编辑 label：编辑文件正文中的
```
**Status:**
```
  字段
- 关闭：将
```
**Status:**
```
  字段编辑为
```
closed
```
- 将 Ticket 关联到 Spec：把 Ticket 写入 Spec 所在目录的
```
issues/
```
  中
- 列出 Spec 的 Tickets：读取
```
.scratch/{feature-slug}/issues/*.md
```
- 查看父项：Spec 是同一目录中的
```
.scratch/{feature-slug}/spec.md
```

⚠️ 此模式下没有 AFK 编排。
implement
skill 在真实 tracker 中通过 labels 管理状态；对于
.scratch/
，它只读取 SPEC 的工作副本，绝不读取 Tickets 的
**Status:**
。本地 Markdown 用于由你引导的工作，并在当前会话中消费。确认选择时，请向用户说明这一点。

Linear

Confirme que o MCP do Linear está conectado (liste workspaces/times disponíveis para o usuário escolher).
Registre: workspace, team key, e os comandos/tools MCP usados para criar e listar issues, vincular um ticket como sub-issue da spec, listar os tickets de uma spec e ver o pai de um ticket.

确认 Linear 的 MCP 已连接（列出可用 workspaces/times，供用户选择）。
记录：workspace、team key，以及用于创建和列出 Issues、将 Ticket 关联为 Spec 的 Sub-issue、列出 Spec 的 Tickets、查看 Ticket 父项的 MCP 命令／工具。

Jira

Peça: base URL, project key, e método de autenticação já configurado (MCP ou API token).
Registre os comandos/tools equivalentes a criar, listar, ver, editar labels, fechar, vincular ticket à spec, listar os tickets de uma spec e ver o pai de um ticket.

询问：base URL、project key，以及已配置的认证方式（MCP 或 API token）。
记录等效命令／工具：创建、列出、查看、编辑 labels、关闭、将 Ticket 关联到 Spec、列出 Spec 的 Tickets，以及查看 Ticket 的父项。

Outro / customizado

其他／自定义

Descubra os comandos equivalentes a criar, listar, ver, editar labels, fechar, vincular ticket à spec, listar os tickets de uma spec e ver o pai de um ticket. Pergunte ao usuário só o que não der para descobrir (ex: qual sistema, onde está a credencial).

找出等效命令：创建、列出、查看、编辑 labels、关闭、将 Ticket 关联到 Spec、列出 Spec 的 Tickets，以及查看 Ticket 的父项。只询问无法自行发现的信息，例如使用什么系统、凭据存放在哪里。

4. Definir o vocabulário de labels de triagem

4. 定义分诊 labels 词汇表

Vocabulário padrão sugerido — apresente ao usuário para confirmação ou ajuste, não grave sem aprovação:

Label	Significado
`ready-for-agent`	Pronta para um agente autônomo (AFK) implementar sem supervisão
`ready-for-human`	Bloqueada — aguardando decisão ou ação humana
`needs-triage`	Ainda não avaliada por um maintainer
`in-progress`	Agente no loop — implementando ou em review
`in-review`	Aprovada pelo revisor, aguardando merge (só SPEC ou issue sem tickets)

ready-for-agent

é obrigatória — é a label que

to-spec

to-tickets

aplicam ao publicar, e é por ela que o

implement

encontra trabalho. As demais podem ser removidas, renomeadas, ou o usuário pode adicionar outras (ex:

wontfix

para issues rejeitadas,

needs-info

para issues que precisam de mais contexto antes de triar).

Duas propriedades deste vocabulário não são negociáveis:

Os estados são exclusivos. Um card anda entre colunas, não acumula colunas. Toda transição remove o estado anterior. Adicionar sem remover deixa a issue em
```
ready-for-agent
```
+
```
in-progress
```
+
```
in-review
```
ao mesmo tempo, e a detecção de estado do
```
implement
```
— que pergunta "algo em
```
in-progress
```
?" — fica verdadeira para sempre.
Não existe label de "concluída". Issue fechada já é essa informação. Uma label
```
done
```
duplica o que o tracker já sabe e exige alguém para mantê-la — é mais um estado para desincronizar. Quem fecha depende do que a issue é: o ticket é fechado pelo
```
implement
```
assim que o revisor aprova, e é isso que faz o progresso de sub-issues da SPEC andar durante a execução; a SPEC (ou a issue sem tickets) fecha no merge, pelo
```
Closes #N
```
do corpo do PR. Por isso
```
in-review
```
só aparece em SPEC ou issue sem tickets: um ticket vai de
```
in-progress
```
direto para fechado. A review é parte do loop e não ganha label própria.

Este é o único vocabulário de labels do pipeline. Nenhum agente define o seu próprio —

implement

reviewer

leem daqui.

建议使用以下默认词汇表——呈现给用户确认或调整，不要未经批准就写入：

Label	含义
`ready-for-agent`	已准备好，可由自主 Agent（AFK）在无人监督的情况下实现
`ready-for-human`	已阻塞——正在等待人工决策或操作
`needs-triage`	maintainer 尚未评估
`in-progress`	Agent 正在循环——实现或 review 中
`in-review`	reviewer 已批准，正在等待 merge（仅适用于 SPEC 或没有 tickets 的 Issue）

ready-for-agent

是必需的——

to-spec

和

to-tickets

在发布时会应用该 label，

implement

也通过它查找工作。其他 labels 可以删除、重命名，用户也可以新增，例如为被拒绝的 Issues 添加

wontfix

，或为分诊前需要更多上下文的 Issues 添加

needs-info

。

该词汇表有两个不可协商的属性：

**状态互斥。**一个 card 在各状态之间移动，而不是同时累积多个状态。每次状态转换都必须移除上一个状态。如果只添加而不移除，Issue 就会同时处于
```
ready-for-agent
```
、
```
in-progress
```
和
```
in-review
```
，而
```
implement
```
的状态检测——即检查“是否存在
```
in-progress
```
”——将永远为真。
**不存在“已完成”label。**Issue 已关闭本身就代表完成。
```
done
```
label 会重复 tracker 已经知道的信息，还需要有人维护它——这只会增加一个可能失去同步的状态。由谁关闭取决于 Issue 的类型：Ticket 在 reviewer 批准后由
```
implement
```
立即关闭，这会推动执行期间 SPEC 的 Sub-issue 进度；SPEC（或没有 tickets 的 Issue）在 merge 时通过 PR 正文中的
```
Closes #N
```
关闭。因此，
```
in-review
```
只出现在 SPEC 或没有 tickets 的 Issue 上：Ticket 会从
```
in-progress
```
直接进入已关闭状态。Review 是循环的一部分，不使用单独的 label。

这是 pipeline 使用的唯一 labels 词汇表。任何 Agent 都不能定义自己的词汇表——

implement

和

reviewer

都从这里读取。

5. Criar as labels no tracker (quando aplicável)

5. 在 tracker 中创建 labels（适用时）

Para Markdown local, não há nada a criar aqui — o vocabulário do passo 4 já é a única fonte de verdade, aplicado diretamente no campo

**Status:**

do corpo de cada arquivo.

Para GitHub Issues, crie (idempotente,

--force

sobrescreve se já existir) as labels confirmadas no passo 4:

bash

gh label create "ready-for-agent" --color "0E8A16" --description "Pronta para agente autônomo implementar" --force
gh label create "ready-for-human" --color "D93F0B" --description "Bloqueada, aguardando ação humana" --force
gh label create "needs-triage" --color "FBCA04" --description "Ainda não avaliada por um maintainer" --force
gh label create "in-progress" --color "1D76DB" --description "Agente no loop: implementação e review" --force
gh label create "in-review" --color "5319E7" --description "Aprovada, aguardando merge (SPEC ou issue sem tickets)" --force

Ajuste os comandos ao vocabulário efetivamente confirmado — não à lista padrão, se o usuário customizou. Para Linear/Jira/outro, crie os labels/estados equivalentes pelas ferramentas daquele sistema, se o sistema exigir criação prévia.

对于本地 Markdown，无需在此创建任何内容——第 4 步的词汇表已经是唯一事实来源，直接应用于每个文件正文中的

**Status:**

字段。

对于 GitHub Issues，创建第 4 步中已确认的 labels（命令具有幂等性，

--force

会在 label 已存在时覆盖其配置）：

bash

gh label create "ready-for-agent" --color "0E8A16" --description "Pronta para agente autônomo implementar" --force
gh label create "ready-for-human" --color "D93F0B" --description "Bloqueada, aguardando ação humana" --force
gh label create "needs-triage" --color "FBCA04" --description "Ainda não avaliada por um maintainer" --force
gh label create "in-progress" --color "1D76DB" --description "Agente no loop: implementação e review" --force
gh label create "in-review" --color "5319E7" --description "Aprovada, aguardando merge (SPEC ou issue sem tickets)" --force

根据实际确认的词汇表调整命令，不要始终使用默认列表，即使用户进行了自定义。对于 Linear、Jira 或其他系统，如果系统要求预先创建 labels／状态，则通过对应系统的工具创建等效项。

6. Gravar

6. 写入

docs/agents/issue-tracker.md
— detalhe completo:

markdown

undefined

docs/agents/issue-tracker.md
——完整详情：

markdown

undefined

Issue Tracker

Estrutura

Spec: [onde a spec é publicada] Tickets: [onde os tickets são publicados, e como se ligam à spec]

Comandos

Criar spec: [comando/operação exata com placeholders] Criar ticket: [comando/operação exata com placeholders] Vincular ticket à spec: [comando/operação exata com placeholders] Listar tickets da spec: [comando/operação exata com placeholders — traz estado, labels e corpo] Ver pai: [comando/operação exata com placeholders] Listar: [comando/operação exata com placeholders] Ver: [comando/operação exata com placeholders] Editar labels: [comando/operação exata com placeholders] Fechar: [comando/operação exata com placeholders]

Bloqueio entre tickets: seção

## Blocked by

do corpo — fonte única, sem relação nativa.

Bloqueio entre tickets: seção

## Blocked by

do corpo — fonte única, sem relação nativa.

Vocabulário de Labels

Label	Significado
ready-for-agent	...
...	...


**Arquivo de instruções** — bloco resumido:

```markdown

Label	Significado
ready-for-agent	...
...	...


**指令文件**——简要区块：

```markdown

Issue Tracker

Tracker: [github-issues | markdown-local | linear | jira | outro]. Ver

docs/agents/issue-tracker.md

para estrutura, comandos e vocabulário de labels.


Se a seção `## Issue Tracker` já existir no arquivo de instruções, **atualize o bloco in-place** — não duplique, não toque nas seções vizinhas do arquivo.

Esses dois arquivos juntos são o contrato que `to-spec`, `to-tickets` e o `implement` leem para saber onde e como publicar — mesmo espírito que `## Commands` cumpre para o `implementer`, mas com o detalhe pesado isolado fora do arquivo de instruções. Sem eles, essas skills devem parar com erro.

Tracker: [github-issues | markdown-local | linear | jira | outro]. Ver

docs/agents/issue-tracker.md

para estrutura, comandos e vocabulário de labels.


如果指令文件中已经存在 `## Issue Tracker` 章节，**请原地更新该区块**——不要创建重复内容，也不要修改相邻章节。

这两个文件共同构成 `to-spec`、`to-tickets` 和 `implement` 用于获知发布位置与方式的契约——其理念与 `## Commands` 对 `implementer` 的作用相同，但将详细内容隔离在指令文件之外。缺少它们时，这些 skills 必须停止并报错。

Parte 2 —

## Commands

第 2 部分——

## Commands

O contrato de execução. O

implementer

lê esta seção para saber o que rodar; sem ela, para com hard stop. O

implement

também a lê, mas só no Bootstrap, para medir a baseline.

这是执行契约。

implementer

会读取该章节以确定需要运行什么；如果缺少该章节，它会 hard stop。

implement

也会读取，但仅在 Bootstrap 阶段用于测量 baseline。

1. Derivar, não perguntar

1. 推导，而不是询问

Leia o manifesto do projeto e extraia os comandos reais:

Stack	Onde olhar
Node	`scripts` do `package.json`
Rust	`Cargo.toml` ( `cargo clippy` , `cargo build` , `cargo test` )
Go	`go vet` , `go build ./...` , `go test ./...`
Python	`pyproject.toml` — `ruff` , `mypy` , `pytest`

Ambiguidade também é sua de resolver, não do usuário. Repo com

test

test:watch

test:e2e

tem três candidatos e só um é o gate: escolha o que roda a suite inteira uma vez e termina — nunca o modo watch, que não termina, nem o e2e, lento demais para gate por task — e informe a escolha em uma linha.

Repo sem manifesto ainda — o caso do repo novo, antes da primeira SPEC: não há de onde derivar. Grave a seção só com o título e a linha

Nenhum label ainda: o implementer declara os comandos na unidade que criar o manifesto.

, pule os passos 1b a 4 e informe isso na saída. Não escreva comando a partir da tabela Stack do PRD — é plano, e a seção nunca documenta comando que ainda não existe. É o mesmo tratamento do

architecture.md

num repo sem código (Parte 5): o

implementer

preenche a seção no mesmo commit em que o manifesto nasce, e a mantém quando muda um script de gate depois; o revisor cobra (CL6).

读取项目 manifest，提取真实命令：

Stack	查看位置
Node	`package.json` 的 `scripts`
Rust	`Cargo.toml` （ `cargo clippy` 、 `cargo build` 、 `cargo test` ）
Go	`go vet` 、 `go build ./...` 、 `go test ./...`
Python	`pyproject.toml` —— `ruff` 、 `mypy` 、 `pytest`

歧义同样由你解决，而不是交给用户。仓库同时包含

test

、

test:watch

和

test:e2e

时，有三个候选项，但只有一个适合作为 gate：选择能够完整运行测试套件一次并结束的选项——绝不能选择不会结束的 watch 模式，也不能选择作为 task gate 过慢的 e2e——并用一行说明选择结果。

尚无 manifest 的仓库——即新仓库、第一次 SPEC 之前：此时没有内容可供推导。只写入章节标题和这一行：

Nenhum label ainda: o implementer declara os comandos na unidade que criar o manifesto.

，跳过第 1b 至第 4 步，并在输出中说明。不要根据 PRD 中的 Stack 表编写命令——那只是计划，而该章节绝不记录尚不存在的命令。对于尚无代码的仓库，

architecture.md

也采用同样处理方式：

implementer

会在创建 manifest 的同一个 commit 中填写该章节，并在之后修改 gate script 时持续维护它；reviewer 会检查这一点（CL6）。

1b. O quinto label:

clean

1b. 第五个 label：

clean

clean

é opcional e apaga artefatos de build, nunca código-fonte. Ele existe porque o problema que resolve é genérico e a solução é específica de cada stack: um artefato deixado por um build de outra branch faz um gate ficar vermelho sem nenhum arquivo-fonte estar errado, e o agente atribui o vermelho a si mesmo. Declarando

clean

, o pipeline resolve o caso mecânico sem que nenhuma skill precise saber que Next.js existe.

Quem o usa: o

implement

roda

clean

no Bootstrap, antes de medir a baseline — é o que torna a foto honesta. E o

implementer

o roda uma vez, quando um gate fica vermelho apontando para arquivo que o diff dele não tocou, antes de escalar.

Se o manifesto não tiver um script de limpeza, crie um e informe em uma linha o que ele apaga — é decisão técnica, não pede aprovação:

Stack	Proposta
Next.js	apagar `.next/`
Vite	apagar `dist/` e `node_modules/.vite`
Rust	`cargo clean`
Go	`go clean -cache`
Python	apagar `.mypy_cache/` , `.pytest_cache/` , `__pycache__/`

⚠️ Portabilidade — regra dura. Use sempre o runtime da stack, nunca comandos de shell.
rm -rf
não existe no PowerShell e
rmdir /s
não existe no Bash; o pipeline roda nos dois. Em Node:
json
"clean": "node -e \"require('fs').rmSync('.next',{recursive:true,force:true})\""
Em Python,
python -c "import shutil; shutil.rmtree(...)"
. Em Rust e Go, os comandos nativos já são portáteis.
O
clean
fica no manifesto (o
package.json
, o
pyproject.toml
), e a linha do
## Commands
só o invoca. Escrever o comando destrutivo inline na seção coloca um
rm
num arquivo de prosa que ninguém revisa.

Ordem obrigatória ao gravar: o script entra no manifesto junto ou antes da linha no

## Commands

. A seção nunca deve documentar um comando que ainda não existe.

clean

是可选的，它删除的是 build 产物，绝不删除源代码。它存在是因为要解决的问题具有通用性，而解决方案因 stack 而异：其他 branch 的 build 留下的产物，可能使某个 gate 变红，但没有任何源文件存在问题，而 Agent 会错误地把红色结果归咎于自己。声明

clean

后，pipeline 可以机械地解决这种情况，而无需任何 skill 了解 Next.js 的存在。

使用者：

implement

在 Bootstrap 阶段运行

clean

，然后再测量 baseline，从而得到真实的基线。

implementer

则在某个 gate 变红、且红色结果指向其 diff 未触及的文件时运行一次，然后再进行升级处理。

如果 manifest 中没有清理 script，请创建一个，并用一行说明它删除的内容——这是技术决策，不需要请求批准：

Stack	建议
Next.js	删除 `.next/`
Vite	删除 `dist/` 和 `node_modules/.vite`
Rust	`cargo clean`
Go	`go clean -cache`
Python	删除 `.mypy_cache/` 、 `.pytest_cache/` 、 `__pycache__/`

⚠️ **可移植性——硬性规则。**始终使用 stack 的 runtime，绝不要使用 shell 命令。
rm -rf
在 PowerShell 中不存在，
rmdir /s
在 Bash 中也不存在；pipeline 必须同时支持两者。在 Node 中：
json
"clean": "node -e \"require('fs').rmSync('.next',{recursive:true,force:true})\""
在 Python 中，使用
python -c "import shutil; shutil.rmtree(...)"
。在 Rust 和 Go 中，原生命令已经具备可移植性。
clean
保存在 manifest（
package.json
、
pyproject.toml
）中，
## Commands
中的一行只负责调用它。把破坏性命令直接写进该章节，会让未经审查的散文文件中出现
rm
。

**写入时的强制顺序：**script 必须与

## Commands

中的命令同时写入，或先于它写入。该章节绝不记录尚不存在的命令。

2. Medir

2. 测量

Rode cada comando uma vez e cronometre — inclusive o

clean

. Você precisa do número para o passo seguinte, e uma medição também prova que o comando funciona neste repo — comando escrito no arquivo de instruções que não roda é o mesmo que não ter seção.

每个命令运行一次并计时——

clean

也包括在内。你需要这些数字来完成下一步；同时，测量也证明命令在此仓库中确实可以运行——写入指令文件却无法运行的命令，等同于没有该章节。

3. Gravar

3. 写入

markdown

undefined

markdown

undefined

Commands

lint:
```
<comando>
```
typecheck:
```
<comando>
```
build:
```
<comando>
```
test:
```
<comando>
```
clean:
```
<comando>
```
← opcional


Cinco labels, uma seção. **Não crie seções separadas para "CI" e "testes"** — a divisão faz o agente escolher qual ler, e escolha errada aqui produz um gate que passa sem ter rodado nada.

Se algum label não existir neste stack (projeto sem typecheck, por exemplo), omita a linha. Os agentes rodam os labels que existem, e o `clean` ausente só significa que o passo de limpeza é pulado — nada quebra.

> **`audit` não é um label desta seção.** Auditoria de dependência vive na CI, num checkout limpo. O motivo não é a ferramenta: vulnerabilidade não aparece porque alguém mexeu no manifesto, aparece porque publicaram um aviso sobre um pacote que já estava lá — e um gate que só roda quando o diff toca o manifesto nunca pega o caso comum. Quem grava `.github/workflows/ci.yml` é a Parte 7. Esta seção continua sem label `audit`, e sem uma segunda seção chamada "CI".

lint:
```
<comando>
```
typecheck:
```
<comando>
```
build:
```
<comando>
```
test:
```
<comando>
```
clean:
```
<comando>
```
← opcional


五个 labels，一个章节。**不要为“CI”和“测试”分别创建章节**——这种划分会让 Agent 不知道该读哪一部分，而在这里选错会导致某个 gate 什么都没运行却直接通过。

如果当前 stack 中不存在某个 label（例如项目没有 typecheck），省略对应行。Agents 只运行实际存在的 labels；缺少 `clean` 只意味着跳过清理步骤，不会造成任何问题。

> **`audit` 不是该章节中的 label。**依赖审计位于 CI 中，并应在干净的 checkout 中执行。原因不在于工具本身：漏洞并不总是在有人修改 manifest 后出现；有人发布了针对既有包的警告时，漏洞就会出现，而只在 diff 修改 manifest 时才运行的 gate 无法覆盖最常见的情况。写入 `.github/workflows/ci.yml` 是第 7 部分的职责。该章节仍不包含 `audit` label，也不创建第二个名为“CI”的章节。

4. Reportar o custo ao usuário

4. 向用户报告成本

Mostre os tempos medidos e explique a consequência, porque ela define o comportamento do

implementer

```
lint
```
,
```
typecheck
```
e
```
test
```
são o gate por task — rodam a cada task fechada
```
build
```
roda uma vez, no fim da unidade

Se a suite de

test

passar de ~60s neste repo, avise o usuário: a esse custo ela sai do gate por task e passa a rodar junto do

build

, uma vez no fim. Registre a exceção como uma linha logo abaixo da seção.

展示测得的时间并解释其影响，因为这会决定

implementer

的行为：

```
lint
```
、
```
typecheck
```
和
```
test
```
是 task gate——每完成一个 task 就运行
```
build
```
只在单元结束时运行一次

如果此仓库中的

test

suite 耗时超过约 60 秒，请提醒用户：达到该成本后，它会退出 task gate，改为与

build

一起在末尾运行一次。将该例外记录为紧接该章节下的一行。

Parte 3 —

## Fluxo

第 3 部分——

## Fluxo

A recomendação que qualquer agente dá ao usuário quando um entendimento compartilhado é atingido — depois de um grill, ou de um pedido que virou conversa.

markdown

undefined

这是任何 Agent 在形成共同理解后——经过 grill，或一次请求演变成对话后——向用户给出的推荐。

markdown

undefined

Fluxo

Ao chegar num entendimento compartilhado de uma mudança, recomende uma das três saídas:

Cabe numa sessão e não muda contrato público (schema, rota, auth, API) →
```
/implement
```
direto, sem SPEC nem issue.
Muda contrato público, ou o registro rastreado importa →
```
/to-spec
```
.
Mais de uma SPEC prevista →
```
/to-prd
```
antes.

Recomende, não decida — a escolha é do usuário. Em qualquer das três, branch e PR sempre.


Confirme o critério com o usuário antes de gravar: o limiar entre "implementa direto" e "vira SPEC" é dele, não seu.

---

Ao chegar num entendimento compartilhado de uma mudança, recomende uma das três saídas:

Cabe numa sessão e não muda contrato público (schema, rota, auth, API) →
```
/implement
```
direto, sem SPEC nem issue.
Muda contrato público, ou o registro rastreado importa →
```
/to-spec
```
.
Mais de uma SPEC prevista →
```
/to-prd
```
antes.

Recomende, não decida — a escolha é do usuário. Em qualquer das três, branch e PR sempre.


写入前与用户确认标准：“直接实现”和“转为 SPEC”之间的阈值属于用户，而不是你。

---

Parte 4 — Remote e

.gitignore

第 4 部分——Remote 与

.gitignore

Remote:

git remote -v

. Sem remote não há PR, e o loop de implementação encerra no bootstrap. Se não houver, crie agora (

gh repo create

) ou instrua o usuário — não siga adiante em silêncio.

.gitignore
: garanta a linha

.scratch/

. A cópia de trabalho é efêmera por design; versioná-la recria a duplicação que o modelo de artefatos evita.

Remote：

git remote -v

。没有 remote 就无法创建 PR，实现循环也会在 Bootstrap 阶段结束。如果没有，请立即创建（

gh repo create

）或指导用户操作——不要在静默状态下继续。

.gitignore

：**确保包含

.scratch/

这一行。工作副本按设计是临时性的；将其纳入版本控制会重新产生产物模型本应避免的重复。

Parte 5 —

docs/agents/architecture.md

第 5 部分——

docs/agents/architecture.md

O mapa do código para os agentes:

to-spec

to-tickets

implementer

e revisor o leem para não redescobrir o repo a cada execução. Não é documento para o dono ler; quem o mantém é o

implementer

, e quem cobra é o revisor (CL6) — a mesma posse que ele tem sobre

## Commands

Se ele já existe, não reescreva. Senão, explore o código e grave, curto:

markdown

undefined

这是供 Agents 使用的代码地图：

to-spec

、

to-tickets

、

implementer

和 reviewer 会读取它，避免每次执行都重新探索仓库。它不是给仓库所有者阅读的文档；

implementer

负责维护，

reviewer

负责检查（CL6）——这与

implementer

对

## Commands

的职责相同。

如果文件已经存在，不要重写。否则，探索代码并简要写入：

markdown

undefined

Arquitetura

Mapa de módulos, seams de teste e invariantes deste repo. Documento vivo: o

implementer

o atualiza quando uma unidade cria módulo ou camada, move um seam, muda uma fronteira ou um invariante.

Mapa de módulos, seams de teste e invariantes deste repo. Documento vivo: o

implementer

o atualiza quando uma unidade cria módulo ou camada, move um seam, muda uma fronteira ou um invariante.

Onde cada coisa mora

Área	Módulo	Nota

Área	Módulo	Nota

Seams de teste

[onde a lógica testável mora e onde os testes rodam; o seam preferido para código novo]

Invariantes

[regras que nenhum lint pega e que o código respeita hoje — direção de dependência, fronteira servidor/cliente, onde input externo é validado]


Escreva só o que o código mostra hoje — não o que o PRD promete. Repo sem código ainda → grave só o esqueleto; o `implementer` preenche conforme os módulos nascem. Aponte para ele no arquivo de instruções, com uma linha fora das três seções do pipeline — ex: `Mapa do código (módulos, seams, invariantes): docs/agents/architecture.md`. Se já houver um ponteiro, não duplique. Informe em uma linha que o gravou.

[regras que nenhum lint pega e que o código respeita hoje — direção de dependência, fronteira servidor/cliente, onde input externo é validado]


只记录当前代码所展示的内容——不要记录 PRD 所承诺的内容。仓库尚无代码时，只写入骨架；随着模块逐步创建，由 `implementer` 填充。使用一行将其从指令文件指向该文档，但放在 pipeline 的三个章节之外，例如：`Mapa do código (módulos, seams, invariantes): docs/agents/architecture.md`。如果已经存在指针，不要重复创建。用一行说明你已写入该文档。

Parte 6 —

docs/agents/review-rules-projeto.md

第 6 部分——

docs/agents/review-rules-projeto.md

O revisor aplica critérios universais — segurança, testes, limpeza, complexidade, code smells — que valem para qualquer stack. O que é deste projeto mora em

docs/agents/review-rules-projeto.md

: critério de framework ou de design system, caminho extra na classificação de risco do PR, e achado do revisor que se repetiu. O

implement

e o revisor leem esse arquivo. Ele deixa de ser opcional: todo projeto configurado por esta skill o tem.

Arquivo ausente: grave o esqueleto abaixo. Arquivo presente: não reescreva critério que já está lá. Se faltar a seção

## Risco

, acrescente só ela no fim e avise. Se

## Risco

já existir, não mexa — o projeto pode ter estendido a lista.

Não pergunte "a stack tem armadilhas?". Decida você. Se houver armadilha que nenhum lint pega (ex.: fronteira servidor/cliente num framework de SSR), grave poucos critérios concretos abaixo do esqueleto, no formato dos universais: código, regra, por quê, como checar por leitura, severidade. Se não houver, o esqueleto basta, e você informa que não acrescentou critério de stack. Critério que exige executar algo não entra: vira label de

## Commands

ou passo da CI.

markdown

undefined

reviewer 会应用适用于任何 stack 的通用标准——安全性、测试、清理、复杂度、code smells。只适用于本项目的内容位于

docs/agents/review-rules-projeto.md

：framework 或 design system 的标准、PR 风险分类中的额外路径，以及反复出现的 reviewer 发现。

implement

和 reviewer 都会读取该文件。它不再是可选项：每个通过此 skill 配置的项目都必须拥有该文件。

**文件不存在：**写入以下骨架。**文件已存在：**不要重写已有标准。如果缺少

## Risco

章节，只在末尾追加该章节并提醒用户。如果

## Risco

已经存在，不要修改——项目可能已扩展该列表。

不要询问“这个 stack 有哪些陷阱？”由你自行决定。如果存在 lint 无法捕获的陷阱，例如 SSR framework 中的服务器／客户端边界，请在骨架下方写入少量具体标准，格式与通用标准一致：代码、规则、原因、如何通过阅读检查、严重级别。如果不存在此类陷阱，骨架即可，并说明未添加 stack 标准。需要执行某项操作才能验证的标准不属于这里：它应成为

## Commands

中的 label 或 CI 中的步骤。

markdown

undefined

Critérios de review do projeto

Critérios que só fazem sentido neste repositório. O revisor lê este arquivo junto com os universais da skill

implement

. Cada critério: código, regra, por quê, como checar por leitura, severidade.

Bug que chega na

main

e achado que se repete em dois PRs entram aqui quando a correção for uma regra de review. O passo está no README do pipeline, seção "Quando um bug chega na main".

Critérios que só fazem sentido neste repositório. O revisor lê este arquivo junto com os universais da skill

implement

. Cada critério: código, regra, por quê, como checar por leitura, severidade.

Bug que chega na

main

e achado que se repete em dois PRs entram aqui quando a correção for uma regra de review. O passo está no README do pipeline, seção "Quando um bug chega na main".

Risco

A lista padrão do pipeline (skill

implement

, seção "Risco do PR") continua valendo e não se copia para cá. Os bullets abaixo só acrescentam caminhos. Nenhum bullet rebaixa um caminho que a lista padrão já marca como alto.

A lista padrão do pipeline (skill

implement

, seção "Risco do PR") continua valendo e não se copia para cá. Os bullets abaixo só acrescentam caminhos. Nenhum bullet rebaixa um caminho que a lista padrão já marca como alto.

Alto

Nenhum caminho extra.

Baixo

Nenhum caminho extra.


Um bullet de extensão é um prefixo de caminho (`services/payments/`) ou um nome de arquivo (`billing.ts`). "Nenhum caminho extra." significa que a lista padrão basta; quando o projeto for estender, essa linha sai e entram os bullets.

---

Nenhum caminho extra.


扩展项 bullet 是一个路径前缀（如 `services/payments/`）或文件名（如 `billing.ts`）。“Nenhum caminho extra.”表示默认列表已经足够；如果项目需要扩展，则删除该行并添加相应 bullets。

---

Parte 7 — CI, template de PR e rótulos de risco

第 7 部分——CI、PR 模板与风险标签

O PR que o

implement

abre tem que chegar com três respostas que o dono lê sem o diff: como foi testado, qual é o risco, como desfazer. O template fixa as seções. A CI roda os gates num checkout limpo, fora da máquina de quem implementou. Os rótulos

risk:*

são o que a lista de PRs mostra.

Nada disso é vocabulário de triagem.

risk:alto

risk:medio

risk:baixo

não entram na tabela de estados da Parte 1, não são exclusivos com

in-progress

e não vão no campo

**Status:**

do markdown local. São rótulo de PR.

implement

创建的 PR 必须包含仓库所有者无需打开 diff 就能读到的三个答案：如何测试、风险是什么、如何回滚。模板固定这些章节。CI 在干净的 checkout 中运行 gates，而不是在实现者自己的机器上运行。

risk:*

标签会显示在 PR 列表中。

这些内容不属于分诊词汇表。

risk:alto

、

risk:medio

和

risk:baixo

不进入第 1 部分的状态表，不与

in-progress

互斥，也不会写入本地 Markdown 的

**Status:**

字段。它们是 PR 标签。

1. Não sobrescrever o que já existe

1. 不要覆盖已有内容

Antes de gravar, veja se o arquivo está no repo:

```
.github/pull_request_template.md
```
```
.github/PULL_REQUEST_TEMPLATE.md
```
ou
```
docs/pull_request_template.md
```
— o GitHub aceita os três. Se qualquer um existir, o projeto já escolheu o template: não crie um segundo.
```
.github/workflows/ci.yml
```

Arquivo que já existe não é reescrito. Avise o caminho e, em uma linha, o que falta em relação ao que esta parte gravaria (as seções do template; no workflow, o job

gates

com os labels de

## Commands

e, em Node, o job

audit

). Quem reconcilia é o dono. Setup que sobrescreve CI alheia troca workflow revisado por arquivo gerado. Arquivo ausente, crie. Diretório

.github/workflows/

ausente, crie também.

写入前，检查仓库中是否存在以下文件：

```
.github/pull_request_template.md
```
```
.github/PULL_REQUEST_TEMPLATE.md
```
或
```
docs/pull_request_template.md
```
——GitHub 接受这三种路径。如果其中任何一个已经存在，说明项目已经选择了模板：不要创建第二个。
```
.github/workflows/ci.yml
```

**已经存在的文件不得重写。**告知其路径，并用一行说明相对于本部分计划写入的内容还缺少什么；对于模板，是缺少的章节；对于 workflow，是包含

## Commands

labels 的

gates

job，以及 Node 项目中的

audit

job。由仓库所有者负责协调。覆盖 CI 的 setup 会架空经过人工审查的 workflow 变更，转而采用生成文件。若文件不存在，则创建。如果

.github/workflows/

目录不存在，也一并创建。

2. Template de PR

2. PR 模板

Grave

.github/pull_request_template.md

com estas seções, nesta ordem. O

implement

preenche as mesmas ao abrir o PR. O template é o que aparece para quem abre PR à mão.

markdown

undefined

写入

.github/pull_request_template.md

，按以下顺序包含这些章节。

implement

创建 PR 时会填写相同内容。该模板就是手动创建 PR 时所看到的内容。

markdown

undefined

O que entrou

Como foi testado

Risco

Como desfazer

Achados do revisor

Ficou de fora

undefined

undefined

3. Workflow de CI

3. CI Workflow

Grave

.github/workflows/ci.yml

. Dispara em todo

pull_request

. Não dispare em

push

só porque é comum: o contrato é o PR.

Job
gates
. Um passo por label de

## Commands

, exceto

clean

clean

apaga artefato local; o checkout da CI já é limpo. Copie o comando da seção literalmente —

npm test

quando a seção diz

npm run test:ci

é outro gate. Cada gate é um

run:

próprio. Sem

||

e sem

continue-on-error

: gate vermelho falha o job.

Antes dos gates, o setup da stack:

Stack	Antes dos gates
Node ( `package.json` )	`actions/checkout@v7` , `actions/setup-node@v7` . Versão de Node: `.nvmrc` , `.node-version` ou `engines.node` ; se nenhuma existir, `22` . Cache `npm` . `npm ci` se existir `package-lock.json` ; senão `npm install` .
Rust ( `Cargo.toml` )	`actions/checkout@v7` , `dtolnay/rust-toolchain@stable`
Go ( `go.mod` )	`actions/checkout@v7` , `actions/setup-go@v7`
Python ( `pyproject.toml` )	`actions/checkout@v7` , `actions/setup-python@v7` , e o install que os comandos da seção exigem

Pine a major (

@v7

), nunca

@main

. Major nova dessas actions, quando sair, substitui a da tabela; não trave o workflow num patch.

Envolva só os passos dos gates com os marcadores. O

implementer

atualiza esse bloco quando

## Commands

muda, e não reescreve o resto do arquivo:

yaml

name: ci

on:
  pull_request:

jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      # pipeline:commands
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test
      - run: npm run build
      # pipeline:commands-fim

  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm audit --audit-level=high

O exemplo é Node com lockfile e os quatro labels. Gere o yaml da stack real. Label ausente em

## Commands

não vira passo.

Job
audit
, só em projeto Node (existe

package.json

). Outra stack não ganha audit inventado — nem

cargo audit

, nem

pip-audit

— se o repo não usa essa ferramenta. O comando é

npm audit --audit-level=high

: falha em

high

critical

moderate

low

não falham o job. Aviso transitivo sem correção publicada deixaria todo PR vermelho, e ninguém age. É o mesmo nível que

review-rules.md

já cita. Com

package-lock.json

, instale com

npm ci

; sem lock,

npm install

, e avise que o resultado do audit não reproduz entre máquinas.

Repo sem manifesto (

## Commands

sem labels): grave o workflow mesmo assim. Job

gates

com checkout e, dentro dos marcadores, só o comentário de que o

implementer

preenche os passos na unidade que criar o manifesto. Sem

package.json

, sem job

audit

. O arquivo nasce aqui; o comando de gate nasce com o código — o mesmo trato do

architecture.md

num repo sem código.

Não coloque chave de API neste arquivo. Não coloque review de IA nem review de segurança de serviço pago. Gates declarados e, no Node,

npm audit

Não rode esta CI daqui. A Parte 2 já mediu os comandos; este workflow roda no GitHub, no PR.

写入

.github/workflows/ci.yml

。在每次

pull_request

时触发。不要仅因为

push

很常见就让它在

push

时触发：契约针对的是 PR。

gates

job。**为

## Commands

中的每个 label 设置一个步骤，但不包括

clean

。

clean

删除本地 build 产物，而 CI 的 checkout 已经是干净的。逐字复制该章节中的命令——当章节写的是

npm run test:ci

时，复制成

npm test

就变成了另一个 gate。每个 gate 都使用独立的

run:

。不要使用

||

，也不要使用

continue-on-error

：gate 失败必须导致 job 失败。

在 gates 之前配置 stack 环境：

Stack	Gates 之前
Node（ `package.json` ）	`actions/checkout@v7` 、 `actions/setup-node@v7` 。Node 版本取自 `.nvmrc` 、 `.node-version` 或 `engines.node` ；如果均不存在，则使用 `22` 。缓存 `npm` 。存在 `package-lock.json` 时使用 `npm ci` ，否则使用 `npm install` 。
Rust（ `Cargo.toml` ）	`actions/checkout@v7` 、 `dtolnay/rust-toolchain@stable`
Go（ `go.mod` ）	`actions/checkout@v7` 、 `actions/setup-go@v7`
Python（ `pyproject.toml` ）	`actions/checkout@v7` 、 `actions/setup-python@v7` ，以及 `## Commands` 中命令所要求的安装步骤

固定 major（

@v7

），绝不要使用

@main

。这些 actions 发布新的 major 后，应使用表格中的新 major 替代旧版本；不要将 workflow 锁定在某个 patch 版本。

仅用标记包裹 gates 步骤。

## Commands

发生变化时，

implementer

会更新该区块，并且不会重写文件的其他部分：

yaml

name: ci

on:
  pull_request:

jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      # pipeline:commands
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test
      - run: npm run build
      # pipeline:commands-fim

  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm audit --audit-level=high

该示例对应带 lockfile 和四个 labels 的 Node 项目。请生成真实 stack 对应的 YAML。

## Commands

中不存在的 label 不会变成步骤。

audit
job，仅用于 Node 项目（存在

package.json

）。其他 stack 不应凭空增加 audit——仓库未使用相应工具时，既不要添加

cargo audit

，也不要添加

pip-audit

。命令为

npm audit --audit-level=high

：在

high

和

critical

级别失败，

moderate

和

low

不会导致 job 失败。如果存在没有已发布修复方案的传递依赖警告，就会让所有 PR 变红，却没有人采取行动。这与

review-rules.md

已引用的级别一致。存在

package-lock.json

时，使用

npm ci

安装；没有 lockfile 时使用

npm install

，并提醒用户 audit 结果在不同机器之间不可复现。

没有 manifest 的仓库（

## Commands

中没有 labels）：仍然创建 workflow。

gates

job 包含 checkout，并在标记内仅保留一条注释，说明

implementer

会在创建 manifest 的单元中填写步骤。没有

package.json

，因此不添加

audit

job。文件在此时创建；gate 命令则随代码一同产生——这与尚无代码仓库中的

architecture.md

采用相同处理方式。

不要在此文件中放入 API key。不要加入 AI review，也不要加入付费服务的安全 review。只配置已声明的 gates；对于 Node，再加入

npm audit

。

不要从当前环境运行此 CI。第 2 部分已经测量过这些命令；此 workflow 会在 GitHub 上、针对 PR 运行。

4. Rótulos de risco

4. 风险标签

Com remote GitHub e

gh

autenticado, crie os três.

--force

é o que torna o comando idempotente: rótulo novo é criado, rótulo existente tem cor e descrição alinhadas a esta lista.

bash

gh label create "risk:alto" --color "B60205" --description "PR toca migracao, auth, cobranca, CI ou deploy" --force
gh label create "risk:medio" --color "FBCA04" --description "PR fora das listas de alto e de baixo" --force
gh label create "risk:baixo" --color "0E8A16" --description "PR so de documentacao, texto ou estilo" --force

A descrição vai sem acento porque o que o dono lê no PR é a linha de

## Risco

, não esta string. O nome do rótulo é o contrato:

risk:alto

risk:medio

risk:baixo

Sem

gh

, ou sem remote GitHub, não invente rótulo. Avise que a linha de risco no corpo do PR continua valendo e o rótulo espera um GitHub. Markdown local não tem rótulo de PR.

对于配置了 GitHub remote 且

gh

已认证的仓库，创建以下三个标签。

--force

使命令具备幂等性：新标签会被创建，已有标签的颜色和描述也会与该列表保持一致。

bash

gh label create "risk:alto" --color "B60205" --description "PR toca migracao, auth, cobranca, CI ou deploy" --force
gh label create "risk:medio" --color "FBCA04" --description "PR fora das listas de alto e de baixo" --force
gh label create "risk:baixo" --color "0E8A16" --description "PR so de documentacao, texto ou estilo" --force

描述不带重音符号，因为仓库所有者在 PR 中阅读的是

## Risco

行，而不是该字符串。标签名称才是契约：

risk:alto

、

risk:medio

、

risk:baixo

。

如果没有

gh

，或者没有 GitHub remote，不要凭空创建标签。提醒用户：PR 正文中的风险行仍然有效，标签会等到有 GitHub 后再创建。本地 Markdown 没有 PR 标签。

5. O que não entra no arquivo de instruções

5. 不写入指令文件的内容

CI, template e rótulo de risco não ganham seção em

AGENTS.md

. Workflow é arquivo, não decisão de processo, e o arquivo de instruções não guarda o que a Parte 2 já separou de propósito. Uma seção "CI" ao lado de

## Commands

continua proibida.

CI、模板和风险标签不会在

AGENTS.md

中获得章节。Workflow 是文件，不是流程决策；指令文件也不保存第 2 部分已经出于特定目的而分离出去的内容。禁止在

## Commands

旁边创建“CI”章节。

Saída

输出

Ao finalizar, informe:

✅ Projeto configurado.
Tracker: [tracker] — labels criadas: [lista]. Detalhe em
docs/agents/issue-tracker.md
. Commands: [lint [Ns] · typecheck [Ns] · test [Ns] · build [Ns] · clean [Ns | não declarado] | sem labels — repo sem manifesto; a unidade que criar o manifesto os declara] Fluxo: gravado no arquivo de instruções. Remote: [URL]. Arquitetura:
docs/agents/architecture.md
[gerado | esqueleto — repo sem código | já existia]. Ponteiro: [
CLAUDE.md
→
@AGENTS.md
criado | não necessário]. Critérios do projeto:
docs/agents/review-rules-projeto.md
[criado | já existia;
## Risco
acrescentada | já existia com
## Risco
, não mexi]. Critérios de stack acrescentados: [N | nenhum]. Template de PR: [
.github/pull_request_template.md
criado | já existia em [caminho], não mexi. Falta: [seções, ou "nada"]]. CI: [
.github/workflows/ci.yml
criado — gates: [labels] · audit: [sim,
--audit-level=high
| não — repo sem
package.json
] | já existia, não mexi. Falta: [o que diverge, ou "nada"]]. Rótulos de risco: [
risk:alto
,
risk:medio
,
risk:baixo
| não criados — sem GitHub].
Próximo passo:
/to-spec
para registrar uma unidade de trabalho, ou
/implement
direto se a mudança for pequena. Loop AFK: [disponível via
/implement
| indisponível neste modo].

完成时告知：

✅ 项目已配置。
Tracker：[tracker]——已创建 labels：[列表]。详情见
docs/agents/issue-tracker.md
。 Commands：[lint [Ns] · typecheck [Ns] · test [Ns] · build [Ns] · clean [Ns | 未声明] | 无 labels——仓库没有 manifest；创建 manifest 的单元将声明这些 commands] **Fluxo：**已写入指令文件。 Remote：[URL]。 架构：
docs/agents/architecture.md
[已生成 | 骨架——仓库没有代码 | 已存在]。 指针：[
CLAUDE.md
→
@AGENTS.md
已创建 | 不需要]。 项目标准：
docs/agents/review-rules-projeto.md
[已创建 | 已存在；已添加
## Risco
| 已存在且包含
## Risco
，未修改]。已添加 stack 标准：[N | 无]。 PR 模板：[
.github/pull_request_template.md
已创建 | 已存在于 [路径]，未修改。缺少：[章节，或“无”]]。 CI：[
.github/workflows/ci.yml
已创建——gates：[labels] · audit：[是，
--audit-level=high
| 否——仓库没有
package.json
] | 已存在，未修改。缺少：[差异内容，或“无”]]。 风险标签：[
risk:alto
、
risk:medio
、
risk:baixo
| 未创建——没有 GitHub]。
下一步：使用
/to-spec
登记一个工作单元；如果改动较小，则直接使用
/implement
。AFK 循环：[可通过
/implement
使用 | 此模式下不可用]。

setup-project

Original

Translation

Skill: setup-project

Skill: setup-project

Portabilidade dos comandos — regra dura

命令可移植性——硬性规则

O modelo de artefatos

产物模型

O que o arquivo de instruções guarda — regra canônica

指令文件保存什么——规范规则

Parte 1 — Issue tracker

第 1 部分——Issue Tracker

1. Explorar antes de perguntar

1. 先探索，再询问

2. Propor um default inferido, não abrir um menu em branco

2. 提出推断出的默认值，不要打开空白菜单

3. Configurar de acordo com o tracker escolhido

3. 根据所选 tracker 进行配置

GitHub Issues

GitHub Issues

Criar spec — devolve a URL da issue no stdout

Criar spec — devolve a URL da issue no stdout

Node ID da spec (necessário para vincular sub-issues)

Node ID da spec (necessário para vincular sub-issues)

Criar ticket — devolve a URL do ticket no stdout; leia-a e use no passo seguinte

Criar ticket — devolve a URL do ticket no stdout; leia-a e use no passo seguinte

Vincular o ticket como sub-issue da spec

Vincular o ticket como sub-issue da spec

Listar os tickets de uma spec (com o corpo, de onde sai o ## Blocked by)

Listar os tickets de uma spec (com o corpo, de onde sai o ## Blocked by)

Ver o pai (a spec) de um ticket — sem pai, parent vem null

Ver o pai (a spec) de um ticket — sem pai, parent vem null

Listar por label / ver / editar labels

Listar por label / ver / editar labels

Fechar (ticket aprovado)

Fechar (ticket aprovado)

Markdown local (.scratch/)

本地 Markdown（.scratch/）

Linear

Linear

Jira

Jira

Outro / customizado

其他／自定义

4. Definir o vocabulário de labels de triagem

4. 定义分诊 labels 词汇表

5. Criar as labels no tracker (quando aplicável)

5. 在 tracker 中创建 labels（适用时）

6. Gravar

6. 写入

Issue Tracker

Issue Tracker

Estrutura

Estrutura

Comandos

Comandos

Vocabulário de Labels

Vocabulário de Labels

Issue Tracker

Issue Tracker

Parte 2 — ## Commands

第 2 部分——## Commands

1. Derivar, não perguntar

1. 推导，而不是询问

1b. O quinto label: clean

1b. 第五个 label：clean

2. Medir

2. 测量

3. Gravar

3. 写入

Commands

Commands

4. Reportar o custo ao usuário

4. 向用户报告成本

Parte 3 — ## Fluxo

第 3 部分——## Fluxo

Fluxo

Fluxo

Parte 4 — Remote e .gitignore

Markdown local (
`.scratch/`
)

本地 Markdown（
`.scratch/`
）

Parte 2 —
`## Commands`

第 2 部分——
`## Commands`

1b. O quinto label:
`clean`

1b. 第五个 label：
`clean`

Parte 3 —
`## Fluxo`

第 3 部分——
`## Fluxo`

Parte 4 — Remote e
`.gitignore`

第 4 部分——Remote 与
`.gitignore`

Parte 5 —
`docs/agents/architecture.md`

第 5 部分——
`docs/agents/architecture.md`

Parte 6 —
`docs/agents/review-rules-projeto.md`

第 6 部分——
`docs/agents/review-rules-projeto.md`