Como integrar e usar o impeccable

10 de jun. de 2026

Como integrar e usar o impeccable

Na verdade, não é nada muito complexo — é apenas integrar uma ferramenta de design ao projeto HagiCode, o que pode ser considerado uma solução completa — incluindo estrutura do repositório, fluxo de trabalho multilíngue e manutenção de conteúdo, tudo isso foi sendo desenvolvido gradualmente na prática.

Contexto

Quando se trata de qualidade de design de UI/UX no desenvolvimento de software, é realmente importante, afinal, pode determinar diretamente a experiência do usuário do produto e o sucesso comercial. No entanto, nos processos de desenvolvimento tradicionais, sempre existe uma barreira invisível entre designers e desenvolvedores: os designers criam mockups estáticos incríveis, os desenvolvedores se esforçam para implementá-los, mas sempre acabam ocorrendo certas discrepâncias em alguns detalhes. Essa fragmentação faz com que seja difícil para o produto final corresponder completamente à visão de design, e os custos de iteração acabam aumentando consideravelmente.

Ao desenvolver aplicativos desktop e produtos web, o projeto HagiCode também precisa de suporte profissional de design UI/UX, ao mesmo tempo em que exige colaboração estreita entre design e implementação de código. Para isso, introduzimos a ferramenta impeccable — uma ferramenta profissional de design e otimização de interface frontend impulsionada por IA. O impeccable não apenas fornece orientação de design, mas também pode lidar diretamente com a implementação de código, preenchendo parcialmente a lacuna entre design e desenvolvimento.

Para que o impeccable possa ser efetivamente integrado e usado no monorepo do HagiCode, precisamos estabelecer métodos de integração padronizados, processos de documentação e normas de manutenção. Isso inclui instalação e configuração da ferramenta, integração de habilidades, construção do site de documentação e melhores práticas de colaboração em equipe.

Sobre o HagiCode

A solução compartilhada neste artigo vem da nossa experiência prática no projeto HagiCode. HagiCode é um projeto de assistente de código IA que oferece duas formas: web e desktop, ajudando desenvolvedores a melhorar a eficiência de codificação. Durante o processo de desenvolvimento, precisamos de ferramentas de design de alta qualidade para apoiar a construção de UI/UX do produto, e foi nesse contexto que o impeccable foi introduzido ao projeto.

Análise da arquitetura técnica

Design impulsionado por habilidades do impeccable

O impeccable adota uma arquitetura de design impulsionada por habilidades, definindo o contexto e o comportamento de diferentes tarefas de design através de arquivos de habilidades padronizados. No projeto HagiCode, o impeccable é integrado na forma de pacote de habilidades npm, sendo usado principalmente das seguintes maneiras:

1. Estrutura de arquivo de habilidades: /home/newbe36524/.agents/skills/impeccable/SKILL.md define a configuração completa de habilidades, incluindo conjunto de comandos, permissões de ferramentas, sugestões de parâmetros e informações de licença.

2. Sistema de classificação de comandos: O impeccable divide as tarefas de design em seis categorias principais:

   • Build: Comandos de construção (craft, shape, teach, document, extract)
   • Evaluate: Comandos de avaliação (critique, audit)
   • Refine: Comandos de otimização (polish, bolder, quieter, distill, harden, onboard)
   • Enhance: Comandos de melhoria (animate, colorize, typeset, layout, delight, overdrive)
   • Fix: Comandos de correção (clarify, adapt, optimize)
   • Iterate: Comandos de iteração (live)

Análise de requisitos do site de documentação

Para apoiar a equipe no uso do impeccable, o HagiCode estabeleceu um site de documentação independente impeccable-site, que precisa atender aos seguintes requisitos:

• Suporte multilíngue: Fornecer documentação completa em inglês e chinês, atendendo às necessidades de equipes internacionais
• Catálogo de comandos: Exibir todos os comandos de forma normalizada, incluindo classificação, descrição e links de referência
• Conteúdo localizado: Manter guias de uso e melhores práticas específicos do HagiCode
• Geração estática: Usar Astro para construir sites estáticos, facilitando a implantação e acesso

Desafios de integração

Durante o processo de integração, enfrentamos os seguintes desafios:

