Ambientes de Desenvolvimento Nix

O que Ambientes de Desenvolvimento Nix faz?

Crie e mantenha ambientes de desenvolvimento de projetos usando Nix flakes, nixpkgs unstable, devenv e direnv. Mantenha a interface pública do flake pequena e coloque detalhes específicos do shell em arquivos Nix separados.

Contrato de interação

Trate a configuração Nix como política executável do projeto. Não a modifique nem a ative implicitamente.

1. Inspecione o repositório e explique as alterações propostas primeiro.
2. Peça uma aprovação explícita antes de criar, editar, renomear ou excluir arquivos. Agrupe edições relacionadas em uma única solicitação clara.
3. Após as edições serem aprovadas e concluídas, proponha comandos de validação e peça uma aprovação separada antes de executar qualquer um deles.
4. Não execute direnv allow sem mencioná-lo pelo nome e receber aprovação. Ele autoriza a avaliação automática da configuração do projeto.

Se o usuário recusar qualquer uma das aprovações, forneça apenas o plano ou os comandos e pare nesse limite.

Padrões e escopo

• Exija um flake para novos trabalhos. Use nixpkgs/nixos-unstable a menos que o projeto já fixe uma revisão diferente e o usuário peça para alterá-la.
• Suporte a todas as linguagens. Adicione pacotes de linguagem, formatadores, linters, serviços e variáveis de ambiente somente quando o projeto precisar deles.
• Prefira nix develop e devShells.<system>.default como a interface portátil.
• Use devenv por seus módulos, serviços, scripts, testes e hooks git declarativos quando esses recursos forem necessários. Não crie definições duplicadas tanto em um mkShell bruto quanto em devenv sem explicar qual é a autoritativa.
• Integre direnv através de um .envrc versionado apenas quando solicitado ou quando o projeto já o utiliza. Preserve as configurações de ambiente somente locais de um usuário.
• Nunca substitua ou exclua um shell.nix, flake.nix, .envrc, devenv.nix, lockfile ou configuração de CI existente apenas porque um layout mais novo é preferido.

Inspecione antes de propor alterações

Procure, no mínimo:

• flake.nix, flake.lock, shell.nix, default.nix e o diretório nix/
• devenv.nix, devenv.yaml e .envrc
• manifestos de linguagem e lockfiles, configuração de formatador/linter, executores de tarefas e fluxos de trabalho de CI
• documentação do projeto mencionando comandos de configuração ou plataformas suportadas

Leia as expressões Nix existentes antes de propor um layout. Determine se o projeto já possui um flake, quais sistemas ele suporta, como as dependências são fixadas, se devenv está instalado ou configurado e se direnv está intencionalmente excluído.

Quando um comando for útil para descoberta, prefira comandos somente leitura como nix flake metadata ou nix flake show. Peça permissão antes de executá-los se a execução do comando ainda não tiver sido aprovada pelo usuário.

Layout de arquivos

Para um repositório novo ou levemente configurado, proponha este layout, a menos que a convenção estabelecida do repositório seja melhor:

.
├── flake.nix
├── flake.lock
├── devenv.nix              # módulos e serviços específicos do devenv, quando usado
├── .envrc                  # ponto de entrada do direnv, quando usado
└── nix/
    └── devshell.nix        # pacotes, variáveis e hooks do shell

flake.nix deve conter inputs, a infraestrutura de sistemas suportados e os outputs exportados. Coloque argumentos mkShell, listas de pacotes, variáveis de ambiente e hooks do shell em nix/devshell.nix. Use mais arquivos focados em nix/ quando o shell crescer substancialmente, por exemplo nix/packages.nix ou nix/hooks.nix.

Não use shell.nix para novas configurações. Se um já existir, mantenha-o a menos que o usuário aprove explicitamente um plano de migração. Durante uma migração, explique as implicações de compatibilidade para usuários que ainda executam nix-shell.

Fluxo de trabalho de design

1. Declare a situação atual

Resuma os arquivos existentes relevantes, as ferramentas de projeto detectadas e quaisquer incertezas. Se os requisitos estiverem incompletos, faça perguntas direcionadas como:

• Quais plataformas devem ser suportadas (por exemplo, apenas Linux ou Linux e macOS)?
• Quais comandos do projeto devem funcionar dentro do shell?
• São necessários banco de dados ou outros serviços locais?
• O devenv deve ser o dono do ambiente, ou deve adicionar recursos em torno de um devShell?

2. Proponha uma implementação

Descreva exatamente quais arquivos serão adicionados ou alterados e por quê. Inclua se flake.lock será alterado, se .envrc será criado ou editado e qual fonte é a dona de cada dependência.

Para um novo flake de uso geral, use uma estratégia explícita de sistemas suportados e exponha devShells.<system>.default. Importe a expressão de shell separada em vez de colocar todo o corpo mkShell em flake.nix. Mantenha o conjunto inicial de pacotes mínimo: não adicione toolchains de linguagem arbitrários apenas para fazer o modelo parecer completo.

Se o usuário solicitar devenv, selecione uma integração compatível com a configuração de devenv instalada/versionada. Mantenha as declarações do devenv em devenv.nix (ou arquivos focados que ele importe). Deixe claro se os usuários entram com nix develop, devenv shell ou ambos, e garanta que os pontos de entrada documentados não divirjam silenciosamente.

