Curso completo: desenvolvimento orientado a especificações com agentes de programação

Ver no idioma original →

Autoria: DeepLearningAI · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: Full Course: Spec-Driven Development with Coding Agents · Canal: DeepLearningAI · 1:01:07 · Assistir no YouTube

Tópicos: Agentes de IA, Engenharia de prompts e contexto, Engenharia de software com IA, Ferramentas de desenvolvimento com IA

Resumo

O curso apresenta o desenvolvimento orientado a especificações como um fluxo de trabalho para construir software com agentes de programação, mantendo as decisões e intenções documentadas em arquivos persistentes. O processo inclui definir uma constituição do projeto, planejar cada funcionalidade, implementar em etapas e validar os resultados com participação humana. O instrutor também mostra como adaptar o fluxo a projetos existentes, automatizar tarefas com skills e usar padrões e ferramentas para trocar de agente sem perder o processo. A ideia central é que especificações claras ajudam a manter o agente alinhado aos objetivos do projeto e reduzem problemas de contexto e revisão.

Pontos-chave

• A especificação registra o que e por que construir, enquanto a implementação descreve como fazer.
• Uma constituição do projeto documenta missão, stack tecnológico e roadmap.
• Cada funcionalidade deve seguir um ciclo de planejamento, implementação e validação, com revisões e commits em etapas.
• O agente deve receber contexto suficiente sobre objetivos e restrições, sem ser excessivamente direcionado em detalhes que pode decidir sozinho.
• A validação humana deve priorizar o alinhamento com a especificação e o funcionamento do software.
• A replanning entre funcionalidades permite atualizar decisões do projeto e melhorar o fluxo de trabalho.
• Skills podem automatizar tarefas repetíveis, como criar changelogs e executar verificações de qualidade.
• O desenvolvimento orientado a especificações também pode ser introduzido em projetos existentes, usando o código e os artefatos disponíveis para elaborar a constituição.
• Padrões e ferramentas como MCP, Agent Skills, ACP, GitHub Spec Kit e OpenSpec ajudam a ampliar ou adaptar o fluxo.
• Especificações documentadas funcionam como memória persistente do projeto, inclusive quando se troca de agente ou IDE.

Capítulos

Início	Capítulo	Resumo
00:00	Introdução ao desenvolvimento orientado a especificações	O curso apresenta os benefícios das especificações para orientar agentes e manter decisões importantes do projeto.
04:09	De vibe coding a especificações de engenharia	O instrutor compara prompts improvisados a especificações persistentes que formalizam o que construir e por quê.
08:18	O fluxo de trabalho e o papel da constituição	O agente é apresentado como executor técnico, enquanto a pessoa define os objetivos e registra o contexto do projeto.
12:28	Preparação do ambiente	O curso configura um projeto TypeScript no WebStorm com Git e Claude Code.
14:30	Criação da constituição do projeto	A pessoa e o agente definem em conjunto a missão, o stack tecnológico e o roadmap de Agent Clinic.
20:08	Planejamento da primeira funcionalidade	O agente ajuda a transformar a primeira etapa do roadmap em especificações, requisitos e critérios de validação.
23:16	Implementação da funcionalidade	Com as especificações revisadas, o agente implementa a funcionalidade em etapas que podem ser acompanhadas e revisadas.
25:20	Revisão e validação humana	A revisão identifica divergências em relação às especificações e atualiza os documentos e o código para corrigi-las.
28:58	Replanning, testes e automação	O curso mostra como atualizar a constituição, adicionar testes, ajustar o roadmap e criar uma skill para changelogs.
35:46	Nova funcionalidade e prevenção da fadiga de IA	O instrutor recomenda começar cada ciclo com contexto limpo e revisar as mudanças em etapas manejáveis.
42:36	Teste de MVP e adoção em projetos existentes	O fluxo é testado com a implementação de um MVP e, em seguida, adaptado a um projeto brownfield.
49:57	Skills, ferramentas e fluxos de trabalho	O curso demonstra a automação com skills e discute MCP, ferramentas de linha de comando, GitHub Spec Kit e OpenSpec.
56:46	Portabilidade entre agentes e encerramento	Padrões como Agent Skills e ACP permitem preservar o fluxo ao trocar de agente ou IDE, mantendo as especificações como memória do projeto.

Citações

O agente é a força; a especificação é o cérebro. — 08:48

Seu papel é projetar, supervisionar a construção e revisar e aceitar os resultados — ou pedir mudanças. — 11:25

A especificação agora é a memória do projeto. — 49:27

O melhor código começa com uma ótima especificação. — 1:01:07

Conceitos e entidades

• Spec-driven development (conceito): Abordagem em que especificações persistentes orientam agentes de programação no planejamento, implementação e validação de software.
• vibe coding (conceito): Estilo de desenvolvimento baseado em prompts rápidos e ajustes sucessivos, que pode não preservar decisões nem escalar bem para projetos maiores.
• Constitution (conceito): Documento de alto nível que registra a missão, as escolhas técnicas e o roadmap de um projeto.
• human-in-the-loop (conceito): Prática em que uma pessoa acompanha e revisa as decisões e os resultados produzidos pelo agente.
• Agent Skills (conceito): Conjunto de instruções e recursos que dá a agentes capacidades para executar fluxos de trabalho repetíveis.
• MCP (conceito): Protocolo citado no curso como uma forma de estender agentes com acesso a ferramentas e fontes externas.
• ACP (conceito): Protocolo apresentado para conectar agentes a clientes, como editores e IDEs.
• GitHub Spec Kit (ferramenta): Ferramenta mencionada como uma forma de formalizar um fluxo de desenvolvimento orientado a especificações com agentes.
• OpenSpec (ferramenta): Alternativa de fluxo de trabalho citada, com etapas de proposta, exploração, aplicação e arquivamento.
• Claude Code (ferramenta): Agente de programação usado nas demonstrações do curso para criar especificações, implementar funcionalidades e trabalhar com skills.
• WebStorm (ferramenta): IDE usada no curso para desenvolver a aplicação e revisar alterações.
• JetBrains (empresa): Empresa parceira do curso, cujo produto WebStorm é usado nas demonstrações.
• Paul Everett (pessoa): Instrutor do curso e developer advocate na JetBrains.
• Agent Clinic (repo): Aplicação de exemplo do curso, uma clínica fictícia em que agentes de IA recebem tratamento para seus problemas.

Tradução completa (pt-BR)

00:00 Boas-vindas a este curso sobre desenvolvimento orientado por especificações, criado em parceria com a JetBrains. Atualmente, o desenvolvimento orientado por especificações é o melhor tipo de workflow para criar aplicações sérias com assistência de programação agentic. Dê ao seu coding agent um arquivo Markdown ou um prompt longo explicando exatamente o que construir, e ele implementará essa especificação. Em vez de escrever código à mão, você se concentra em registrar o contexto que o agent ainda não tem. Fico muito feliz que o instrutor deste curso seja Paul Everett, que é developer advocate na JetBrains. Obrigado, Andrew. E espere, eu

00:31 não sabia que você usava óculos. >> Você tem razão. Na verdade, não preciso deles. Certo, foi o que pensei. Enfim, o desenvolvimento orientado por especificações tem três benefícios principais que você começará a perceber logo de cara. Primeiro, você pode controlar grandes mudanças no código com pequenas alterações na especificação. Uma frase como “use SQLite com Prisma” talvez afete centenas de linhas de código. Troque isso por MongoDB e terá a mesma amplificação nos resultados. Isso torna a escrita de especificações muito eficiente,

01:03 muito mais do que escrever código. Segundo, as especificações ajudam a eliminar a perda de contexto entre sessões, preservando o que não é negociável. Agents não têm estado, então é importante carregá-los com o contexto da mais alta qualidade assim que são iniciados. E, por fim, as especificações melhoram a fidelidade à sua intenção. Você define o problema, os critérios de sucesso, as restrições e assim por diante. E o agent pode elaborar isso para criar um plano mais completo. Uma forma que uso com frequência para

01:34 escrever uma especificação é conversar com um agent como Claude Code, Gemini ou Codex para tomar as principais decisões arquiteturais, usando meu conhecimento sobre como quero fazer diferentes concessões. Depois, peço ao agent que resuma as principais decisões em um arquivo Markdown. Escrever uma especificação exige reflexão, e isso dá trabalho. Você precisa decidir que produto quer construir. Quais são os recursos? Qual é a arquitetura técnica? Sem a especificação, você deixaria essas decisões importantes a cargo dos caprichos do coding agent, o que talvez seja aceitável

02:06 se você quiser avançar muito rápido e simplesmente contar com a sorte, mas certamente isso leva a um código menos sustentável e, às vezes, a produtos bem estranhos. Por exemplo, já vi equipes trabalhando em um produto de software complexo sem uma especificação clara, o que levou a muitas dores de cabeça mais adiante: diferentes coding agents, orientados por diferentes desenvolvedores, construíam rapidamente, mas de maneiras contraditórias. O desenvolvimento orientado por especificações envolve criar uma constituição no nível do projeto para definir os padrões imutáveis e, depois,

02:37 passar por ciclos iterativos de desenvolvimento de recursos. Esses ciclos isolam cada recurso em sua própria branch, com etapas de planejamento, implementação e verificação, deixando tudo pronto para começar do zero entre os recursos e reduzindo as dores de cabeça e a troca de contexto. Esse mesmo workflow funciona tanto para projetos greenfield quanto brownfield. Em projetos greenfield, você começa do zero. Você desenvolverá a constituição em uma conversa com o agent. Em bases de código existentes, ou seja, projetos brownfield, você

03:08 gerará a constituição do projeto com base na base de código existente. Nos dois casos, você passará então por esses ciclos de desenvolvimento de recursos, gerenciando o versionamento em pequenas etapas. Neste curso, você também verá como escrever suas próprias agent skills para automatizar seu workflow orientado por especificações. Sabe, se você consegue fazer o que precisa com apenas um prompt curto, ótimo. Sou definitivamente a favor de usar prompts simples quando isso funciona. Mas os grandes desenvolvedores que conheço quase sempre

03:38 escrevem especificações detalhadas para projetos com qualquer complexidade significativa, porque têm contexto próprio e uma opinião sobre o que construir e como construir que será melhor do que deixar o LLM, que não tem esse contexto, escolher aleatoriamente. Se o seu coding agent vai passar 20 ou 30 minutos escrevendo código — o que pode corresponder a várias horas de trabalho de um desenvolvedor tradicional —, muitas vezes é melhor parar por três ou quatro minutos e escrever instruções bem claras. Muitas pessoas contribuíram para este curso, incluindo

04:09 Constantine Chiker e Zena Smeova, da JetBrains, e Isabel Zaro, da DeepLearning.AI. Vamos ao próximo vídeo e escrever algumas especificações. Quando você ouve falar de programação, talvez pense em vibe coding. Vamos comparar os dois e ver como o desenvolvimento orientado por especificações traz resultados melhores ao recuperar a engenharia. O vibe coding produz resultados rápidos. Você escreve um prompt descrevendo o que quer, como “crie um botão para mim”, e torce para

04:40 que dê certo. Depois, você olha o resultado. É um botão grande. Está mais ou menos perto, mas erra em alguns pontos importantes. Então, você aponta os erros para o agent, ele tenta de novo e assim por diante, até você ficar satisfeito. Como resultado, você acaba com um diálogo longo com o agent, cujo histórico nem sequer será salvo. Essa abordagem funciona razoavelmente para um botão, mas não escala para um projeto grande e contínuo. Embora prompts de alto nível sejam

05:11 rápidos, eles levam a código descartável e ao acúmulo de dívida técnica. Precisamos de engenharia: uma especificação bem mantida que crie um artefato técnico permanente. O desenvolvimento orientado por especificações é a resposta profissional ao caos da geração de código por IA sem supervisão. É uma mudança de paradigma em que a especificação, que explica o quê e o porquê, fica separada da implementação, que explica o como. Com as especificações, temos

05:41 um contrato entre as pessoas, mas também com o agent. Agora, sua principal tarefa como pessoa muda: aprender a converter suas intenções em especificações claras. O desenvolvimento orientado por especificações com assistência de programação agentic tem três benefícios principais. Primeiro, você consegue controlar grandes mudanças no código com pequenas alterações na especificação. Algumas frases na especificação descrevendo a aparência e a sensação do aplicativo podem se traduzir em centenas de linhas de

