wuyining0130/c-room — Geração de Código

Propósito

A solução técnica está pronta. O próximo passo é escrever o código. A abordagem tradicional é o desenvolvedor ler a solução técnica, examinar o código existente e escrever arquivo por arquivo. O problema é que a solução técnica já define o design das interfaces, os DDLs, o escopo das alterações e a decomposição das tarefas, mas o desenvolvedor ainda precisa traduzir manualmente essas informações em código — um processo altamente repetitivo e propenso a erros (nome de parâmetro digitado errado, caminho de interface inconsistente, esquecimento de alteração em algum serviço).

Este skill lê a solução técnica, o PRD, o protótipo e a base de conhecimento de codificação e, seguindo a decomposição de tarefas da solução técnica, gera/modifica arquivos de código diretamente no repositório alvo. Ele não gera "scaffold" ou "código template" — mas sim código de implementação com lógica de negócio completa, pronto para ser submetido à revisão (CR).

A capacidade central está no uso profundo do coding-knowledge: por meio dos índices de símbolos, cadeias de chamada, DDLs e padrões de código da base de conhecimento de codificação, o código gerado mantém consistência com o código existente do projeto em termos de estilo de nomenclatura, estrutura de camadas e tratamento de exceções — parecendo ter sido escrito por um veterano do projeto, e não por um terceirizado.

Entrada

• requirements/{modulo}/tech-design.md (entrada principal, contém design de interfaces, DDLs, decomposição de tarefas, escopo de alterações)
• requirements/{modulo}/prd-draft.md (critérios de aceitação, regras de negócio, condições de contorno)
• requirements/{modulo}/prototype/ (referência de estrutura de páginas front-end)
• coding-knowledge/ (referência central — estilo de código, padrões de arquitetura, índices de símbolos, cadeias de chamada, padrões de DDL, normas de código)
• Caminho do repositório de código alvo (especificado pelo usuário ou extraído do escopo de alterações do tech-design)

Fluxo de Trabalho

Fase 0: Ler Entradas, Construir Contexto

0.1 Ler tech-design.md

Extrair as seguintes informações, que servirão como fonte autoritativa para a geração:

• Escopo de impacto das alterações (quais repositórios, quais arquivos precisam ser criados/modificados)
• Design de interfaces (lista de APIs, parâmetros de requisição, estrutura de resposta, códigos de erro)
• Alterações no banco de dados (DDL)
• Decomposição de tarefas de desenvolvimento (T-01, T-02... com dependências)
• Diagramas de sequência de interação (relacionamentos de chamada entre serviços)
• Notas sobre parâmetros de interfaces reutilizadas (distinguir parâmetros e diferenças de comportamento)

0.2 Ler prd-draft.md

Extrair as seguintes informações para garantir a completude da lógica de negócio:

• Lista de funcionalidades e critérios de aceitação (garantir que o código gerado cubra cada ponto funcional)
• Regras de negócio e condições de contorno (garantir que haja lógica de validação correspondente no código)
• Requisitos de tratamento de erros (textos específicos de mensagens de erro)

0.3 Leitura Profunda do coding-knowledge (Passo Central)

Esta é a maior diferença entre o code-gen e a geração de código por IA comum. Não se trata de "ler para ter uma ideia geral", mas sim extrair padrões de codificação específicos camada por camada de código.

Primeira Camada: Normas Básicas (Leitura Obrigatória)

Ler os arquivos em coding-knowledge/infra/ para extrair restrições globais de codificação:

• code-quality.md → convenções de nomenclatura (camelCase vs snake_case, prefixos/sufixos), estilo de comentários, padrão de tratamento de exceções, normas de logging
• Outras normas de infraestrutura → modo de uso de middlewares (padrão de produção/consumo MQ, modo de operação de cache)

Segunda Camada: Arquitetura do Repositório (Ler por Repositório Envolvido)

Para cada repositório listado no tech-design, ler os arquivos em coding-knowledge/repos/{repo}/:

• architecture.md → Estrutura de pacotes e convenções de camadas. Ao criar um novo arquivo, determinar em qual pacote colocá-lo e como nomear a classe. Prestar atenção especial à descrição "este serviço não é responsável por" — evitar escrever lógica que não pertence àquele serviço.
• symbols.md → Índice de assinaturas de classes e métodos existentes. Esta é a porta de entrada para o "aprendizado de estilo" — encontrar implementações existentes do mesmo tipo (por exemplo, Controllers e Services existentes) para posteriormente ler o código-fonte completo na Fase 1.
• database-schema.md → DDL real das tabelas existentes. Ao criar uma nova tabela, referenciar as regras de conversão de nomes de campos (ex.: create_time vs createdAt), convenções de nomenclatura de índices (ex.: prefixo idx_), configuração de charset e engine.
• call-chains.md → Código real de chamadas entre serviços. Se o tech-design envolve chamadas entre serviços, descobrir a forma real de chamada usada no projeto (Feign Client? RestTemplate? WebClient? gRPC stub?), bem como a forma de escrever tratamento de erros e configuração de timeout.

Terceira Camada: Domínios de Negócio (Leitura Sob Demanda)

Se o tech-design envolve colaboração entre serviços, ler coding-knowledge/business/domains/{domain}/:

• cross-service.md → Relacionamentos de chamada entre repositórios e fluxo de dados

0.4 Aprendizado de Estilo (Passo Crítico)

A partir do symbols.md, localizar 2 a 3 arquivos de implementação existentes do mesmo tipo e usar a ferramenta de Leitura (Read) para ler o código-fonte completo. O objetivo é aprender os padrões de codificação do projeto, não apenas ver as assinaturas.

Detalhamento:

Camada de código a ser gerada	Objeto de referência no symbols.md	Pontos de aprendizado
Entity/Model	Classe Entity existente no mesmo repositório	Modo de uso de anotações, conversão de nomes de campos, herança de classe base, tratamento de campos de auditoria
Mapper/Repository	Mapper/Repository existente no mesmo repositório	MyBatis XML vs anotações, padrão de nomenclatura de métodos de consulta personalizados, implementação de paginação
Service	Classe Service existente no mesmo repositório	Modo de uso de anotações de transação, forma de lançar exceções, estilo de injeção de dependências (construtor vs @Autowired), hábitos de logging
Controller	Classe Controller existente no mesmo repositório	Empacotamento de valor de retorno unificado, anotações de validação de parâmetros, anotações de permissão, estilo de anotações Swagger
Camada de API front-end	Arquivo de API existente no mesmo projeto	Forma de encapsulamento do axios, interceptadores de requisição/resposta, tratamento de erros
Página front-end	Página de lista/formulário existente no mesmo projeto	Uso de bibliotecas de componentes, gerenciamento de estado, layout de condições de busca

O produto do aprendizado de estilo é uma "lista de verificação de codificação" implícita — não precisa ser exibida ao usuário, mas deve ser seguida ao gerar cada linha de código na Fase 2. Por exemplo:

• "Os Controllers deste projeto usam @RestController + @RequestMapping, nunca @Controller + @ResponseBody"
• "As exceções na camada Service são sempre lançadas com throw new BusinessException(ErrorCode.XXX), nunca retornando código de erro"
• "Todos os métodos de consulta são chamados listXxx/getXxx, nunca queryXxx/findXxx"

Fase 1: Gerar Plano (Confirmar com o Usuário)

Antes de escrever qualquer código, é obrigatório exibir um plano estruturado ao usuário e obter sua confirmação.

Com base nos resultados da análise da Fase 0, gerar um plano de geração estruturado:

## Plano de Geração de Código

### Referência de Estilo de Código
- Backend: {caminho do arquivo Controller/Service de referência localizado no symbols.md}
- Frontend: {caminho do componente de referência localizado a partir de páginas existentes}
- Padrões de Codificação: {restrições chave do coding-knowledge/infra/code-quality.md}

### Backend ({nome do repositório})
| # | Operação | Caminho do Arquivo | Descrição | Tarefa Correspondente |
|---|----------|--------------------|-----------|-----------------------|
| 1 | Novo | {caminho do pacote derivado do architecture.md}/XxxEntity.java | Nova classe de entidade | T-01 |
| 2 | Novo | {caminho do pacote}/XxxMapper.java | Nova interface Mapper | T-01 |
| 3 | Modificar | {caminho exato do arquivo localizado no symbols.md}:L{linha} | Novo método createXxx() | T-02 |
| 4 | Novo | {caminho do pacote}/XxxController.java | Nova interface CRUD | T-03 |

