new-feature
Desenha uma funcionalidade nova do Codehood em conversa com o humano, camada por camada, até virar um spec com plano de ação dividido em tarefas para sub-agentes. Use quando o humano pedir para desenhar, planejar ou especificar uma funcionalidade nova.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- new-feature
- description
- Desenha uma funcionalidade nova do Codehood em conversa com o humano, camada por camada, até virar um spec com plano de ação dividido em tarefas para sub-agentes. Use quando o humano pedir para desenhar, planejar ou especificar uma funcionalidade nova.
03 SKILL.md 正文
Nova funcionalidade
O objetivo é chegar a um entendimento comum com o humano e terminar com um
spec em dev/specs/to-do/<slug>.md que sub-agentes consigam executar sem
voltar a perguntar. Escreva o spec e a conversa em português. Código,
identificadores e comentários no código continuam em inglês.
1. Entender o problema
- Pergunte qual é o problema, quem usa (aluno, professor, CLI) e o cenário concreto de uso. Uma pergunta curta basta; não faça questionário.
- Leia os termos do
GLOSSARY.mde os modelos deprisma/schema.prismaligados ao tema. Procure specs parecidas emdev/specs/. Use o que existe (ex.: prender uma funcionalidade aCalendarEventem vez de criar outra noção de aula).
2. Propor antes de ouvir a solução do humano
Antes de o humano detalhar o que tinha em mente, proponha de 5 a 10 ideias agrupadas por eixo (mecanismo, antifraude, resultado...). Marque a recomendação com 🟢 e diga qual seria a v1. Isso dá ao humano algo para comparar e costuma revelar requisitos que ele não tinha dito.
Quando a ideia do humano tiver um furo, diga com 💩 e mostre o caso concreto que quebra. Em seguida, proponha o ajuste que preserva a intenção dele.
3. Decidir em camadas
Valide uma camada por vez, nesta ordem, e só passe para a próxima quando o humano aprovar a atual:
- Banco: modelos Prisma, com comentários
///e cascatas. - Entidades: schemas Zod em
src/core/schemas/, métodos do service além do CRUD. Siga os ADRs 0004 a 0006 e o RFCdev/rfc/como-criar-e-escrever-um-service.md. - REST e permissões: tabela de rotas e tabela papel × ação.
- Telas e fluxos: uma linha por tela, com quem acessa e o que faz.
- CLI: o que muda em
cli/(leiacli/AGENTS.mdantes). - Dados de dev: o que
src/db/bootstrap.tsprecisa semear para cada estado da funcionalidade.
Em cada rodada:
- Mostre o artefato concreto (trecho de schema, tabela), não só a descrição.
- No máximo 3 decisões
Dpor rodada, com opções e 🟢 na recomendada, mais perguntasQcurtas quando faltar informação. - Decida sozinho o que é pequeno e reversível e registre como
J, sem perguntar. - Antes de propor algo que depende de código existente, confira o código (rotas, como o service apaga, o que a CLI chama). Aponte consequências que o humano pode não ver, como uma cascata que apaga dados ou uma chave natural que não pode mudar.
- Termos novos de domínio: pergunte se entram no
GLOSSARY.md.
4. Escrever o spec
Arquivo dev/specs/to-do/<slug>.md, em português, no formato das specs
existentes (frontmatter type: spec, status, tags, relatedTo):
- Contexto: o problema em um parágrafo.
- Requisitos: numerados (
R1,R2...), agrupados pelas camadas da seção 3. Cada decisãoDeJda conversa vira um requisito; nenhuma pode ficar só na conversa. - Fora do escopo: o que foi discutido e ficou para depois.
- Plano de ação: tarefas numeradas (
T1,T2...), cada uma com: arquivos tocados, requisitos cobertos, dependências, modelo do sub-agente e critério de pronto verificável (teste que passa, comando que sai 0). - Critérios de aceite: o que o humano vai conferir no fim, com evidência (screenshot, saída de teste).
Mostre o spec ao humano e espere aprovação antes de executar.
5. Executar com sub-agentes
Você coordena: distribui as tarefas, revisa o resultado e roda as verificações. Não repasse a coordenação a um sub-agente.
Testes primeiro
Cada tarefa com lógica segue TDD, em três papéis:
- Projetista de testes (
opus). Um único agente para a funcionalidade inteira, reaproveitado entre tarefas comSendMessagepara manter o contexto do spec. Para cada tarefa, ele lista os casos de teste: entrada, resultado esperado e o requisitoRque o caso prova. Mantém só testes de regra de negócio que pegariam um bug real. Corta testes de getter, de framework, de forma de objeto já garantida pelo Zod e casos que repetem outro. - Escritor de testes (
haikuousonnet). Transforma a lista em código de teste e confirma que os testes falham pelo motivo certo. Usehaikuquando os casos forem diretos;sonnetquando o teste exigir montar cenário com várias entidades ou interagir com páginas. - Implementador (
sonnet). Faz os testes passarem sem editá-los. Se achar um teste errado, devolve para você com a justificativa em vez de mudar o teste.
Tarefas mecânicas sem regra de negócio (schema já aprovado, seed, glossário) pulam o projetista e vão direto ao implementador.
Histórias de usuário e e2e
Toda funcionalidade com tela ganha uma tarefa própria de histórias, feita por
um escritor de testes (sonnet) antes dos implementadores das telas. Ele lê
test/stories/README.md e docs/user-stories/README.md e:
- Escreve as histórias novas nos catálogos
docs/user-stories/<papel>.md. - Escreve um teste e2e por história em
test/stories/<papel>-<categoria>.test.ts, com o título da história, e confirma que ele falha porque a tela ainda não existe.
O objetivo do e2e é provar que a funcionalidade funciona de ponta a ponta com o menor número possível de histórias, não localizar um erro com precisão (isso é papel dos testes de service). Por isso:
- Uma história não precisa ser atômica. Ela percorre um fluxo inteiro do
usuário: primeiro os caminhos errados e as validações (código expirado,
campo vazio, acesso negado), cada um num
test.step, e por fim o caminho feliz. - Prefira poucas histórias longas a muitas curtas. Junte numa só tudo o que o mesmo usuário faz em sequência.
- Arrume o cenário pelos services, aja pela interface, como manda o README.
Os implementadores das telas recebem essas histórias como critério de pronto.
Modelos
Escolha do modelo por tarefa:
| Modelo | Quando |
|---|---|
haiku |
Mecânico e totalmente especificado: migração de schema já aprovado, seed, glossário, changelog. |
sonnet |
Lógica de service, permissões, endpoints, telas, testes, mudanças na CLI. |
-
Dê a cada sub-agente o caminho do spec, os requisitos e a tarefa
Tdele, os arquivos que pode tocar e o critério de pronto. Ele não vê a conversa. -
Mande o sub-agente ler, antes de começar, os guias das partes que a tarefa toca:
Se a tarefa toca Leia src/db/,src/core/schemas/ADRs 0004 a 0006, RFC como-criar-e-escrever-um-servicesrc/api/ADRs 0007 e 0008, src/api/README.mdrotas e páginas de curso src/urls/README.mdsrc/commands/src/commands/README.mdtest/stories/test/stories/README.mdcli/cli/AGENTS.mdecli/README.md -
Rode em paralelo só as tarefas sem dependência entre si e sem arquivos em comum. Se precisarem de isolamento, use
isolation: "worktree". -
Ao receber cada resultado, confira o diff e rode o critério de pronto antes de liberar as tarefas que dependem dela.
-
No fim:
pnpm exec biome check --write .,pnpm run lint, os testes afetados, seed conferido no dev server. Depois mova o spec paradev/specs/to-review/e registre noCHANGELOG.md.
04 同仓库更多 Skills
unslop
Cut AI tells from any writing. Must always apply.
python-publish
Guidelines to publish Python packages
python-projects
Style and good practices when implementing Python projects
python-paths
Good practices when working with file paths in Python
python-modules
Style and good practices when implementing or refactoring Python modules
python-functions
Style and good practices when implementing or refactoring Python functions and methods