06:12 CSS. Essa abordagem orientada por especificações reduz o esforço cognitivo necessário para trabalhar com esses coding agents ultrarrápidos. Segundo, as especificações eliminam o problema da perda de contexto que prejudica as sessões de várias interações com agents. Enquanto você trabalha com seu coding agent, a context window dele vai se preencher, o que muitas vezes leva a mais erros, conforme o agent tenta lidar com a memória de trabalho cheia. As especificações persistem entre sessões e até entre agents, ancorando o agent ao contexto essencial

06:45 necessário para trabalhar em uma base de código e implementar um recurso. Terceiro, as especificações melhoram a fidelidade à intenção, ou seja, aumentam a probabilidade de o agent produzir código que corresponda aos seus objetivos. Isso acontece porque as especificações obrigam você a definir o problema, os critérios de sucesso, as restrições, os fluxos de usuário e assim por diante, antes de o agent começar a gerar código. As especificações são um diferencial fundamental entre fazer vibe coding e produzir código de qualquer jeito, e criar um produto de software viável por meio da engenharia.

07:15 Quer você esteja começando um projeto do zero ou queira implementar a abordagem de desenvolvimento orientado por especificações em um projeto que está em andamento há anos, as especificações ajudam a resolver os problemas de desvio e produtividade. Para fazer uma comparação, pense em compiladores, que convertem código-fonte compreensível em código de máquina. O desenvolvimento orientado por especificações guia o agent, convertendo as especificações em código-fonte por meio de prompts. Melhor ainda, as especificações estão em linguagem

07:45 natural, o que facilita o trabalho das partes interessadas. O desenvolvimento orientado por especificações ganhou força recentemente como solução para preocupações com a produtividade. Há vários projetos de desenvolvimento orientado por especificações, ferramentas criadas em torno da elaboração de especificações e palestras em conferências sobre como registrar intenções. Tudo isso faz parte de um esforço mais amplo para aplicar ao desenvolvimento com agents as lições de engenharia aprendidas ao longo do ciclo de vida do desenvolvimento de software. O desenvolvimento orientado por especificações é usado com coding agents, não com simples chatbots. Um chatbot pode falar sobre código, mas o

08:18 chatbot não tem acesso ao código do seu projeto nem às ferramentas que você instalou. Ele apenas responde aos seus prompts. Agents são diferentes. Eles recebem seu prompt, criam um plano e se orientam até chegar a um resultado, usando raciocínio ao longo do caminho. É importante destacar que os agents têm acesso à sua base de código e às suas ferramentas de desenvolvimento. No workflow de desenvolvimento orientado por especificações, tratamos esses agents como programadores em dupla altamente capacitados. Eles fornecem o

08:48 conhecimento técnico e a velocidade, e você, arquiteto sênior, fornece os projetos. À medida que avançamos neste curso, lembre-se: o agent é a força, mas a especificação é o cérebro. Com a prática, você garante que o software produzido não seja apenas funcional, mas também esteja alinhado aos seus objetivos de longo prazo. O desenvolvimento orientado por especificações diz ao agent, de antemão, como construir o que você quer para o projeto e, depois, para cada recurso, melhorando à medida que avança. Com o desenvolvimento orientado por especificações, ajudamos o

09:19 agent com o contexto da mais alta qualidade. Primeiro, com decisões sobre o projeto; depois, com detalhes sobre cada recurso. Esta especificação é muito detalhada. Uma habilidade fundamental no desenvolvimento orientado por especificações é saber qual é o nível certo de detalhe. Se você tratar seu agent como um programador em dupla altamente capacitado, muitas vezes chegará ao nível certo. Bastante contexto sobre os objetivos, a missão, o público-alvo e as restrições, e menos sobre as decisões de baixo nível que o agent consegue tomar por conta própria. O que este desenvolvimento orientado por especificações

09:53 Como seria o workflow? Primeiro, definimos a constituição. Qual é a missão? A stack tecnológica, o roteiro. Uma constituição é apenas uma forma de formalizar esses detalhes do projeto. Muitos desenvolvedores usam um arquivo agents.md de nível superior para esse fim, mas uma constituição do projeto é agnóstica em relação ao agent e mais estruturada. A constituição registra o acordo sobre decisões importantes entre a pessoa e o agent, mas também o

10:23 acordo entre as pessoas. A missão explica o porquê, a visão deste projeto, o público, o escopo etc. Definir esses parâmetros com antecedência é muito comum em projetos de software e ajuda a orientar as decisões ao longo do trabalho. A stack tecnológica é para a equipe de engenharia: um entendimento comum das tecnologias e restrições de desenvolvimento e deploy. O roteiro é um documento vivo com uma sequência de fases, cada uma implementada por meio de seu próprio processo de especificação de funcionalidades.

10:55 Depois de elaborar a constituição, trabalhamos em cada funcionalidade com um processo repetível. Primeiro, planejamos a funcionalidade, implementamos e, por fim, validamos o resultado. Entre uma funcionalidade e outra, é hora da fase de replanejamento. Revise a constituição, atualize o roteiro e até melhore o próprio processo. Como você ouviu há pouco, uma das principais habilidades do desenvolvimento orientado a especificações é fornecer o nível certo de detalhe para criar o

11:25 contexto da mais alta qualidade. Nas fases de funcionalidade e de replanejamento, você orienta o agent. Pense assim: imagine que você é um arquiteto e entrega desenhos detalhados de um prédio aos construtores. Depois, cabe a eles fazer o trabalho. Seu papel é projetar, supervisionar a construção e, então, revisar e aceitar os resultados ou pedir alterações. Você vai querer evitar dizer aos construtores como fazer o trabalho deles e se concentrar em fornecer o

11:56 contexto que eles não têm. O desenvolvimento orientado a especificações leva você da concepção inicial até a entrega final. E, o melhor de tudo, permite continuar melhorando a partir daí. Este é um workflow de desenvolvimento orientado a especificações que desenvolvedores modernos estão começando a usar. Em breve, veremos o começo: a constituição do projeto. Mas, primeiro, vamos fazer alguns preparativos. Para configurar o repo do projeto, siga as instruções do próximo material de leitura. A configuração apresentada no vídeo a seguir é opcional.

12:28 Se você já se sente à vontade para configurar um agent de programação como Claude Code em uma IDE como WebStorm, pode pular este vídeo opcional. Até o próximo vídeo ou o seguinte. Antes de enviar seu primeiro prompt, vamos conversar um pouco sobre como configurar seu espaço de trabalho. Se você já se sente à vontade

12:59 para configurar um agent de programação como Claude Code em uma IDE como WebStorm, pode pular este vídeo opcional. O desenvolvimento orientado a especificações é uma boa prática que não está vinculada a nenhuma IDE ou agent de programação específico. Então, você pode escolher a configuração que já usa ou a mesma que verá neste curso. VS Code com Codex CLI, editor Zed com um modelo local: todas são ótimas opções para o desenvolvimento orientado a especificações. Como vamos

13:29 desenvolver uma aplicação web, neste curso usaremos a IDE WebStorm com Claude Code como agent de programação. As instruções para baixar e instalar ambos foram incluídas no material de leitura anterior. Vamos abrir o WebStorm e começar um projeto novo chamado Agent Clinic. Este será um projeto TypeScript com um repositório Git para acompanhar de perto o versionamento do código e das especificações.

13:59 Embora muitas IDEs, incluindo o WebStorm, ofereçam um painel de conversa, sabemos que há muita diversidade na forma como as pessoas interagem com seus agents de programação. No desenvolvimento orientado a especificações com agents, é importante acompanhar de perto o versionamento do código. Digamos que queremos criar um commit inicial usando o agent. Sempre que ele precisar executar um comando, vai pedir sua confirmação, a menos que você inicie o Claude Code em modo inseguro. Preste muita atenção ao que o Claude Code

14:30 pedir que você faça. A responsabilidade final pelo código é sua. Nas próximas aulas, você verá vários truques e boas práticas para o desenvolvimento orientado a especificações com Git. Ótimo. Nossa configuração está pronta, e a sua também. Vamos começar. Você precisa falar ao agent sobre seu projeto, a missão, o público e outras decisões. Nesta aula, vamos trabalhar com o agent para escrever a constituição. Afinal, o que é o seu

15:00 projeto? Digamos que você esteja trabalhando em uma nova aplicação web para sua empresa. Qual é a ideia central por trás do desenvolvimento? Como ela se encaixa na stack tecnológica preferida da empresa? Quais funcionalidades estão planejadas? Esses três princípios fundamentais formam a constituição: um conjunto global de requisitos de alto nível que orientará o desenvolvimento futuro de funcionalidades e explicará aos stakeholders a estrutura do projeto. Por exemplo, há muitas opções para sua stack tecnológica. Você vai querer restringi-las

15:31 com base nas compensações apropriadas e no que sua empresa usa. Precisamos registrar isso para o agent, para os colegas de equipe e para o futuro. Mas não escrevemos sozinhos. Escrevemos em uma conversa com o agent. Você vai se surpreender com as ótimas perguntas que ele fará, os padrões de arquitetura que você não tinha considerado, os pacotes externos que já fazem o trabalho ou as compensações, por exemplo, entre velocidade e

16:02 fidelidade dos dados. A missão, a stack tecnológica e o roteiro não são apenas características de um projeto em campo verde que você está começando do zero. Bases de código existentes também usam esses três pilares. Daqui a alguns vídeos, vamos falar sobre como levar o workflow de desenvolvimento orientado a especificações para projetos existentes. Este é o projeto de exemplo que usaremos ao longo do curso. Estamos criando o Agent Clinic, um lugar onde agents de IA podem encontrar alívio de seus humanos. O Agent Clinic é uma paródia divertida do popular projeto de aprendizado Pet Clinic. Os agents de programação estão fazendo muito trabalho. É estressante. Alucinações, deterioração do contexto, problemas de memória e coordenação entre subagents colegas de trabalho afetam a saúde dos agents. Vamos criar uma clínica onde eles possam obter ajuda com seus problemas. É uma aplicação web full stack com backend Next.js e frontend React. O aplicativo permite gerenciar consultas, doenças como alucinação e tratamentos como

16:33 uma infusão de contexto. Vamos ver como você poderia escrever uma especificação detalhada para um projeto assim. Vamos conversar com o agent. Primeiro, fornecemos ao agent a descrição do projeto e informamos que os stakeholders deram suas opiniões no readme.md, que adicionamos ao repo. Na nota importante, mencionamos diretamente a ferramenta ask user question do Claude Code. Essa ferramenta é totalmente opcional, mas

17:04 gostamos da aparência dela na interface. Além disso, para a constituição do projeto, peça ao agent que trabalhe com você na missão, na stack tecnológica e no roteiro. O desenvolvimento orientado a especificações funciona melhor com uma abordagem com a pessoa no loop, em que você revisa pequenas alterações. Então, peça ao agent para organizar o roteiro em etapas pequenas. Enquanto trabalhamos juntos, você verá que o agent faz algumas perguntas muito boas. Talvez as suas sejam diferentes.

17:34 A primeira pergunta é: “Que tom a missão.md deve ter?” Vou escolher, como você já deve ter adivinhado, um tom divertido. Isso resolve a missão. Agora, algumas perguntas sobre a stack tecnológica. Nossos engenheiros estão acostumados a usar TypeScript no backend. Então, vamos incluir isso nos requisitos. Em seguida, sobre o roteiro, ele pergunta qual deve ser o nível de granularidade. Vou escolher a primeira opção. Terminamos a entrevista inicial. Vamos selecionar “Enviar respostas”.

18:04 O agent vai pedir permissão para gravar. Isso mantém as alterações sob seu controle. Se você se sentir confortável com as compensações de segurança, pode selecionar a opção para aprovar todas as ocorrências de um comando específico nesta sessão. Você verá isso no restante do curso. Agora terminamos e temos três arquivos no diretório specs: Mission.md, text.md e roadmap.mmd.

18:36 É hora de manter a pessoa no loop. Vamos revisar. Por exemplo, a missão não inclui um público-alvo. Isso é razoável. Como o agent poderia conhecer seu negócio? Em vez de editar diretamente, vamos continuar a conversa. Para manter todos os artefatos consistentes, é melhor pedir ao agent que faça as alterações manualmente, pois você pode deixar de atualizar documentos relacionados.

