desenvolvimento-padroes

Padrões de Desenvolvimento / 开发要求与编码规范

Um skill, um fluxo de trabalho, dois idiomas de recurso. / 一个技能、一套流程、两种资源语言。

Revisão de recurso pareada / 双语资源配对修订：2026-10-05.9. Isso identifica o pacote de recursos, não aprovação de projeto ou verificação aprovada. / 仅标识资源包，不代表项目批准或验证通过。

Seleção de Idioma / 语言选择

• Escolha o idioma de instrução com base na preferência explícita do usuário; caso contrário, use zh-CN para solicitações em chinês e en para solicitações em inglês. Para outros idiomas, use recursos em inglês e responda no idioma do usuário. Não infira o idioma a partir de metadados da interface ou do idioma dos arquivos de origem. 规则语言优先遵循用户明确偏好，否则中文请求选 zh-CN、英文请求选 en；其他语言使用英文资源并以用户语言沟通。不根据界面配置或源文件语言推断用户偏好。
• Para conversas, siga o idioma solicitado pelo usuário, caso contrário, a solicitação atual. Para cada documento, use o idioma solicitado explicitamente; caso contrário, a convenção de documentação existente do projeto; caso contrário, o idioma da conversa. Use o modelo correspondente; para outros idiomas, adapte um modelo em inglês. Não traduza arquivos não relacionados nem renomeie identificadores de código como efeito colateral. 对话优先遵循用户指定语言，否则跟随当前请求；每份文档优先遵循明确指定的语言，再遵循项目已有文档语言约定，最后跟随对话语言。使用相应模板，其他语言可基于英文模板调整；不顺带翻译无关文件或重命名代码标识符。
• Antes de iniciar uma tarefa, leia exatamente uma linha de base correspondente abaixo e, em seguida, apenas suas referências relevantes para a tarefa. O idioma solicitado para um documento pode ser diferente do idioma da instrução; não carregue ambos os conjuntos completos de recursos apenas por esse motivo. 开始任务工作前读取下方一种语言的核心规范，再按需加载其中相关参考。文档目标语言可与规则语言不同，不因此加载两套完整资源。

Linha de Base / 核心规范	Quando ler / 读取条件
Normas em Chinês	Idioma de instrução em chinês / 规则语言为中文
Padrões em Inglês	Idioma de instrução em inglês ou substituto / 规则语言为英文或使用英文回退

Invariantes Compartilhados / 共同约束