### Frontend ({nome do repositório})
| # | Operação | Caminho do Arquivo | Descrição | Tarefa Correspondente |
|---|----------|--------------------|-----------|-----------------------|
| 1 | Novo | src/api/xxx.js | Camada de chamada de API | T-05 |
| 2 | Novo | src/pages/xxx/index.vue | Página de lista (referência: prototype/list.html) | T-05 |
| 3 | Novo | src/pages/xxx/form.vue | Formulário de criação/edição | T-05 |

### Banco de Dados
- Executar o DDL do tech-design (estilo já verificado com database-schema.md)

### Observações
- {itens que precisam de confirmação do usuário}

Os caminhos de arquivo no plano devem ser precisos — não são caminhos chutados, mas sim derivados do architecture.md (estrutura de pacotes) e symbols.md (localização de arquivos existentes). Para operações de modificação de arquivos existentes, indicar o número da linha.

A Fase 2 só começa após a confirmação do usuário.

Fase 2: Gerar Código na Ordem de Dependências

Princípio de Geração: Gerar das camadas mais baixas para as mais altas, seguindo as dependências, garantindo que as referências estejam corretas. Cada arquivo é escrito imediatamente após a geração.

Ordem de Geração Backend

Seguir a ordem: Entity → Mapper/Repository → Service → Controller → Configuração/Outros:

1. Camada Entity/Model

• Gerar a classe de entidade com base no DDL do tech-design
• Padrão aprendido na Fase 0.4: forma de anotação de campos (JPA @Column vs MyBatis-Plus @TableField), herança de classe base (existe BaseEntity?), campos de auditoria (como createTime/updateTime são tratados?), campo de exclusão lógica
• Referência do database-schema.md: regras de conversão de nomes de campos (como create_time no banco → createTime em Java; alguns projetos usam @TableField("create_time"), outros contam com configuração global para conversão automática)

2. Camada Mapper/Repository

• Gerar a interface de acesso a dados correspondente à Entity
• Padrão aprendido na Fase 0.4: MyBatis XML vs anotações, herdar BaseMapper<T>? Regras de nomenclatura de métodos de consulta personalizados, forma de implementação de paginação (PageHelper? MyBatis-Plus IPage?)
• Incluir métodos de consulta personalizados mencionados no tech-design

3. Camada Service

• Implementar a lógica de negócio, correspondendo ao fluxo de processamento de cada interface no tech-design
• Padrão aprendido na Fase 0.4: modo de uso de anotações de transação (níveis de propagação do @Transactional), forma de tratamento de exceções (BusinessException personalizada? Enum ErrorCode unificado?), estilo de injeção de dependências (injeção por construtor vs @Autowired), hábitos de logging
• Derivar lógica de validação dos critérios de aceitação do PRD: cada condição de aceitação corresponde a um ramo de validação
• Chamadas entre serviços: a partir do call-chains.md, descobrir a forma real de chamada usada pelo projeto e replicar seu padrão de código (em vez de inventar uma nova forma de chamada)

4. Camada Controller

• Caminhos de interface, parâmetros e estrutura de resposta devem seguir rigorosamente o design de interfaces do tech-design
• Padrão aprendido na Fase 0.4: classe de empacotamento de valor de retorno unificada (Result<T>? ResponseEntity<T>?), anotações de validação de parâmetros (@Valid + JSR 303 vs validação manual), anotações de permissão (@PreAuthorize? @Permission personalizada?), estilo de anotações Swagger/OpenAPI
• Usar os códigos de erro de negócio definidos no tech-design

5. Configuração/Outros

• MQ Consumer/Producer (se o tech-design envolver) — a partir do call-chains.md, encontrar a forma de escrever código MQ existente
• Arquivos de configuração de menu/permissão (se necessário)
• Novas classes de constantes/enums

Ordem de Geração Frontend

Seguir a ordem: Camada de Chamada de API → Configuração de Rota → Componentes de Página:

1. Camada de Chamada de API