19:07 Queremos usar SQLite neste projeto. Como este é um protótipo rápido, não mencionamos isso, mas o agent deduziu essa necessidade nas recomendações. Agora, isso faz parte da nossa stack tecnológica. Faça uma revisão final. É importante acertar tudo desde o início. Vamos criar um commit da constituição para que ela seja um documento vivo do projeto. Agora, o Agent Clinic tem uma constituição, uma missão, um roteiro e uma stack tecnológica para orientar nosso

19:38 Queremos usar SQLite neste projeto. Como é um protótipo rápido, não mencionamos isso, mas o agent percebeu nas recomendações. Agora, isso faz parte da nossa stack tecnológica. Faça uma revisão final. É importante acertar tudo desde o início. Vamos fazer o commit da constituição para que ela seja um documento vivo do projeto. Agent Clinic agora tem uma constituição, uma missão, um roteiro e uma stack tecnológica para orientar nosso

20:08 projeto. Estamos prontos para encarar nosso primeiro recurso. Agora temos um roteiro com os recursos. Mas como vamos desenvolvê-los com especificações? Claro, começando pelo primeiro recurso do roteiro. Vamos dar uma olhada no roteiro do Agent Clinic. Aqui está nosso recurso da fase um: Hello Hono. Mas ainda é cedo demais para começar a programar. Precisamos discutir a especificação e esclarecer todos os detalhes. Um bom plano descreve a abordagem, a sequência de trabalho e como validar o sucesso.

20:41 Vamos começar com um contexto novo para o agent. O agent pode obter o que precisa da fonte oficial: a constituição. Vamos trabalhar nesse recurso em uma branch separada, o que indicaremos ao agent. Nosso prompt vai ajudar a iniciar uma conversa com o agent sobre a especificação do recurso, um plano de tarefas, a coleta de requisitos e uma ficha de avaliação para validação. O agent vai pedir que você tome decisões importantes. Preste atenção a possíveis conflitos ou problemas. Você

21:11 não precisa concordar com as soluções propostas pelo agent. Não deixe de esclarecer qualquer coisa que incomode você. Primeiro, quanto ao escopo da fase 1, vamos mantê-lo exatamente como está escrito. Para os requisitos, vamos definir a versão do Hono e exigir TypeScript estrito. Para a confirmação, usar curl manualmente parece bom. Então, vamos enviar. Foi rápido. Deve ter sido o nano.

21:41 O trabalho foi concluído e agora cabe a nós revisar a especificação do recurso criada pelo agent. Vamos revisar primeiro o plano do recurso. É importante acertar esses documentos desde o início para manter o agent no rumo. Se encontrar algo errado, peça ao agent que corrija, para garantir que os requisitos e a validação continuem alinhados. Por exemplo, gostaríamos de uma página inicial de placeholder com um visual agradável nesta primeira especificação de recurso. Fazemos a alteração por meio do agent.

22:13 Em seguida, os requisitos. Eles também foram atualizados para refletir a alteração na página inicial. Este é o lugar certo para indicar necessidades ou restrições técnicas importantes. Não passe por isso às pressas, mas também não indique detalhes técnicos menores, como nomes de variáveis. Queremos controlar o processo, mas sem direcionar demais o agent. Por último, a validação. Certifique-se de que o agent possa verificar se fez tudo certo. Mais uma vez, esses itens foram atualizados para a página inicial. Terminamos a especificação do recurso.

22:44 Vamos criar um commit na IDE. Legal. Formulamos uma estratégia de especificação de recursos. Criamos uma branch do recurso. Entrevistamos o agent sobre o que o recurso deveria fazer. Registramos os resultados em documentos Markdown. Revisamos esses arquivos de especificação. Fizemos o commit. As alterações que você faz aqui nas especificações vão se expandir, mais adiante, em centenas de linhas de código. Portanto, o tempo gasto aqui é bem aproveitado. Está na hora da implementação.

23:16 Estamos trabalhando no plano para o primeiro recurso do roteiro do projeto. Terminamos a especificação do recurso. Vamos implementar esse recurso por completo. Só para relembrar, vamos fazer uma revisão rápida do plano dessa especificação de recurso. Este era o primeiro recurso: Hello Hono. Os documentos de especificação do recurso contêm o que precisamos. Para começar a implementação, você vai querer limpar seu contexto com o comando /clear. Vamos voltar ao agent e inserir um prompt para

23:47 implementar todos os grupos de tarefas. Às vezes, você pode optar por fazer os grupos de tarefas um por vez, em etapas e commits ainda menores. Essa técnica é especialmente útil em áreas onde pequenos erros podem se acumular mais tarde, como segurança ou gerenciamento de banco de dados. Enquanto o Claude está em execução, você pode observar as alterações exibidas no console e acompanhar o progresso em tempo real. Depois, podemos observar as alterações finais na janela de commit e visitar

24:17 as alterações. Isso nos permite começar a revisar o trabalho mais cedo. Esse é o papel fundamental do desenvolvedor nesse paradigma: atuar como arquiteto ou supervisor e garantir que o agent receba um contrato claro. Também podemos ver um resumo do que foi feito. Como você pode ver, o agent fornece detalhes adicionais sobre o trabalho realizado em cada grupo de tarefas. Agora, vamos ao arquivo package.json e, nele, vamos

24:50 executar o aplicativo. O servidor é iniciado no console. O navegador mostra o resultado desta especificação de recurso. Não é muita coisa. Dissemos nano, mas é bom ver pixels na tela. Acabamos de implementar um recurso. O agent fez a validação dele. Na próxima aula, faremos a nossa. É bom ter um recurso pronto, mas ainda não faça o merge. Nesta última etapa do recurso, nós

25:20 colaboramos com o agent para revisar o trabalho. Felizmente, os programadores têm boas ferramentas para essa tarefa de validação. Afinal, programadores há muito dedicam várias horas por semana à revisão de código. Comece pela visualização do commit. Vamos analisar as alterações. Concentre sua revisão em questões de alto nível, como se os recursos funcionam e correspondem à especificação, em vez de detalhes como quais classes CSS foram implementadas. Por exemplo, o arquivo home.tsx é minimalista.

25:51 Nano realmente queria dizer nano. Queremos um componente de layout com áreas claramente definidas para cabeçalho, conteúdo principal e rodapé, mas como subcomponentes, e também criar um arquivo CSS. Acontece que esse erro no código veio de um erro no plano. Não pedimos isso. Vamos pedir ao agent que faça a correção, corrigindo assim tanto a especificação quanto a implementação. Esse processo, em que o agent gera algo e nós verificamos,

26:24 é conhecido como human in the loop. Como os agents escrevem código muito rapidamente, os desenvolvedores de software têm falado ultimamente sobre dívida cognitiva: a carga mental de acompanhar o que o seu código está fazendo e como ele evoluiu. Por isso, para que esse processo seja rápido, fácil de controlar e reduza a dívida cognitiva, as alterações precisam ser gerenciáveis. O agent está fazendo nossas alterações, mas também está validando se elas

26:54 não quebraram nada. Boa notícia: o agent terminou e nos deu um resumo rápido. Você também pode ver isso no editor. O plano do recurso foi alterado para adicionar um grupo cinco e listar essas novas etapas. Agora, o código tem um componente de layout e foi adicionado um arquivo CSS. Parece que os três subcomponentes

27:26 foram colocados no mesmo arquivo, mas isso não segue as convenções. Vamos colocá-los em seus próprios arquivos usando a ferramenta de movimentação da IDE. Esse tipo de alteração é fácil nos editores e sempre fomos bons nisso. Não precisamos de um agent, certo? Vamos simplesmente fazer isso. Calma lá. Isso pode causar divergências

27:56 e deixar outros artefatos, especificações e arquivos README desatualizados. Vamos pedir ao agent que corrija todas as menções e garantir que isso não nos faça perder tempo mais tarde. Todas as alterações foram feitas. Será que quebramos alguma coisa? Testes ajudariam, mas o agent não instalou nosso pacote de testes. Como isso é necessário para todos os recursos, vamos abordar o assunto na próxima aula. Agora, estamos prontos para marcar este trabalho como concluído e fazer o merge dos resultados.

28:27 Observe que a parte da constituição foi atualizada junto com o recurso nesta branch. Como lidar com o versionamento das especificações e como associar quais especificações geraram quais alterações no código são temas em evolução na comunidade. A alteração no roteiro é pequena. É só marcar uma etapa como concluída no roteiro. Portanto, não tem problema manter essas atualizações na mesma branch. Se a atualização geral da constituição for mais complicada, talvez seja melhor fazê-la em uma branch separada. Agora, estamos

28:58 prontos para marcar este trabalho como concluído e fazer o merge dos resultados. Acabamos de usar desenvolvimento orientado por especificações para desenvolver e validar nosso primeiro recurso. Mas espere: não deveríamos dar outra olhada no escopo mais amplo do projeto? Implementamos o primeiro recurso com sucesso. Mal posso esperar para fazer isso de novo e de novo. Não tenha pressa. Dê um passo atrás e reflita, replanejando um pouco. É preciso ir devagar para ir rápido. Temos uma

29:29 etapa do workflow chamada validação. Testes são bons para validar, mas não informamos ao agent todas as nossas preferências de testes. Vamos criar uma branch de replanejamento para atualizar a stack de testes na nossa constituição. Como você viu no vídeo anterior, o versionamento de especificações é um tema em evolução. A constituição é um documento vivo. É uma boa prática atualizá-la em uma branch separada, para que você possa acompanhar quais versões dela produziram qual código. Vamos usar um

29:59 prompt para declarar nossa política. Parece que o agent atualizou o package.json apenas para adicionar um script, sem dependências. Algo para anotar para mais tarde, quando executarmos os testes. Essa alteração, que adiciona uma estrutura de testes, se aplica ao código futuro. Mas vamos pedir ao agent que atualize as especificações e a implementação do recurso existente com base nessa alteração na constituição.

30:30 Depois desses dois prompts, temos algumas boas mudanças. O agent configurou essa alteração nos testes, mas não escreveu os testes. Vamos pedir ao agent que escreva alguns testes novos. Com essa configuração, podemos executar os testes facilmente no nosso editor. Vamos executar no depurador para termos a oportunidade de acompanhar a execução do código como parte do processo com participação humana.

31:03 Está bom. Agora temos testes como parte da validação. Vamos fazer um commit. Às vezes percebemos que queremos fazer algo de outro jeito no plano do produto. Por exemplo, depois de implementar o primeiro recurso, recebemos uma atualização da pessoa gerente de produto. Como 40% dos nossos usuários usam dispositivos móveis, queremos dar ênfase a um design responsivo. Vamos falar com o agent. Vamos dizer ao agent que queremos um design responsivo e que corrija as

31:34 especificações do produto e do recurso, além de qualquer código. Como ainda estamos bem no início do desenvolvimento, essa atualização é pequena. Então, faz sentido implementá-la diretamente durante o replanning. Mas, se o novo trabalho for grande, é melhor programá-lo no roadmap como uma fase própria de recurso, em vez de simplesmente fazê-lo durante o replanning. Use seu bom senso. Lembre-se: queremos que as especificações registrem decisões, não apenas o código. Queremos tentar manter as duas coisas sincronizadas para ajudar na

32:05 comunicação da equipe. O agent implementou nossa correção de responsividade, com atualizações não só no código, mas também nas especificações do produto e do recurso. É hora de fazermos a nossa parte e revisar as mudanças. Vamos examinar os diffs. Está bom. Vamos fazer um commit. Lembre-se: trabalhar em etapas pequenas, com commits frequentes, evita que a revisão sobrecarregue sua cabeça. Enquanto essa primeira parte do replanning está funcionando, vamos

32:37 dar um passo atrás e cuidar da organização do projeto. Por exemplo, vamos rever o roadmap do projeto e conferir a próxima tarefa. Ela ainda faz sentido? O roadmap mostra o próximo recurso, que abordaremos na próxima aula. Ele ainda é o correto? Analisando o roadmap, parece que os recursos 2, 3, 4 e 5 estão meio que relacionados. Vamos atualizar o roadmap para abordar todos de uma vez. Vamos fazer um commit e começar esse novo recurso em breve.

33:09 A etapa de replanning pode ser sobre um recurso ou sobre o projeto inteiro, mas também pode ser sobre aprimorar seu workflow de desenvolvimento orientado por especificações entre projetos e em toda a sua organização. Por exemplo, talvez você tenha algumas partes interessadas não técnicas que queiram acompanhar o progresso do projeto. Você gostaria que um changelog fosse atualizado a cada merge. A maioria dos agentes de codificação com IA oferece suporte a skills, um conjunto de instruções e recursos que dão ao

