AGENTS.md

1# AGENTS.md
2 
3## Visão Geral do Projeto
4 
5Este é um repositório educacional para ensinar fundamentos de desenvolvimento web a iniciantes. O currículo é um curso abrangente de 12 semanas desenvolvido pelos Microsoft Cloud Advocates, com 24 aulas práticas abordando JavaScript, CSS e HTML.
6 
7### Componentes Principais
8 
9- **Conteúdo Educacional**: 24 aulas estruturadas organizadas em módulos baseados em projetos  
10- **Projetos Práticos**: Terrarium, Jogo de Digitação, Extensão de Navegador, Jogo Espacial, App Bancário, Editor de Código e Assistente de Chat de IA  
11- **Quizzes Interativos**: 48 quizzes com 3 perguntas cada (avaliações pré e pós-lesson)  
12- **Suporte Multilíngue**: Traduções automáticas para mais de 50 idiomas via GitHub Actions  
13- **Tecnologias**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (para projetos de IA)  
14 
15### Arquitetura
16 
17- Repositório educacional com estrutura baseada em lições  
18- Cada pasta de lição contém README, exemplos de código e soluções  
19- Projetos independentes em diretórios separados (quiz-app, vários projetos de lição)  
20- Sistema de tradução usando GitHub Actions (co-op-translator)  
21- Documentação servida via Docsify e disponível em PDF  
22 
23## Comandos de Configuração
24 
25Este repositório é principalmente para consumo de conteúdo educacional. Para trabalhar com projetos específicos:
26 
27### Configuração Principal do Repositório
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Configuração do Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Iniciar servidor de desenvolvimento
40npm run build      # Construir para produção
41npm run lint       # Executar ESLint
42```
43 
44### Projeto API Bancária (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Iniciar servidor API
50npm run lint       # Executar ESLint
51npm run format     # Formatar com Prettier
52```
53 
54### Projetos de Extensão de Navegador
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Siga as instruções específicas do navegador para carregar extensões
60```
61 
62### Projetos de Jogo Espacial
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Abra index.html no navegador ou use o Live Server
68```
69 
70### Projeto de Chat (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Defina a variável de ambiente GITHUB_TOKEN
76python api.py
77```
78 
79## Fluxo de Desenvolvimento
80 
81### Para Contribuidores de Conteúdo
82 
831. **Fork o repositório** para sua conta no GitHub  
842. **Clone seu fork** localmente  
853. **Crie uma nova branch** para suas alterações  
864. Faça mudanças no conteúdo das lições ou exemplos de código  
875. Teste quaisquer alterações de código nos diretórios dos projetos relevantes  
886. Envie pull requests seguindo as diretrizes de contribuição  
89 
90### Para Aprendizes
91 
921. Faça fork ou clone do repositório  
932. Navegue sequencialmente pelos diretórios das lições  
943. Leia os arquivos README de cada lição  
954. Complete os quizzes pré-lição em https://ff-quizzes.netlify.app/web/  
965. Trabalhe nos exemplos de código nas pastas da lição  
976. Complete as tarefas e desafios  
987. Faça os quizzes pós-lição  
99 
100### Desenvolvimento ao Vivo
101 
102- **Documentação**: Rode `docsify serve` na raiz (porta 3000)  
103- **Quiz App**: Rode `npm run dev` no diretório quiz-app  
104- **Projetos**: Use a extensão Live Server do VS Code para projetos HTML  
105- **Projetos API**: Rode `npm start` nos diretórios das APIs respectivas  
106 
107## Instruções de Teste
108 
109### Teste do Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Verificar problemas de estilo de código
114npm run build      # Verificar se a compilação foi bem-sucedida
115```
116 
117### Teste da API Bancária
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Verificar problemas de estilo de código
122node server.js     # Verificar se o servidor inicia sem erros
123```
124 
125### Abordagem Geral de Teste
126 
127- Este é um repositório educacional sem testes automatizados abrangentes  
128- Teste manual foca em:  
129  - Exemplos de código executando sem erros  
130  - Links na documentação funcionando corretamente  
131  - Builds dos projetos completando com sucesso  
132  - Exemplos seguindo as melhores práticas  
133 
134### Checagens Pré-envio
135 
136- Execute `npm run lint` em diretórios com package.json  
137- Verifique se os links markdown são válidos  
138- Teste exemplos de código no navegador ou Node.js  
139- Verifique que as traduções mantêm a estrutura adequada  
140 
141## Diretrizes de Estilo de Código
142 
143### JavaScript
144 
145- Use sintaxe moderna ES6+  
146- Siga as configurações padrão do ESLint fornecidas nos projetos  
147- Use nomes significativos para variáveis e funções para clareza educacional  
148- Adicione comentários explicando conceitos para os aprendizes  
149- Formate usando Prettier quando configurado  
150 
151### HTML/CSS
152 
153- Elementos semânticos HTML5  
154- Princípios de design responsivo  
155- Convenções claras de nomenclatura de classes  
156- Comentários explicando técnicas CSS para aprendizes  
157 
158### Python
159 
160- Diretrizes de estilo PEP 8  
161- Exemplos de código claros e educacionais  
162- Dicas de tipo onde úteis para aprendizagem  
163 
164### Documentação em Markdown
165 
166- Hierarquia clara de títulos  
167- Blocos de código com especificação de linguagem  
168- Links para recursos adicionais  
169- Capturas de tela e imagens nas pastas `images/`  
170- Texto alternativo para imagens para acessibilidade  
171 
172### Organização de Arquivos
173 
174- Lições numeradas sequencialmente (1-getting-started-lessons, 2-js-basics, etc.)  
175- Cada projeto tem diretórios `solution/` e frequentemente `start/` ou `your-work/`  
176- Imagens armazenadas em pastas `images/` específicas da lição  
177- Traduções na estrutura `translations/{language-code}/`  
178 
179## Build e Deploy
180 
181### Deploy do Quiz App (Azure Static Web Apps)
182 
183O quiz-app está configurado para deploy no Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Cria a pasta dist/
188# Implanta via workflow do GitHub Actions ao enviar para a branch main
189```
190 
191Configuração Azure Static Web Apps:  
192- **Localização da app**: `/quiz-app`  
193- **Localização de saída**: `dist`  
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`  
195 
196### Geração de PDF da Documentação
197 
198```bash
199npm install                    # Instalar docsify-to-pdf
200npm run convert               # Gerar PDF a partir do docs
201```
202 
203### Documentação Docsify
204 
205```bash
206npm install -g docsify-cli    # Instalar Docsify globalmente
207docsify serve                 # Servir em localhost:3000
208```
209 
210### Builds específicos de projetos
211 
212Cada diretório de projeto pode ter seu próprio processo de build:  
213- Projetos Vue: `npm run build` cria bundles para produção  
214- Projetos estáticos: Sem etapa de build, servem arquivos diretamente  
215 
216## Diretrizes para Pull Requests
217 
218### Formato do Título
219 
220Use títulos claros e descritivos indicando a área de mudança:  
221- `[Quiz-app] Add new quiz for lesson X`  
222- `[Lesson-3] Fix typo in terrarium project`  
223- `[Translation] Add Spanish translation for lesson 5`  
224- `[Docs] Update setup instructions`  
225 
226### Checagens Necessárias
227 
228Antes de enviar um PR:
229 
2301. **Qualidade do Código**:  
231   - Rode `npm run lint` nos diretórios afetados  
232   - Corrija todos os erros e avisos de lint  
233 
2342. **Verificação de Build**:  
235   - Rode `npm run build` se aplicável  
236   - Garanta que não ocorram erros no build  
237 
2383. **Validação de Links**:  
239   - Teste todos os links markdown  
240   - Verifique referências a imagens  
241 
2424. **Revisão de Conteúdo**:  
243   - Revise ortografia e gramática  
244   - Assegure que exemplos de código estão corretos e educativos  
245   - Verifique que as traduções mantêm o significado original  
246 
247### Requisitos de Contribuição
248 
249- Aceite o CLA da Microsoft (verificação automática no primeiro PR)  
250- Siga o [Código de Conduta Open Source da Microsoft](https://opensource.microsoft.com/codeofconduct/)  
251- Veja [CONTRIBUTING.md](./CONTRIBUTING.md) para diretrizes detalhadas  
252- Referencie números de issues na descrição do PR, se aplicável  
253 
254### Processo de Revisão
255 
256- PRs são revisados por mantenedores e comunidade  
257- Clareza educacional tem prioridade  
258- Exemplos de código devem seguir melhores práticas atuais  
259- Traduções revisadas quanto à precisão e adequação cultural  
260 
261## Sistema de Tradução
262 
263### Tradução Automatizada
264 
265- Usa GitHub Actions com workflow co-op-translator  
266- Traduz para mais de 50 idiomas automaticamente  
267- Arquivos originais nos diretórios principais  
268- Arquivos traduzidos em `translations/{language-code}/`  
269 
270### Adicionando Melhorias Manuais nas Traduções
271 
2721. Localize o arquivo em `translations/{language-code}/`  
2732. Faça melhorias preservando a estrutura  
2743. Garanta que exemplos de código permanecem funcionais  
2754. Teste qualquer conteúdo de quiz localizado  
276 
277### Metadados de Tradução
278 
279Arquivos traduzidos incluem cabeçalho de metadados:  
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Depuração e Solução de Problemas
293 
294### Problemas Comuns
295 
296**O quiz app não inicia**:  
297- Verifique a versão do Node.js (recomendado v14+)  
298- Apague `node_modules` e `package-lock.json`, rode `npm install` novamente  
299- Verifique conflitos de portas (padrão: Vite usa porta 5173)  
300 
301**Servidor API não inicia**:  
302- Confirme a versão mínima do Node.js (node >=10)  
303- Verifique se a porta não está em uso  
304- Garanta que todas as dependências foram instaladas com `npm install`  
305 
306**Extensão de navegador não carrega**:  
307- Verifique se o manifest.json está formatado corretamente  
308- Verifique erros no console do navegador  
309- Siga as instruções específicas de instalação da extensão para o navegador  
310 
311**Problemas no projeto de chat Python**:  
312- Certifique-se que o pacote OpenAI está instalado: `pip install openai`  
313- Verifique se a variável de ambiente GITHUB_TOKEN está definida  
314- Confirme as permissões de acesso ao GitHub Models  
315 
316**Docsify não serve a documentação**:  
317- Instale docsify-cli globalmente: `npm install -g docsify-cli`  
318- Rode a partir do diretório raiz do repositório  
319- Confira se `docs/_sidebar.md` existe  
320 
321### Dicas para Ambiente de Desenvolvimento
322 
323- Use VS Code com extensão Live Server para projetos HTML  
324- Instale as extensões ESLint e Prettier para formatação consistente  
325- Use DevTools do navegador para depurar JavaScript  
326- Para projetos Vue, instale a extensão Vue DevTools para navegador  
327 
328### Considerações de Performance
329 
330- Grande número de arquivos traduzidos (50+ idiomas) torna clones completos grandes  
331- Use clone raso se estiver trabalhando apenas no conteúdo: `git clone --depth 1`  
332- Exclua traduções das buscas ao trabalhar no conteúdo em inglês  
333- Processos de build podem ser lentos na primeira execução (npm install, build Vite)  
334 
335## Considerações de Segurança
336 
337### Variáveis de Ambiente
338 
339- Chaves de API nunca devem ser commitadas no repositório  
340- Use arquivos `.env` (já listados no `.gitignore`)  
341- Documente variáveis de ambiente necessárias nos READMEs dos projetos  
342 
343### Projetos Python
344 
345- Use ambientes virtuais: `python -m venv venv`  
346- Mantenha as dependências atualizadas  
347- Tokens GitHub devem ter permissões mínimas necessárias  
348 
349### Acesso GitHub Models
350 
351- Tokens de Acesso Pessoal (PAT) são exigidos para GitHub Models  
352- Os tokens devem ser armazenados como variáveis de ambiente  
353- Nunca commit tokens ou credenciais  
354 
355## Notas Adicionais
356 
357### Público-alvo
358 
359- Iniciantes completos em desenvolvimento web  
360- Estudantes e autodidatas  
361- Professores utilizando o currículo em salas de aula  
362- Conteúdo desenhado para acessibilidade e construção gradual de habilidades  
363 
364### Filosofia Educacional
365 
366- Abordagem de aprendizado baseada em projetos  
367- Verificações frequentes de conhecimento (quizzes)  
368- Exercícios práticos de codificação  
369- Exemplos de aplicação no mundo real  
370- Foco em fundamentos antes de frameworks  
371 
372### Manutenção do Repositório
373 
374- Comunidade ativa de aprendizes e contribuintes  
375- Atualizações regulares em dependências e conteúdo  
376- Issues e discussões monitoradas por mantenedores  
377- Atualizações de tradução automatizadas via GitHub Actions  
378 
379### Recursos Relacionados
380 
381- [Módulos Microsoft Learn](https://docs.microsoft.com/learn/)  
382- [Recursos Student Hub](https://docs.microsoft.com/learn/student-hub/)  
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recomendado para aprendizes  
384- Cursos adicionais: AI Generativa, Ciência de Dados, ML, currículos IoT disponíveis  
385 
386### Trabalhando com Projetos Específicos
387 
388Para instruções detalhadas sobre projetos individuais, consulte os arquivos README em:  
389- `quiz-app/README.md` - Aplicação de quiz Vue 3  
390- `7-bank-project/README.md` - Aplicação bancária com autenticação  
391- `5-browser-extension/README.md` - Desenvolvimento de extensão de navegador  
392- `6-space-game/README.md` - Desenvolvimento de jogo baseado em canvas  
393- `9-chat-project/README.md` - Projeto assistente de chat IA  
394 
395### Estrutura Monorepo
396 
397Embora não seja um monorepo tradicional, este repositório contém múltiplos projetos independentes:  
398- Cada lição é autocontida  
399- Projetos não compartilham dependências  
400- Trabalhe em projetos individuais sem afetar outros  
401- Faça clone do repositório completo para experiência total do currículo  
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Aviso Legal**:  
407Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->