The Architecture Quality Checklist for AI-Built Salesforce Orgs

Every prior generation of advice about Salesforce technical debt described the same disease: years of accreted clicks-not-code, orphaned fields, a trigger per object, and a cleanup project nobody funds. That framing is now obsolete. In an org where agents author most of the metadata, debt no longer accumulates slowly over five years of admin drift — it can accumulate in an afternoon, at production quality, with passing tests. The cleanup metaphor breaks because there is no lull in which to clean up.

Here is the reframe this piece is built on, and it inherits the line from our pillar, Agentic Development for Salesforce: capability got cheap; ground truth didn't. Salesforce technical debt in the agentic era is not legacy sludge. It is the compounding gap between how fast agents can ship metadata and how fast humans can verify it. Generation is free now. Review is the constraint. Quality stops being a post-hoc cleanup project and becomes the governance spine that lets you run agents fast without accruing debt faster than you can pay it down.

This is the concrete companion to that series. The pillar makes the economic argument; this post is the what-do-I-actually-check checklist — the review spine you hang on every AI-authored change before it lands in a compliance-sensitive org.

Capability got cheap. Review didn't.

An agent will now write a permission set, refactor an Apex batch class, generate the test coverage, and open a clean merge request in minutes. The craft floor is high. The bottleneck moved: it is no longer can we build it? but can anyone confirm what was built is safe to land?

Salesforce's own engineering org measured this directly. In Scaling Code Reviews: Adapting to a Surge in AI-Generated Code, they report code volume rising roughly 30% as AI tooling landed, with pull requests routinely ballooning past 20 files and 1,000 lines — and, tellingly, review time on the largest PRs plateauing or declining. That last signal is the whole problem in one data point. When review time falls as change size rises, reviewers have stopped meaningfully engaging. The dominant risk of AI-generated code is not that it is uniformly bad. It is diminished scrutiny — competent-looking code merged without anyone actually reading it.

That is the mechanism behind agentic-era debt. Not bad code. Unreviewed code that looked good enough to wave through.

The new tech-debt equation: velocity − review capacity = compounding debt

Say it as a formula. Debt accrues at the rate agent output velocity exceeds human review capacity. When agents authored 20% of changes, informal review kept up and the term stayed near zero. When agents author 80%, the same review capacity is overwhelmed and the gap compounds — each unreviewed change becomes the assumed-correct baseline the next agent builds on, so an unverified decision doesn't just sit there, it reproduces.

You can make this measurable. The Technical Debt Ratio (TDR) — remediation cost over development cost — is the standard gauge, and its bands are well established: SonarQube rates a codebase A below 5%, B at 5–10%, C at 10–20%, D at 20–50%, and E above 50%. Under 5% is healthy; over 20% is severe. In our experience most mature Salesforce orgs live in the manageable-to-concerning band — and an agent pointed at that org without a review gate moves it the wrong way, fast. The point of a quality checklist is to keep the ratio flat while the throughput goes up.

Mapping quality to Salesforce Well-Architected

