🪜 Identify the three phases of AI in code
The use of AI in development has gone through three phases. They don’t replace one another: they coexist in your day-to-day work. What changes in each one is how much of the execution is out of your hands — and, as a result, what kind of control you need to put in place.
🆕 New here?
LLM is the AI model that generates text — the same kind that runs behind ChatGPT or Claude. Tools ("tools") are actions this model can trigger on its own: read a file, run a command in the terminal, search the web. Agent is the model more these tools more a cycle that makes it repeat until it thinks it’s finished. Remember these three: the entire course uses them.
Autocomplete
AI suggests lines, functions, or small snippets as you type.
The human remains responsible for virtually all decisions. The possible error is local: a bad suggestion that you accept without reading. Review costs little because the diff is small.
Assistant
AI answers questions, explains code, creates functions, and generates files.
It already participates in implementation, but still depends on frequent instructions. The first scaling risk appears here: you accept entire blocks you haven’t read line by line because they “seemed right.”
Agent
Receives a task and carries it out: explores the repository, reads documentation, modifies files, runs commands and tests, analyzes errors, and tries to fix their own implementation.
This phase calls for a new kind of engineering. The agent shouldn’t be treated as a clever chatbot, but as a operational component within a controlled system — with permissions, limits, verification, and logging.
Suggestion
Phase 1: local risk
Response
Phase 2: block risk
Execution
Phase 3: systemic risk
Control
Moves from line to system
🧩 List What an Agent Needs to Work
When an agent “doesn’t work,” the cause is almost never the model. It’s a missing item from this list. Use it as a diagnostic: go through all thirteen points and check what’s missing from your current setup.
How to read: the central box is the only thing many teams configure — and it’s the smallest part of the problem. Everything in cyan around it is what you build. If any of these boxes is empty, the agent fails right there: without an “end condition,” it won’t stop; without a “log,” you won’t know what it did.
✓ Setup that works
- ✓Repository access with a declared scope (what it can read, what it can write)
- ✓A test command that runs in seconds and fails loudly
- ✓Explicit, verifiable completion criteria
- ✓Log of all actions performed
✗ Setup that turns into an accident
- ✗Full access to the machine "for convenience"
- ✗No tests—the verification is you looking at the diff
- ✗"Finish when it’s good" as a criterion
- ✗No record: nobody knows which commands ran
Context
What it can see
Permission
What it can do
Verification
How to tell if it worked
Record
What evidence remained
🎛️ Take on the engineer’s new role
The work hasn’t decreased—it’s moved elsewhere. Less time typing the implementation, more time defining what is correct, assembling the context, setting limits, and judging the result. People who do this well multiply the entire team’s output.
🎯 The shift in one sentence
Before, your product was the code. Now, your product is the system that produces reliable code — the spec, the harness, the loop, the gates. The code is the output of this system.
- •You write fewer lines and review more changes.
- •You turn your team’s tacit knowledge into documentation and tests.
- •You decide where autonomy stops and a human signs off.
💡 Practical tip
The next time you delegate a task to AI, spend 10 minutes writing the spec before opening the agent. Measure how many back-and-forths you saved. That number is what will convince your team—not the pitch.
Specify
Define what’s correct
Provide context
Choose what it sees
Limit
Define where to stop
Judge
Accept or reject
🏗️ Understand why fundamentals matter again
AI generates code quickly, but it doesn't replace engineering knowledge. The more code it produces, the more valuable your ability to evaluate the result — and that ability comes from fundamentals, not from knowing the latest tool.
🔍 What goes unnoticed without fundamentals
All these defects pass happy-path tests. That’s exactly why they make it to production.
Durable knowledge
Architecture, testing, operating systems, networks, APIs, security, databases, and infrastructure. None of these age at the pace of tools.
Durable knowledge isn’t about memorizing a tool.
It lies in understanding how systems work.
Quick check (doesn’t block anything): an agent delivered a fix and all tests passed. What’s the correct conclusion?
Evaluate > produce
Judgment has become the bottleneck
Sad path
That’s where the defect lives
Durable
Systems, not products
Scale
More code, more review
🚧 Recognize the Current Limits of Tools
Knowing where the tool fails isn’t pessimism—it’s what determines which tasks you delegate today and which still require human approval. These four limitations explain most poor results.
1. Only the context you provided exists
The agent doesn’t know about the hallway conversation, the rule only Paulo knows, or the neighboring system that consumes its API in an undocumented way. Anything that didn’t make it into the context gets filled in with a plausible assumption.
2. "The test passed" doesn't mean "the intent was fulfilled"
It optimizes for the verifier you provided. If the verifier is weak, the solution will be weak in exactly the way the verifier can’t detect.
3. Constant confidence, variable accuracy
The tone of the response doesn’t vary with its quality. You can’t use “it sounded confident” as a signal.
4. Side effects outside the repository
Databases, infrastructure, permissions, and external integrations don’t come back with a git revert. That is why these actions call for approval, not autonomy.
⚠️ Attention
Changes to production, databases, infrastructure, permissions, and security always need additional controls. No time savings are worth an irreversible migration applied by an automated loop at 3 a.m.
Missing context
Becomes an assumption
Weak verifier
Weak solution
Tone ≠ correctness
Confidence is not a signal
Irreversible
Requires a human
⚠️ Avoid prompt-only development
Prompt-only development is when the only input is the prompt of the moment: no specification, no tests, no limits, no independent review. It seems productive for a week, then you pay the price the following month.
🧪 Copyable exercise — the same request, two levels
Objective: experience firsthand the difference context makes. Run both in your agent (Claude Code, Codex, Cursor—it doesn’t matter) in a test repository.
Prompt A (prompt only):
Adicione cache no endpoint de listagem de produtos.
Prompt B (same task, with engineering around it):
Tarefa: adicionar cache na listagem de produtos em <caminho/do/arquivo>. Fora do escopo: não alterar o contrato da resposta, não tocar em outros endpoints, não adicionar dependências novas sem me perguntar antes. Critérios de aceitação: - resposta idêntica à atual para os mesmos parâmetros (byte a byte); - invalidação do cache quando um produto é criado, alterado ou removido; - TTL configurável por variável de ambiente, com default de 60s; - teste automatizado cobrindo hit, miss e invalidação. Antes de implementar: me mostre o plano em até 10 linhas e espere aprovação. Ao terminar: rode <comando de teste do seu projeto> e cole a saída real.
How to verify: compare the two diffs. Count changed files, added dependencies, and tests created. Prompt A tends to invent a generic cache layer and touch files that weren’t requested; B delivers a reviewable change in minutes. Keep both diffs—they’re your case to the team.
✓ Sign that you’ve moved beyond “just prompting”
- ✓A written artifact exists that defines “correct” before execution
- ✓A command exists that answers “did it work?” without human judgment
- ✓A boundary exists around what must not be touched
- ✓A second set of eyes exists (human or reviewer agent)
✗ Symptoms of prompt debt
- ✗Two solutions to the same problem in different modules
- ✗PRs too large to review properly
- ✗Tests that cover only the happy path
- ✗Dependencies that no one can explain why they were added
Double speed
For delivery and errors
Boundary
Written negative scope
Verifier
Command, not opinion
System
The real differentiator
📌 Module Summary
Next Module:
1.2 - Spec-Driven Development: turning intent into verifiable criteria.