refactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refatoração Segura

安全重构

<critical>Preservar comportamento e contratos existentes</critical> <critical>Aplicar passos pequenos, testáveis e reversíveis</critical>

<critical>保留原有行为和现有契约</critical> <critical>采用小型、可测试、可回滚的步骤执行</critical>

Procedimentos

流程

Etapa 1: Definir Modo de Operação

Identifique o modo solicitado:
- ```
advisory
```
  : gere apenas plano e recomendações (padrão).
- ```
execution
```
  : aplique refatoração no código.
Se o modo não for explícito, assuma
```
advisory
```
e confirme com o usuário.

Etapa 2: Mapear Hotspots

Identifique arquivos e funções que satisfaçam qualquer critério:
- Alta complexidade ciclomática.
- Tamanho excessivo (>50 linhas/função ou >300 linhas/arquivo).
- Violações de regras em
```
.claude/rules/
```
  .
- Alto acoplamento entre módulos.
Priorize hotspots por impacto na manutenibilidade.

Etapa 3: Planejar Refatoração

Defina objetivo de refatoração por hotspot.
Descreva cada mudança como passo incremental e reversível.
Identifique dependências entre passos.

Etapa 4: Executar (apenas modo
execution
)

Aplique cada passo incremental.
Execute
```
go test ./...
```
após cada passo.
Se testes falharem, reverta o passo e registre como
```
blocked
```
.

Etapa 5: Avaliar Risco

Classifique o risco com critérios objetivos:
- ```
Low
```
  : todos os testes passam, sem violações, complexidade mantida ou reduzida.
- ```
Medium
```
  : testes passam mas complexidade aumentou ou novas dependências introduzidas. Prossiga com aviso explícito.
- ```
High
```
  : falhas de teste, violações de regras ou contratos quebrados. Pare com
```
blocked
```
  .

Etapa 6: Gerar Relatório

Persista o relatório no caminho indicado pelo chamador.
- Contexto de task:
```
tasks/prd-[feature-name]/refactor_report.md
```
  .
- Padrão:
```
./refactor_report.md
```
  .

步骤1：定义操作模式

识别要求的模式：
- ```
advisory
```
  ：仅生成计划和建议（默认模式）
- ```
execution
```
  ：对代码执行重构操作
如果没有明确指定模式，默认采用
```
advisory
```
并向用户确认。

步骤2：定位热点代码

识别满足任意以下条件的文件和函数：
- 高圈复杂度
- 代码量过大（单函数超过50行/单文件超过300行）
- 违反
```
.claude/rules/
```
  目录下的规则
- 模块间耦合度过高
按照对可维护性的影响程度对热点代码排序优先级。

步骤3：规划重构方案

为每个热点代码定义重构目标
将每个改动描述为增量、可回滚的步骤
识别步骤间的依赖关系。

步骤4：执行重构（仅
execution
模式下使用）

执行每个增量步骤
每步执行完成后运行
```
go test ./...
```
如果测试失败，回滚该步骤并标记为
```
blocked
```
。

步骤5：风险评估

按照客观标准对风险分级：
- ```
Low
```
  ：所有测试通过，无规则违反，复杂度持平或降低
- ```
Medium
```
  ：测试通过但复杂度升高或引入了新依赖，需给出明确警告后继续
- ```
High
```
  ：测试失败、违反规则或契约被破坏，停止操作并标记为
```
blocked
```
  。

步骤6：生成报告

将报告存储到调用方指定的路径：
- 任务上下文场景：
```
tasks/prd-[feature-name]/refactor_report.md
```
- 默认路径：
```
./refactor_report.md
```

Condições de Parada

停止条件

```
done
```
: objetivo do modo selecionado completado com evidência.
```
blocked
```
: risco residual aumentou ou dependência externa bloqueia progresso.
```
failed
```
: limite de remediação excedido sem convergência.

```
done
```
：所选模式的目标已完成，并有相关证据支撑
```
blocked
```
：残余风险升高或外部依赖阻碍进度
```
failed
```
：修复次数超出上限且无法收敛。

Formato de Saída

输出格式

markdown

undefined

markdown

undefined

Relatório de Refatoração

Modo: advisory | execution
Hotspots: [lista com critério de seleção]
Mudanças: [lista de passos aplicados ou recomendados]
Validação: [evidência de testes]
Risco residual: Low | Medium | High

undefined

Modo: advisory | execution
Hotspots: [lista com critério de seleção]
Mudanças: [lista de passos aplicados ou recomendados]
Validação: [evidência de testes]
Risco residual: Low | Medium | High

undefined

Tratamento de Erros

错误处理

Se
```
go test
```
falhar após um passo, reverta imediatamente e registre o motivo.
Se o escopo de refatoração for ambíguo, solicite confirmação antes de prosseguir com
```
needs_input
```
.
Se nenhum hotspot for encontrado, informe e encerre com
```
done
```
.

如果某个步骤执行后
```
go test
```
失败，立即回滚并记录原因
如果重构范围不明确，需先向用户确认再继续，标记为
```
needs_input
```
如果未找到任何热点代码，告知用户并以
```
done
```
状态结束。