Ótima pergunta, tenho lidado com isso nas últimas semanas, e cheguei num ponto que tem me atendido bem.

Costumo dividir a documentação dos meus projetos nas seguintes partes:

1. Estilo de código
   Aqui ficam as regras de como a IA deve escrever código, padrão de nomenclatura de classes, funções e variáveis. Vai criar um novo ebdpoit? Divida nesses 3 arquivos: service, view e serializer. Vai criar uma tabela nova no banco de dados? Escreva o nome das tabelas e colunas em português brasileiro. Essas regras ficam num diretório docs/styleguide e com um arquivo pra cada área, como python, django e banco-de-dados
2. Decisões de arquitetura
   Na pasta docs/adr deixo uma lista de arquivos listando quais as decisões de arquitetura foram tomadas e porque. Usa redis pra filas e não Rabbitmq? Aqui é o local ideal para descrever o porquê.
3. Decisões de funcionalidades
   Na pasta docs/fdr deixo as principais decisões relacionadas à funcionalidades específicas. Tem uma integração com sistema legado que roda de forma assíncrona? Aqui é o local ideal pra explicar o porquê.
4. Diagramas
   Na pasta docs/diagrams ficam os principais diagramas do projeto, normalmente usando markdown e mermaid. C4, DER e alguns diagrams de fluxo ficam aqui.

Com essa estrutura, dá pra trazer bastante contexto pra IA antes dela começar a gerar código. Para novas funcionalidades, começamos escrevendo a FDR (Feature Description Record), junto com a própria IA, e com base nela a IA gera o código.

Se algo fugir das especificações, como por exemplo, a IA escreveu toda a implementação na view, podemos pedir pra ela revisar o styleguide e decisões de arquitetura e começar novamente.

A ideia dessa abordagem é trazer o máximo de decisões que normalmente estão espalhadas em diversos lugares, ou até mesmo decisões verbais que são passadas entre os membros do time, para dentro do repositório, visando facilitar esse processo de desenvolvimento mais focado em especificações do que em código fonte.

Exatamente, spec-driven development é o nome formal. Na prática é isso: quanto mais contexto você dá pro modelo antes de pedir código, melhor o resultado.

Sobre até onde vale detalhar: minha regra é focar no COMPORTAMENTO esperado, não na implementação. Tipo: "quando o usuário clica em X, acontece Y" em vez de "crie um onClick handler que chama a API". O modelo decide o como, você define o quê.

Se a spec está grande demais, provavelmente o escopo está grande demais. Quebra em pedaços menores.