• Gerar métodos de API com base na lista de interfaces do tech-design
• Padrão aprendido na Fase 0.4: forma de encapsulamento do axios (função request unificada? arquivos de API independentes?), tratamento de interceptadores de requisição/resposta
• Nomes de métodos e parâmetros devem corresponder aos IDs das interfaces no tech-design

2. Configuração de Rota

• Registrar rotas para novas páginas
• Referenciar a forma de organização dos arquivos de rota existentes

3. Componentes de Página

• Referenciar a estrutura de páginas do prototype/: a ordem das colunas da tabela, o layout dos campos de busca e a estrutura dos modais no protótipo orientam diretamente o código do componente
• Usar a biblioteca de componentes real do projeto (a partir do coding-knowledge ou package.json, determinar se é Element UI / Ant Design / componentes próprios, etc.)
• A definição das colunas da tabela é derivada dos campos de resposta das interfaces no tech-design
• Os campos do formulário e as regras de validação são derivados dos parâmetros de requisição das interfaces no tech-design

Fluxo de Geração de Cada Arquivo

1. Se for um arquivo novo:
   • Verificar se o diretório alvo existe (usando ls)
   • Criar usando a ferramenta Write
2. Se for um arquivo a ser modificado:
   • Primeiro, ler o conteúdo completo do arquivo com Read
   • Usar Edit para fazer a modificação precisa (não reformatar o código ao redor)
3. Após a geração, escrever imediatamente no sistema de arquivos (não acumular para escrever tudo no final)

Fase 3: Gerar Relatório

Gerar o arquivo code-gen-report.md no diretório requirements/{modulo}/:

---
title: "{módulo} — Relatório de Geração de Código"
tech_design_version: "{versão do tech-design}"
date: "{data de geração}"
---

# {módulo} — Relatório de Geração de Código

## 1. Visão Geral da Geração

| Repositório | Arquivos Novos | Arquivos Modificados | Tarefas Correspondentes |
|-------------|----------------|----------------------|-------------------------|
| {nome do repositório} | {N} | {M} | T-01 ~ T-03 |

## 2. Referências de Estilo de Codificação

| Camada de Código | Arquivo Existente de Referência | Padrões Chave Aprendidos |
|-----------------|--------------------------------|--------------------------|
| Controller | {caminho do arquivo} | Retorno unificado Result<T>, uso de @Valid para validação |
| Service | {caminho do arquivo} | Injeção por construtor, tratamento de exceções com BusinessException |
| Entity | {caminho do arquivo} | Herda BaseEntity, anotação @TableField |

## 3. Lista de Arquivos

### {nome do repositório}

#### Arquivos Novos
| Caminho do Arquivo | Descrição | Tarefa do tech-design |
|--------------------|-----------|-----------------------|
| src/.../XxxEntity.java | Nova entidade | T-01 |

#### Arquivos Modificados
| Caminho do Arquivo | Conteúdo da Modificação | Tarefa do tech-design |
|--------------------|-------------------------|-----------------------|
| src/.../XxxService.java | Novo método createXxx() | T-02 |

## 4. Verificação de Cobertura de Requisitos

| Funcionalidade PRD | ID da Interface | Arquivo de Código | Cobertura dos Critérios de Aceitação |
|--------------------|-----------------|-------------------|---------------------------------------|
| F-01 | API-01, API-02 | XxxController.java | Cobertura total |
| F-02 | API-03 | XxxService.java | Cobertura parcial (item pendente Q-01 não implementado) |

## 5. Itens Não Cobertos

{Tarefas presentes no tech-design mas não geradas nesta iteração, e o motivo}

## 6. Observações

{Itens que precisam de tratamento manual pelo desenvolvedor, como:}
- Novos itens de configuração a serem adicionados no centro de configurações
- DDLs que precisam ser executados manualmente
- Lógica de negócio que precisa de confirmação humana
- Inconsistências encontradas entre o coding-knowledge e o tech-design

Fase 4: Resumo Final

Após a conclusão da geração, informar ao usuário:

1. Localização do relatório de geração de código
2. Número de arquivos criados/modificados (agrupados por repositório)
3. Cobertura das tarefas do tech-design
4. Itens que precisam de tratamento manual
5. Sugestão de usar /code-review para revisar o código gerado

Diretório de Saída

