What Salesforce technical debt is, and why AI agents make it visible
Last reviewed: October 14, 2026
Salesforce technical debt is configuration, automation and code that makes every further change to an org slower. It was implemented for earlier requirements, under deadline pressure or with the platform features available at the time. Every Salesforce org that has grown over a few years carries some. It says far less about the quality of a team's work than the word suggests.
You notice technical debt when the org needs to change. A new requirement takes longer because someone first has to understand what's already there. AI agents add a second effect, since an agent works with exactly the context the org gives it.
How Salesforce technical debt differs from debt in a codebase
In Salesforce, most technical debt lives in metadata, meaning fields, Flows, permissions, page layouts and reports. Apex code is often only part of it.
Much of that metadata is created with clicks in Setup, often by admins, developers and partners at the same time. Adding a field takes a few minutes. Which Flows, reports and Apex classes use a field can be traced through the metadata. What the metadata doesn't show is whether a change affects any of those dependencies in business terms. Without a field description, the team can misjudge that business context. A change made for sales then alters a process customer service relies on.
| Traditional codebase | Salesforce org | |
|---|---|---|
| Where the debt lives | Source code and its dependencies | Metadata such as fields, Flows, permissions, layouts, reports and code |
| Who creates it | Mostly developers | Admins, developers, partners and installed packages |
| How it becomes visible | Compilers, tests and static analysis | Often only when a follow-up requirement runs into a solution that won't scale |
| What makes removal hard | Missing tests | Missing business context for dependencies between metadata |
The practices software teams use to pay down technical debt still carry over to Salesforce. Whether a team configures or writes code makes little difference to them.
Why Salesforce orgs accumulate technical debt
Salesforce technical debt has three typical causes. The platform moves forward with three releases a year. Over the years, changing teams and partners work on the same org. On top of that, requirements often have to go live faster than a scalable implementation allows.
Automation shows the platform's own movement most clearly. Salesforce stopped letting orgs create new Workflow Rules and new Process Builder processes some time ago, and it ended support for both tools on December 31, 2025. Existing automations keep running, but Salesforce no longer fixes bugs in them. What was the recommended way to automate many years ago counts as legacy now.
A typical example is a central object in an older org. In the early years, a Workflow Rule sets a field on it. A later requirement goes beyond what the Workflow Rule can do, so a Process Builder process is added. Then another team implements a Flow, and an integration project adds an Apex trigger. Every new requirement on that object now starts with understanding how the four automations interact.
Salesforce describes this state without blame. According to the Record-Triggered Automation decision guide, mature orgs commonly run record-triggered flows and Apex triggers on the same object, often as a result of "evolving platform capabilities or legacy technical debt". The guide asks architects to treat that as "a calculated trade-off rather than an end state".
Day-to-day delivery adds time pressure. Typical triggers are fixed go-live dates, change requests shortly before a release and project plans with no time for follow-up work. When a project has to go live by the end of the quarter, someone widens an existing profile instead of creating a matching permission set. A shortcut like that can be a deliberate and reasonable decision. It gets expensive when nobody records it and the next requirement builds on top of it. Installed packages also bring their own fields and automation. If the old package isn't uninstalled after a vendor switch, all of that stays in the org.
How to spot technical debt in your org
Technical debt shows up in an org through recurring signs. None of them is a mistake on its own, but together they show where changes cost more effort than they need to:
- several automation types on the same object, such as Workflow Rules, Flows and Apex triggers side by side
- fields nobody has filled in for years, and fields without a description
- large profiles whose permissions could be split into reusable permission sets
- Apex classes on old API versions
- hard-coded URLs and record IDs in code and formulas
- reports and dashboards nobody opens anymore
The Salesforce Health Check won't flag any of these, because it scores security settings against a baseline. Which questions the Health Check does answer is covered in What a Salesforce Health Check doesn't tell you.
What technical debt costs once AI agents read the org
Once AI agents work with an org, technical debt shapes the quality of what they produce. That's true for customer-facing AI agents and for AI coding agents that write changes back to the org.
An AI agent that answers customer requests or handles tasks for employees reads fields, field descriptions, records and permissions. If three fields hold the same customer status, the agent has to guess which one counts. If a field has no description, the agent only has the field name to infer its meaning from.
AI coding agents read the org differently. An AI coding agent uses existing Flows and Apex code as templates when it writes new automation. If most of what it finds follows older approaches, it carries them into new changes. Our article on AI coding agents and current Flow best practices shows what that looks like for Flows.
Good context also works the other way round. People misread fields too, for example when a field name promises more than the field holds. If that assumption ends up in a requirement, it often surfaces only in testing. An AI coding agent that reads clear field descriptions can notice the mismatch between requirement and metadata before anything is implemented. We have seen exactly that happen several times in our own projects.
Technical debt that used to cost people time now carries into every answer and every generated change. Before any AI initiative, it's worth asking where in the org an AI agent can start safely and where it will struggle. Areas with little technical debt make good first candidates.
How to make technical debt visible and set priorities
Paying down technical debt starts with an inventory of the whole org, because in Salesforce the debt is spread across many areas. Salesforce retired Salesforce Optimizer, which used to give that overview, with the Winter '26 and Summer '26 releases.
Not every piece of legacy has to go. Start where technical debt slows down the next planned change or stands in the way of an AI use case. An unused field on an object that rarely changes and that no AI agent reads can wait. Three fields for the same status on the object an AI agent is supposed to read belong at the top of the list.
The Platform Assessment helps with that order. We sort every finding into one of three groups: quick wins, larger clean-up work and structural topics that only come up with a future initiative. Your team can move the first two groups straight into a refactoring backlog. The structural topics belong in the technical refinement of the initiative they touch.
How to pay down technical debt sprint by sprint
A team pays down technical debt most reliably when the work has a fixed place in every sprint. Software teams have worked this way for a long time, and Salesforce teams can adopt the same building blocks.
A dedicated refactoring backlog
Every piece of legacy the team finds gets an entry in its own refactoring backlog, kept apart from the feature backlog. That way a finding doesn't get lost in notes or chat threads, and the team estimates and plans legacy work like any other task.
Technical refinement for shared standards
In technical refinement, the team agrees on upcoming requirements and also on which technical standards apply from now on. Since Spring '25, approval processes can be implemented in Flow as Flow Approval Processes. A team can decide in refinement that new approvals are implemented in Flow only, even though classic approval processes still work. Existing approval processes then move into the refactoring backlog one at a time.
With Workflow Rules and Process Builder, many teams waited until Salesforce set a deadline and then had to migrate under time pressure. A team that decides earlier can plan the migration into its regular sprints.
A fixed budget in every sprint
Salesforce's Well-Architected Framework recommends deliberately reserving engineering capacity for technical debt reduction. A team that spends all of its capacity on features, Salesforce notes, has no time left for improvement and accumulates technical debt as a result.
What works in practice is a fixed share of every sprint that's reserved for the refactoring backlog alone. In our experience, 15 percent of capacity works well. Because the share is fixed, nobody has to negotiate it again against the next release. Teams that don't work in sprints can apply the same idea to a fixed share per month or per Salesforce release.
Team rules that AI coding agents read too
Whatever the team decides in technical refinement belongs in written team rules, for example in the definition of done or in a document listing the agreed standards. Those rules help new team members get started. They also serve AI coding agents as project instructions, so an agent that knows the rule "new approvals only in Flow" is far less likely to suggest a classic approval process.
How to keep technical debt in view over time
Technical debt keeps building up, even in a team with a fixed budget, because every release, project and AI-generated change alters the org. That's why the Well-Architected Framework recommends detecting and remediating configuration drift every quarter, so configuration debt doesn't accumulate.
Recurring Platform Reviews follow exactly that cadence. Each review compares the org with the last baseline and shows which technical debt is new. Your team can see whether the sprint budget removes more than the org adds in the same period.
The Platform Assessment fills the refactoring backlog and the fixed budget works through it sprint by sprint. The reviews show every quarter whether that pace keeps up with how the org changes.