Agentic Engineering

Appearance

Quality Prompts ​

Agents generate quality artifacts — tests, reviews, docs — with the same fluency they generate bugs, and the two cancel out unless you control what the artifact is allowed to assume. A test suite written by the agent that wrote the code inherits the code's blind spots. A review prompt that asks "any issues?" gets a polite shrug. Every pattern here works by breaking symmetry: different assumptions, adversarial stance, or explicit enumeration.

Test-generation prompts ​

Three levers decide whether generated tests are worth anything: behavior focus (test the contract, not the implementation), an explicit mock policy (the single biggest determinant of test value — left unstated, agents mock everything and produce suites that test mocks against mocks), and enumerated edge cases (agents cover the happy path plus whatever edge cases you name; the ones you don't name don't exist).

Weak:

text
Write tests for src/services/proration.ts.

Predictable output: one test per function, mirroring the implementation's structure, mocks for every import, assertions that restate the code ("calls calculateDaily with the right args"). 100% coverage, near-zero bug-detection power — and worse, it cements the current implementation, so every future refactor breaks tests without breaking behavior. See Reviewing AI Tests for how to audit this kind of suite.

Strong:

text
Write behavior tests for src/services/proration.ts.

Test the public contract only: calculateProration(subscription,
changeDate) → ProrationResult. Do not assert on internal calls,
private helpers, or call counts.

Mock policy:
- Do NOT mock anything inside src/services/.
- Use the real date logic — no fake timers except where a test
  needs a fixed "now" (use test/helpers/clock.ts).
- The DB is not touched by this module; if you find yourself
  needing a DB mock, stop and tell me — that's a design smell.

Cover these behaviors (one describe block each):
1. Mid-cycle upgrade: charge is proportional to days remaining.
2. Mid-cycle downgrade: credit, never a negative charge.
3. Change on the billing anniversary itself: zero proration.
4. Annual plans: proration by day over 365/366 — leap year case
   explicitly (Feb 29 subscription, changed March 1).
5. Timezone edge: changeDate 23:30 UTC when the account TZ is
   UTC+10 — which billing day does it land on? Pin whatever the
   current behavior is and flag it in a comment.
6. Currency rounding: 3 line items that each round up — total
   must not drift by a cent (property: sum of parts == charged
   total).

For each behavior, one negative case too. If you discover
behavior that seems wrong while writing these, write the test to
pin CURRENT behavior and list it separately as "questionable".

Case 5's "pin whatever the current behavior is" matters: test generation is not the moment to change behavior, even when the behavior looks wrong. Tests first, judgment call second, fix (if any) third — each its own diff.

Review checklist for generated tests:

  • [ ] Could this suite catch a real bug? Pick one test, mentally break the code, check the test fails
  • [ ] No assertion restates the implementation (expect(mock).toHaveBeenCalledWith(...) as the only assertion is a red flag)
  • [ ] Every enumerated edge case actually appears, not just the easy ones

Review prompts ​

The useful pattern is the adversarial second agent: a fresh session (or subagent) with no memory of writing the code, prompted to find problems rather than to summarize. Review quality tracks the stance you assign — an agent asked to "review" defaults to book-report mode; an agent told its job is to find the three worst problems goes looking.

Weak:

text
Review this PR and let me know if it looks good.

Output: a bulleted summary of what the diff does, two style nits, "overall looks good!" The agent optimized for agreeableness because nothing in the prompt paid for disagreement.

Strong:

text
You are reviewing a PR written by another engineer you don't
trust yet. Diff: git diff main...feature/csv-export.
Context: the task spec is docs/specs/csv-export.md.

Review these dimensions IN ORDER, worst findings first:
1. Spec compliance: list each acceptance criterion in the spec;
   mark met / not met / can't tell from the diff.
2. Scope: every file in the diff the spec didn't require — flag it.
3. Correctness: concurrency, error paths, boundary values. Trace
   the streaming path by hand: what happens when the client
   disconnects mid-export?