• Para desenvolvimento formal, aprove os requisitos primeiro, depois o design completo do módulo/arquitetura para o escopo de implementação atual; novos projetos também exigem confirmação explícita da pilha de tecnologia. A aprovação parcial cobre apenas o escopo identificado; dependências necessárias também devem ser aprovadas, não incluídas implicitamente. Não implemente ou crie andaimes antes que as portas aplicáveis sejam aprovadas. Reutilize aprovações autênticas e aplicáveis; nunca as fabrique. 正式开发先确认需求，再确认本次实施范围的完整模块架构；新项目还须明确确认技术栈。部分确认仅覆盖指定范围，必要依赖也须已确认，不自动扩大批准。适用门槛未通过前不实施或初始化工程；复用真实有效确认，不伪造批准。
• Durante o design da arquitetura, módulos complexos exigem diagramas de arquitetura e fluxos de trabalho complexos exigem fluxogramas, salvos com o design e consistentes com as descrições do módulo/interface. A falta de diagramas necessários deixa esse escopo incompleto; diagramas não substituem contratos nem adicionam uma etapa de aprovação. Designs simples e tarefas somente leitura/leves não exigem preenchimento retroativo de diagramas de todo o projeto. 架构设计阶段，复杂模块必须用架构图、复杂流程必须用流程图表示，随设计文档保存并与模块/接口说明一致。缺少必需图示时对应范围设计不完整；图不替代契约、不新增审批。简单设计及只读/轻量任务不要求补画全项目图。
• Quando o design da interface for necessário, entregue três protótipos visuais HTML genuinamente distintos, visualizáveis no navegador, para os mesmos requisitos de escopo e telas representativas, priorizando estética, layout, tipografia e hierarquia visual. HTML/CSS estático é suficiente; JavaScript e demonstrações de interação são opcionais, a menos que explicitamente solicitados. Forneça entradas e resultados reais da verificação de renderização, registre os trade-offs e a seleção do usuário antes da implementação formal. O trabalho de design isolado não ignora as portas de requisitos/pilha/arquitetura nem autoriza serviços ao vivo. Reutilize seleções válidas e aplicáveis; revisões somente leitura e reparos que preservam o design estabelecido não forçam a reseleção. 涉及界面设计时，基于相同范围需求和代表性页面交付 3 套有实质差异、浏览器可查看的 HTML 视觉原型，重点关注美观、布局、排版及视觉层级。静态 HTML/CSS 示意页面即可，JS 与轻量交互默认可选；用户明确要求交互演示时按指定范围实现。提供入口及真实渲染检查结果，记录取舍和用户选择后再正式实施。隔离设计不绕过需求/技术栈/架构门槛，也不授权真实服务操作；复用有效且适用的既有选择，只读评审及保持既定设计的修复不强制重选。
• No início da codificação, verifique se a implementação no escopo usa um banco de dados. Em caso afirmativo, produza e salve seu design antes do código relacionado ao banco de dados: proponha um novo banco de dados ou inspecione e reutilize/atualize o design existente, padronizando para docs/database-design.md. Sem banco de dados significa sem documento de banco de dados. Isso é um entregável de codificação, não um pré-requisito de aprovação de arquitetura ou etapa de aprovação extra. As salvaguardas aplicáveis de mudança de escopo e operação de dados ainda se aplicam; trabalho somente leitura não autoriza edições. 开始编码时检查本次实现是否使用数据库；涉及时，数据库相关代码前必须输出并保存设计，默认 docs/database-design.md：新库给出方案，已有库先核对并复用/更新现有设计。不使用数据库则不生成该文档。它是编码阶段交付物，不是架构批准的前置附件，不增加审批阶段；仍遵守范围变更和数据操作安全要求，只读工作不授权编辑。
• Cada alteração completa no código do projeto, incluindo correções de bugs e refatorações, deve incrementar a versão do produto afetado sob seu esquema estabelecido. Atualize a fonte de versão real e as entradas sincronizadas necessárias antes da entrega, relatando valores e locais antigos/novos. Conte uma alteração completa, não cada edição de arquivo ou nova tentativa. Trabalho puramente de documentação/somente leitura não aciona um incremento de produto; esquemas pouco claros ou conflitos de autoridade exigem esclarecimento. Incrementos de versão não autorizam lançamento nem dispensam requisitos de compatibilidade. 每次完整的项目代码变更，包括 Bug 修复和重构，都必须按既有规则递增受影响产品版本；交付前更新真实版本入口及必要同步项，报告旧值、新值和位置。按完整变更计数，不按文件编辑或重试次数；纯文档/只读工作不触发产品升版，规则不明或授权冲突时先澄清。升版不授权发布，也不豁免兼容要求。
• Reparos localizados de baixo risco qualificados restauram a intenção clara; refatorações que preservam o comportamento qualificadas retêm comportamento observável, erros e efeitos colaterais. Ambos permanecem dentro do escopo autorizado sem novos recursos, mudanças de contrato/limite ou efeitos de alto risco. Declare o objetivo, evidência, escopo e plano de verificação; não force preenchimento retroativo de documentação histórica do produto ou aprovação redundante. Esclareça ambiguidades e escale o trabalho afetado quando o escopo ou risco aumentar. 合格低风险局部修复恢复明确预期，行为保持重构保留可观察行为、异常和副作用；均限于授权范围，不新增功能、改变契约/边界或涉及高风险。简述目标、依据、范围和验证方式，不追补历史产品文档或重复审批；有歧义先澄清，范围或风险扩大时升级受影响流程。
• Para produtos Cliente/Servidor, as alterações no Servidor devem preservar os protocolos, interfaces, semântica de campos e fluxos de trabalho principais dos Agentes de produtos mais antigos, sem atualizações forçadas de Agentes. O escopo de compatibilidade do usuário/projeto e evidências reais de Agentes mais antigos são necessários para interações afetadas. Incompatibilidade, falha ou falta de verificação bloqueiam merge/lançamento, não apenas um aviso. Agente aqui é um cliente de software, não um LLM. 对客户端/Server 产品，服务端改动须保持低版本产品 Agent 的协议、接口、字段语义及核心流程，不强制升级 Agent。涉及交互时遵循用户/项目兼容范围并提供实际低版本证据；不兼容、验证失败或缺失阻断合并发布。Agent 指软件客户端，不是大模型。
• Preserve o escopo do usuário, regras do repositório e instruções de prioridade mais alta. Solicitações somente leitura não autorizam edições. Aprovação não concede permissões de commit, push, PR, implantação, dados de produção ou gravação externa não relacionadas. Relate evidências reais e trabalho não verificado; auto-revisão não é revisão independente. 遵守用户范围、仓库规则及更高优先级指令；只读请求不授权编辑，批准不授予无关提交、推送、PR、部署、生产数据或外部写入权限。按实际证据报告未验证项，自审不冒充独立审查。

Manutenção de Tradução / 翻译维护

Termo / 术语	Significado / 含义
Obrigatório / 必须	Obrigação aplicável, não uma sugestão / 适用时须满足，不是建议
Não deve / 不得	Ação proibida / 禁止的操作
Recomendado / 建议	Preferido, com adaptação justificada permitida / 优先采用，可按依据调整
Aprovado / 已确认	Aprovação autêntica de conteúdo e escopo identificados / 真实确认指定内容与范围
Verificado / 已验证	Verificações relevantes realmente aprovadas, não aprovação ou implantação / 相关检查实际通过，不等于批准或部署

references/zh-CN e assets/zh-CN são as fontes de regras/modelos em chinês; os arquivos en correspondentes são traduções, não políticas independentes. Ao atualizar, sincronize os arquivos correspondentes, links, READMEs e cenários comportamentais afetados; avance a revisão pareada do pacote neste ponto de entrada, em ambos os READMEs e nos cabeçalhos de recursos. Uma revisão correspondente não é prova de equivalência semântica. Mantenha os termos acima, modos de tarefa, restrições de segurança e padrões de evidência equivalentes. A simples troca de idioma não invalida aprovações nem autoriza trabalho. Se uma discrepância for descoberta, relate-a e consulte apenas a fonte chinesa afetada; não selecione silenciosamente uma tradução mais fraca. Se a fonte não puder ser verificada, divulgue a incerteza e não afirme que a porta afetada foi aprovada. Instruções de prioridade mais alta permanecem controladoras.

references/zh-CN 和 assets/zh-CN 是中文规则/模板源，同名 en 文件是译文，不是独立政策。修改时同步对应文件、链接、README 及受影响行为场景，并更新入口、两份 README 和资源头部的配对修订标识；标识一致不证明语义等价。保持上表术语、任务模式、安全约束和证据标准等价。仅切换语言不使批准失效或授予实施权限。发现差异时报告并仅核对受影响中文源，不静默选择更宽松译文；源文无法核验时说明不确定性，不声称相关门槛已通过。更高优先级指令始终优先。