Quality with agents
Coding with agents · topic coding-with-agents/quality
Agents make it cheap to produce code and just as cheap to produce debt. This topic covers keeping tests meaningful, documentation current, dependencies deliberate, and reviewing agent output for the security and supply-chain problems it introduces more readily than a careful human would.
Concepts
- Testing
- Keeping tests that prove behavior rather than mirror implementation. Agents write tests readily, and readily write tests that pass by asserting what the code happens to do. Review agent tests for what they would catch if the code were wrong, keep them fast enough to run in an agent's loop, and never let an agent delete or weaken a test to make a change pass. glossary
- Documentation
- Keeping the written explanation of a system current as agents change it. Agents can draft documentation from code well, and equally well leave it stale. Treat docs as part of the change: the brief names what must be updated, the review checks it, and project instructions tell the agent where documentation lives and what style it follows. glossary
- Dependency hygiene
- Adding libraries deliberately and keeping them pinned, current and few. An agent asked to solve a problem will often add a package where a few lines would do, or pick one it has seen frequently rather than one that is maintained. Review every new dependency for need, license, maintenance and size, and lock versions so builds stay reproducible. glossary
- Security review of agent output
- Checking agent-written code for the classic mistakes it makes easily: unvalidated input, string-built queries and commands, secrets in code, permissive defaults, disabled checks, error handling that hides failures. Agents reproduce common patterns including common vulnerabilities. Static analysis catches some; a reviewer asking "what if the input is hostile" catches more. glossary
- Supply-chain risk
- The risk that something you install is not what it seems: a package name the agent hallucinated that an attacker has registered, an action or plugin pinned to a moving tag, a transitive dependency with a known flaw. Agents increase exposure by suggesting names from memory. Verify that packages exist and are the intended ones, pin to exact versions, and audit regularly. glossary
Links
- Builds on: Verifying agent work, Agent risk
- Leads to: Agents in a team
- Competencies drawing on it: Verifies agent-written code before trusting it
Lessons
- Reviewing what the agent pulled in (explanation)
- Reading agent code as if the input were hostile (tutorial)
- Tests that prove behavior and docs that stay current (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Reviewing what the agent pulled in
Unlocks when you finish Reviewing what the agent pulled in.
Takeaways
- Start from the lockfile diff, and classify each change as a new direct dependency, a new transitive dependency, or a version bump. Each kind gets a different review.
- Spend review effort in proportion to risk, count the future cost, be wary of surprises, and apply the same principles to writing it yourself, because the review has no default outcome.
- The dimensions are architecture (direct dependencies only), quality, governance and support, security, code, and license. A version bump keeps only security, code, and license if it changed.
- Run or look up the OpenSSF Scorecard checks, and treat a low score as a question to answer in writing.
- Read the code on your critical path and the parts that need a specialist. Skip style, unchanged reviewed code, individual tests, foreign platforms and non-API documentation, and say that you skipped them.
- Commit the lockfile, consider a release age floor, write the verdict with reasons, record a rejection in the project instructions, and give real findings back upstream.
Example
Predict the classification · open in the lesson
The root entry of package-lock.after.json lists date-fmt, microroute-js and zero-pad-left-lite. week-of-year-iso appears only as a dependency of date-fmt, and microroute-js moved from 4.19.2 to 4.21.2. What does the script print? Type all four lines in the format name version: kind.
for name, version, kind in classify(before, after): print(f"{name} {version}: {kind}")Prints the lines below (verified in CI from site/examples/coding-with-agents/dependency-review/classify.py)
date-fmt 2.4.0: new direct microroute-js 4.19.2 -> 4.21.2: version bump week-of-year-iso 1.0.3: new transitive zero-pad-left-lite 0.2.1: new direct
Reading agent code as if the input were hostile
Unlocks when you finish Reading agent code as if the input were hostile.
Takeaways
- Agents learn from public code, and they learn the security bugs in it too. Look for unvalidated input, string-built queries and commands, secrets in code, permissive defaults, disabled checks, and error handling that hides failures.
- A static analyzer such as Bandit finds the patterns it has rules for. Read its findings, including the ones with Low confidence, and then read the code for what it can't know.
- At each place where data enters, ask what happens when the input is hostile, and follow every
exceptto what the user sees. - Brief the fix with placeholders and a test that fails on the old code, and run that test on both versions before you accept it.
- The blast radius of an injection is everything the code's connection can reach, and SQL injection is the same mistake as prompt injection: data placed where instructions go.
Example
Predict how many titles come back · open in the lesson
The database holds four notes, two of Alice's and two of Bob's. How many titles does search_notes(conn, "alice", "%' OR owner != '") return?
print(len(search_notes(notes_db(), "alice", "%' OR owner != '")))Prints: 4 (verified in CI from site/examples/coding-with-agents/security-review/hostile_count.py)
Tests that prove behavior and docs that stay current
Unlocks when you finish Tests that prove behavior and docs that stay current.
Takeaways
- Review an agent's test by making the code wrong on purpose and running it. A test that still passes either gives the code an input that never reaches the broken line, or takes its expected value from the code it tests, so it mirrors the implementation. Rewrite it with an input that reaches the line and the value the program must produce, from the spec or worked out by hand.
- Give the agent the fast tests for the part it changes to run in its loop, and run the full suite before the merge. The agent never deletes, skips or loosens a test to make a change pass. When a test looks wrong, it stops and says why.
- A rule in the instructions file is context for the agent, and nothing enforces it. Read the diff of the test files to confirm that no test was deleted, skipped or loosened.
- Documentation is part of the change. The brief names what to update, the instructions say where the docs are, and the review searches those places for what the change made stale.
Example
The agent's tests, before any change · open in the lesson
Run the tests in your copy and compare what you see with the output below.
Prints the lines below (verified in CI from site/examples/coding-with-agents/tests-and-docs-that-hold/run_tests.py)
$ python3 test_pricing.py test_subtotal_adds_the_lines: pass test_small_order_pays_shipping: pass test_large_order_ships_free: pass test_total_adds_shipping: pass test_total_of_a_known_order: pass 5 passed, 0 failed exit status 0
Sources
DLAI-7Team Software Engineering with AI, DeepLearning.AI (course)Brilliant SECSecurity and adversarial thinking, Brilliant, Coding with AI skills map (reference)Fuchsia reviewReview process for external Rust crates, Fuchsia documentation (reference)OpenSSF ScorecardOpenSSF Scorecard checks, Open Source Security Foundation (reference)Academy ai-native-sdlc-playbookThe AI-native SDLC playbook, Claude Academy (course)Academy claude-code-in-actionClaude Code in action, Claude Academy (course)Pearce 2022Asleep at the Keyboard? Assessing the Security of GitHub Copilot's Code Contributions, 2022 IEEE Symposium on Security and Privacy (SP 2022), 754-768 (paper)