You do not need to invent quality criteria for agents. Salesforce already published them. The Salesforce Well-Architected framework organizes solution health under three pillars — Trusted, Easy, Adaptable — and at TDX 2026 the architect team refreshed it for exactly this moment. In The Next Chapter of the Well-Architected Framework, the pillars stay the same but the questions under them are rewritten for a world where the dominant unit of architecture is an AI agent (see also Salesforce's real-world Agentforce lens on the pillars). The framework's own device — prescriptive patterns paired with named antipatterns — is exactly the shape a review checklist wants.

Each pillar as a review question for agent output

Turn each pillar into a question you ask of every AI-authored change:

• Trusted — Is this secure, compliant, and reliable against the live org? Trusted solutions protect the business, users, and data by design. For agent output this is the field-level security, sharing, and CRUD question — the layer that is invisible from the metadata the agent reasoned over.
• Easy — Does this conform to how this org already works, or does it invent a parallel pattern? Easy solutions are intentional and consistent. An agent that ignores your existing trigger framework and hand-rolls a new one has produced technically valid, architecturally corrosive code.
• Adaptable — Will this survive the next change, or does it hard-code assumptions that break at real scale? Adaptable solutions evolve. Hard-coded IDs, un-bulkified loops, and record-count assumptions are adaptability debt the moment data volume moves.

Trusted, Easy, Adaptable are the why. The next section is the what to check.

The review spine: quality gates for what agents ship

This is the extractable checklist — the specific things AI-authored Salesforce code reliably gets wrong, and the review that catches each. These are the checks a diligent senior architect runs on autopilot, and precisely the ones that get skipped under AI-amplified volume. Encode them, and diminished scrutiny stops being an option.

1. Pattern conformance

Check: Does the change use the org's existing trigger framework, service layer, and naming conventions — or did the agent invent its own?

Agents optimize for a locally correct diff, not for consistency with a codebase they were only partially shown. The classic tell is a new trigger with business logic inline, sitting next to an org that already routes everything through a handler framework. It compiles, it passes, and it fractures the architecture. Reject net-new patterns where a house pattern exists.

2. Collision checks

Check: Does new SOQL or DML collide with existing automation — recursion, trigger re-entry, or governor-limit stacking?

An agent reasoning from a partial view cannot see the Flow, the other trigger, and the managed-package automation that already fire on the same object. New DML inside a context that is already mid-transaction produces recursion and limit exhaustion that never appears in isolated testing. This is the same ground truth is expensive failure the stale-baseline trap describes — the collision lives in the live org, not in the agent's context window. Verify new queries and DML against what already runs on that object.

3. Edge-case and bulkification review

Check: Is the Apex bulk-safe, and does it handle nulls, empty collections, and mixed-shape data — not just the happy path?

This is what AI Apex misses most reliably. Code generated against a clean mental model assumes one record, well-formed. Production hands it 200 in a trigger and 50,000 in a batch, with nulls and collision shapes the agent never imagined. SOQL-in-a-loop, DML-in-a-loop, and single-record assumptions are the default failure mode. This maps directly to the shapes we catalog in Seven Shapes of Rework: logic validated against volume-without-shape. Review for bulkification explicitly — it is the check most worth its time.

4. Security and sharing

Check: FLS and CRUD enforced? with sharing declared? No hard-coded IDs?

Trusted, from the checklist above, made mechanical: does Apex enforce field-level security and object permissions (Security.stripInaccessible / WITH SECURITY_ENFORCED / explicit CRUD checks), is the sharing keyword present and correct, and are there zero hard-coded record or profile IDs? Agents routinely omit all three because none are required to compile — the class runs fine in the org it was written against and leaks data in the org it lands in. This is the highest-stakes gate in a compliance-sensitive context.

5. Test integrity

Check: Do the tests assert real behavior, or do they manufacture coverage without verifying anything?

The most dangerous artifact an agent produces is a test that hits the coverage number and asserts nothing — System.assert(true), no negative cases, no bulk case, SeeAllData leaning on org state. Coverage theater passes the deployment gate and verifies nothing. Read the assertions, not the coverage percentage. A test with no meaningful assertion is negative-value: it looks like a safety net and is a hole.

The antipattern table: agentic-era Salesforce debt signals

Consolidated, this is the diagnostic. Scan any AI-authored change against it.

This table is a net-new, ownable asset because nobody else is naming these as agentic debt signals. Every competitor's tech-debt content still points at legacy sludge. These are the signals that show up when a high-capability agent meets a low-fidelity picture of the org — and they are the specific things a review gate exists to stop.

From checklist to governance spine

A checklist a human is supposed to remember is a checklist that gets skipped under load — that is the diminished-scrutiny finding restated. So the checklist only pays off when it stops being advice and becomes enforcement: a named owner and a mechanical gate.

Who owns the gate. A governance owner (an architect or a lead, not "whoever opened the PR") owns the spine. Their job is not to review every line by hand — that is the bottleneck we are trying to escape — but to encode the checks above as policy-as-code in CI so they run on every merge request, in parallel, without waiting on human availability. Deploy-validate against the live target org, a security-scan-actually-ran assertion, a bulkification lint, a static check for hard-coded IDs, a baseline-drift diff. Advisory gates are still Level 3; enforced gates are Level 4.

We lay out that full maturity ladder — and why most capable teams sit one rung lower than they think — in High-Capability, Low-Control, the governance-spine companion to this series. The checklist here is the content of the Validate gate that piece describes. Tooling helps carry it — Gearset and AutoRABIT automate code review and static analysis, and Salesforce's native Health Check and Optimizer cover org-level security and configuration hygiene. Use them. But no tool ships your review methodology — the org-specific pattern conformance and collision judgment that turns a generic scanner into a real gate. That layer above the tools is the work.

A repeatable review loop

Facet's point of view: the review gate is not a speed bump on the agent loop — it is a control in the loop. A Builder-loop that generates without a verification step generates debt. The same gate, run on every change, keeps the Technical Debt Ratio flat while throughput climbs. That is the entire promise of going fast with agents without shipping a debt bomb: velocity and verification move together, or the velocity is fake.

The loop is simple and repeatable:

1. Agent generates the change against the live org baseline.
2. The spine runs the checklist as policy-as-code — pattern, collision, bulk, security, tests.
3. Gate fires only where a check fails; the safe majority flow through untouched.
4. The owner adjudicates the fired gates and feeds new gotchas back into the checklist.

The faster the agent authors, the more often the spine checks, and the tighter the loop stays. That is how you run agents fast and keep the org healthy — not by slowing the agents, but by making verification as cheap and automatic as generation already is.

The takeaway

Salesforce technical debt is no longer a cleanup project you schedule for next quarter. It is a rate — the gap between agent velocity and review capacity — and it compounds. The fix is not to slow down and it is not more capability. It is a review spine: a concrete, Well-Architected-aligned checklist of the things AI-authored code reliably gets wrong, enforced mechanically so scrutiny cannot be skipped under load. Capability is table stakes now. A quality gate that keeps ground truth unskippable is the moat.

If you are scaling agentic development into a real Salesforce org and you do not yet have a mechanical answer to "what proves this change is safe before it merges?", that is the conversation worth having. A Salesforce org assessment — a structured architecture and org health check against these exact signals — is where we start. Let's talk about your review spine.