4. Blast radius: callers/consumers of anything modified that the
   diff does NOT update.
5. Tests: which acceptance criteria have no test? Which tests
   would still pass if the feature were broken?

Rules: no style commentary, no praise, no summarizing what the
code does. Every finding = severity (blocker/major/minor) +
file:line + one-line why. If you find nothing at severity major
or above, say what you checked and what evidence convinced you —
"looks good" alone is an unacceptable answer.

"You didn't write this" is not decoration — reviews of someone else's code are measurably harsher than an agent reviewing its own output in the same session, where it defends its choices. Always review in a fresh context. Human side of the process: Reviewing AI PRs.

The self-attack pattern ​

Between implementation and review sits a cheap intermediate: make the implementing agent attack its own work before you spend a fresh session on it. It won't find everything (it shares its own blind spots) but it reliably surfaces the edge cases it noticed and silently deprioritized while building.

text
Before I review this: attack your own implementation.

List the 5 most likely ways this code is wrong or will break in
production. For each: the specific input or condition that
triggers it, file:line where it would fail, and severity. Include
at least one concurrency/timing case and one malformed-input case.

Then, for each attack, either (a) show the existing test that
covers it, or (b) admit it's uncovered. Do not fix anything yet.

Banned answers: "edge cases in general", "more testing needed",
anything without a concrete triggering input.

The forced choice in the second paragraph — show the test or admit the gap — is what makes this non-theatrical. Expect (b) answers; those are your review agenda.

Security review prompts ​

Generic "check for security issues" prompts produce generic OWASP recitals. Scope the review to the change surface: what this diff newly exposes, touches, or trusts. Dimensions that matter for agent-written code, in rough order of how often agents get them wrong: authorization (agents copy authn faithfully but forget object-level authz — the exported-other-org's-invoices bug), injection at every new input boundary, secrets in code/logs/error responses, and data exposure (over-broad SELECTs and serializers that leak columns the feature never needed).

text
Security review, scoped to this diff only:
git diff main...feature/csv-export

For each NEW input, endpoint, or query this diff introduces:
1. AuthZ: not just "is a user logged in" — can user A reach
   user B's objects? Trace the org/tenant scoping from route to
   query and quote the WHERE clause that enforces it.
2. Injection: every place external input meets a query, a shell,
   a file path, or CSV output (CSV formula injection: does a
   customer name of "=cmd|..." get escaped?).
3. Secrets & leakage: error responses, logs, and headers added
   by this diff — anything that echoes internals?
4. Data exposure: columns selected vs. columns the feature needs;
   anything serialized that wasn't before?

Findings as: severity + file:line + attack scenario in one
sentence + suggested fix. Explicitly state which of the 4
categories came up clean, so I know they were checked and not
skipped.

The "state which categories came up clean" line converts silence from ambiguous to meaningful. For repo-wide review rather than diff-scoped, use the operations prompts in Prompt Library: Quality.

Documentation prompts ​

Two rules. First, docs are for the next agent as much as the next human — API docs, module READMEs, and ARCHITECTURE.md are retrieval targets in future sessions, so accuracy beats polish (Docs as Memory). Second, forbid aspiration: agents document what the code should do unless told to document what it does.

text
Write a module README for src/services/proration/.

Source of truth is the CODE, not intent: document actual behavior,
including the two quirks flagged in test/services/proration.test.ts
under "questionable". Structure: what it does (3 lines), public
API with types, invariants callers can rely on, known sharp edges.
Max 80 lines. If code and existing comments disagree, trust the
code and flag the disagreement.

Deployment prompts ​

Deployment work (CI configs, Dockerfiles, release scripts) is high-blast-radius and low-feedback — a wrong pipeline change fails at 2am, not in review. Two prompt rules: demand a dry-run or plan output before anything applies (--dry-run, terraform plan, a printed job graph), and require every change to state its rollback. Never let an agent "fix the pipeline" by iterating against CI directly — that's the stuck-loop generator. Copyable versions: Prompt Library: Operations.

A field manual for AI-native software engineering.