33:41 agent novas capacidades e conhecimentos especializados. Skills são ótimas para workflows definidos e repetíveis que exigem contexto específico do seu projeto ou da sua organização. Uma skill seria ótima para implementar a atualização de um changelog. Você poderia escrever essa skill manualmente, mas muitos agentes têm skills que ajudam você a escrever uma skill. Vamos usar o agent para nos ajudar a escrever e manter uma skill de changelog.

34:12 O agent começa a trabalhar. Uma coisa a considerar é se essa skill é exclusiva deste projeto ou se deveria ser padrão em todos os projetos. É uma escolha de estilo, e você vai entender melhor à medida que usar a skill. Você vai aprender a automatizar seu workflow de desenvolvimento orientado por especificações com skills. Por exemplo, sua etapa de validação pode incluir atualizar o README, executar o linting, formatar, executar testes e fazer outras verificações de qualidade. Você

34:42 pode trabalhar com seu agent para agrupar tudo isso em uma skill de validação. Processo repetível, menos trabalho manual. O agent terminou. Podemos percorrer a janela para ver o que ele criou e como usar. Observe que ele escolheu criar isso na área global de skills. Agora, essa skill poderá ser usada em todos os projetos. Além disso, o Claude Code usou a nova skill para gerar um changelog neste projeto. Os changelogs são uma forma de se comunicar com as partes interessadas, incluindo o

35:14 agent. Então, vamos abri-lo e revisá-lo manualmente. Está bom. Terminamos esse trabalho de replanning. Vamos concluir com um commit e, em seguida, fazer o merge do branch. Agora que a maior parte do seu trabalho como desenvolvedor envolve planejamento e validação, e não implementação, reserve um tempo entre os recursos para fazer replanning. No próximo vídeo, vamos trabalhar em outro recurso do roadmap

35:46 do projeto. Temos uma constituição aprimorada e um workflow aprimorado. Estamos melhorando. Mas, antes de passar para o próximo recurso do roadmap, vamos abordar algumas estratégias para lidar com um problema comum: a fadiga de IA. Os agentes podem gerar muito código com muitas mudanças. Essa quantidade enorme de código torna exaustiva a validação com participação humana. Há muita coisa para revisar. Para combater essa confusão, certifique-se de

36:16 que haja uma divisão clara entre cada fase do recurso. Devemos começar cada recurso no estado de fluxo certo. Tenho trabalho inacabado? Fiz o merge do branch do último recurso em main? O próximo item do roadmap é o que devemos fazer? Limpei o contexto do agent para garantir que as especificações registrem a intenção, em vez de capturas da memória, e para que ele possa concentrar seu orçamento limitado de contexto no próximo trabalho? Reserve um momento para começar bem e

36:48 ajudar a si mesmo a terminar. Fizemos tudo isso. Vamos limpar o contexto e começar o próximo recurso: agentes e doenças. Uma observação: continuamos digitando a mesma coisa. Em uma aula futura, vamos falar sobre como você pode transformar esses prompts repetidos em um workflow personalizado. Como antes, o agent faz boas perguntas. A primeira é se devemos manter todos esses recursos em uma única fase. Já decidimos na aula anterior que faríamos isso juntos, então vamos responder que sim.

37:21 Para as migrações, vamos escolher SQL puro. Para a validação, vamos selecionar as opções 1, 2 e 3. Muito bem. Agora, vamos enviar. Quando o agent redigir a especificação, poderemos ver algumas das escolhas que fez. É útil acompanhar o processo de raciocínio do agent. Se você estiver usando um agent no modo verboso, isso pode dar ainda mais visibilidade às ideias intermediárias dele.

37:52 Está bom. Mas queremos fazer uma pequena mudança para registrar nossa intenção. Queremos usar Pico CSS como nosso framework CSS. Em seguida, vamos revisar os três arquivos da especificação do recurso, começando pelos requisitos. Vamos pedir ao agent que altere os requisitos e garanta que os outros arquivos também reflitam essa mudança. Quando o trabalho terminar, vamos fazer um commit da especificação do recurso. Desta vez, vamos deixar o agent sugerir a mensagem. Com a

38:22 especificação do segundo recurso pronta, vamos para a implementação. A divisão entre a fase de planejamento e a fase do recurso nos ajuda a evitar que o contexto, nosso e dos agentes, transborde. Se o recurso parecer grande demais para implementar de uma só vez, peça ao agent que implemente primeiro uma parte do plano do recurso. Isso manterá as mudanças em um tamanho administrável. Nosso

38:54 agent implementou o recurso da fase 2. Acompanhamos o progresso do agent, então temos uma ideia geral do que foi feito. Mas isso não basta. Vá com calma. Pense um pouco. Vamos fazer uma revisão aprofundada das mudanças. Cada pessoa tem seu próprio estilo quanto ao nível de revisão dos resultados dos agentes. Para aproveitar os pontos fortes dos agentes e reduzir a fadiga de IA, concentre-se nos requisitos de alto nível. Evite implicar com coisas como nomes de variáveis. Só garanta que ele crie código

39:26 que você possa commitar em seu nome. Por exemplo, ele usou informações de tipo inline para as props. Preferimos que a definição das props fique em um tipo TypeScript separado. Vamos pedir ao agent que corrija isso em todo o código. Provavelmente você não incluiu essa decisão na especificação. Lembre-se: uma omissão, como não extrair os tipos das props, não é uma falha. Você está evoluindo a

39:57 especificação à medida que descobre novos detalhes, e registrá-los leva a resultados melhores no futuro. Terminamos a revisão. Este é um bom momento para outro commit pequeno. Última etapa: validação. Vamos revisar o que o agent planeja fazer na etapa de validação desta especificação de recurso. Está bom. Vamos fazer nossa validação. Lembre-se: queremos garantir que as mudanças estejam boas executando a aplicação.

40:32 Mas também queremos evitar dívida cognitiva, validando se entendemos essas mudanças. Os testes são um ótimo lugar para acompanhar o fluxo. Vamos ler alguns testes e executá-los no depurador para explorá-los. Às vezes, você precisa validar que não mentiram para você. Peça ao agent para iniciar vários subagents para fazer uma revisão aprofundada do projeto inteiro com essa mudança de

41:02 recurso. Essa revisão aprofundada dá ao agent mais espaço para pensar sobre as mudanças, e usar subagents preserva o context window do agent principal, em vez de poluí-lo. Esses subagents vão voltar com uma série de problemas e recomendações. Tudo isso parece bom. Então, vamos prosseguir. O agent vai trabalhar, faz uma série de correções, executa testes e deixa nosso projeto

41:34 em um bom estado. Guarde isso no seu arsenal de ferramentas. O agent geralmente consegue encontrar problemas importantes ao revisar uma segunda vez. Depois que terminarmos nossa validação, nossa funcionalidade estará completa. É hora de fazer o commit do trabalho da funcionalidade. Como última etapa dessa funcionalidade, vamos usar a skill de registro de alterações que criamos na aula anterior. Já documentamos as alterações nesta branch da funcionalidade. Mais um commit e, então, vamos mesclar a

42:05 branch. Em uma aula anterior, vimos a etapa de replanejamento entre funcionalidades. Vamos fazer uma versão rápida disso analisando o roteiro. A próxima funcionalidade ainda parece adequada? Parece bom. Nosso projeto está em boa forma, pronto para a próxima funcionalidade. Essa pausa bem definida entre funcionalidades ajuda a lidar com a fadiga causada pela IA. Agora você pode fazer uma pausa para tomar um café. Estamos começando a ver um processo repetível de desenvolvimento orientado a especificações para o desenvolvimento de funcionalidades

42:36 que registra nossas decisões. Na próxima etapa, vamos testar essa hipótese. Temos o suficiente para criar um MVP? Fizemos bastante progresso: duas funcionalidades implementadas com nosso workflow de especificações, mas a gerência acabou de pedir um MVP. Avançamos o suficiente para fazer um experimento? Vamos variar um pouco nosso prompt padrão de especificação de funcionalidade. Desta vez, vamos pedir que implemente o restante do roteiro e dar algumas

43:08 orientações sobre as especificações existentes das funcionalidades. Em geral, você só deve implementar um trecho tão grande se confiar na qualidade da sua constituição e da sua especificação. Quanto melhor for o contexto que você fornecer ao agent, mais confiança terá de obter um resultado alinhado às suas intenções. E você precisa ter certeza de que consegue fazer a revisão e a validação. Mas, já que assumimos esse risco, vamos tratar o MVP como um teste extremo da nossa constituição e das especificações de funcionalidades concluídas.

43:39 Se agora obtivermos algo diferente do que queríamos, isso significa que precisamos realizar, com bastante responsabilidade, outra fase de replanejamento para eliminar o que levou o agent ao caminho errado. O agent me fez algumas perguntas. Mais uma vez, são boas perguntas e recomendações. Muitos arquivos de especificação começam como uma conversa de vai e volta com um agent. Terminamos a entrevista e selecionamos “Enviar respostas”. Vamos gravar as especificações do MVP no disco.

44:11 É sempre bom revisar as especificações. Muitas vezes, você vai perceber suposições incorretas que o agent fez para preencher as lacunas. Vamos dar uma olhada rápida no plano, nos requisitos e na validação. Como sempre, gostamos de trabalhar em etapas pequenas, com commits frequentes. Vamos salvar a especificação da funcionalidade nas etapas de planejamento. Terminamos o planejamento. É hora de o agent fazer uma grande etapa de implementação. Agora, o agent faz

44:41 bastante trabalho. Quando terminar, é hora da verdade. Vamos conferir o MVP. Vamos aos nossos scripts para executar a aplicação. Como você pode ver, agora cada seção tem muito mais conteúdo, alimentado por dados de exemplo consultados no banco de dados. Neste ponto, normalmente validaríamos os resultados do código, mas este é um MVP. Vamos pedir ao agent que valide as especificações. Acontece que isso foi útil. O

45:13 agent mostrou pontos em que o MVP revelou lacunas no nosso planejamento. Podemos compartilhar essa avaliação com as partes interessadas para que revisem o MVP e, depois, mesclar ou arquivar a branch. Nosso workflow de desenvolvimento orientado a especificações deu certo. Depois de criarmos uma constituição e duas funcionalidades, o MVP produziu uma demonstração útil graças às nossas orientações. Claro que nem todos os projetos de software envolvem a criação de um MVP. Muitos projetos são os chamados brownfield. Eles começam com uma

45:44 base de código existente. A seguir, vamos ver como introduzir esse workflow em projetos legados. As pessoas dizem que o desenvolvimento orientado a especificações, e até mesmo a IA, só serve para projetos greenfield, mas o desenvolvimento orientado a especificações também é bom para projetos legados existentes. Nesta aula, vamos introduzir esse método em um projeto existente. Para facilitar, vamos começar com um projeto que você já conhece: o MVP do agent clinic. Vamos torná-lo legado começando na branch main, sem a pasta de especificações, em uma nova sessão do Claude Code, em um diretório de projeto diferente.

46:15 Temos algumas informações sobre o projeto no arquivo readme.md, com algumas tarefas em aberto listadas em to-do.md. Seu projeto legado pode ter planos completos do produto em rastreadores de issues, planilhas, documentos do Word etc. Lembra do nosso workflow? Vamos começar pela etapa da constituição. Vamos usar quase o mesmo prompt da aula 4. Desta vez,

46:47 vamos pedir que procure itens do roteiro nos materiais existentes. Neste caso, em um arquivo de tarefas. Lembre-se: o agent vai descobrir e, de certa forma, fazer engenharia reversa dos artefatos de desenvolvimento orientado a especificações a partir da base de código existente. A constituição ajudará a alinhar futuras alterações no código feitas pelo agent ao que os desenvolvedores anteriores já criaram. Você sempre pode adicionar mais contexto, se tiver. Por exemplo, talvez você tenha sido incluído neste projeto para melhorar sua eficiência ao

47:18 implementar funcionalidades muito solicitadas. O processo é o mesmo, mas a conversa pode ser mais rica, já que o agent tem mais artefatos, código, commits, documentos etc. Você verá muitas chamadas de ferramentas aqui enquanto o agent explora a base de código. Vamos conferir a constituição do nosso projeto legado. Na missão, temos o público, a ideia do projeto e algumas informações adicionais sobre ele. A pilha tecnológica mostra que Claude extraiu a estrutura de arquivos do projeto,

