Every platform we've ever worked on has a security trade-off it made on a Tuesday, for a reason that made total sense at the time, that now lives exclusively in the memory of whoever was in the room. This post is a mild plea to write those down somewhere more durable than a person's memory, ideally before that person changes teams.
Nobody Ships With Zero Accepted Risk
We used to think "secure platform" meant a platform where every risk had been eliminated. We don't believe that anymore, and we suspect nobody who's actually shipped one does either. Real platforms accumulate a small, honest queue of accepted trade-offs: a managed database that, in some environment, can't do full certificate-chain verification because of how the managed service is configured; a short-lived credential that's technically visible in a workflow engine's execution history for the duration of a run; a development environment that trusts a weaker identity check than production does, because the alternative would slow every engineer down for a threat model that doesn't really apply pre-production.
None of these are secrets, exactly. They're decisions. Reasonable ones, usually, made by someone who weighed a real cost against a real risk and landed somewhere defensible. The problem isn't that these trade-offs exist. The problem is what happens to them by default, which is: nothing. They live in a Slack thread, a PR description nobody will search for again, or the recollection of the one engineer who made the call - and when that engineer leaves, or when an auditor asks "why is this acceptable," the honest answer becomes "we're not entirely sure anymore, but it's been fine so far." That answer does not go well in an audit, and it doesn't sit especially well with us either, if we're honest.
What a Ledger Actually Looks Like
We don't think this needs to be fancy. A living, reviewed table - checked into the same repo as the system it describes, so it moves and gets reviewed alongside the code - does the job. The columns that have worked for us:
| Trade-off | Why Accepted | Mitigation | Revisit Trigger |
|---|---|---|---|
| Managed database can't do full cert-chain verification in the shared non-prod tier | Managed service doesn't expose the CA bundle needed for full verification there; prod tier does support it and uses it | Traffic stays inside a private network boundary; connection still uses TLS, just without full chain validation | Revisit if the provider ships CA bundle support for this tier, or if this environment ever handles regulated data |
| Short-lived credential appears in workflow execution history for the duration of a run | Workflow engine's execution history is itself access-controlled and encrypted at rest; credential expires in minutes | History access is scoped to the same operators who could already reach the underlying secret; expiry window kept short on purpose | Revisit if the workflow engine adds field-level redaction for sensitive activity inputs |
| Dev environment accepts a weaker identity assertion than prod | Full identity federation setup adds real onboarding friction for a tier explicitly excluded from handling real data | Dev environment is network-isolated and never holds production data or credentials | Revisit if dev environment scope ever expands to touch anything customer-facing |
The specific columns matter less than the discipline of forcing four honest answers for every entry: what did we give up, why did that feel acceptable at the time, what's actually limiting the damage if we're wrong, and - this is the column we think gets skipped most often - under what future condition does this stop being acceptable. That last column is the difference between a ledger and a list of excuses. Without a revisit trigger, "temporarily acceptable" quietly becomes "permanently acceptable," because nothing ever prompts anyone to look again.
A ledger like this is genuinely more useful as a plain table than any diagram we could draw for it - which is itself a small point in favor of keeping this whole practice low-tech and reviewable, rather than building tooling around it.
Why We Think This Beats a Comment in Code
The instinct to just leave a // this is intentionally weak because X comment near the code in question is understandable, and we've done it plenty. It's better than nothing. But a comment lives exactly where the code that made the trade-off lives, and nowhere else - so nobody doing a security review of the system will find it unless they already happen to be reading that specific file. A ledger is the opposite: it's the thing you hand a new security reviewer, an auditor, or a new hire on the platform team as a starting point, precisely because it's searchable and centralized rather than scattered across a codebase.
We'll admit a limitation we haven't fully solved: keeping the ledger current requires someone to actually remember to add an entry when a new trade-off gets made, and we don't have great tooling forcing that yet beyond "please add a ledger entry" showing up in our PR template. It helps, but it's not enforcement, and we know it.
A Small Worked Example
A scaling logistics company's security team, doing a routine review, found a Vault-adjacent integration where JWT-based authentication had never actually been exercised outside of production, because the local development setup for Vault didn't support the auth method being used in prod. Nobody had lied about this - it just wasn't written down anywhere a reviewer would naturally look. Once it went into the ledger, with a note that the JWT auth path needed a dedicated integration test against a real instance rather than local dev, the gap stopped being an invisible assumption and became a tracked, owned item with a plan attached. That's really the whole value proposition: not eliminating the risk, just making sure it can't quietly disappear from view.
Pitfalls
The most common way we've seen this practice die is scope creep in the other direction: teams start logging every minor design decision as a "trade-off," and the ledger balloons into a general decision log that nobody reads because it's mostly noise. We'd keep the bar high - this is for things a reasonable security reviewer would flag if they found it undocumented, not for ordinary engineering judgment calls. If you've found a cleaner line to draw there, we'd like to steal it.
That closes out our governance arc. Next, we move into agent runtime architecture itself, starting with a modeling question that trips up almost every team building agent platforms: Identity vs. Instance: Why Your Agent's Config Shouldn't Live Inside Its Deployment.
Suggested hashtags: #EnterpriseAI #AIInfrastructure #AIPlatform #AIGovernance #PlatformEngineering #SecurityEngineering #RiskManagement #Compliance