requirements/{modulo}/
├── prd-draft.md              ← Rascunho do PRD (entrada)
├── review/                   ← Saída do prd-review
├── prototype/                ← Saída do proto-gen
├── tech-design.md            ← Saída do tech-design (entrada)
└── code-gen-report.md        ← Saída deste skill

As alterações de código em si são escritas diretamente no diretório do repositório alvo (não dentro de requirements/).

Relação com Outros Skills

coding-knowledge-init                         ← Passo zero: mapa do projeto
  gera coding-knowledge/
        ↓ (referência)
project-import → knowledge-init → prd-draft → prd-review → proto-gen
                                                                ↓
                                              tech-design → code-gen → code-review
                                                             ↑
                                                     coding-knowledge/
                                                     (uso profundo)

• Pré-requisito: A solução técnica tech-design é a entrada principal; a base de conhecimento de codificação coding-knowledge-init é a referência central
• Próximo passo: As alterações de código geradas são revisadas por code-review
• Relação com o tech-design: O tech-design define "o que fazer" (design de interfaces, DDLs, decomposição de tarefas), enquanto o code-gen executa "como fazer" (gerar código real). Os IDs das interfaces (API-XX) e os IDs das tarefas (T-XX) no tech-design são os índices diretos do code-gen
• Relação com o coding-knowledge: O coding-knowledge é o "mentor de codificação" do code-gen:
  • symbols.md informa quais classes e métodos existem no projeto e onde encontrar referências do mesmo tipo
  • architecture.md informa onde colocar o novo código e qual camada seguir
  • database-schema.md informa qual estilo usar ao criar tabelas
  • call-chains.md informa como escrever chamadas entre serviços
  • infra/code-quality.md informa quais normas devem ser seguidas
  • É possível gerar código sem o coding-knowledge, mas o resultado degrada de "escrito por um veterano" para "escrito por um estagiário"

Modificação de Código Existente vs Nova Funcionalidade

A IA, com base no escopo de alterações do tech-design, decide automaticamente se cada arquivo é uma "modificação de código existente" ou um "arquivo novo", e adota estratégias de geração diferentes.

Regras de Ouro ao Modificar Código Existente

Altere apenas o que precisa ser alterado, não mexa no que não deve ser mexido. Este é o problema mais comum e grave em modificações de código existente — a IA, depois de ler o código existente, "aproveita" para refatorar a lógica ao redor, introduzindo bugs de regressão.

Requisitos específicos:

• Primeiro, leia o arquivo existente por completo com Read, entenda o contexto e só então aja
• Use Edit para fazer a modificação precisa, não use Write para sobrescrever o arquivo inteiro
• Não renomeie variáveis/métodos existentes, mesmo que ache que o nome não é bom — isso é assunto para outro requisito
• Não ajuste a formatação do código existente (indentação, linhas em branco, ordem de imports), a menos que seja adjacente ao código que você está adicionando
• Não "otimize" a lógica existente — se o tech-design diz "adicione uma validação no método createOrder", adicione apenas a validação, não altere a lógica existente de createOrder
• Ao adicionar um método, preste atenção à posição de inserção: siga a ordem de disposição dos métodos do projeto (ex.: CRUD, métodos públicos antes dos privados), inserindo em uma posição razoável

Critérios de Decisão

Sinal	Decisão	Estratégia de Geração
tech-design marca "modificar: XxxService:L120"	Modificar existente	Read → Edit com modificação precisa
tech-design marca "novo: {caminho do pacote}/XxxController.java"	Arquivo novo	Write com arquivo completo
tech-design marca "novo método createXxx()"	Adicionar em arquivo existente	Read → Edit para inserir na posição adequada

Princípios de Geração

Consistência de estilo é a prioridade número um: o código gerado deve parecer uma extensão natural do código existente no projeto. A abordagem não é "ler as normas e depois fazer do jeito que achar melhor", mas sim:

1. Encontrar, no symbols.md, arquivos de implementação existentes do mesmo tipo
2. Ler o código-fonte completo com Read e extrair os padrões de codificação
3. O novo código deve replicar rigorosamente esses padrões — mesmas combinações de anotações, mesma nomenclatura de métodos, mesma forma de tratamento de exceções