1. Sincronização do código-fonte: O repositório upstream do impeccable contém o código completo da ferramenta e a documentação, mas é necessário integrar seletivamente a parte de documentação, evitando depender de toda a base de código da ferramenta

2. Manutenção de conteúdo: É necessário manter o conteúdo localizado e os guias de uso enquanto mantém a sincronização com as atualizações upstream

3. Fluxo de build: Estabelecer processos automatizados de sincronização de conteúdo, geração de catálogo e build do site

4. Fluxo de trabalho multilíngue: Projetar processos eficientes de tradução e manutenção de localização

Design da solução

Design da estrutura do repositório

Integrar o repositório upstream do impeccable através do mecanismo de Git submodule:

[submodule "vendor/impeccable"]
    path = vendor/impeccable
    url = https://github.com/pbakaus/impeccable.git

As vantagens deste design incluem:

• Controle de versão: É possível controlar com precisão a versão upstream, evitando problemas causados por atualizações inesperadas
• Integração leve: Apenas buscar o código-fonte necessário, evitando introduzir dependências desnecessárias
• Atualização flexível: É possível atualizar seletivamente o conteúdo upstream

Design do modelo de conteúdo

Adotar um modelo de conteúdo em camadas:

1. Código-fonte upstream: vendor/impeccable/ - Fornece definições originais de comandos e documentação de referência
2. Conteúdo localizado: src/content/commands/ - Mantém explicações de comandos em chinês e inglês
3. Texto de UI compartilhado: src/i18n/locales/ - Gerencia texto multilíngue da interface do site
4. Catálogo gerado: src/lib/generated/command-catalog.json - Catálogo de comandos gerado durante o build

Otimização do fluxo de build

Projetar um fluxo de build automatizado, integrando várias etapas através de scripts npm:

{
  "scripts": {
    "prepare": "npm run i18n:generate && npm run catalog:generate",
    "i18n:generate": "node scripts/generate-i18n-resources.mjs",
    "catalog:generate": "node scripts/build-command-catalog.mjs",
    "content:sync:vendor": "node scripts/sync-vendor-command-content.mjs",
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

O fluxo de build é dividido em quatro fases:

1. Fase de preparação: Gerar recursos multilíngues e catálogo de comandos
2. Sincronização de conteúdo: Sincronizar conteúdo de comandos do upstream para local
3. Fase de validação: Verificar integridade do conteúdo e correção do build
4. Saída de build: Gerar arquivos de site estático

Fluxo de trabalho multilíngue

Estabelecer um fluxo de trabalho multilíngue padronizado baseado na ferramenta hagi18n:

localesRoot: src/i18n/locales
repoRoot: .
baseLocale: en-US
targetLocales:
  - zh-CN

Fornecer scripts de manutenção completos:

• i18n:audit - Verificar integridade da tradução
• i18n:sync - Sincronizar entradas de tradução
• i18n:prune - Limpar traduções obsoletas
• i18n:doctor - Diagnosticar problemas de tradução

Guia prático

Configuração inicial

Primeiro, inicialize o submodule e instale as dependências:

# Entre no diretório raiz do monorepo
cd /home/newbe36524/repos/hagicode-mono

# Inicialize o submodule
git submodule update --init --recursive

# Entre no diretório impeccable-site
cd repos/impeccable-site

# Instale as dependências
env -u NPM_CONFIG_PREFIX npm install

Esta etapa é a base de todo o processo de integração. A falha na inicialização do submodule impede que todas as etapas subsequentes sejam realizadas. O HagiCode encontrou este problema na primeira integração e, posteriormente, esclareceu as etapas de inicialização na documentação.

Fluxo de desenvolvimento diário

Execute comandos de desenvolvimento diários no diretório repos/impeccable-site:

# Inicie o servidor de desenvolvimento
env -u NPM_CONFIG_PREFIX npm run dev

# Verificação de tipos
env -u NPM_CONFIG_PREFIX npm run typecheck

# Execute testes
env -u NPM_CONFIG_PREFIX npm test

# Construa o site
env -u NPM_CONFIG_PREFIX npm run build

# Validação completa
env -u NPM_CONFIG_PREFIX npm run validate

O servidor de desenvolvimento é executado por padrão em http://localhost:31266, e a porta pode ser personalizada através da variável de ambiente PORT_IMPECCABLE_SITE. Durante o processo de desenvolvimento, os membros da equipe HagiCode descobriram que, ao alternar com frequência entre diferentes ambientes de idioma, o uso de um comando de prefixo unificado pode evitar problemas de poluição de variáveis de ambiente.

Estratégia de manutenção de conteúdo

Ao adicionar ou atualizar a documentação de comandos, é necessário criar os arquivos correspondentes nos dois diretórios de idioma:

# Documentação de comando em inglês
src/content/commands/en-US/polish.mdx

# Documentação de comando em chinês
src/content/commands/zh-CN/polish.mdx

Cada arquivo MDX precisa conter metadados de frontmatter:

---
title: "Polish"
slug: "polish"
seoTitle: "Polish Command - Impeccable"
seoDescription: "Final quality pass before shipping with impeccable polish command"
routeSlug: "polish"
highlights:
  - "Visual hierarchy review"
  - "Spacing and typography optimization"
  - "Accessibility validation"
related:
  - "audit"
  - "critique"
---

Sincronização de conteúdo upstream

Quando o upstream do impeccable for atualizado, é necessário sincronizar o conteúdo mais recente dos comandos:

# Atualize o submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# Sincronize o conteúdo dos comandos
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# Sincronize um único comando
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# Regere o catálogo
env -u NPM_CONFIG_PREFIX npm run catalog:generate

O script de sincronização lê o conteúdo dos comandos upstream de vendor/impeccable/site/content/skills/ e o copia para o diretório src/content/commands/en-US/. Na prática, a equipe HagiCode descobriu que, após cada sincronização, é necessário regerar o catálogo de comandos, caso contrário, ocorrerão problemas de inconsistência de conteúdo.

Manutenção multilíngue

Mantenha o texto multilíngue da interface do site:

# Verifique a integridade da tradução
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# Sincronize entradas de tradução
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# Limpe traduções obsoletas
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# Diagnostique problemas de tradução
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

Os arquivos de tradução estão localizados no diretório src/i18n/locales/:

src/i18n/locales/
├── en-US/
│   ├── common.yml
│   └── docs.yml
└── zh-CN/
    ├── common.yml
    └── docs.yml

Exemplo de arquivo YAML:

src/i18n/locales/en-US/docs.yml

commands:
  title: "Commands"
  subtitle: "Explore the complete command surface"
  overview: "Overview"
  related: "Related Commands"

# src/i18n/locales/zh-CN/docs.yml
commands:
  title: "命令"
  subtitle: "探索完整的命令集"
  overview: "概览"
  related: "相关命令"

Usando comandos do impeccable

No projeto HagiCode, você pode chamar comandos do impeccable das seguintes maneiras:

# Desenhar novos recursos
npx impeccable craft "user settings page"

# Planejar UI/UX
npx impeccable shape "checkout flow"

# Configurar contexto do projeto
npx impeccable teach

# Gerar documentação de design
npx impeccable document

# Revisar qualidade do design
npx impeccable critique "landing page"

# Verificação de qualidade técnica
npx impeccable audit "navigation component"

# Otimização final
npx impeccable polish "onboarding flow"

# Iteração de design em tempo real
npx impeccable live

Cada comando tem um propósito específico e documentação de referência. Por exemplo, o comando craft é usado para construir recursos de ponta a ponta, incluindo planejamento de UX/UI e implementação de código; o comando audit é usado para verificação de qualidade técnica, incluindo acessibilidade, desempenho e design responsivo. Durante o processo de desenvolvimento, esses comandos tornaram-se parte do fluxo de desenvolvimento diário da equipe HagiCode.

Validação de implantação

Realize uma validação completa antes da implantação:

# Execute o processo de validação completo
env -u NPM_CONFIG_PREFIX npm run validate

O processo de validação verifica:

• Se o caminho do vendor está correto
• Se todos os comandos têm conteúdo correspondente nos diretórios chinês e inglês
• Se os recursos multilíngues gerados são os mais recentes
• Se o catálogo de comandos está atualizado
• Se as rotas do Astro são compiladas corretamente
• Se a saída estática foi construída com sucesso

Considerações importantes e melhores práticas

Considerações importantes

1. Atualização do Submodule: Após atualizar o submodule, é necessário regerar os recursos derivados e fazer o commit. A equipe HagiCode encontrou uma vez uma situação em que esqueceram de regerar os recursos e fizeram o commit diretamente, o que causou problemas de inconsistência de conteúdo no site online.

2. Paridade de idioma: Certifique-se de que todos os comandos tenham conteúdo correspondente nos diretórios chinês e inglês, caso contrário, o build falhará. Esta verificação já está integrada no processo de validação, permitindo identificar problemas no início do desenvolvimento.

3. Proxy frontend: O impeccable-site é proxy através do script de desenvolvimento de sites estáticos no diretório raiz do monorepo:

# Inicie a partir do diretório raiz do monorepo
npm run dev:static-sites

4. Implantação de produção: O site de produção é implantado em https://impeccable.hagicode.com, com implantação automatizada através do GitHub Actions. O HagiCode adotou um processo de CI/CD totalmente automatizado, garantindo que cada commit possa ser implantado automaticamente.

5. Links de documentação de comandos: Ao selecionar comandos do impeccable no UI Master do frontend web, os links de documentação correspondentes são exibidos, com o formato:

https://impeccable.hagicode.com/{lang}/commands/{command-name}

Resumo das melhores práticas

1. Sincronização regular do upstream: Acompanhe as atualizações do upstream do impeccable e sincronize regularmente novos comandos e melhorias. A equipe HagiCode adota uma frequência de sincronização semanal, garantindo que não perca atualizações importantes.

2. Manutenção de conteúdo localizado: Após sincronizar o conteúdo upstream, atualize prontamente a documentação em chinês e inglês, garantindo a precisão e atualidade do conteúdo.

3. Controle de versão: Após atualizar o submodule, valide o resultado do build antes de enviar para o sistema de controle de versão.

4. Colaboração em equipe: Através de um fluxo de trabalho multilíngue padronizado, apoie a colaboração dos membros da equipe na manutenção do conteúdo da documentação.

5. Garantia de qualidade: Execute o processo de validação completo após cada atualização de conteúdo para garantir a correção do site.

6. Uso de categorias de comandos: Escolha a categoria de comando adequada de acordo com diferentes estágios da tarefa de design:

   • Use craft ou shape ao projetar novos recursos
   • Use critique ou audit ao revisar designs existentes
   • Use polish, bolder ou quieter ao otimizar a qualidade do design
   • Use animate, colorize ou delight ao melhorar efeitos visuais
   • Use clarify, adapt ou optimize ao corrigir problemas
   • Use live ao iterar em tempo real

7. Gerenciamento de contexto: Antes de usar o comando craft, certifique-se de ter definido os arquivos de contexto PRODUCT.md e DESIGN.md do projeto através do comando teach.

Resumo

Através dos métodos de integração e uso acima, o projeto HagiCode pode usar efetivamente a capacidade de design profissional da ferramenta impeccable, melhorando a qualidade de UI/UX do produto, ao mesmo tempo em que estabelece um processo de manutenção de documentação padronizado, apoiando a colaboração de longo prazo e o desenvolvimento da equipe.

A solução compartilhada neste artigo foi desenvolvida pelo HagiCode através de múltiplas iterações e otimizações no desenvolvimento real. Ela não apenas resolve o problema de colaboração entre design e desenvolvimento, mas também estabelece um sistema de documentação extensível, fornecendo referência para a integração de outras ferramentas.

Se você também enfrenta problemas semelhantes de colaboração design-desenvolvimento em sua equipe, espero que as práticas compartilhadas neste artigo sejam inspiradoras para você. A ideia central desta solução é: estabelecer processos padronizados, manter a sincronização com o upstream, focar na manutenção de localização e apoiar a colaboração em equipe.

Resumo

Em torno de “como integrar e usar o impeccable”, uma maneira mais segura de avançar é primeiro fazer funcionar gradualmente a configuração chave, os limites de dependência e o caminho de implementação, e depois preencher os detalhes de otimização.

Quando os objetivos, etapas e pontos de aceitação estiverem claros, este tipo de solução geralmente pode entrar mais suavemente na entrega real.

Tags:

• impeccable
• design
• integration
• workflow

O que é MonoSpecs: por que é uma atualização e extensão do OpenSpec

Otimizando a eficácia de cada etapa do OpenSpec com diferentes Agentes: resumo da prática do HagiCode