Share
Embed
Transcript
64 slides
-
droidcon Lisbon 2026 AI is already on the team. Is
your Android project ready for it? Yes, parts of this deck were drafted by AI. I reviewed them. Mostly. Sim, partes desta apresentação foram rascunhadas por IA. Eu revi-as. Quase todas. 1 / 68 -
Quick Question Uma pergunta rápida When the AI doesn't
do what you expected — what do you do? Quando a IA não faz o que esperavam — o que fazem? Switch the model? Mudar de modelo? Fix the prompt? Corrigir o prompt? Show of hands — who switched models? Who rewrote the prompt? Levantem a mão — quem mudou de modelo? Quem reescreveu o prompt? 2 / 68 -
droidcon Lisbon 2026 A Pause · Uma pausa So, which
one can we realistically change, first thing Monday morning? Então, qual destas podemos mudar de forma realista, logo na segunda de manhã? Model Prompt O modelo O prompt Not yours to change. You wait for the next release. Rewritten every time. Not shared, not reproducible. Não depende de nós. Só resta esperar pela próxima versão. Reescrito sempre. Nem partilhado, nem reproduzível. ? The third option A terceira opção 3 / 68 -
The Answer · A resposta The project. (its requirements
and specs) Então, o que podem mesmo mudar na segunda-feira? O projeto. 4 / 68 -
droidcon Lisbon 2026 Today's Path · O percurso de hoje
Problem → Demo → System → Failures → Takeaways Problema → Demo → Sistema → Falhas → Lições 01 Why AI output isn't stable Porque é que a IA é instável 02 A demo: one fix, from spec to verification Demo: uma correção, da spec à verificação The six pillars behind it Os seis pilares por trás 03 04 05 What went wrong, why, and the fix Three things you can try starting today O que correu mal, porquê, e a correção Três coisas para experimentar já hoje 5 / 68 -
droidcon Lisbon 2026 Background: Why the Project · Contexto: porquê
o projeto AI Is on the Team — but Our Docs Are Written for Humans A IA já faz parte da equipa — mas a documentação e o código foram escritos para humanos AI is one of the team But the reader is assumed human The result A IA é um membro da equipa It designs, codes, and reviews with us every day. Desenha, programa e revê connosco todos os dias. Mas pressupõe-se um leitor humano Docs and code assume a human reader. Unwritten context never reaches the AI. Docs e código pressupõem um leitor humano. O contexto não escrito nunca chega à IA. O resultado Inconsistent code Código inconsistente The wrong architecture Arquitetura errada Rule-breaking commits Commits que violam as regras The root cause isn't the AI's ability — it's a project built for human readers only. A causa não é a capacidade da IA — é um projeto feito só para leitores humanos. 7 / 68 -
droidcon Lisbon 2026 The Fix · A solução Don't Chase
the Wrong Fix — Face the Root Cause Não persigam a solução errada — enfrentem a causa The usual fix · A solução habitual Tweak the prompt. Switch the model. Ajustar o prompt. Mudar de modelo. → Time and money drain away → Tempo e dinheiro desperdiçados The right fix · A solução certa Revisit the docs and code written for humans, and make them readable by the AI too. Rever a documentação e o código feitos para humanos, para que a IA também os entenda. = designing the project = desenhar o projeto What matters most: a project workflow both AI and humans can understand. That's what "the project" meant. O mais importante: um fluxo de trabalho que a IA e as pessoas entendem. Era isso o "projeto". 8 / 68 -
droidcon Lisbon 2026 Where the AI Reads · Onde a
IA lê The Project Map: Humans and AI Read the Same Places O mapa do projeto: pessoas e IA leem os mesmos sítios CLAUDE.md docs/ specs/<n>-<feature>/ app/…/ data, di, ui The rulebook. Read first. O livro de regras. Lido primeiro. The basis for decisions. Details in the Context section. A base das decisões. Detalhes na secção Context. Spec and history, per feature. Spec e histórico, por funcionalidade. Where each layer's code lives. Onde vive o código de cada camada. 01 Rules 02 Context 03 Specs Code Fixed places and roles mean the AI never has to guess where things go. Com lugares e papéis fixos, a IA nunca tem de adivinhar onde pôr as coisas. 9 / 68 -
droidcon Lisbon 2026 Roadmap · Roteiro What's ahead: demo →
six pillars → failures → wrap-up O que vem aí: demo → seis pilares → falhas → conclusão DEMO 01–06 FAIL END Live demo Six pillars Failures Wrap-up One fix, a fixed prompt, verified live How the project behind the demo is built What went wrong, why, and the fix When it works, when it doesn't, three things to try Uma correção, um prompt fixo, verificada ao vivo Como é feito o projeto por trás da demo O que correu mal, porquê, e a correção Quando funciona, quando não, e três coisas a experimentar Rules Context Specs Tasks Examples Validation This bar appears on every section divider: you-are-here / Esta barra aparece em cada divisória de secção: estão aqui 10 / 68 -
droidcon Lisbon 2026 LIVE DEMO · START Live Demo
Wiring up the empty-collection icon, with a fixed prompt Ligar o ícone da coleção vazia, com um prompt fixo Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 11 / 68 -
droidcon Lisbon 2026 Live Demo (1): Scope and Result ·
Demo ao vivo (1): âmbito e resultado Design Is Already Done. Live, We Just Wire It Up O design já está feito. Ao vivo, só fazemos a ligação What We'll Do · O que vamos fazer Approved beforehand · Aprovado antes requirements design The Result · O resultado Before / Antes After / Depois tasks ic_book_2 exists but is unused, so behavior is unchanged. Wired live · Ligado ao vivo Wire up CollectionThumbnails Column Box Icon only when empty, plus a golden update. Ícone só quando vazio, mais uma atualização da golden. Success = the book_2 icon on the empty tile Sucesso = o ícone book_2 na tile vazia 13 / 68 -
droidcon Lisbon 2026 Live Demo (2): the Fix · Demo
ao vivo (2): a correção A Fixed Prompt. No Improvising on Stage Um prompt fixo. Sem improvisos em palco For `CollectionThumbnails` in `CollectionTile.kt`, add `Icon(painterResource(R.drawable.ic_book_2))`, tinted `onSurfaceVariant`, 24dp, centered, shown only when `landmarks.isEmpty()`. Change nothing else. 14 / 68 -
droidcon Lisbon 2026 Overview · Visão geral Six Pillars of
an AI-Ready Project — What's Driving the Demo Right Now Seis pilares de um projeto preparado para IA — o que move a demo agora mesmo AI-Ready Project · Projeto preparado para IA 01 02 03 04 05 06 Rules Context Specs Tasks Examples Validation CLAUDE.md docs/ specs/ Small steps, TDD Reusable models Machine-checked Passos pequenos, TDD Modelos reutilizáveis Verificado por máquina 15 / 68 -
droidcon Lisbon 2026 SECTION 01 / 06 · SIX PILLARS
Rules One rulebook: CLAUDE.md — reason, constraint, promise Um só livro de regras: CLAUDE.md — razão, restrição, compromisso Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 16 / 68 -
droidcon Lisbon 2026 1. Rules · Pilar 1 One Rulebook:
CLAUDE.md Um só livro de regras: CLAUDE.md This Repo's CLAUDE.md, Section by Section · O que lá vai Project overview Kotlin, Compose, Hilt, Room… Visão geral do projeto Stack tecnológica Every task starts as an issue Issue First: tudo começa num issue Directory layout Estrutura de diretórios Spec-driven, no code before design ktlint and detekt must pass Abordagem: orientada a specs Qualidade: lint e análise estática How work is handed to the AI Why · Porquê Re-explain every time and decisions drift. One standard, for people and AI. Como o trabalho é entregue à IA Reexplicar sempre faz as decisões derivarem. Um só padrão para todos. Branches and commit format Details live in docs/; CLAUDE.md is only the index. Regras de git 17 / 68 -
droidcon Lisbon 2026 Inside Rules: Harness Engineering for the AI
· Por dentro das Rules: harness engineering para a IA Three Layers: Reason → Constraint → Promise Três camadas: razão → restrição → compromisso 1. Reason "Why it matters," first · e.g. unverified changes cause rework Razão Primeiro, "porque importa" · ex.: alterações não verificadas geram retrabalho 2. Constraint "So, never do X" · e.g. never commit directly to main or develop Restrição "Por isso, nunca fazer X" · ex.: nunca fazer commit direto em main ou develop 3. Promise "Then, always do X" · e.g. never start coding before the spec is approved Compromisso "Depois, fazer sempre X" · ex.: não programar antes de a spec ser aprovada Don't hand down bare rules — give the reason first. That's harness engineering for the AI: with the why, its judgment holds even in edge cases. Não passem só regras — deem primeiro a razão. Isso é harness engineering para a IA: com o porquê, o critério aguenta até nos casos-limite. 18 / 68 -
droidcon Lisbon 2026 Rules Deep Dive (1/2): Design & Naming
Rules a fundo (1/2): design e nomes Architecture · Arquitetura Naming · Nomes Reason So state survives rotation. Follows Android's official architecture guide. Razão: o estado sobrevive à rotação. Segue o guia oficial de arquitetura Android. Constraint ViewModel calls only the Repository. Never touches Room directly. Restrição: o ViewModel só chama o Repository. Nunca toca no Room diretamente. Promise Screens only render state. Logic lives in the ViewModel. Compromisso: os ecrãs só desenham o estado. A lógica vive no ViewModel. Reason A clear role name helps both people and AI. Based on the Android Kotlin style guide. Razão: um nome que mostra o papel ajuda pessoas e IA. Segue o guia de estilo Kotlin do Android. Constraint Function names checked by detekt. Suffixes (Screen, etc.) checked in review. Restrição: nomes de funções verificados pelo detekt. Sufixos (Screen, etc.) na revisão. Promise One suffix per role: LandmarkListScreen / ViewModel / UiState. Compromisso: um sufixo por papel: LandmarkListScreen / ViewModel / UiState. AI does the work. A human must keep the judgment axis — skip that, and within about a year packages drift and naming splits (search vs. find). A IA faz o trabalho; o critério fica com uma pessoa — senão, num ano, os pacotes derivam e os nomes dividem-se (search vs. find). Sources: Android architecture guide developer.android.com/courses/pathways/android-architecture / Kotlin style guide developer.android.com/kotlin/style-guide 19 / 68 -
droidcon Lisbon 2026 Rules Deep Dive (2/2): Android Specifics &
Testing Rules a fundo (2/2): especificidades Android e testes Android-Specific · Específico do Android Testing · Testes Reason Wallpaper-based dynamic color once made a status unreadable by color alone. Razão: a cor dinâmica do papel de parede já tornou ilegível um estado indicado só por cor. Constraint No heavy work on the main thread. Ask permissions only when needed. Restrição: nada pesado na main thread. Pedir permissões só quando necessário. Promise Survives rotation and back. Touch targets ≥48dp. Compromisso: sobrevive à rotação e ao back. Alvos de toque ≥48dp. Reason Device tests are slow and flaky. Fast Small (unit) tests carry most of the weight. Razão: testes em dispositivo são lentos e instáveis. Os Small (unitários), rápidos, levam o peso. Constraint 3 layers: unit, screenshot, device. Below 95% coverage fails the build. Restrição: 3 camadas: unitário, screenshot, dispositivo. Abaixo de 95% de cobertura, o build falha. Promise Decide which layer tests each feature. Compromisso: decidir que camada testa cada funcionalidade. Every rule here came from a real bug or an official doc — nothing is decoration. Cada regra aqui nasceu de um bug real ou de documentação oficial — nada é decoração. Sources: Issue #29, #32 (dynamic color) / Android testing fundamentals developer.android.com/training/testing/fundamentals 20 / 68 -
droidcon Lisbon 2026 SECTION 02 / 06 · SIX PILLARS
Context The basis for decisions lives in docs/ — naming and history as a shared language A base das decisões vive em docs/ — nomes e histórico como linguagem comum Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 21 / 68 -
droidcon Lisbon 2026 2. Context · Pilar 2 Decisions Live
in docs/: a Single Source of Truth A base das decisões fica em docs/ — a única fonte de verdade docs/architecture.md docs/design/*.md docs/design/golden-images/ Layers and dependency direction Camadas e direção das dependências Spacing, color, type values Valores de espaçamento, cor e tipografia Reference images, auto-compared to the build (DesignGoldenComparisonTest) Imagens de referência do design, comparadas automaticamente com o build docs/naming_conventions.md docs/testing/ How things get named Como se dão nomes às coisas Test policy and scope Política e âmbito dos testes Words as numbers and rules, looks as reference images → the AI has nothing left to guess. Texto em números e regras, aspeto em imagens de referência → a IA não tem nada a adivinhar. 22 / 68 -
droidcon Lisbon 2026 TIPS How the Docs Get Made ·
Como se faz a documentação Turn Doubt Into Words, Check It, Keep It Pôr a dúvida em palavras, verificar, guardar 1. Doubt 2. Write It Down 3. Check the Source Which layer owns what? Hands pause. Turn the reasoning into text. Match it to official docs/standards. Que camada tem o quê? Paramos. Pôr o raciocínio em texto. Comparar com docs oficiais e normas. 4. Document It 5. Verify in Code 6. Audit & Fix Put it in docs/, one source of truth. Let the AI follow it, find the gaps. Log the gaps, fix them. Em docs/, uma só fonte de verdade. A IA segue-o; achamos as falhas. Registar as falhas e corrigi-las. Tip: decide in one place, decide with numbers, keep the source. Dica: decidir num só lugar, decidir com números, guardar a fonte. 23 / 68 -
droidcon Lisbon 2026 Naming: Follow the Industry Standard · Nomes:
seguir o padrão da indústria Only Write Down the Exceptions Só se escrevem as exceções Class / type PascalCase LandmarkRepository Function / property camelCase toggleFavorite() Package all lowercase landmarks.data Constant SCREAMING_SNAKE_CASE MAX_ITEMS Based on the Android Kotlin style guide. Custom rules live in docs/naming_conventions.md. Baseado no guia de estilo Kotlin do Android. Regras próprias em docs/naming_conventions.md. 24 / 68 -
droidcon Lisbon 2026 Shared Vocabulary: Commits, Branches · Vocabulário comum:
commits, branches Make the History a Common Language Too Fazer do histórico também uma linguagem comum Commits: Gitmoji + Conventional Commits Format: emoji type(scope): description / Formato: emoji tipo(âmbito): descrição 🐛 fix(detail): handle crash when unfavoriting ✨ feat New feature / Nova funcionalidade 🐛 fix Bug fix / Correção de bug ♻️ refactor No behavior change / Sem mudar comportamento 📝 docs Docs only / Só documentação ✅ test Add or fix tests / Adicionar ou corrigir testes 🔖 release Cut a release / Fechar uma release Branches: git-flow Roles main / develop Always builds. No direct commits feature/001-landmark-list One per spec. Branches off develop release/0.2.1 Release prep. Merges to main and develop hotfix/1.0.1 Urgent production fix. Off main A history the machine can read means the AI and the human share the same context. Um histórico legível por máquina deixa a IA e as pessoas partilhar o mesmo contexto. 25 / 68 -
droidcon Lisbon 2026 SECTION 03 / 06 · SIX PILLARS
Specs requirements → design → tasks, EARS notation and approval gates requirements → design → tasks, notação EARS e gates de aprovação Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 26 / 68 -
droidcon Lisbon 2026 3. Specs · Pilar 3 Built in
Stages, Each With an Approval Gate Construído por etapas, cada uma com um gate de aprovação requirements.md Acceptance criteria, written in EARS Critérios de aceitação, escritos em EARS design.md The technical design No início, uma pessoa aprova cada etapa antes da seguinte. tasks.md Broken into implementation tasks Dividido em tarefas de implementação O design técnico At first, a human approves each stage before the next. As trust builds, repeated stages move to AI auto-approval. Com confiança, as etapas repetidas passam a aprovação automática pela IA. Human review of everything, forever, kills productivity. Start strict, loosen gates as confidence grows — a maturity curve, not a permanent rule. Rever tudo à mão, para sempre, mata a produtividade. Comecem rigorosos e aliviem os gates com a confiança — uma curva de maturidade, não uma regra fixa. 27 / 68 -
droidcon Lisbon 2026 Aside: EARS Notation · Nota: notação EARS
Requirements in a Fixed Shape, No Ambiguity Requisitos num formato fixo, sem ambiguidade Easy Approach to Requirements Syntax (Mavin et al., 2009) Ubiquitous Event THE system SHALL response WHEN trigger, THE system SHALL response The app SHALL show the list. WHEN the user taps the star, THE app SHALL toggle the favorite. Ex.: a app mostra a lista. Ex.: quando o utilizador toca na estrela, a app alterna o favorito. State Unwanted WHILE state, THE system SHALL response IF condition, THEN THE system SHALL response WHILE offline, THE app SHALL show cached data. IF the read fails, THEN THE app SHALL show an error. Ex.: enquanto está offline, a app mostra os dados em cache. Ex.: se a leitura falhar, a app mostra um erro. One acceptance criterion maps to one test. Um critério de aceitação corresponde a um teste. 28 / 68 -
droidcon Lisbon 2026 Approval Gates: Stages of Involvement · Gates
de aprovação: níveis de envolvimento Start With Humans Reviewing Everything Comecem com pessoas a rever tudo 1. Start-Up · Arranque A human approves every gate. AI output is treated as a draft. Uma pessoa aprova cada gate. O output da IA é um rascunho. 2. Stabilizing · Estabilização AI judges machine checks. Humans review only design and spec changes. A IA julga as verificações mecânicas. As pessoas só revêem design e specs. 3. Settled · Consolidação Items with few rejections autoapprove. Only exceptions get a human. Itens com poucas rejeições aprovamse sozinhos. Só as exceções vão a uma pessoa. When to move on: count recent rejections. No threshold set yet, so every gate stays human for now. Quando avançar: contar as rejeições recentes. Ainda sem limiar, por isso todos os gates continuam humanos. 29 / 68 -
droidcon Lisbon 2026 SECTION 04 / 06 · SIX PILLARS
Tasks 1 task = 1 criterion = 1 cycle, run as TDD 1 tarefa = 1 critério = 1 ciclo, em TDD Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 30 / 68 -
droidcon Lisbon 2026 4. Tasks · Pilar 4 Small Tasks,
the TDD Cycle Tarefas pequenas, o ciclo TDD 1. RED Write a failing test Teste a falhar primeiro Give the AI exactly one task at a time. Uma tarefa de cada vez para a IA. 3. REFACTOR 2. GREEN Clean up, stay green Least code to pass Limpar, sempre verde Código mínimo que passa 31 / 68 -
droidcon Lisbon 2026 The Size of One Task · O
tamanho de uma tarefa 1 Task = 1 Criterion = 1 Cycle 1 tarefa = 1 critério = 1 ciclo NG NG A whole feature as one task Code alone as one task 1 criterion = 1 cycle Uma funcionalidade inteira numa tarefa Só o código numa tarefa 1 critério = 1 ciclo Leaves untested code behind. Test → code → refactor → retest. Too big to pause partway through. Fica código sem testes. Teste → código → refatorar → testar de novo. OK Grande demais para parar a meio. Managed as one cycle. Only the commits split test from code. Gerido como um ciclo. Só os commits separam teste e código. 32 / 68 -
droidcon Lisbon 2026 The Cycle, Step by Step · O
ciclo, passo a passo AI Runs It, a Human Stops It at Key Points A IA conduz, uma pessoa trava nos pontos-chave AI 1 2 3 Write test Criar teste Implement Implementar Run (auto) Executar 4 Refactor Refatorar 5 Retest (auto) Re-testar Next task Seguinte Human G1 Review tests Rever testes G2 Final review Revisão final A human stops it in just two places: G1 (the tests) and G2 (final review). The AI runs the other five. The spec approval gate is separate. Uma pessoa só trava em dois pontos: G1 (os testes) e G2 (revisão final). A IA faz os outros cinco. O gate de aprovação da spec é à parte. As results stay stable and a metrics-based check matures, G1/G2 can gradually move to the AI too — weighed against the risk and the harness that backs it. Com resultados estáveis e uma avaliação por métricas madura, G1/G2 podem passar aos poucos para a IA — pesando o risco e o harness que os sustenta. 33 / 68 -
droidcon Lisbon 2026 SECTION 05 / 06 · SIX PILLARS
Examples Models to copy: templates and finished examples Modelos para copiar: templates e exemplos acabados Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 34 / 68 -
droidcon Lisbon 2026 5. Examples · Pilar 5 A Model
to Follow Makes It Reproducible Um modelo a seguir torna tudo reproduzível A new team can copy the model for their first feature. Uma equipa nova pode copiar o modelo na primeira funcionalidade. specs/_template/ Templates for specs and the review log Templates para specs e registo de revisão specs/001–999-*/ Real examples (design, tasks, reviews), a growing 3-digit series docs/design/components.md Example values for components · valoresmodelo dos componentes Exemplos reais (design, tarefas, revisões), numa série de 3 dígitos que cresce 35 / 68 -
droidcon Lisbon 2026 SECTION 06 / 06 · SIX PILLARS
Validation A human sets the goal, machines fail fast, a human makes the final call — 10 checks and the test strategy Uma pessoa define o objetivo, as máquinas falham cedo, uma pessoa decide no fim — 10 verificações e a estratégia de testes Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 36 / 68 -
droidcon Lisbon 2026 6. Validation (Automated) · Pilar 6: validação
automática Machines Watch Tests and Releases As máquinas vigiam testes e releases Tests · Testes testDebugUnitTest Unit tests, every run. JaCoCo fails below 95% coverage. · testes unitários sempre. O JaCoCo falha abaixo de 95%. Screenshot tests Compares against a golden image. · compara com uma imagem golden. connectedAndroidTest UI tests on a device (run less often). · testes de UI em dispositivo (menos frequentes). ktlintCheck / detekt Format and static analysis. · formatação e análise estática. Release Management · Gestão de releases git-flow Prepared on a release/* branch. · preparada num branch release/*. main / develop Always buildable, always passing. · sempre compila, testes sempre a passar. Before a PR · Antes de um PR /ponytail-review checks the diff for waste. · o /ponytail-review procura desperdício no diff. At release time · Na release /ponytail-audit checks the whole codebase. · o /ponytail-audit verifica todo o código. 37 / 68 -
droidcon Lisbon 2026 10 Checks, One Flow: Human Decides →
AI Processes → Human Makes the Final Call (example) 10 verificações, um fluxo: a pessoa decide → a IA processa → a pessoa decide no fim (exemplo) ① Human decides · #1 # Who / Quem Check Verificação 1 Human Set the goal. Humans give input; AI never invents it Definir o objetivo — a IA não o inventa 2 AI Criteria follow the EARS patterns Critérios no formato EARS 3 AI Design matches docs/ conventions (match only) Design conforme docs/ (só comparação) 4 AI Every criterion maps to a task Cada critério tem uma tarefa 5 AI Tests are written first and fail first Teste primeiro, falha primeiro 6 AI ktlintCheck and detekt pass ktlintCheck e detekt passam 7 AI testDebugUnitTest is all green testDebugUnitTest todo verde 8 AI Screenshot diff is as expected Diff de screenshot é o esperado 9 AI review.md logs findings and responses review.md regista problemas e correções 10 Human Final gate: approve design, UX, and intent Gate final: design, UX, intenção ② AI processes — 8 machine-checkable items · #2–9 ③ Human final call · #10 38 / 68 -
droidcon Lisbon 2026 CAN SKIP from here ▸ Test Strategy
(1): Small / Medium / Large · Estratégia de testes (1): três tamanhos Build most of the defense in Small tests; Large covers only the key flow A maior parte da defesa nos Small; os Large só cobrem o fluxo principal Large: on device List → Detail → Favorite Medium: screens and DB Screenshot tests, Room DAO (in-memory) Small: unit (JVM) ViewModel, Repository, logic — most tests live here Takeaway: defend with Small Conclusão: defender com os Small Fast Runs on the JVM, no device or emulator Rápido: corre na JVM, sem dispositivo Broad Easy to cover every branch (95% coverage) Amplo: cobre os ramos (95%) Every time Runs on every change Sempre: corre em cada alteração 39 / 68 -
droidcon Lisbon 2026 Test Strategy (2): From Criteria to Tests
· Estratégia de testes (2): dos critérios aos testes One EARS criterion, mechanically, becomes a test Um critério EARS torna-se, mecanicamente, um teste 1. Acceptance criterion (EARS) R10: if data is empty, show the empty state 2. Happy-path test With data, show the list Real Test Names · Nomes reais de testes (R9, R10 = acceptance criterion numbers in requirements.md) shows empty state when data is empty (R10) 3. Error and boundary tests 0 items (boundary), read failure (error) sets errorMessage when seedIfEmpty throws (R9) 4. Branch coverage (JaCoCo) ≥ 95% Find unvisited branches in the report White = criteria a human writes e.g. a human writes R10 in requirements.md Blue = automated tests (AI-written, run every time) e.g. the 0-item and read-failure tests Yellow = a machine gate (not a human) e.g. at 94%, the build fails 40 / 68 -
droidcon Lisbon 2026 Test Strategy (3): Flow · Estratégia de
testes (3): Flow A Flow emits again and again — so test for re-emission Um Flow emite vezes sem conta — por isso testem a reemissão 1 On every Room update · A cada atualização Arrives at launch Chega no arranque Regression test (Turbine, simplified) · Teste de regressão featured = A viewModel.uiState.test { 2 Toggle a favorite — it arrives again Alternar um favorito — chega outra vez val first = awaitItem().featured featured = A repository.toggleFavorite(id) assertEquals(first, 3 Any other update — again Outra atualização — outra vez awaitItem().featured) featured = A } However often it arrives, the result must not change (spec R7). Chegue quantas vezes chegar, o resultado não pode mudar (spec R7). Trigger the re-emission inside the test, and assert nothing changed. Provoquem a reemissão dentro do teste e confirmem que nada mudou. 41 / 68 -
droidcon Lisbon 2026 CAN SKIP Test Strategy (4): Tools &
Pass/Fail · Estratégia de testes (4): ferramentas e critérios Test policy and measurement are different — decide each by problem, tool, pass/fail A. Test policy: which layer guards what, with what · Política de testes Layer / Camada Problem / Problema Tool / Ferramenta Pass when / Passa se Small (unit) Wrong logic branches JUnit4 · MockK · Turbine testDebugUnitTest all green Medium Broken visuals, DAO bugs Preview Screenshot Testing · Room inmemory No diff vs. the golden Large (device) Key flow breaks Compose UI Test (androidTest) List → Detail → Favorite passes B. Measurement: pass/fail by the numbers · Medição Metric / Métrica Problem / Problema Tool / Ferramenta Pass when / Passa se Coverage Untested branches remain JaCoCo (jacocoTestCoverageVerification) Build fails below 95% Design match Build drifts from the design DesignGoldenComparisonTest Fails on drift from the reference Performance Slow startup or scrolling Macrobenchmark (not adopted yet) TBD — not measured today 42 / 68 -
droidcon Lisbon 2026 LIVE DEMO · RESULTS Let's check
in on the demo Vamos ver como está a demo Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 43 / 68 -
droidcon Lisbon 2026 CAN SKIP Live Demo (3): Verification ·
Demo ao vivo (3): verificação Lint, Static Analysis, Tests — One Command Before the Commit Lint, análise estática, testes — um só comando antes do commit ./gradlew :app:ktlintCheck :app:detekt :app:testDebugUnitTest --no-daemon -q Heads-up Right after a clean checkout, one unrelated test can false-fail (nothing to do with this fix). Rerunning after the screenshot task clears it — don't panic on stage. Logo após um checkout limpo, um teste não relacionado pode falhar por engano (nada a ver com esta correção). Voltar a correr após a tarefa de screenshots resolve — sem pânico em palco. 44 / 68 -
droidcon Lisbon 2026 Live Demo (4): the Golden Diff ·
Demo ao vivo (4): o diff da golden Before and After, Checked on a Real-Device Screenshot Antes e depois, verificados numa screenshot real Left: before (nothing shows) / Right: after (book_2 icon) — shot on an emulator Esquerda: antes (nada aparece) / Direita: depois (ícone book_2) — capturado num emulador 45 / 68 -
droidcon Lisbon 2026 LIVE DEMO · DONE Demo Recap
Fixed prompt → one-command check → a human reviews the golden diff Prompt fixo → verificação com um comando → uma pessoa revê o diff da golden Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 48 / 68 -
droidcon Lisbon 2026 CAN SKIP from here ▸ FAILURE STORIES
· TIME PERMITTING Failure Stories Time permitting: what went wrong, why, and the fix O que correu mal, porquê, e a correção Time permitting — skip straight to the wrap-up if we're running long / Se houver tempo — senão, saltamos para a conclusão Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 49 / 68 -
droidcon Lisbon 2026 CAN SKIP A Failure Story (Time Permitting)
· Uma história de falha (se houver tempo) Skip a Gate, and the Drift Shows Up Later Saltem um gate, e o desvio aparece mais tarde All-at-once implementation before approval: spec 003 skipped the gate, saved as a WIP commit Implementação de uma vez antes da aprovação: a spec 003 saltou o gate, guardada como commit WIP A broken reference never fixed: 003's requirements.md points to a file that doesn't exist (#45 open) Uma referência partida por corrigir: o requirements.md da 003 aponta para um ficheiro inexistente (#45 aberto) A spec numbering mistake: 004 wasn't a new screen, it was a fix to 001 — merged back into 001 Um erro de numeração: a 004 não era um ecrã novo, era uma correção à 001 — integrada na 001 The audit's SSOT count went stale; today 5 specs actually have images A contagem SSOT da auditoria ficou desatualizada; hoje, 5 specs têm imagens Without context and a record (review.md), drift goes unnoticed as work continues. Sem contexto e registo (review.md), o desvio passa despercebido à medida que o trabalho avança. 50 / 68 -
droidcon Lisbon 2026 CAN SKIP Plot Twist · Reviravolta
The AI did exactly what was written. A IA fez exatamente o que estava escrito. The problem was what we'd written. O problema era o que nós tínhamos escrito. Our most obedient teammate — faithful even to our contradictions. O colega mais obediente — fiel até às nossas contradições. 51 / 68 -
droidcon Lisbon 2026 CAN SKIP Deep Dive: How It Got
In · A fundo: como entrou The Docs and the Spec Both Said "Build an Interface" A documentação e a spec diziam ambas "criem uma interface" Premise architecture.md "only the interface needs to be known" "basta conhecer a interface" Premise design_guidelines.md "bind interface + impl with @Binds" "ligar interface + impl com @Binds" Spec The design doc defines LandmarkRepository as an interface O documento de design define LandmarkRepository como interface Code Built exactly as designed: interface, impl, and DI Feito tal como desenhado: interface, impl e DI Caught A release audit found "one impl, one interface" Uma auditoria de release encontrou "uma impl, uma interface" The same doc also said "don't over-abstract" — with no concrete bar for it. O mesmo documento dizia "não abstrair demais" — sem um critério concreto. 52 / 68 -
droidcon Lisbon 2026 CAN SKIP Deep Dive: How the AI
Likely Read It · A fundo: como a IA provavelmente o leu It Took the Docs Literally (this is inference) Levou a documentação à letra (é uma inferência) "only the interface needs to be known" "so the data source can be swapped" "don't over-abstract" "make it easy to test" Reading (inferred): a Repository must always be an interface There's still only one impl Reading (inferred): build the swap point now for a future API That future API never came Reading (inferred): no concrete bar, so nothing to act on Skimmed as a platitude Reading (inferred): swapping needs an interface MockK + a concrete class was enough A concrete "build X" beat a vague "don't over-build" (my read, not a log). Um "criem X" concreto venceu um vago "não exagerem" (a minha leitura, não um log). 53 / 68 -
droidcon Lisbon 2026 CAN SKIP Deep Dive: the Fix (Constraints)
· A fundo: a correção (restrições) Put Constraints in Three Places: Docs, Approval, Automation Restrições em três sítios: documentação, aprovação, automação Docs Documentação State the "don't build" case too / Escrever também o caso "não criar" Proposed Convention Convenção No single-impl interfaces (PR#97 removed one; Collections gained a 2nd impl) Not started Spec Especificação Every new abstraction states why concrete wasn't enough / Cada nova abstração explica porque o concreto não bastava Not started Approval Aprovação Log pushback on a new abstraction / Registar objeções a uma nova abstração In use Automation Automação /ponytail-review required before every PR Adopted Audit Auditoria /ponytail-audit during release prep Adopted Leave the convention unwritten, and the same pattern grows back after the fix. Sem a convenção escrita, o mesmo padrão volta a crescer depois da correção. 54 / 68 -
droidcon Lisbon 2026 CAN SKIP A Failure Story (Implementation Bugs)
· Uma história de falha (bugs de implementação) Bugs Found in Review: the Spec Wasn't Met Bugs encontrados na revisão: a spec não foi cumprida 4 real review-caught bugs: unstable featured pick · unreadable text on photo · stale selected tab · lost scroll state 4 bugs reais apanhados na revisão: destaque instável · texto ilegível na foto · separador desatualizado · scroll perdido Before After Real device screenshots, spec 003-featured-list (R7) — featured item stays the same across a Room re-emit Screenshots reais, spec 003-featured-list (R7) — o destaque mantém-se quando o Room reemite 55 / 68 -
droidcon Lisbon 2026 CAN SKIP Deep Dive: Root Cause (the
Shuffling Featured Item) · A fundo: causa raiz (o destaque que muda) The Assumption: "a Flow Only Delivers a Value Once" O pressuposto: "um Flow só entrega um valor uma vez" 1. Code · Código randomOrNull() Picks randomOrNull() on every emission. Assumed it fires once, at launch. Escolhe randomOrNull() a cada emissão. Assumiu-se que corria uma vez, no arranque. 2. On Device · No dispositivo Toggling a favorite updates the same table; Room re-emits the Flow. Alternar um favorito atualiza a mesma tabela; o Room reemite o Flow. 3. Result · Resultado The featured item jumps to another one — violates spec R7 (stability). O destaque salta para outro — viola a spec R7 (estabilidade). Inference: the AI treated the Flow as a "value delivered once" and never checked how often it re-emits. Inferência: a IA tratou o Flow como um "valor entregue uma vez" e nunca verificou quantas vezes reemite. Fix: add a regression test that assumes re-emission. Proposed: document "Flows re-emit" in the design guide. Correção: um teste de regressão que assume reemissão. Proposta: escrever "os Flows reemitem" no guia de design. 56 / 68 -
droidcon Lisbon 2026 CAN SKIP A Failure Story (Visual Bug)
· Uma história de falha (bug visual) Goldens Catch Changes — Not a Baseline That Was Wrong From the Start As goldens apanham mudanças — não uma base errada desde o início #285 WHY PR #286 1. What happened 2. Why it passed 3. How we fixed it On the Featured hero, the "Learn More" button overlapped the landmark title. A human spotted it on screen. Title and button were each pinned to the bottom edge on their own. The overlap was baked into the golden, so the test stayed green. Stacked in one Column (title, then button). Goldens regenerated and eyeballed by a human. No hero Featured, o botão "Learn More" sobrepunha-se ao título. Uma pessoa reparou no ecrã. Título e botão fixados cada um à margem inferior. A sobreposição ficou gravada na golden, e o teste continuou verde. Empilhados num só Column (título, depois botão). Goldens regeneradas e vistas por uma pessoa. Validation lesson: when a golden is created or updated, a human looks at the image itself, not just the diff. Lição de Validation: ao criar ou atualizar uma golden, uma pessoa olha para a imagem, não só para o diff. 57 / 68 -
droidcon Lisbon 2026 CAN SKIP A Failure Story (Process) ·
Uma história de falha (processo) Spec to Code, Generated in One Shot, Before Approval Da spec ao código, gerado de uma vez, antes da aprovação Before · Antes Work paused, then resumed by generating spec, design, and code all at once. After · Depois Marked unverified, saved as WIP. O trabalho parou e retomou gerando spec, design e código de uma só vez. Marcado como não verificado, guardado como WIP. No approval, no tests. Da próxima vez, recomeçar na aprovação da spec. Next time, restart at spec approval. Sem aprovação, sem testes. Lesson: resuming after a pause also starts back at the first gate. Lição: retomar após uma pausa também recomeça no primeiro gate. 58 / 68 -
droidcon Lisbon 2026 CAN SKIP A Picture of the Failure
· Um retrato da falha One Image, a Text-Only Spec, a Broken Link Uma imagem, uma spec só de texto, um link partido Left: the mock image (one file, could be a source of truth) Esquerda: a imagem mock (um ficheiro, podia ser a fonte de verdade) Middle: the spec points to the wrong filename — still broken Centro: a spec aponta para o nome de ficheiro errado — ainda partido Right: numbers only. No image, so the AI guesses at the look Direita: só números. Sem imagem, a IA adivinha o aspeto 59 / 68 -
droidcon Lisbon 2026 CAN SKIP What Didn't Work · O
que não funcionou The System Still Has Real Limits O sistema ainda tem limites reais Agent Teams: can't enforce role boundaries. A human checks the diff in practice. Agent Teams: não impõe fronteiras entre papéis. Na prática, uma pessoa verifica o diff. Custom subagents don't work in the Desktop environment (a CLAUDE.md constraint). Subagentes personalizados não funcionam no ambiente Desktop (restrição no CLAUDE.md). Agent Teams burns more tokens. Agent Teams gasta mais tokens. Today the only human reviewer is me. More human eyes is next. Hoje o único revisor humano sou eu. Mais olhos humanos é o próximo passo. Scaling to an 8-person team, per-feature cost, and handoff when someone changes — all untested. Escalar para uma equipa de 8, custo por funcionalidade e passagem de testemunho — tudo por testar. Naming the limits up front lets the whole team reason from the same baseline. Dizer os limites à partida deixa toda a equipa raciocinar da mesma base. 60 / 68 -
droidcon Lisbon 2026 A Common Question · Uma pergunta frequente
Do Small Changes Need a Spec Too? Mudanças pequenas também precisam de spec? No. If behavior, UI, or data don't change, skip the spec process. Skip it for: build config, dependency bumps, docs, .claude changes Não. Se o comportamento, a UI ou os dados não mudam, saltem o processo de spec. Dispensável: configuração de build, dependências, docs, alterações em .claude Spec needed for: any change in behavior Spec necessária: qualquer mudança de comportamento Still unsettled: test-only changes (under discussion, Issue #151) Ainda por decidir: mudanças só de testes (em discussão, Issue #151) 61 / 68 -
droidcon Lisbon 2026 What Stays Under Human Control · O
que fica nas mãos humanas What We Hand to AI, and What We Don't O que entregamos à IA, e o que não To the AI · Para a IA Drafts Rascunhos Test scaffolding Esqueletos de testes Repetitive work Trabalho repetitivo Machine checks Verificações mecânicas A Human Decides · Uma pessoa decide Framing the request Formular o pedido Architecture Arquitetura Spec approval Aprovação da spec Final quality call Decisão final de qualidade 62 / 68 -
droidcon Lisbon 2026 CAN SKIP Evidence: the Class Dependency Graph
· Evidência: o grafo de dependências de classes Scale Tripled. The Layers Never Broke. A escala triplicou. As camadas nunca se partiram. Zero Violations · Zero violações Classes grew 19→53 (2.8x) across 34 snapshots; data/di never depended on ui — not once. The Audit Actually Shrank It · A auditoria encolheu-o mesmo PR#97 (ponytail-audit): classes 30→29, deps 25→24. Removed a single-impl interface and a dead Type.kt. As classes passaram de 19→53 (2,8x) em 34 snapshots; data/di nunca dependeu de ui. PR#97 (ponytail-audit): classes 30→29, dependências 25→24. Removida uma interface de impl única e um Type.kt morto. Dependencies pulled mechanically from imports, checked across every snapshot. Dependências extraídas mecanicamente dos imports, verificadas em todos os snapshots. 53 "Shrink it" became a number you can see in the graph. "Encolher" tornou-se um número visível no grafo. 30→29 25→24 19 Classes Deps Evidence that it didn't break and that it got smaller — not evidence the AI improved it on its own (a human ran the audit). Prova de que não se partiu e de que encolheu — não de que a IA o melhorou sozinha (foi uma pessoa que correu a auditoria). Scope: app/src/main/java, 34 merges that changed .kt files between spec001 and spec020 (estimated from imports) 63 / 68 -
droidcon Lisbon 2026 WRAP-UP · SUMMARY Wrap-Up When the
pillars work, when they don't — and three things to try today Quando os pilares funcionam, quando não — e três coisas a experimentar hoje Demo 01 Rules 02 Context 03 Specs 04 Tasks 05 Examples 06 Validation Failures Wrap-up 64 / 68 -
droidcon Lisbon 2026 Summary: When the Six Pillars Work, and
When They Don't Resumo: quando os seis pilares funcionam, e quando não When it works / Quando funciona When it doesn't / Quando não funciona Rules Shared standard, less re-explaining Padrão partilhado, menos reexplicações Every AI decides differently; humans re-explain too Cada IA decide à sua maneira; as pessoas reexplicam Context Numbers and rules decide, less guessing Números e regras decidem, menos adivinhação A wrong premise in the docs gets followed too Um pressuposto errado na documentação também é seguido Specs Clear criteria, mapped to tests Critérios claros, ligados a testes No spec, code runs ahead, rework follows Sem spec, o código adianta-se e vem retrabalho Tasks Small, stoppable, reviewable diffs Diffs pequenos, interrompíveis, fáceis de rever A big task hides a mid-way failure Uma tarefa grande esconde uma falha a meio Examples A model to copy for new features Um modelo a copiar nas novas funcionalidades A stale model makes style drift Um modelo desatualizado faz o estilo derivar Validation Machines fail fast, humans focus on design As máquinas falham cedo; as pessoas focam-se no design A rubber-stamp check lets bugs reach the device Uma verificação de fachada deixa os bugs chegar ao dispositivo 65 / 68 -
droidcon Lisbon 2026 The Whole Loop on One Slide ·
O ciclo inteiro num só diapositivo One spec-driven loop, run by a human and the AI Um ciclo orientado a specs, feito por uma pessoa e pela IA Human · Humano Framing the request, approval, final call AI · Agente Drafts, implementation, machine checks requirements design tasks TDD checks Write criteria in EARS Tech design + approval gate 1 task = 1 criterion Red → Green → Refactor Human → AI ×8 → Human Android app 03 Specs 03 Specs 04 Tasks 04 Tasks 06 Validation Write lessons from failures back into Rules and Context — the next loop is steadier / As lições voltam para Rules e Context; a próxima volta fica mais estável Foundation · Base: 01 Rules (CLAUDE.md) 02 Context (docs/) 05 Examples (models) 66 / 68 -
droidcon Lisbon 2026 Summary · Resumo Three Things You Can
Try Starting Today Três coisas para experimentar já hoje 1 Write one page of CLAUDE.md (reason, constraint, promise) Escrevam uma página de CLAUDE.md (razão, restrição, compromisso) 2 Try it on one small feature (write the spec in EARS) Experimentem numa funcionalidade pequena (spec em EARS) 3 Pick one approval gate Escolham um gate de aprovação 67 / 68 -
droidcon Lisbon 2026 Thank You Obrigado Example topics: cost, team
adoption, the failures Por exemplo: custos, adoção em equipa, as falhas X: @Takahiro_1984 x.com/Takahiro_1984 Scan for my profile / Leiam o QR para o meu perfil 68 / 68