47:50 as versões dos frameworks e os esclarecimentos que nos foram solicitados. No roteiro, podemos ver que o trabalho está organizado em fases que correspondem ao arquivo de tarefas. Vamos criar um commit para os arquivos da constituição que produzimos, com uma mensagem de commit. Lembre-se de que, no desenvolvimento orientado a especificações, as especificações fazem parte da sua estratégia de versionamento. Agora, nosso projeto legado está baseado em fundamentos de desenvolvimento orientado a especificações. Daqui em diante, o workflow é exatamente o mesmo que

48:21 discutimos nas aulas anteriores. Primeiro, pegamos a próxima funcionalidade do roteiro e planejamos em uma conversa com o agent. Vamos trabalhar na fase um: formulário de feedback. Muito bom. Agora temos uma branch e especificações para essa funcionalidade. Vamos revisar a especificação da funcionalidade, o plano, os requisitos e a validação.

48:53 Depois, fazemos o commit da especificação da funcionalidade. Quando corrigirmos o que for necessário conversando com o agent, passamos à implementação. Quando o agent terminar, fazemos nossa validação para garantir que o código está bom e que a funcionalidade funciona como esperado. Nosso ciclo de funcionalidade está concluído. Podemos fazer o commit e, em seguida, mesclar a branch.

49:27 Agora é hora de replanejar. Não deixe de reservar tempo para isso. Como você acabou de adicionar o desenvolvimento orientado a especificações ao seu projeto, talvez encontre muitas coisas para ajustar. Agora temos um projeto legado adaptado ao desenvolvimento orientado a especificações sem muito trabalho manual. Isso nos dá um fluxo bem documentado, que avança em etapas, usa engenharia e nos mantém no controle. A especificação agora é a memória do projeto.

49:57 Só não se esqueça. Agora você domina um workflow de desenvolvimento orientado a especificações. Quer algo mais rápido e leve? Nesta aula, vamos automatizar as coisas, mas do nosso jeito, com um processo personalizado. Já apresentamos as skills de agent, um padrão aberto para dar aos agents novas capacidades e conhecimentos especializados. Por exemplo, repetimos o mesmo prompt ao começar uma especificação de funcionalidade: faça isto, faça aquilo, escreva estes três arquivos. Vamos

50:28 automatizar isso com uma skill, com a ajuda do agent para criá-la. Peça ao agent que use seu criador de skills para conversar conosco sobre isso. Vale lembrar que há muitas skills desse tipo na comunidade, que você também pode instalar e usar. Enquanto o agent trabalha, ele pode fazer perguntas complementares. Geralmente, são muito boas. Quando a entrevista terminar, enviamos as respostas e o agent prossegue. Enquanto o agent estiver criando a skill, fique de olho no resultado. Ele está fazendo

51:00 as escolhas que você queria? Como você pode ver, o agent gravou a skill neste diretório. Vale lembrar que as skills podem ser específicas de um projeto ou globais. Há várias maneiras de invocar skills. No seu prompt, mencione a skill antes de dizer o que deve ser feito. Você também pode pedir ao agent que chame uma skill a partir de outra. De acordo com o padrão aberto de skills,

51:31 os agents usam a descrição da skill para decidir quando chamá-la, em um processo chamado divulgação progressiva. Mas o julgamento deles nem sempre é perfeito, especialmente quando a context window fica maior. Use a mesma heurística que usaria para marcar arquivos. Se você sabe que quer usar uma skill, mencione-a pelo nome. Isso economiza alguns tokens de raciocínio. Os agents têm comandos de barra integrados, como

52:03 /clear. Embora tenham sido populares no início, muitos agents estão deixando os comandos de barra personalizados e migrando para skills. Às vezes, você precisa dar ao agent mais recursos, como acesso a alguma API, a uma base de conhecimento privada, a um banco de dados e assim por diante. Até agora, a maneira universal de estender um agent tem sido o MCP, o protocolo de contexto de modelo. Por exemplo, os agents precisam de informações atualizadas e de qualidade sobre pacotes. A opção mais popular,

52:35 O Context7 é um MCP que traz a documentação atualizada de pacotes para o contexto do seu agent. Agora, seu agent pode se manter atualizado com o React 9.2 e versões superiores, em vez do React 9.0. Os servidores MCP ainda são populares, mas skills que usam ferramentas de código, como uma interface de linha de comando (CLI), muitas vezes cumprem a mesma função com mais elegância. O Context7 agora sugere uma skill que chama uma ferramenta CLI para acessar o Context7.

53:08 Vamos instalar o pacote Context7 para o Claude Code. Durante a configuração, vemos imediatamente uma escolha entre um servidor MCP e CLI mais skills. Vamos usar a segunda opção. Se esta for sua primeira vez, você precisará criar uma conta. Nós já fizemos isso e entramos na conta. Depois, podemos voltar ao Claude Code e colocá-lo em uso com um exemplo de prompt que usa o Context7. Enquanto o agent é executado, nós

53:39 vemos que ele detecta a necessidade de usar o Context7. Quando termina, o agent mostra que agora sabe como encontrar informações sobre nossa stack de texto. Essa tendência de passar dos servidores MCP para skills mais CLI está se acelerando. As pessoas estão repensando o MCP porque ferramentas CLI podem executar ações com menos configuração e menos uso de contexto. À medida que você amplia a implementação do seu workflow, das skills etc., vai querer compartilhá-los consigo mesmo

54:11 em diferentes máquinas, com colegas de equipe e talvez com o mundo exterior. Alguns agents, como o Claude Code, têm plugins: um conjunto de extensões de agent que podem ser instaladas e atualizadas. Há uma comunidade crescente de plugins gratuitos. Confira-os para ver se algum pode aumentar sua produtividade com desenvolvimento orientado a especificações. Lembre-se: plugins ainda não são um padrão comum a todos os agents. Assim como apps ou dependências, plugins podem executar código, então certifique-se de confiar neles

54:41 ao instalá-los e atualizá-los. O Spec Kit do GitHub é uma tentativa de formalizar um workflow de desenvolvimento orientado a especificações com agents. Instalar o Spec Kit em um projeto dá acesso a comandos de barra no seu agent, semelhantes ao workflow usado neste curso. O Spec Kit tem comandos para constituição, planejamento, tarefas e implementação. Outra alternativa popular é o OpenSpec, da Vision AI. O OpenSpec segue um workflow semelhante: propor, explorar, aplicar e arquivar

55:14 em que propor e explorar correspondem à etapa de planejamento, aplicar corresponde à implementação e arquivar corresponde ao replanejamento. Ele também tem padrões canônicos para funcionalidades rápidas. Ambos os pacotes incluem recursos úteis, como gerenciamento de branches, scripts de verificação e formatos de documentos de especificação com opiniões bem definidas. Recomendo que você experimente esses workflows open source para ajudar a aprimorar o seu. Às vezes, no meio de uma funcionalidade, você tem uma ideia. Quer pesquisá-la

55:45 com o agent, mas não quer interromper o trabalho na sua branch. Por exemplo, uma escolha de bancos de dados, mas você ainda não se decidiu sobre essa ideia, então não quer colocá-la no roadmap. A conversa gera algumas boas ideias e algumas boas perguntas. Aceitamos a maioria das recomendações, mas mudamos de ideia sobre uma delas. Você não quer perdê-la. Então, vamos manter um backlog de pesquisa, pedindo ao agent que escreva um

56:16 relatório em um local conhecido. Esse arquivo registra sua conversa e os resultados. Mais tarde, você pode pedir ao agent que agende essa pesquisa no roadmap, com um link para o arquivo do backlog. À medida que esse material cresce, você pode escrever uma skill para automatizar sua pesquisa. O desenvolvimento orientado a especificações ajuda o agent a escrever código do seu jeito. Você pode adotar um framework ou uma ferramenta existente de desenvolvimento orientado a especificações,

56:46 e depois personalizá-lo usando skills para trabalhar nos seus projetos do seu jeito e com sua equipe. O desenvolvimento orientado a especificações desloca o foco do como para o quê e o porquê. Como os agents e os modelos avançam tão rápido, você não vai querer que seu workflow fique preso a uma única opção. Nesta aula, vemos como os padrões nos permitem trocar de agent sem deixar de usar nosso workflow e até mesmo nossas ferramentas. Esses padrões para agents ajudam a alcançar esse objetivo: MCP para ferramentas externas,

57:19 agents.md para regras, agent skills para registrar workflows repetíveis com contexto adicional e ACP para conectar agents a clientes. Por exemplo, o Codex é um agent de IA líder da OpenAI. Ele funciona em um app para desktop e em editores, além de no terminal. Vamos vê-lo em ação. Aqui está nossa skill de especificação de funcionalidades da aula 12, copiada para o Codex, que

57:50 armazena as skills em um caminho diferente. Ela funciona perfeitamente depois da migração. Isso permite alternar entre agents no mesmo projeto, mantendo seu workflow de desenvolvimento orientado a especificações. Também podemos usar editores diferentes com agents diferentes, usando o padrão Agent Client Protocol. O ACP facilita conectar agents e editores. Se seu agent e seu cliente são compatíveis com ACP, você tem uma combinação perfeita.

58:20 Para tornar essa integração plug-and-play ainda mais fácil, o registro do ACP automatiza a busca, a instalação e a conexão de agents nos clientes. O registro do ACP abrange todo o ciclo de vida, facilitando combinar diferentes opções. Por exemplo, no JetBrains, a janela de chat de IA leva à instalação a partir do registro do ACP. Em seguida, o IDE pode mostrar uma lista de agents compatíveis. O OpenCode é um agent popular open source

58:51 O registro do ACP facilita adicioná-lo ao nosso IDE. Clicar em instalar automatiza tanto a instalação do próprio OpenCode, caso seja necessária — o que é ótimo — quanto a integração com o IDE. Quando tudo termina, seu IDE passa a ter integração nativa com um novo agent. Você pode usar esse novo agent junto com os outros agents no mesmo editor, como parte do desenvolvimento orientado a especificações. Esses novos padrões para agents estão trazendo

59:23 novas possibilidades. Mas como eles funcionam de fato? A arquitetura do ACP foi projetada para facilitar a conexão de agents e clientes. Na verdade, o protocolo corresponde ao que é usado no LSP. O ACP faz mais do que você imagina. Por exemplo, ele abrange sugestões de próxima edição no editor e o modo de planejamento. Para ir um passo além com o ACP, você pode escrever seu próprio agent personalizado, instalado localmente na sua ferramenta. Qual agent escolher? A

59:55 indústria muda rapidamente, e surgiram sites de benchmark com tabelas de classificação que oferecem diferentes avaliações. É claro que essas tabelas mudam rápido. Portanto, mantenha-se atualizado e baseie sua decisão nos critérios que importam para você. Nossas especificações funcionam em um nível mais alto e não estão vinculadas a nenhum agent ou IDE específico. Nesta aula, mostramos que criamos nosso workflow e nossas ferramentas para serem independentes do agent. À medida que surgirem mais padrões, essa flexibilidade deverá aumentar.

1:00:37 Ótimo trabalho por concluir este curso. Você viu como sair do vibe coding, em que torce para que o agent faça o que você quer, e chegar ao desenvolvimento orientado a especificações, em que você se aproxima mais do que realmente precisa. Você escreveu constituições, planejou funcionalidades por meio de conversas, validou como pessoa no ciclo e automatizou seu workflow com skills e padrões. As especificações que você escreve hoje se tornam a memória dos seus projetos amanhã. Mantenha-as bem definidas. Continue aprimorando seu processo.

1:01:07 E lembre-se: o melhor código começa com uma ótima especificação. Você e muitos dos engenheiros que conheço talvez já tenham visto as consequências de avançar rápido demais. Vamos trazer de volta um pouco da engenharia. Vamos manter você no comando do seu software. Eu realmente me importo em encontrar alegria e propósito em tudo, e estou animado para ver o que você fará com isso. Vá com tudo. Vá fazer coisas legais.

Transcrição original

