Engineering

API Review Checklist Prompt

Architecture review for the public surface: abstractions that earn their place, dependency direction, seams, and the patterns the codebase already has.

Overview

An API surface is a promise — every exposed type and method is something callers will depend on and you will maintain. This setup reviews a client SDK's public surface under the architecture focus: layer violations, responsibilities in the right modules, abstractions earned by real variation rather than speculation, dependency direction from volatile toward stable, interface seams for testing, and consistency with the codebase's established patterns — with the TypeScript pack watching for any-leaks and assertion-hidden errors at the boundary.

Workflow

Review the surface, not the internals
Paste the public types and signatures — the architecture focus judges what callers see and depend on.
Challenge every abstraction
"Earned by real variation, or speculative generality?" — the question that shrinks APIs before they ship.
Hold new code to the old patterns
Consistency findings matter most at the surface: callers learn the API's patterns once and expect them everywhere.

Why This Works

Architecture focus reviews position and responsibility, which surface-level style review misses
The earned-abstraction test prevents the speculative generality that bloats public APIs
Pattern-consistency checks protect the API's learnability — its real usability metric

Best for

Client SDKs and shared libraries with real consumers
Public surfaces about to be frozen by semver
Teams whose API grew endpoint by endpoint without a review

Not for

Writing the API documentation — that's the Markdown Output Builder's api-documentation setup
Reviewing endpoint performance — switch focus to Performance

Use cases

Reviewing an SDK's public surface before the first external release
Catching speculative abstractions before they become permanent API
Checking that new endpoints follow the API's established patterns

Customize This Resource

Opens this setup in Code Review Prompt Generator. Generate to get the full review contract — then adjust the focus, scope, language, and style.

Open in Code Review Prompt Generator

Prompt Template

REVIEW OBJECTIVE
Review the public API surface of the client SDK for architectural soundness.
Primary focus: architecture — judge where this code sits in the system, not just what it does.
Review only — report findings; do not rewrite the code.

REVIEW SCOPE
You are reviewing a complete file — judge both the code and the file's structure: imports, ordering, and what this file owns.
Language: TypeScript.

REVIEW CRITERIA
- Layer violations and responsibility placement
- Abstractions: earned by real variation, not speculative
- Dependency direction and interface seams
- Transaction and consistency boundaries
- Consistency with the codebase's established patterns

SEVERITY RULES
- Tag every finding with exactly one severity: [CRITICAL], [MAJOR], [MINOR], or [NIT].
- CRITICAL: must be fixed before merge — bugs, vulnerabilities, data loss.
- MAJOR: should be fixed — real risk or real debt.
- MINOR: worth fixing — small risk or friction.
- NIT: style preference; fixing is optional.
- Severity reflects impact, not effort to fix.

REVIEW CHECKLIST
Work through every item; report only the items that fail:
1. Any layer violations — UI reaching into data access, domain importing infrastructure?
2. Is each responsibility in the right module, or convenient-but-wrong places?
3. Are the abstractions earned by real variation, or speculative generality?
4. Does the dependency direction point from volatile toward stable?
5. Are there interface seams where tests need to substitute behavior?
6. Is wiring/configuration externalized rather than hardcoded?
7. Is the error-handling strategy consistent with the rest of the system?
8. Are transaction boundaries placed where consistency actually requires them?
9. Are cross-cutting concerns (logging, auth, retries) centralized, not re-implemented?
10. Does this change follow or silently break the codebase's established patterns?
TypeScript-specific:
11. Any "any" types leaking through signatures?
12. Are type assertions (as) hiding real type errors?
13. Any non-null assertions (!) where a check belongs?
14. Do narrowed types survive across async boundaries?

REQUIRED OUTPUT FORMAT
- One finding per bullet: [SEVERITY] location — what is wrong and why it matters.
- Group findings by severity, CRITICAL first.
- Cite the exact line, function, or symbol for every finding.
- Do not mention checklist items that pass — findings only.
- Prioritize findings that matter; skip pure style nits unless they hurt readability.
- If something is done notably well, say so once — briefly.

FINAL VERDICT
- End with a verdict: APPROVED, APPROVED WITH COMMENTS, or CHANGES REQUIRED.
- Base the verdict only on the findings listed above.

CODE TO REVIEW
[Paste the file here]

Related Resources

Explore more resources that work well with this one.