O tech-design é a fonte autoritativa: caminhos de interface, nomes de parâmetros, estrutura de resposta e códigos de erro devem seguir o tech-design, sem improvisações. Se achar que o tech-design tem algum problema (ex.: tipo de parâmetro inadequado), anote na seção "Observações" do relatório, mas o código ainda deve ser gerado de acordo com o tech-design.

O coding-knowledge é o mentor de codificação: quando surgir a dúvida "como devo escrever isso aqui?", a primeira reação deve ser consultar o coding-knowledge, não usar o conhecimento geral para adivinhar. Por exemplo:

• "Como a paginação é implementada neste projeto?" → Consultar métodos relacionados a paginação no symbols.md
• "Qual é a forma de chamada entre serviços?" → Consultar call-chains.md
• "Como lançar exceções?" → Consultar code-quality.md e a implementação de Service de referência

Não quebrar o código existente: ao modificar arquivos existentes, adicione/modifique apenas o código necessário, não reformate ou refatore o código ao redor. Use a ferramenta Edit para fazer a modificação precisa, não use Write para sobrescrever o arquivo inteiro.

Lógica de negócio deve ser completa: não gerar apenas assinaturas de métodos e comentários TODO, mas sim código com lógica de negócio completa. As regras de validação devem ser derivadas dos critérios de aceitação do PRD, e o fluxo de processamento deve ser derivado dos diagramas de sequência do tech-design.

Gerar em lotes, escrever imediatamente: seguir a ordem da Fase 2, gerar arquivo por arquivo e escrever cada um imediatamente após a geração. Não acumular para escrever tudo no final — se ocorrer um erro no meio do caminho, os arquivos já escritos não serão afetados.

Armadilhas Comuns

Pular o aprendizado de estilo e gerar diretamente: criar um novo Controller sem ler os Controllers existentes no projeto, resultando em combinações de anotações e empacotamento de retorno completamente diferentes. O aprendizado de estilo da Fase 0.4 não pode ser omitido.

Olhar apenas o symbols.md sem ler o código-fonte: o symbols.md contém apenas as assinaturas, não mostra os padrões de codificação dentro do corpo dos métodos (como transações são usadas, como exceções são lançadas, como logs são feitos). É obrigatório ler o código-fonte completo de 2 a 3 arquivos de referência.

Parâmetros de interface inconsistentes com o tech-design: o tech-design define knowledgeType, mas o código usa knowledge_type ou type. Os nomes de parâmetros devem seguir rigorosamente o tech-design.

Ignorar arquivos a serem modificados: o tech-design diz para modificar 3 arquivos, mas o code-gen modifica apenas 2. A lista do plano da Fase 1 deve cobrir completamente o escopo de alterações do tech-design.

Código frontend não referenciar o protótipo: a estrutura das páginas no prototype/ é a expressão visual do PRD. O código frontend deve referenciar o layout e a estrutura de componentes do protótipo, em vez de redesenhar a página.

Gerar apenas assinaturas, sem implementação: o corpo dos métodos Service gerados contém apenas // TODO: implement. O valor deste skill está em gerar a implementação completa da lógica de negócio, não em deixar espaços em branco para o desenvolvedor preencher.

"Aproveitar" para refatorar ao modificar código existente: ao modificar um método existente, adicione apenas a lógica necessária. Não renomeie variáveis, ajuste formatação de código ou otimize a lógica ao redor. Essas "melhorias" são a principal fonte de bugs de regressão.

Reimplementar lógica existente ao modificar código existente: o tech-design diz "adicione uma nova etapa de validação no fluxo existente", mas o code-gen reescreve todo o fluxo (incluindo a lógica já existente). O código incremental deve ser o único a ser adicionado; a lógica existente deve permanecer intacta.

Ignorar a anotação "não é responsável por" no coding-knowledge: o architecture.md diz "este serviço não é responsável por XXX", mas o código gerado inclui essa lógica. Antes de gerar o código, verifique os limites de responsabilidade do serviço.

Forma de chamada entre serviços inconsistente: o código existente do projeto usa Feign Client para chamar outros serviços, mas o código gerado usa RestTemplate. É obrigatório aprender a forma real de chamada a partir do call-chains.md ou do código de referência.