When AI writes code faster than humans can explain it, decision logs become core engineering infrastructure.
01 THE PROBLEM
Cognitive debt is the failure mode where a team can still change the code, but can no longer explain why the code is the way it is.
Agentic coding accelerates that failure mode.
The immediate win is obvious: an agent opens files, traces dependencies, writes tests, patches code, updates Terraform, and drafts the pull request in minutes. The hidden cost arrives 30 to 90 days later, when a Staff engineer, new hire, incident commander, or auditor has to answer a simple question: why did we choose this approach instead of the obvious alternative?
If the answer lives only in model prompts, ephemeral chat history, half-reviewed pull requests, or one engineer’s short-term memory, the organization has taken on cognitive debt.
Technical debt is visible in the system: flaky tests, brittle interfaces, duplicated code, operational toil. Cognitive debt is different. The code may look clean. The deploy may succeed. Benchmarks may even improve. But the team has lost the chain of reasoning behind important implementation and architectural choices.
That loss compounds faster with agents than with human-only development for one reason: agents increase decision throughput without increasing organizational memory.
A senior engineer writing a complex change manually leaves traces by default. They think aloud in code review. They leave deliberate commit messages. They ask for input in Slack. They usually take longer, which sounds inefficient until you realize the elapsed time is often when alignment gets built.
An agent compresses all of that. It can evaluate multiple options, generate a plausible implementation, and discard rejected paths without leaving durable evidence of the tradeoffs. The team sees the final diff, not the decision process.
That is manageable for low-consequence work: internal tooling, one-off scripts, trivial CRUD endpoints. It becomes dangerous in areas where intent matters more than syntax:
- authentication and authorization
- billing logic
- data retention and deletion
- rate limiting
- migration sequencing
- failure recovery paths
- API compatibility
- compliance controls
- performance-sensitive infrastructure
In these domains, the decision is often more important than the code.
A rollback does not solve this problem. If an agent-generated migration causes production instability, reverting the change might restore service. It does not restore shared understanding. The next person still does not know why the migration was structured in that order, what assumptions were made about read/write traffic, or which edge cases were consciously deferred.
This is why decision logs are no longer documentation hygiene. They are operational controls for teams using agentic coding at scale.
The real-world consequence is straightforward. Within one or two quarters, teams that rely heavily on agents without durable decision capture start seeing three symptoms:
- Review quality drops. Reviewers can judge style and local correctness, but not intent.
- Incidents take longer to untangle. The code exists, but the rationale is missing.
- Roadmap speed becomes deceptive. Teams ship more changes, yet revisit the same architectural questions repeatedly.
Nicole Forsgren, Jez Humble, and Gene Kim’s work in Accelerate made a useful distinction years ago: high performance in software delivery depends on fast flow and fast feedback, not just raw output. Agentic coding improves output and often improves local feedback. Without decision logs, it degrades a third variable that matters just as much in practice: retained organizational understanding.
That missing understanding shows up exactly where CTOs feel it most: handoffs, incidents, audits, and strategic replatforming.
This quarter, the decision is not whether your engineers will use agentic coding. They already are. The decision is whether your engineering system will preserve reasoning at the same rate your agents produce code.
02 WHY IT HAPPENS
This happens because the bottleneck in software development has shifted.
For years, most teams were constrained by code production. Writing, wiring, and debugging changes took the bulk of effort. Documentation quality mattered, but the pace of code creation naturally limited how much undocumented decision-making accumulated.
Agentic coding changes the ratio.
The scarce resource is no longer keystrokes. It is decision supervision.
An agent can propose five valid implementations before a human has fully articulated which one aligns with the product constraint, the security boundary, the future migration plan, or the on-call reality. That is not a tooling issue. It is a systems issue.
The incentive misalignment is brutal and predictable.
The engineer is rewarded for merged output, reduced cycle time, and visible momentum. The organization bears the future cost when the rationale disappears. In accounting terms, the engineer captures the short-term benefit while the team inherits the long-term liability.
Fred Brooks’ coordination warning from The Mythical Man-Month applies here in a new form. More “workers” do not just create more output; they create more coordination overhead. In agentic coding, the coordination burden is not only among people. It is between generated artifacts and human intent.
This gets worse because agents are good at producing locally coherent code from globally incomplete context.
A human senior engineer often notices missing context as friction. They stop and ask: “What is the migration plan?” “Are we preserving backwards compatibility?” “Does support rely on this field?” The agent often proceeds unless explicitly constrained. It fills in gaps with plausible choices.
Plausible is not aligned.
The pattern is familiar to anyone who has run a platform team or managed architecture through a growth stage. The system starts to drift, not because individual decisions are irrational, but because they are unrecorded and therefore unreconcilable.
The arXiv paper From Technical Debt to Cognitive and Intent Debt gets at the core issue: requirements documents, ADRs, implementation plans, specs, and tests are externalized memory. Without them, a system gradually drifts from intended purpose. That observation matters more in agentic environments because AI systems consume those artifacts too. If your documentation is weak, both your humans and your agents operate from partial memory.
This creates a nasty feedback loop:
- Teams use agents to move faster.
- Faster output creates more decisions.
- The decisions are weakly recorded or not recorded at all.
- Future agents receive poorer context.
- They generate code against a fuzzier model of system intent.
- Humans spend more time validating outcomes manually.
- The team becomes simultaneously faster at producing changes and slower at trusting them.
That is cognitive debt in operational form.
There is also a structural reason this hits growth-stage companies particularly hard.
A 20-person startup can often get away with tacit knowledge. Founders sit close to the code. The engineer who made the call is still around. Product context is mostly live in people’s heads.
At 80 people, that breaks.
Now there are multiple teams, parallel roadmaps, a rotating incident commander pool, a security review process, customer-specific edge cases, and engineers joining every month who were not present when the core abstractions were chosen.
This is where companies either institutionalize decision memory or start paying compounding tax.
Stripe’s engineering culture is relevant here. Across public engineering writing and developer-facing docs, Stripe has been unusually disciplined about making implicit infrastructure choices explicit: API versioning behavior, idempotency semantics, backwards compatibility, and operational guarantees are documented as first-class product and engineering decisions. That discipline is not accidental polish. It is what allows complex systems to evolve without every engineer rediscovering old intent.
Cloudflare has shown a similar pattern in post-incident and architecture writing. Their public explanations of reliability incidents and systems design choices tend to surface the constraint, the chosen tradeoff, and the operational implication. The value is not the blog post itself. The value is the organizational muscle that such explanations imply.
Most startups do not need Stripe-level rigor everywhere.
They do need to recognize that agentic coding has changed the economics of omitted reasoning. What used to be a minor documentation lapse is now a scaling hazard because agents can create more undocumented consequential decisions per week than a human-only team could produce in a month.
The root cause is not laziness. It is that most engineering systems were designed for a world where humans were the limiting reagent. They are not anymore.
03 WHAT MOST GET WRONG
The most common misdiagnosis is to treat this as a code quality problem.
It is not.
Teams see questionable agent output and respond with stronger linting, stricter CI, more tests, mandatory human review, or tighter model permissions. Those controls matter. None of them solve the core issue: the missing rationale behind non-obvious choices.
A passing test suite cannot tell you why the agent duplicated logic instead of centralizing it.
A successful deploy cannot tell you why the retry policy was increased from three attempts to seven.
A clean pull request cannot tell you why the migration runs in-app on startup rather than via a separate job with throttling.
These are decision-quality questions, not syntax-quality questions.
The second mistake is assuming pull requests are sufficient as decision records.
They are not.
Pull requests are optimized for change review, not durable memory. Discussion gets fragmented across inline comments, Slack threads, CI reruns, and verbal conversation. Rejected alternatives often disappear. The PR title changes. The context is obvious this week and gone six weeks later.
GitHub itself has invested heavily in preserving development context through issues, discussions, code review, and Copilot integrations, but any engineering leader who has tried to reconstruct a six-month-old architectural decision from a merged PR knows the limit of the medium. The artifact contains the what. It only inconsistently preserves the why.
The third mistake is overcorrecting into heavyweight ADR bureaucracy.
This usually fails within two sprints.
The team declares that every meaningful change needs an ADR. Engineers comply for large projects and ignore it for the dozens of medium-impact decisions that actually shape the architecture over time. The template is too long, the review path is unclear, and nobody knows which decisions truly merit a record.
The result is the worst of both worlds: ceremonial documentation plus continued reasoning loss.
A useful precedent comes from software incident management, not AI.
Google’s SRE practices did not improve reliability by demanding infinite process. They improved reliability by standardizing what must be captured after impactful failures: trigger, impact, contributing factors, remediation, and prevention. Good postmortems are structured memory.
Decision logs should work the same way.
Another common failure mode is believing that more autonomy for agents should be matched by more human spot checks.
That does not scale.
Charity Majors has been consistent on a related point in observability: systems become brittle when humans are expected to manually infer too much from insufficient telemetry. The same is true here. If your safety model assumes senior engineers can repeatedly reverse-engineer the intent behind agent-made changes from diffs alone, you are building a review system on unpaid cognition.
That review burden shows up as fatigue, not just delay.
Leif’s point that “agentic coding compresses cognitive effort” is exactly right. The danger is not only that engineers think less. The danger is that they think in bursts at the wrong moment: late in review, during incident response, or after a customer escalation. Cognitive work deferred is not cognitive work saved.
There are real company examples of what happens when rationale is weak, even outside agentic coding.
Knight Capital’s 2012 deployment failure is still one of the clearest reminders that software incidents are often rooted not in a single buggy line of code but in undocumented operational assumptions and inconsistent rollout logic. Their systems activated legacy functionality in unintended ways, leading to a loss of over $440 million in 45 minutes, according to the U.S. SEC’s order. That incident predates modern coding agents, but the lesson is current: if teams cannot clearly track decision intent across deployments and execution paths, local correctness is meaningless.
A less catastrophic but more common startup version looks like this: an agent refactors billing service retries to “improve resiliency.” Tests pass. Reviewers skim because the diff is large but polished. Two weeks later, duplicate charges appear under an edge-case webhook replay condition. The code is easy to inspect. The reason the retry boundary moved is not.
At that point, the team does not have a bug-fixing problem. It has an archaeology problem.
That is what most teams get wrong. They add controls around generated code while leaving generated decisions weakly captured.
04 THE FRAMEWORK
The approach that works is simple to state and harder to operationalize:
Treat important engineering decisions as first-class artifacts, and require agents to produce them as part of the work. Not every change deserves a formal record. Every consequential change does.The right model is not “document everything.” The right model is “log decisions where future readers will otherwise have to reconstruct intent under time pressure.”
Here is the framework.
1. Define what counts as a log-worthy decision
If you do not define this, engineers will either log nothing or log everything. Both fail.
A decision should require a record if it changes one of these:
- System behavior visible to users or customers
- Operational risk
- Architectural direction
- Compliance or security posture
A practical threshold for growth-stage teams:
- Anything expected to take more than 2 engineer-days and modify production behavior across service boundaries gets a decision log.
- Anything touching auth, billing, data deletion, migrations, or customer-visible reliability gets a decision log regardless of size.
That threshold is intentionally blunt. Precision sounds good but kills adoption.
2. Use a short template built for engineering speed
The template should fit on one screen.
If it takes 30 minutes to fill out, usage collapses. Aim for 5 to 10 minutes for a normal decision, 20 minutes for a major one.
Use this structure:
- Context
- Decision
- Alternatives considered
- Tradeoffs
- Operational implications
- Expiry or revisit trigger
- Links
This is lighter than a classic ADR and more durable than a pull request.
The critical field is not the decision itself. It is the alternatives and tradeoffs. That is the part agents tend not to preserve unless explicitly required.
3. Make the decision log an output of the agent workflow
Do not ask humans to retroactively document what the agent already decided.
Instead, change the workflow so the agent drafts the decision log before or alongside the code.
For example:
- The issue template includes a “decision impact” section.
- The coding agent must populate a log if the change hits certain paths or labels.
- The PR cannot move to final review unless the linked decision log exists for matching categories.
This is where most teams leave value on the table. They use AI to generate implementation, but not to externalize rationale.
A strong prompt pattern is:
Before coding, summarize the decision being made, two alternatives rejected, the key tradeoff, operational risk, and a revisit trigger. Save this as a decision log linked to the task.
That is not compliance theater. It improves agent behavior because the model has to articulate constraints before it commits to a path.
Kaaveh Mohamedi’s point about giving agents the ability to test hypotheses is relevant here. An agent that can verify against tests, logs, or a real database is doing engineering. Extend that logic: an agent that can state and verify its assumptions is doing safer engineering.
4. Store logs where engineers already work
If the log lives in a separate knowledge base no one opens, it is dead on arrival.
The lowest-friction setups usually look like one of these:
- markdown in the repo under `/docs/decisions/`
- GitHub Discussions linked to issues and PRs
- Notion or Linear docs auto-linked to engineering tasks
- an internal developer portal page tied to service ownership
The winning criterion is retrieval speed during review and incidents.
If an incident commander cannot find the relevant decision in under 2 minutes, your storage model is wrong.
Linear offers a useful product lesson here. Linear’s public changelog and product writing consistently show an obsession with reduced workflow friction. Engineering systems survive when they fit the main path, not when they require moral virtue. Apply the same principle to decision logs: the system has to meet engineers where the work already happens.
5. Add review rules based on risk, not on code volume
A 1,500-line generated diff may be low risk. A 12-line change to authorization middleware may be high risk.
So review policy should key off decision class, not just diff size.
A practical model:
- Class A: auth, billing, deletion, migrations, public API changes
- Class B: internal service behavior, performance path, infra config
- Class C: local refactors, test improvements, docs, internal tooling
This mirrors what high-functioning teams already do informally. The difference is making it explicit enough that agents and humans can follow it.
6. Track a small set of metrics
If you cannot measure whether this is helping, the process will either calcify or get cut.
Do not overdo metrics. Use four.
- Decision log coverage
- Incident rationale retrieval
- Reopened architectural debates
- Review cycle time by decision class
The benchmark matters here. DORA has repeatedly shown that elite software delivery performance is not just speed; it is speed with stability. Decision logs should improve change failure rate and mean time to restore, especially in agent-heavy workflows.
7. Tie logs to service ownership
A decision without an owner is trivia.
Each log should name:
- the service or domain owner
- who approved the tradeoff
- the revisit trigger owner
This matters when the original engineer leaves.
Will Larson has written extensively about scaling engineering organizations through clear ownership and decision structures. Decision logs work because they reinforce ownership boundaries. They fail when they become anonymous prose detached from accountable teams.
8. Use them in onboarding and incident review
This is where the ROI becomes obvious.
A good decision log reduces onboarding time because it gives new engineers a map of why the system looks the way it does. It also improves incident response because responders can distinguish intended behavior from accidental behavior quickly.
Cloudflare and Netflix both provide useful public examples of engineering communication that explains not just architecture, but operational reasoning. Netflix’s tech blog, especially around resilience patterns and platform evolution, often spells out why certain tradeoffs were made under scale and reliability constraints. Those explanations are effectively curated decision memory.
Your startup does not need a public tech blog to get the same benefit internally.
9. Expire stale decisions
A surprising number of bad engineering constraints survive because nobody remembers they were temporary.
Every decision log should include a revisit trigger:
- traffic threshold
- customer count
- p95 latency threshold
- compliance milestone
- cloud cost threshold
- team size change
- next platform rewrite window
For example:
- “Chosen because current write volume is under 50 QPS; revisit above 500 QPS.”
- “Deferred service split until the team supporting this domain exceeds 4 engineers.”
- “Accept eventual consistency until enterprise export SLA is signed.”
This prevents the worst documentation failure mode: fossilized reasoning.
10. Keep the tradeoff visible
Every consequential decision buys one thing by paying for another.
If your decision logs do not state what got worse, they are not useful.
Examples:
- “We chose app-level retries for speed of implementation; this increases duplicate side-effect risk on idempotency failure.”
- “We kept tenant isolation in the application layer to avoid a quarter-long data-plane redesign; this raises audit burden for enterprise deals.”
- “We introduced a queue to protect p95 latency; this makes debugging user-visible delays harder.”
This is the sentence future engineers need.
Without it, they assume the current system is either accidental or optimal. It is usually neither.
A concrete example
Suppose a team at a Series B SaaS company uses an agent to move webhook processing from synchronous request handling to an asynchronous job queue.
The code change is clean. Tests pass. Throughput improves.
A proper decision log would capture:
- Context: p95 request latency exceeded 800 ms under burst load.
- Decision: move webhook side effects to a queue with at-least-once delivery.
- Alternatives: increase worker count; keep sync path with per-tenant rate limiting.
- Tradeoff: lower request latency, but possible duplicate processing; requires idempotency keys.
- Operational implication: on-call must monitor queue age and dead-letter volume.
- Revisit trigger: if queue delay exceeds 60 seconds for 3 consecutive days or enterprise customers require synchronous confirmation semantics.
That single artifact is more valuable than another page of generated unit tests because it preserves intent.
The tradeoffs
Decision logs are not free.
They impose three real costs.
First, they slow some work down. On Class A and B changes, expect an extra 5 to 20 minutes of authoring and 5 to 10 minutes of review. For a team shipping dozens of risky changes per week, that is material. Second, they can become cargo cult. If leaders reward completion over clarity, engineers will fill templates with generic text that no one trusts. Third, they can overfit early-stage teams. A 10-person company building MVP features should not document every storage decision like a public company preparing for SOX review.But the alternative cost is larger once you cross a certain throughput threshold. If your team is shipping agent-assisted production changes daily across multiple services, your biggest risk is no longer writing bad code slowly. It is producing untraceable decisions quickly.
05 STRATEGIC TAKEAWAY
Decision logs are a management control for engineering throughput. If you adopt agentic coding without a system for preserving rationale, you will increase local velocity and decrease organizational intelligence at the same time. Within one or two quarters, that shows up in higher review fatigue, slower incident diagnosis, repeated architectural debates, and lower confidence in change safety. A CTO deciding this quarter whether to push harder on AI-assisted development should not ask, “How many engineer hours do we save?” The better question is, “How much decision volume can our current system absorb before reasoning starts to leak out of the company?” If the answer is unclear, decision logging is the next piece of infrastructure.
06 IMPLEMENTATION ANGLE
Start small and attach this to one workflow your team already respects: pull requests for high-risk changes. Do not roll out a company-wide ADR program. Pick three categories—auth, billing, and migrations—and require a one-screen decision log for those changes only. Instrument coverage for 30 days. In most organizations, that pilot is enough to show whether reviewers ask better questions and whether incident response gets faster.
The tool choices are already available. GitHub templates, Linear issue fields, repo-based markdown, and lightweight automation are enough. The important move is enforcement by path or label: if a PR touches `auth/`, `billing/`, or `migrations/`, the decision log check appears automatically. If you are already using coding agents internally, update their system prompts so they must draft the log before opening the PR. That is a high-leverage change because it improves both artifact quality and model behavior.
For scaling teams, this also becomes an onboarding advantage. New Staff engineers do not need more generated code to read; they need the shortlist of non-obvious decisions that shape the system. The Real Cost of Hiding Salary Ranges in Engineering Job Posts If you are growing quickly and trying to preserve technical judgment while increasing output, Amplify helps engineering teams scale—but the core principle is tool-agnostic: preserve reasoning as aggressively as you preserve code.