[00:00] Welcome to this course on specdriven development built in partnership with Jet Brains. Spec driven development is currently the best type of workflow for building serious applications with agentic coding assistance. Give your coding agent a markdown file or a long prompt explaining exactly what to build and it implements that spec. Rather than writing code by hand, you focus on writing down the context that the agent doesn’t already have. I’m delighted that our instructor for this course is Paul Everett, who’s developer advocate at Jet Brains. Thank you, Andrew. And wait, I

[00:31] didn’t know you wore spectacles. >> You’re right. I don’t actually need these. Okay, that’s what I thought. Anyway, Spectrum development has three main benefits that you’ll start to see right away. First, you can control large code changes with small changes to the spec. One sentence like use SQLite with Prisma or might affect hundreds of lines of code. Change that to MongoDB for the same downstream amplification. This makes writing specs really efficient,

[01:03] far more so than writing code. Second, specs help eliminate context decay between sessions, preserving the non-negotiables. Agents are stateless, so loading them with the highest quality context right when they boot up is important. And finally, specs improve your intent fidelity. You define the problem, success criteria, constraints, and so on. And the agent can elaborate to create a fuller plan. One way I often

[01:34] write a spec is by having a conversation with an agent like cloud code or Gemini or CHB codeex to make the key architectural choices using my knowledge of how I want to make different tradeoffs. Then have the agent summarize the key decisions in a markdown file. Writing a spec requires thinking and this is hard work. You have to decide what product you want to build. What is features is technical architecture. And without the spec, you’d be leaving these important decisions up to the wins of the coding agent, which might be okay

[02:06] if you want to move really fast and just roll the dice, but certainly leads to less maintainable code and sometimes pretty weird products. For example, I’ve seen teams working on a complex software product where there was no clear spec and this led to many downstream headaches from these different coding agents under the direction of different developers building quickly but in contradictory ways. Specdriven development involves developing a constitution at the project level to define the immutable standards then

[02:37] iterating through feature development loops. These loops isolate each feature on its own branch with plan, implement, and verify steps that leave a clean slate between features and reduce headaches and context switching. This same workflow supports both green field and brownfield projects. In green field projects, you start from scratch. You’ll develop the constitution in a conversation with the agent. In brownfield existing code bases, you’ll

[03:08] generate the project constitution. based on the existing codebase. In both cases, you’ll then iterate through these feature development loops, managing versioning in small steps. In this course, you’ll also see how to write your own agent skills to automate your spec driven workflow. You know, if you can accomplish what you need in just one short prompt, that’s great. I’m definitely an advocate of lazy prompting when it works. But the great developers I know out there almost always will

[03:38] write detailed specs for projects with any significant complexity because they have unique context and an opinion on what or how to build that’ll be superior to letting the OM which is missing that context pick randomly. If your coding agent is going to go off and write code for 20 or 30 minutes, which may correspond to several hours of traditional developer work, you’re often better off sitting down for three or four minutes and writing it really clear instructions. Many people have contributed to this course, including

[04:09] Constantine Chiker and Zena Smeova from Jet Brains and Isabel Zaro from deep learning.ai. Let’s go on to the next video and let’s write some specs. When you hear a coding, you might think vibe coding. Let’s compare the two and see how specri development gives better results by bringing back engineering. Vibe coding gives quick results. You write a prompt describing what you want, like create me a button, and hope for

[04:40] the best. Then you look at the result. That’s a big button. It’s kind of close, but off on some important things. So you point out the mistakes to the agent, it tries again and so on until you are satisfied. As a result, you will end up with a long dialogue with the agent the history of which will not even be saved. This approach works okay for a button, but it doesn’t scale to a large ongoing project. While high-level prompts are

[05:11] fast, they lead to disposable code and mounting technical debt. We need engineering, a well-maintained specification that creates a permanent technical artifact. Specdriven development is the professional response to the chaos of unsupervised AI generation. It is a paradigm shift where the specification explaining the what and why is decoupled from the implementation, the how. With specs, we

[05:41] get a contract between the humans, but also with the agent. Your main task as the human now shifts. Learn how to convert your intentions into clear specifications. Spectdriven development with aentic coding assistance has three main benefits. First, you’re able to control large code changes with small changes to the spec. A few sentences in the spec outlining the look and feel of the app might translate to hundreds of lines of

[06:12] CSS. This specdriven approach reduces the cognitive overhead needed for working with these ultra fast coding agents. Second, specs eliminate the context decay problem that derails multi-turn agent sessions. As you work with your coding agent, its context window will fill up, often leading to more mistakes as the agent tries to cope with a full working memory. Specs persist between sessions and even agents, anchoring the agent to the core

[06:45] context needed to work in a codebase and implement a feature. Third, specs improve intent fidelity, meaning that the agent is more likely to produce code that matches your goals. That’s because specs force you to define the problem, success criteria, constraints, user flows, and so on before the agent starts generating code. Specs are a key differentiator between vibe coding some slop and engineering a viable software

[07:15] product. Whether you are starting a new project from scratch or want to implement the STD approach into a project that has been running for years, specs help solve the drift and productivity problems. As a comparison, think of compilers which convert understandable source code into machine code. STD guides the agent and prompts converting specs into source code. Even better, the specs are in a human

[07:45] language, making it easy for stakeholders. Speciven development has taken off recently as a solution to concerns about productivity. Multiple STD projects, tools built around spec authoring, conference talks on capturing intent. This is all part of a broader push to bring engineering lessons learned from the software development life cycle to agentic coding. Spectdriven development is used with coding agents, not simple chat bots. A chatbot can talk about code, but the

[08:18] chatbot doesn’t have access to your project’s code, nor tools you have installed. It just responds to your prompts. Agents are different. They take your prompt, make a plan, and guide themselves to a result using reasoning along the way. Importantly, agents have access to your code base and your development tools. In the STD workflow, we treat these agents as highly capable pair programmers. They provide the

[08:48] technical knowledge and the speed and you, the senior architect, provide the blueprints. As we move forward in this course, remember the agent is the muscle, but the spec is the brain. With practice, you ensure that the software produced is not just functional, but is aligned with your long-term goals. Speciven development tells the agent how to build what you want upfront for the project, then for each feature, getting better as you go. With STD, we help the

[09:19] agent with the best quality context. First with decisions about the project, then with details about each feature. This spec is very detailed. One key skill in STD is knowing the right level of detail. If you treat your agent as a highly capable pair programmer, you’ll often hit the right level. Lots of context about the goals, mission, target audience, and constraints and less about the low-level decisions the agent can figure out on its own. What does this SD

[09:53] workflow look like? First, we specify the constitution. What is the mission? The tech stack, the road map. A constitution is just one way to formalize these project level details. Many developers use a tople agents.md file for this purpose, but a project constitution is agent agnostic and more structured. The constitution captures the agreement on key decisions between the human and the agent, but also the

[10:23] agreement between the humans. The mission explains the why, this project’s vision, audiences, scope, etc. Defining these parameters in advance is very common in software projects and helps guide ongoing decisions. The tech stack is for the engineering team, a common understanding of development and deployment technologies and constraints. The road map is a living document with a sequence of phases, each implemented with their own feature spec process.

[10:55] Once the constitution has been drafted, we work on each feature with a repeatable process. First, plan the feature, implement it, and finally validate the result. In between features, it’s time for the replanning phase. Revise your constitution, update the road map, even improve the process itself. As you heard a moment ago, one of the key skills of STD is providing the right level of detail to create the

[11:25] highest quality context. In the feature phase and the replanning phases, you steer the agent. Look at it this way. Imagine that you are an architect and you give detailed drawings of a building to builders. Then it’s up to them. Your role is to design, supervise the construction, then review and accept the results or ask for changes. You’ll want to avoid telling the builders how to do their jobs and focus on providing the

[11:56] context they don’t know. Spectriven development gets you from thinking at the start to delivering at the finish. Best of all, it keeps you improving from there. This is one std workflow that modern developers are starting to use. Soon we’ll look at the start, the project constitution. But first, let’s do a little setup preparation. To get set up with the project repo, follow instructions in the next reading item. The following video setup is optional.

[12:28] If you’re already comfortable with setting up a coding agent like Claw Code in an IDE such as WebStorm, feel free to skip this optional video. See you in the next video or the next one. Before you send your first prompt, let’s talk a little bit about setting up your workspace. If you’re already comfortable

[12:59] with setting up a coding agent like Claude Code in an IDE such as WebStorm, feel free to skip this optional video. Spec driven development is a best practice that isn’t tied to any specific IDE or coding agent. So you can choose the setup you’re already using or the same one you’ll see in this course. VS Code with the codec CLI, Z editor with a local model, all great for specdriven development. Since we are planning to

[13:29] develop a web application, this course will use the WebStorm IDE with Cloud Code as a coding agent. Instructions on downloading and installing both have been included in the previous reading item. Let’s open up WebStorm and start a brand new project named Agent Clinic. This will be a TypeScript project with a Git repository to keep close track of versioning your code and specs.

[13:59] Although many IDEs, including WebStorm, offer a chat panel, we know there’s a lot of diversity in how you interact with your coding agents. In Spectrum and Development with agents, it’s important to keep close track of versioning your code. Let’s say we want to create an initial commit using the agent. Every time it needs to execute a command, it will ask you for the confirmation unless you start clawed code in an unsafe mode. Pay close attention to what Claude code

[14:30] asks you to do. The ultimate responsibility for the code is yours. Throughout the coming lessons, you’ll see several tricks and best practices for specri development with Git. Great. We’ve got our setup ready and you’ve got yours ready. Let’s get started. You need to tell your agent about your project, the mission, audience, and other decisions. In this lesson, we’ll work together with the agent to write the constitution. What really is your

[15:00] project? Say you’re working on a new web app for your company. What’s the core idea behind its development? How does it fit within your company’s preferred tech stack? what features are planned. These three foundational principles form the constitution, a global set of high-level requirements that will guide future feature development and explain the project shape to stakeholders. For example, you have so many choices for your tech stack. You’ll want to narrow

[15:31] down your options based on appropriate trade-offs and what you use at your company. We need to write this down for the agent, for your teammates, for the future. But we don’t write it alone. We write it in a conversation with the agent. He’ll be surprised at the great questions that we’ll ask, architecture patterns you hadn’t considered, external packages that already do the work, or tradeoffs, for example, speed versus

[16:02] data fidelity. The emission, text stack, and road map aren’t just properties of a green field project you’re starting from scratch. Existing code bases use these three pillars, too. We will talk about bringing the SD workflow to existing projects in just a few videos from now. Here’s the example project we’ll use throughout this course. We are writing Agent Clinic, a place for AI agents to get relief from their humans. Agent Clinic is a fun parody of the popular

[16:33] learning project Pet Clinic. Coding agents are doing a lot of work. It’s stressful. Hallucinations, context, rot, memory issues, and co-worker sub agent coordination all take a toll on agent health. Let’s build a clinic where they can get help with their issues. It’s a full stack web app with a Nex.js backend and a React front end. The app allows you to manage appointments, ailments like hallucination, and treatments like

[17:04] a context infusion. Let’s take a look at how you might go about writing a detailed spec for a project like this. Let’s chat with the agent. First, we provide our project description to the agent and tell it that our stakeholders gave their input in readme.md which we added to the repo. In the important note, we directly mention Claude codes ask user question tool. This tool is totally optional, but

[17:34] we just like the way it looks in the interface. Also, for the project’s constitution, tell the agent to work with you on a mission, tech stack, and road map. Spectriven development works best with a human in the loop approach where you review small changes. So tell the agent to organize the road map in small steps. As we work together, you’ll see the agent asks some really good questions. You might see different ones.

[18:04] The first question says, “What tone should the mission MD take?” I’ll choose, you guessed it, playful. That covers the mission. Now, some questions for the text stack. Our engineers are used to TypeScript on the back end. So let’s add that to the requirements. Next, for our road map, it asks how granular it should be. I’ll choose the first option. We finished the initial interview. Let’s choose submit answers.

[18:36] The agent will ask you for write permissions. This keeps changes under your control. If you are comfortable with the security trade-offs, you can select the option to approve all instances of a particular command for this session. You’ll see this in the rest of the course. Now, we’re done and we have three files in the specs directory. Mission.md, text.md, roadmap.mmd.

[19:07] It’s human in the loop time. Let’s review. For example, the mission left out a target audience. That’s reasonable. How could the agent know your business? Instead of editing directly, let’s continue the conversation. To keep all artifacts consistent, it is better practice to ask the agent to make changes to them manually, and you might miss updating related documents.