Para direnv, use a convenção existente do projeto. Um .envrc baseado em flake geralmente depende do suporte nix-direnv; um .envrc baseado em devenv depende da integração apropriada do devenv. Não escreva um ponto de entrada cuja extensão direnv necessária não tenha sido identificada.

Trate estes como fatos separados: se nix-direnv está instalado, se está integrado com o direnv deste usuário e se o .envrc deste projeto é avaliado com sucesso. Não use direnv stdlib (ou a ausência de use flake em sua saída) como uma verificação de instalação: ele reflete a biblioteca padrão disponível para aquela invocação e não é autoritativo para a configuração declarativa do NixOS ou Home Manager. Em particular, um resultado vazio de direnv stdlib | grep -F 'use flake' não é evidência de que nix-direnv está ausente.

Quando a descoberta for aprovada, inspecione a evidência relevante sem exagerar o que ela prova:

• No NixOS ou com a configuração do Home Manager disponível, procure por programs.direnv.enable = true e programs.direnv.nix-direnv.enable = true (ou a configuração de módulo equivalente). Relate isso como configuração declarativa, não como prova de que o shell ativo o carregou.
• Verifique se nix-direnv e direnv estão disponíveis no ambiente atual e inspecione o direnvrc aplicável ou a configuração gerada do direnv quando acessível. Relate um executável indisponível ou arquivo de integração ausente como uma observação do ambiente atual, não uma afirmação sobre a configuração declarativa do usuário.
• Leia o .envrc do projeto para identificar sua extensão necessária. Use direnv status para inspecionar seu estado atual de autorização/carregamento. Não infira que um ponto de entrada use flake funciona até que tenha sido avaliado naquele projeto.

Somente após aprovação explícita, autorize e teste um .envrc do projeto. Mencione que direnv allow altera o estado de confiança; siga com direnv reload ou direnv exec . <comando-inofensivo> para exercitar a configuração. Se a avaliação não puder ser realizada, diga que a integração não foi verificada em vez de declarar nix-direnv desinstalado.

3. Obtenha aprovação para edição

Use uma solicitação de confirmação concisa semelhante a:

Vou adicionar nix/devshell.nix, atualizar flake.nix para exportar o dev shell padrão, adicionar/atualizar devenv.nix e .envrc, e gerar/atualizar flake.lock se a resolução de dependências exigir. Posso fazer essas edições?

Aguarde uma resposta afirmativa. Se o trabalho proposto for diferente do plano aprovado, pergunte novamente antes de fazer as edições adicionais.

4. Edite com cuidado

Preserve a formatação e as convenções de nomenclatura locais. Mantenha os comentários focados em restrições não óbvias em vez de reafirmar a sintaxe Nix. Fixe os inputs do flake através de flake.lock; não substitua URLs flutuantes por um lockfile.

Ao adicionar um pacote de shell, prefira o pacote fornecido pelo pkgs fixado do projeto. Evite pacotes não livres, permissões de pacotes inseguros, caches binários ou configuração de substituter, a menos que o usuário solicite e aprove explicitamente.

5. Proponha validação e obtenha aprovação separada

Após as edições, liste apenas os comandos relevantes, explique seu propósito e solicite aprovação. Selecione entre:

nix flake check
nix flake show
nix develop --command <comando-de-verificação-do-projeto-ou-versão-da-ferramenta>
devenv test
devenv shell -- <comando-de-verificação-do-projeto-ou-versão-da-ferramenta>
direnv allow

Use um comando inofensivo para verificação de entrada no shell quando possível, como --version de uma ferramenta necessária ou o modo de verificação de um formatador do projeto. Explique o acesso de rede esperado, compilações, downloads ou atualizações de lockfile antes de comandos que possam causá-los. Nunca execute nix flake update, coleta de lixo ampla, exclusão de armazenamento ou comandos de alteração de perfil, a menos que o usuário peça explicitamente.

6. Relate o resultado

Declare os arquivos alterados, o(s) comando(s) de entrada, os resultados da validação e qualquer etapa manual restante. Por exemplo, identifique se o usuário deve executar nix develop, devenv shell e/ou direnv allow após revisar .envrc.

Princípios de solução de problemas

• Reproduza e inspecione o erro real antes de alterar pins ou adicionar sobrescritas.
• Distinga falhas de avaliação, atributos ausentes, problemas de suporte de plataforma, falhas de compilação e problemas de dependência em tempo de execução.
• Verifique o input fixado e o atributo do pacote antes de assumir que um pacote unstable existe ou tem o nome esperado.
• Prefira uma correção pequena e documentada em vez de alterações globais na configuração Nix.
• Quando uma alteração puder afetar a reprodutibilidade ou todos os contribuidores, apresente alternativas e solicite aprovação antes de editar.

Critérios de conclusão

Considere a tarefa concluída somente quando a configuração estiver modular, o ponto de entrada declarado estiver documentado na resposta final, as verificações solicitadas tiverem passado ou seu resultado estiver claramente relatado, e cada edição e comando de validação tiver sido precedido pela aprovação necessária.