[19:38] We want to use SQLite for this project. Since this is a quick prototype, we didn’t mention it, but the agent figured it out in recommendations. It’s now part of our text stack. Do one final review. It’s important to get everything right up front. Let’s commit the constitution so it will be a living document for the project. Agent Clinic now has a constitution mission road map text stack to guide our

[20:08] project. We’re ready to tackle our first feature. We now have a road map with features. But how do we build them with specs of course starting with the first road map feature. Let’s take a look at the agent clinic road map. Here’s our phase one feature. Hello Hano. But it’s too early to start coding. We need to discuss the spec and clarify all the details. A good plan outlines the approach, the sequence of work, and how to validate success.

[20:41] Let’s start with fresh agent context. The agent can get what it needs from the official source, the constitution. We will work on this feature in a separate branch, which we will indicate to the agent. Our prompt will help start a conversation with the agent about the feature spec, a plan for tasks, collect requirements, and a scorecard for validation. The agent will ask you to make key decisions. Pay attention to potential conflicts or problems. You

[21:11] don’t have to agree with the solutions proposed by the agent. Make sure to clarify anything that bothers you. First, regarding phase 1 scope, we’ll keep it exactly as written. For the requirements, let’s pin the HANA version and enforce strict TypeScript. For the confirmation, manual curl looks good. Then, let’s submit. That was fast. Must have been the nano.

[21:41] Work is done and the ball is back on our side for reviewing the feature spec created by the agent. Let’s review the feature plan first. It’s important to get these docs right in the beginning to keep the agent on track. If you find something wrong, ask the agent to fix it to make sure it keeps the requirements and validation in sync. For example, we would like a nice looking placeholder homepage in this first feature spec. We make the change via the agent.

[22:13] Next, the requirements. These were also updated to reflect the homepage update. This is the right place to indicate any important technical needs or constraints. Don’t speed through this, but don’t state minor technical details like variable names here. We want to control the process, but not over steer the agent. Last, the validation. Make sure the agent can check that it got it right. Again, these were updated for the homepage. We’re done with the feature

[22:44] spec. Let’s create a commit in the IDE. Nice. We formulated a feature spec strategy. Made a feature branch. Interviewed with the agent about what the feature should do. Put the results in markdown documents. Reviewed these spec files. Committed. The changes you make here in the specs will expand downstream into hundreds of lines of code. So time spent here is well spent. It’s time for implementation.

[23:16] We’re working on the plan for the first feature in the project roadmap. We finished the feature spec. Let’s do the full implementation of this feature. Just to refresh ourselves, we do a quick review of this feature specs plan. This was the first feature. Hello HANA. The feature spec documents have what we need. To start your implementation, you’ll want to clear out your context with a slashclear command. Let’s go back to the agent and enter a prompt to

[23:47] implement all the task groups. Sometimes you might choose to do task groups one at a time for even smaller steps and commits. This technique is especially helpful for areas where small mistakes can compound later, like in security or database management. While claw is running, you can observe the changes it displays in the console to see its progress in real time. Afterwards, we can watch for the final changes in the commit window and visit

[24:17] the changes. This gives us an early jump on reviewing the work. This is the key role of the developer in such a paradigm to act as an architect or supervisor and ensure that the agent is provided with a clear contract. We can also see the summary of what was done. As you can see, the agent provides extra details on the work performed for each of the task groups. Now, let’s go to the package.json file and in there, let’s

[24:50] run the app. The server starts in the console. The browser shows the result of this feature spec. Not much. We said nano, but it’s a good feeling to see pixels on the screen. We just implemented a feature. The agent did its validation. In the next lesson, we’ll do ours. It’s nice to have a feature ready, but don’t merge yet. In this last feature step, we

[25:20] collaborate with the agent to review the work. Fortunately, programmers have good tools for this validation task. After all, programmers have long spent several hours per week on code review. Start with the commit view. Let’s go through the changes. Focus your review on high-level concerns like whether the features work and reflect the spec rather than details like which CSS classes were implemented. For example, the home.tsx is minimal.

[25:51] Nano really meant nano. We want a layout component with clear landmarks for header, main, and footer, but do these as subcomponents and create a CSS file. As it turns out, this mistake in the code flowed from a mistake in the plan. We didn’t ask for this. Let’s ask the agent to do the fix, thus correcting both spec and implementation. This process that consists of the agent generating something and us verifying it

[26:24] is known as the human in the loop. Because agents are so fast at writing code, software developers have lately been talking about cognitive debt, the mental load of tracking what your code is doing and how it has evolved. That is why in order for this process to be fast and easy to control and to reduce cognitive debt, the changes should be manageable. The agent is making our changes but also validating that these

[26:54] changes didn’t break anything. Good news, the agent finished and gave us a quick summary. You can also see this in the editor. The feature plan was changed to add a group five to list these new steps. The code now has a layout component and a CSS file was added. It looks like the three subcomponents

[27:26] were just put in the same file, but that doesn’t follow conventions. Let’s put these in their own files using the IDE move tool. These kinds of changes are easy in editors and we’ve always been good at this. No need for an agent, right? Let’s just do it. Not so fast. This can lead to drift

[27:56] where other artifacts, specs, readmes get out of sync. Let’s ask the agent to fix any mentions and to make sure this doesn’t waste some time later. All changes are done. Did we break something? Test would help, but the agent didn’t install our testing package. Since this is needed for all features, we’ll cover it in the next lesson. Now, we’re ready to mark this work as complete and merge our results.

[28:27] Notice that the part of the constitution was updated alongside the feature in this branch. How to handle versioning of the specs and how to associate which specs created which code changes is an evolving topic in the community. The change to the road map is small. Just checking off a step in the road map. So, it’s okay to keep these updates on the same branch. If the overall constitution update is more complicated, it might be better to do this in a separate branch. Now, we’re

[28:58] ready to mark this work as complete and merge our results. We just used specdriven development to develop and validate our first feature. But wait, shouldn’t we take another look at the project’s broader scope? We successfully implemented the first feature. Can’t wait to do it again and again. Don’t rush into it. Take a step back and reflect with some replanning. You have to run slow to run fast. We have a

[29:29] workflow step called validation. Tests are good for validation, but we didn’t give the agent all our testing preferences. Let’s make a replanning branch to update the text stack in our constitution. As you saw in the previous video, spec versioning is an evolving topic. The Constitution is a living document. It’s good practice to make updates to it in its own separate branch so you can keep track of which versions of it produced which code. We’ll use a

[29:59] prompt to state our policy. It looks like the agent updated the package.json just to have a script, no dependency. Something to note for later when we do run tests. This change to add a testing framework applies to future code. But let’s tell the agent to update existing feature specs and implementation based on this constitution change.

[30:30] After these two prompts, we have some good changes. The agent set up this testing change but didn’t write the test themselves. Let’s tell the agent to write some new tests. With this setup, we can run tests conveniently in our editor. Let’s run under the debugger to give us a chance to step through code execution as part of the human in the loop.

[31:03] Looks good. We now have tests as part of validation. Let’s commit. Sometimes we realize we want to do something differently in the product plan. For example, after implementing the first feature, we got an update from the product manager. Because 40% of our users are on mobile, we want to emphasize a responsive design. Let’s go to the agent. Tell the agent we want responsive design and to correct the

[31:34] product specs and feature specs as well as any code. Since we’re so early on in development, this update is a small change. So, it makes sense to directly implement it during replanning. But if the new work is big, it’s better to schedule it on the road map as its own feature phase instead of just doing it in replanning. Use your judgment. Remember, we want the specs to capture decisions, not just the code. We want to try to keep both in sync to help team

[32:05] communication. The agent has implemented our responsive fix with updates not just in code but also to the product and feature specs. Time for us to do our part and review the changes. Let’s go through the diffs. This looks good. Let’s do a commit. Remember, working in small steps with frequent commits keeps the review from overloading your brain. While this first part of replanning is working, let’s

[32:37] step back and do some project housekeeping. For example, let’s revisit the project road map and look at the next task. Does it still make sense? The road map shows the next feature which we cover in the next lesson. Is it still the correct one? Looking through the road map, it looks like features 2, three, four, and five kind of hang together. Let’s update the road map to tackle those in one step. We’ll commit and start on this new feature shortly.

[33:09] The replanning step can be about a feature or the whole project, but replanning can also be about improving your specdriven development workflow across projects across your organization. For example, maybe you have a few non-technical stakeholders that want to monitor the project’s progress. You’d like it to update a change log on each merge domain. Most AI coding agents support skills, a package of instructions and resources providing the

[33:41] agent new capabilities and expertise. Skills are great for definable, repeatable workflows that require context specific to your project or organization. A skill would be great for implementing a change log update. You could write this skill by hand, but many agents actually have skills that help you write a skill. Let’s use the agent to help us write and maintain a change log skill.

[34:12] The agent gets to work. One thing for us to consider is this skill unique to this project or should it be a standard part of all projects. This is a style choice and you’ll gain better understanding as you use it. You’ll learn to automate your STD workflow with skills. For example, your validation step might include updating the readme, linting, formatting, test running, and other quality checks. You

[34:42] can work with your agent to package those into a validation skill. Repeatable process, less manual work. The agent is finished. We can scroll through the window to see what it created and how to use it. Note that it chose to create this in the global skills area. This skill will now be usable across all projects. Also, cloud code used the new skill to generate a change log in this project. Change logs are how you talk to your

[35:14] stakeholders, including the agent. So, let’s open it and review it manually. Looks good. We are finished with this replanning work. Let’s wrap up with a commit, then merge the branch. Now that most of your work as a developer is in planning and validation rather than implementing, make time between features to replan. In the next video, we’ll work on another roadmap

[35:46] feature. We have an improved constitution and an improved workflow. We’re getting better. But before moving on to the next road map feature, let’s tackle some strategies to deal with a common pain point. AI fatigue. Agents can generate a lot of code with a lot of changes. This massive amount of code makes the human in the loop validation exhausting. So much to review. To fight this confusion, make

[36:16] sure you have a clean division between each feature phase. We should start each feature in the right flow state. Do I have unfinished work? Did I merge the last feature branch to main? Is the next road mapap item the right thing to do? Did I clear the A’s context to ensure the specs capture the intent instead of memory snapshots and to let it focus its limited context budget on the next work. Take a moment to make a good start to

[36:48] help yourself finish. We’ve done all this. Let’s clear the context and start the next feature, agents and ailments. As a note, we keep typing the same thing. We’ll talk about how you can streamline this repeated prompting into a custom workflow in a future lesson. As before, the agent asks good questions. The first one is about whether to keep all these features in one phase. We already decided to do this together in the previous lesson, so we’ll say yes.

[37:21] For the migrations, we’ll choose plain SQL. For validation, let’s select one, two, and three. That’s good. Now, let’s submit. When the agent drafts the spec, we can see some of its choices. The agent’s reasoning process is useful to watch. If you’re using an agent with verbose mode, that could give you even more insight into its intermediate ideas.

[37:52] Looks good. But we want to make one small change to capture our intent. We want to use Pico CSS as our CSS framework. Next, we review the three files in the feature spec. Starting with the requirements. Let’s ask the agent to change the requirements to make sure any other files reflect the change. When the work is finished, let’s commit the feature spec. This time, we’ll let the agent come up with the message. With the

[38:22] spec for the second feature ready, let’s go to implementation. The division between the planning phase and the feature phase helps us to not overflow context. Ours and agents. If the feature seems too big to implement all at once, ask the agent to implement part of the feature plan first. This will keep the size of the changes manageable. Our

[38:54] agent has implemented the phase 2 feature. We watched the agents progress so we have a rough idea of what was done. But that’s not enough. Slow down. Do some thinking. Let’s do an indepth review of the changes. Everybody has their own style on how much to review the agents results. To play to the agents strengths and reduce AI fatigue, stick to higher level requirements. Avoid nitpicking stuff like variable names. Just make sure it creates code

[39:26] that you can commit under your name. For example, it used inline type information for the props. We’d like the prop definition in a standalone TypeScript type. Let’s tell the agent to fix this everywhere in the code. You probably didn’t include this decision in your spec. Remember, an emission such as extracted prop types isn’t a failure. You are evolving the

[39:57] spec as you discover new details, and capturing that leads to better future results. We’re finished with our review. This is a good moment for another smallstep commit. Last step, validation. Let’s review what the agent plans to do for the validation step in this features spec. Looks good. Let’s do our validation. Remember, we want to make sure the changes are good by running the application.

[40:32] But we also want to prevent cognitive debt by validating that we understand these changes. Tests are a great place to work through the flow. Let’s read some tests and run them under the debugger as exploration. Sometimes you need to validate that you weren’t lied to. Tell the agent to spawn several sub aents to do a deep review of the entire project with this feature

[41:02] change. This deep review gives the agent more space to think about the changes and using sub agents preserves the main agents context window rather than polluting it. These sub agents will come back with a number of issues and recommendations. All of these look good. So, let’s proceed. The agent goes off, does a bunch of fixes, runs tests, and gets our project

[41:34] into a good state. Keep this in your tool chest. The agent can usually find important issues during a second look. Once we are finished with our validation, our feature is complete. It’s time to commit our feature work. As our last step on this feature, let’s use the change log skill that we made in the previous lesson. We’ve now documented the changes on this feature branch. One more commit, then merge the

[42:05] branch. In a previous lesson, we saw the replan step in between features. Let’s do a quick version of this by looking at the road map. Does the next feature still seem right? Looks good. Our project is in good shape, ready for the next feature. This clean break between features helps manage AI fatigue. Now you can take a break for some coffee. We’re starting to see a repeatable STD process for feature

[42:36] development. One that captures our decisions. In the next step, let’s test that hypothesis. Do we have enough to build an MVP? We made a lot of progress. two features implemented with our spec workflow, but management just asked of course for an MVP. Have we made enough progress to do an experiment? Let’s do a variation of our standard feature spec prompt. This time, we’ll tell it to implement the rest of the road map and give some

[43:08] guidance about existing feature specs. In general, you should only implement such a large chunk if you feel confident in the quality of your constitution and spec. The better the context you provide your agent, the more confident you can be in getting a result aligned with your intentions. And you should be sure that you can handle review and validation. But since we’ve taken this risk, now let’s view the MVP as an extreme test of our constitution and completed feature

[43:39] specs. If we now get something different from what we wanted, it means we need to very responsibly carry out another replanning phase to eliminate whatever led the agent astray. The agent asked me some questions. Again, these are good questions and recommendations. A lot of spec files start as a back and forth conversation with an agent. Finished with the interview and we selected submit answers. Let’s write the MVP specs to disk.

[44:11] It’s always good to review the specs. You’ll often notice incorrect assumptions the agent made to fill the gaps. Let’s give a quick look at the plan, the requirements, and the validation. As always, we like to work in small steps with frequent commits. Let’s save the planning stages feature spec. We are finished with planning. It’s time for the agent to go do a big implementation step. The agent now does

[44:41] a lot of work. Once it’s finished, it’s showtime. Let’s see the MVP. We’ll go to our scripts to run the application. As you can see, each section now has much more driven by sample data queried from the database. At this point, usually we would validate the code results, but this is an MVP. Let’s ask the agent to validate the specs. As it turns out, this was useful. The

[45:13] agent showed places where the MVP found holes in our planning. We can share this evaluation with the stakeholders for their MVP review, then merge or archive the branch. Our specdriven workflow succeeded. After a constitution and two features, the MVP produced a useful demo thanks to our guidance. Of course, not all software projects involve building an MVP. Many projects are so-called brownfield. They start from an existing

[45:44] codebase. Next, let’s see how to introduce this workflow to legacy projects. People say spec driven development and even AI are only good for green field projects, but STD is also good for existing legacy projects. In this lesson, we’ll introduce STD to an existing project. To make it easy, we’ll start with a project you already know, the agent clinic MVP. We’ll make it a legacy by starting on

[46:15] main without the specs folder in a new cloud code session in a different project directory. We have some project background in the readme.md file with some open work listed in to-do.md. Your legacy project might have full product plans in issue trackers, spreadsheets, word documents, etc. Remember our workflow? We’ll start with the constitution step. We’ll use almost the same prompt from lesson 4. This time

[46:47] we’ll tell it to look for road map items in existing artifacts. In this case, a to-do file. Remember, the agent will discover and in a sense reverse engineer the SD artifacts from the existing codebase. The constitution will help align future code changes made by the agent with what past devs have already created. You can always add more context if you have it. For example, you might have been dropped into this project in order to improve its efficiency while

[47:18] implementing highly requested features. The process is the same, but the conversation might be richer as the agent has more artifacts, code, commits, documents, etc. You’ll see a lot of tool calls here as the agent explores the codebase. Let’s look at the constitution for our legacy project. In the mission, we have an audience, the project idea, and some extra information about the project. The text stack shows that Claude extracted the project file

[47:50] structure, framework versions, and the clarifications we were asked. In the road map, we can see the work is organized in phases matching the to-do file. Let’s create a commit for the constitution files that we produced with a commit message. Remember that in SDDD specs are part of your versioning strategy. Our legacy project is now placed on an SD foundation. From now on, the workflow is exactly the same as we

[48:21] discussed in previous lessons. First, we grab the next feature on the road map and plan it in a conversation with the agent. We’ll be doing phase one feedback form. Very good. We now have a branch and specs for this feature. Let’s review the feature spec, the plan, the requirements, and the validation.

[48:53] Then we commit the feature spec. After we have made any corrections by chatting with the agent, we proceed to implement the feature. Once the agent is finished, we do our validation to make sure the code is good and the feature works as expected. Our feature loop is done. We can commit and then merge the branch domain.

[49:27] Now it’s time for replanning. Make sure you give time for this. Since you just added SDDD into your project, you may find a lot of things to tune. We now have a legacy project rebased onto specdriven development without a bunch of manual work. This gives us a well doumented flow working in steps using engineering and staying in control. The spec is now the memory of the project.

[49:57] Just don’t fade. You’ve now mastered an SD workflow. Want something faster and lighter weight? In this lesson, we will automate things, but doing it our way with a custom process. We previously showed agent skills, an open standard to give agents new capabilities and expertise. For example, we repeat the same prompt when starting a feature spec. Do this, do that, write these three files. Let’s

[50:28] automate this with a skill and with help from the agent to write it. Ask the agent to use its skill creator to talk through this with us. As a note, there are many of these skill skills in the community that you can also install and use. As the agent runs, it might ask some follow-up questions. These are usually quite good. When the interview is done, we submit the responses and the agent proceeds. While the agent is working on the skill, keep an eye on the output. Is it making

[51:00] the choices you wanted success? As you can see, the agent wrote the skill to this directory. As a note, skills can be per project or global. Skills can be invoked in several ways. In your prompt, refer to the skill before saying what to do. Also, you can ask the agent to call a skill from another skill. According to the skills open standard,

[51:31] agents use the skill description to decide when to call it in a process called progressive disclosure. But their judgment isn’t always perfect, especially as the context window gets larger. Use the same heristic as file tagging. If you know you want a skill used, name it. That saves you some thinking tokens. Agents have built-in slash commands like

[52:03] slashcle. Though initially popular, many agents are moving from custom slash commands over to skills. Sometimes you need to give the agent more resources like access to some API, a private knowledge base, database and so on. Until now, the universal way to extend an agent has been MCP model context protocol. For example, agents need current quality context about packages. The most popular choice,

[52:35] context 7, an MCP that brings updated documentation of packages into your agent context. Now your agent can stay upto-date with React 9.2 and higher instead of React 9.0. MCP servers are still popular, but skills that use code tools like a CLI command line interface often accomplish the same purpose more elegantly. Contact 7 now suggests this a skill that calls a CLI tool for context 7.

[53:08] Let’s install the context 7 package for claude code. During the setup, we see this immediately a choice between MCP server and CLI plus skills. We’ll use the second choice. If this is your first time, you’ll need to make an account. We already did so and logged in. Once done, we can go back into clawed code and put it to use with an example prompt that uses context 7. As the agent runs, we

[53:39] see it detects the need to use context 7. When it completes, the agent shows it now knows how to find out information about our text stack. This trend from MCP servers to skills plus CLI is accelerating. People are rethinking MCP because CLI tools can take action with less setup and less context usage. As you scale your workflow implementation, skills, etc., you will want to share it with yourself

[54:11] across machines with teammates, perhaps with the outside world. Some agents, such as Clawed Code, have plugins, a collection of agent extensions that can be installed and updated. There’s a growing community of free plugins. Check them out to see if any will boost your SD productivity. Remember, plugins are not yet a cross agent standard. Like apps or dependencies, plugins can execute code, so make sure you trust

[54:41] them on install and update. GitHub’s spec kit is one attempt at formalizing a specdriven development workflow with agents. Installing specit for a project gives you access to slash commands in your agent similar to the workflow you used in this course. Specit.comstitution plan tasks and implement. Another popular alternative is openspec from visionai. Openspec follows a similar propose explore apply archive workflow

[55:14] where propose and explore match with the plan step. apply matches with implement and archive matches with replanning. It also has canonical patterns for quick features. Both packages include helpful features like branch management, verification scripts, and opinionated spec document formats. I encourage you to experiment with these open- source workflows to help refine your own. Sometimes in the middle of a feature, you have an idea. You want to research

[55:45] it with the agent, but you don’t want to stop your branch work. For example, a choice of databases, but you’re not yet committed to this idea, so you don’t want it on the road map. The conversation produces some good ideas and some good questions. We accept most of the recommendations, but change our mind on one of them. You don’t want to lose it. So, let’s keep a backlog of research by telling the agent to write a

[56:16] report in a well-known location. This file is a record of your conversation and results. You can later ask the agent to schedule this research on the road map with a link to the backlog file. As this grows, you can write a skill to automate your research. Specdriven development helps the agent write code your way. You can adopt an existing STD framework or tool,

[56:46] then customize it using skills to operate your projects with your team your way. Specdriven development moves the work from the how to the what and why. Since agents and models progress so fast, you don’t want your workflow tied to just one choice. In this lesson, we see how standards let us switch agents while keeping our workflow and even our tools. These agent standards help for this goal. MCP for external tools,

[57:19] agents.md for rules, agent skills for capturing repeatable workflows with extra context, and ACP for connecting agents to clients. For example, Codeex is a leading AI agent from OpenAI. It runs in a desktop app and in editors as well as in a terminal. Let’s see it in action. Here is our feature spec skill from lesson 12 copied into codecs which

[57:50] stores them in a different path. It runs just fine once migrated. This lets you switch back and forth between agents in the same project, keeping your SD workflow. We can also use different editors with different agents using the agent client protocol standard. ACP makes it easy to connect agents and editors. If your agent and client support ACP, you have a perfect match.

[58:20] To make this plug-and-play even easier, the ACP registry automates finding, installing, and connecting agents within clients. The ACP registry covers the whole life cycle, making it easier to mix and match. For example, in Jet Brains, the AI chat window leads to installation from the ACP registry. The IDE can then show a listing of compatible agents. Open Code is a popular open-source

[58:51] agent. The ACP registry makes it easy to add to our IDE. Clicking install automates both the installation of Open Code itself if needed, which is nice, and integration into the IDE. Once finished, your IDE now has native integration with a new agent. You can use this new agent alongside the other agents in your same editor as part of SDDD. These new agent standards are bringing

[59:23] new possibilities. But how do they actually work? The ACP architecture was designed to ease plugging together agents and clients. In fact, the protocol matches what’s used in LSP. ACP is more than you think. For example, it covers next edit suggestion in the editor and plan mode. To go one step further with ACP, you can write your own custom agent installed locally in your tool. Which agent to choose? The

[59:55] industry changes fast and benchmark sites have sprung up with leaderboards providing different evaluations. Of course, these leaderboards change fast. So, make sure to keep up to date and base your decision on the criteria that matter to you. Our specs work at a higher level, not tied to any one agent or IDE. In this lesson, we prove that we built our workflow and tools to be independent of the agent. As more standards emerge, this flexibility should grow.

[1:00:37] Great work completing this course. You’ve seen how to go from vibe coding where you hope the agent does what you want to specriven development where you get closer to what you actually need. You’ve written constitutions, planned features through conversation, validated as the human in the loop, and automated your workflow with skills and standards. The specs you write today become the memory of your projects tomorrow. Keep them sharp. Keep improving your process.

[1:01:07] And remember, the best code starts with a great spec. You and many of the engineers I know may have seen the consequences of moving too fast. Let’s bring back some engineering. Let’s keep you as the driver of your software. I really care about finding the joy and purpose in all things, and I’m excited to see what you do with this. Take it sleazy. Go do some cool stuff.