AI engineering · Module 21a · Level 6: Lead the team
Governance and cognitive debt
Agents let a team change code faster than ever. Two risks grow with that speed: the team slowly stops understanding its own system, and agents act with more access than anyone can account for. This module covers both, plus the regulation dates software teams need to know and how to measure whether AI is actually helping. It's the leadership side of everything in Modules 08a to 16a.
A 5-minute conversation: Sam asks, Priya explains
- Sam Our team ships twice as much code since we got agents. That's good news, right?
- Priya Maybe. Two risks grow with that speed. The team slowly stops understanding its own system, and agents act with more access than anyone can account for. And twice the code isn't the same as twice the value.
- Priya Picture a city that suddenly builds ten times faster. The maps fall behind, so every new dig risks hitting a water main. If every contractor has a master key and nobody signs a log, no one knows who opened which door. A fast city needs current maps, a key per contractor, and a measure of working homes, not bricks laid.
- Sam So three ideas.
- Priya Cognitive debt: Margaret-Anne Storey's term for the gap between a system and the team's shared understanding of it. It lives in people's heads, not in the code, and Thoughtworks has it in Caution. Governance: every agent gets an identity, only the access it needs, a human owner and an audit trail. And measuring outcomes: DORA metrics, not lines of code. The DORA report calls AI an amplifier of a team's existing strengths and weaknesses.
- Sam How does cognitive debt build up?
- Priya As a loop. Agents make change cheap, so much more changes. Understanding falls behind. People who don't understand the system can't brief agents well or catch their mistakes. Fixes cause regressions, which need more fixes, which means more change. The brakes: someone who understands each change before it ships, the reasoning recorded with it, fitness functions that hold the design, and regular walkthroughs.
- Sam How would I spot it in the numbers?
- Priya The page follows two teams for six months. Team A celebrates output: pull requests more than double. But lead time doesn't fall, and rework climbs to a quarter of its work. Team B adds sensors, owners and the DORA metrics. It ships less code, faster and more reliably.
- Priya Your turn. Your CI agent runs on a senior engineer's personal token. What's wrong with that?
- Priya When something breaks, the log blames the person, and nobody can tell which job did it. Give each agent its own identity, a short-lived token scoped to one job, and a named owner.
- Sam What can I try?
- Priya A cognitive debt self-check: eight symptoms, like "only one or two people can explain how key parts fit together". And a sorter: is each metric an outcome to track, an early warning to watch, or a vanity number to drop?
- Sam What about regulation?
- Priya Three EU AI Act dates. Since February twenty twenty-five, AI literacy: people using AI systems for an organisation need sufficient training. From August twenty twenty-six, transparency: people must know when they're talking to an AI, and generated content must be marked. From December twenty twenty-seven, the high-risk rules for uses like hiring or credit scoring. Most coding agents aren't high-risk, but a feature you build might be, so check with your legal team.
- Sam And shadow IT?
- Priya AI makes it easy for anyone to build workflows outside IT. The Radar's advice: give people tracked sandboxes, keep a shared catalogue, and rebuild the workflows that become critical.
- Sam What do I measure?
- Priya DORA's five: change lead time, deployment frequency, change failure rate, time to restore, and the newer rework rate. Plus first-pass acceptance: how often agent output is used with little rework. The Radar puts coding throughput as a productivity measure in Caution.
- Sam Does each tool help?
- Priya Each keeps shared permissions somewhere: Claude Code's settings file and managed settings, Antigravity's tool permissions, Copilot's policies and firewall, Cursor's sandbox and permissions files, and Codex's sandbox mode and approval policy. Whatever the tool: a separate identity per automated agent, a pull request template that names an owner, and CI logs you keep.
- Sam The memory hook?
- Priya Keep the map, count the keys, measure the homes.
- Sam Common mistakes?
- Priya Measuring lines of AI code. Approval without understanding. Agents on personal tokens. Governance as a slow queue. Ignoring shadow tools. Assuming the vendor handles compliance. And turning metrics into a leaderboard.
- Sam And the lab?
- Priya Run the self-check with your team. Add the pull request template and a commit trailer for agent work. Baseline the DORA metrics before and after agents. Audit every agent's identity, token and owner. Catalogue the shadow tools. And confirm your AI Act obligations with your legal team.
1. The idea
A city that suddenly builds ten times faster. New streets and pipes go in every week, but the city's maps fall behind, and soon nobody is sure where the water mains run; every new dig risks hitting one. Meanwhile, if every contractor gets a master key and nobody signs a log, no one can say who opened which door. A fast-growing city needs up-to-date maps, a key for each contractor and a logbook, and it should count working homes, not bricks laid.
Three ideas carry this module:
| Idea | What it means | Thoughtworks Radar (April 2026) |
|---|---|---|
| Cognitive debt | "The growing gap between a system's implementation and a team's shared understanding of how and why it works." Margaret-Anne Storey, who named it, says it "lives in developers' minds", unlike technical debt, which lives in the code. | Codebase cognitive debt: Caution |
| Governance | Every agent has an identity, only the access it needs, a human owner and an audit trail. Tools people build for themselves with AI are found and looked after, not left to grow in the dark. | AI-accelerated shadow IT: Caution |
| Measuring outcomes | Judge AI by delivery flow and stability (DORA metrics), not by lines of code or pull requests produced. | DORA metrics: Adopt. Coding throughput as a measure of productivity: Caution |
The 2025 DORA report sums up why this matters: AI's "primary role is as an amplifier, magnifying an organization's existing strengths and weaknesses". A team with good understanding, checks and metrics gets faster; a team without them gets into trouble faster.
2. How it works
Metrics show the loop before the incidents do. Follow two teams for six months after rolling out coding agents:
Governance starts with a simple question after any incident: which agent did this, with whose access, and who owns it? Compare two setups:
3. Try it yourself
How much cognitive debt does your team have?
Tick what's true for one system you work on. The symptoms come from Storey's description of cognitive debt.
Keep the metric, or drop it?
For each metric: an outcome to track, an early warning to watch, or a vanity number to drop.
4. Why it matters at work
Keeping the team's understanding
| Practice | Why |
|---|---|
| At least one person fully understands each AI-written change before it ships | Storey's first rule. Ownership is understanding, not approval. |
| Record the reasoning, not just the change | The why in the PR description or a short decision record; agents can draft it, a person checks it. |
| Architecture fitness functions | Automated checks of key constraints (Module 12a), so the design holds even when nobody remembers why. Radar: recommended alongside feedback sensors. |
| Regular checkpoints | Reviews, retrospectives, walkthroughs, pairing. Use agents to summarise changes, but people still have to absorb them. |
| Watch team cognitive load | When a team owns more than it can understand, split the system or slow down. |
| Avoid complacency | The Radar's earlier warning (Hold, November 2025): AI-written code looks plausible, so it gets less scrutiny than it needs. |
Governing agents
| Control | What it looks like |
|---|---|
| An identity per agent | Each automated agent runs as its own app or bot account, never on a person's token (Modules 13, 13a). |
| Least privilege, short-lived | Tokens scoped to one job and one repository, expiring after the run; no production secrets in sandboxes (Module 18). |
| A named human owner | For every agent and every agent PR. Someone answers for it. |
| An audit trail | Which agent, which task, which checks, which owner: CI logs, commit trailers and your tool's admin logs, kept. |
| An approved list | Models, tools, MCP servers, plugins and skills, each with an owner and a review date (Module 21). |
| A path for shadow IT | The Radar's advice: let non-coders experiment in tracked sandboxes, keep a shared catalogue of existing workflows, and separate throwaway tools from critical ones that need a proper build. |
The EU AI Act: dates for software teams
| From | What applies | What it means for most teams |
|---|---|---|
| 2 February 2025 | Article 4, AI literacy | Providers and deployers must take measures so the people who use AI systems on their behalf have sufficient AI literacy. Training like this course counts towards it. |
| 2 August 2026 | Article 50, transparency, and enforcement | People must be told when they're talking to an AI system; AI-generated audio, images, video and text must be marked in a machine-readable way; deepfakes and AI-written public-interest text must be disclosed. |
| 2 December 2027 | High-risk rules for Annex III uses (as amended by the Digital Omnibus) | Systems used for things like hiring, credit scoring or essential services carry heavy obligations. Most internal coding agents are not in this category, but a feature you build with AI might be. |
Dates from the European Commission's AI Act Service Desk timeline. This is an overview, not legal advice: check with your legal team how your products are classified.
The portable setup
Three small habits that work with any agent and any tool:
<!-- .github/pull_request_template.md -->
## What and why
<!-- the reasoning, not just the change -->
## AI involvement
- [ ] Written mostly by an agent - [ ] Partly - [ ] Not at all
Agent and task: ______
## Understanding
Owner who understands this change end to end: @______
Risky areas a reviewer should read closely: ______# Record agent involvement in commits with a git trailer, then measure it
git commit -m "Fix order date timezone" -m "Assisted-by: agent/fix-dates (task #812)"
git log --since="3 months ago" --grep="Assisted-by:" --oneline | wc -l# AGENTS.md: two lines that slow cognitive debt
In every PR description, explain why the change is shaped the way it is.
If a change touches more than one module boundary, stop and ask for a design decision.Then track the five DORA metrics (change lead time, deployment frequency, change failure rate, time to restore, and the newer rework rate) and the Radar's suggested first-pass acceptance rate: how often agent output is used with little rework. Look at them in retrospectives, not on a leaderboard.
The honest caveatsNobody has a good way to measure cognitive debt yet; Storey calls for research on exactly that, so the self-check above is a conversation starter, not a score. Governance can turn into a three-week approval queue, which pushes people to unofficial tools (Module 21: keep the gate fast). The EU AI Act's later dates were changed by the Digital Omnibus and may change again. And metrics can be gamed like any target: use them to learn, not to rank people.
5. In your five tools
Where each tool keeps the controls that governance relies on. Taken from Modules 09, 12, 13a, 18 and 21; checked October 2026.
| Tool | Shared permissions and policy | Agent identity and audit |
|---|---|---|
| Claude Code | .claude/settings.json allow, ask and deny rules; organisations can push managed settings users can't override | Adds a co-author trailer to its commits by default; OpenTelemetry usage export; in CI, runs under the GitHub App or your API key |
| Antigravity CLI | toolPermission and enableTerminalSandbox in settings | In CI, agy -p runs under the job's own token |
| GitHub Copilot | Cloud agent behind a firewall allowlist; enterprise and organisation policies | The person who asked can't approve the agent's PR; Copilot's approvals are opt-in and path-limited (Module 13a) |
| Cursor | sandbox.json; rules in permissions.json; admin-controlled cloud agent settings | Cloud agents push from their own branches; Bugbot reads its rules from the base branch |
| Codex CLI | sandbox_mode and approval_policy in config.toml | OpenTelemetry export from user config; openai/codex-action runs under the job's token |
Whatever the tool: a separate identity per automated agent, a PR template that names an owner, and CI logs you keep.
6. Remember it
Memory hook: "Keep the map, count the keys, measure the homes"Keep the team's understanding current, give every agent its own key and log, and judge progress by working software, not bricks laid.
How this hook works: what “Keep the map, count the keys, measure the homes” means
What the slogan means, phrase by phrase
- “Keep the map”
- Shared understanding: an owner who understands each change, recorded reasoning, fitness functions.
- “count the keys”
- An identity, least privilege, an owner and an audit trail for every agent.
- “measure the homes”
- DORA metrics and first-pass acceptance, not lines of code.
Why this picture fits: a city that builds fast without maps, keys or the right measures looks productive right up to the first burst main.
The story → the concept
| City | Engineering with agents |
|---|---|
| Out-of-date maps | Cognitive debt |
| Building regulations | Fitness functions and checks |
| A key per contractor | An identity and scoped token per agent |
| The key log | The audit trail |
| Unlicensed sheds | AI shadow IT |
| Working homes, not bricks | DORA metrics, not lines of code |
The trap it saves you from
Celebrating output. More code and more PRs feel like progress while understanding erodes and rework climbs; by the time incidents show it, the debt is large.
7. Common mistakes
Measuring lines of AI codeIt rewards volume and hides the review and rework it causes. Radar: Caution.
Approval without understandingA click on "approve" isn't ownership. Someone must be able to explain the change.
Agents on personal tokensWhen something goes wrong, the log says a person did it. One identity per agent.
Governance as a queueA slow approval process creates the shadow tools it was meant to prevent.
Ignoring shadow ITTeam-built AI workflows quietly become critical. Find them, catalogue them, and rebuild the ones that matter.
"The vendor handles compliance"Deployers have their own duties under the EU AI Act, starting with AI literacy and transparency.
Metrics as a leaderboardRanking people by AI usage or PR counts gets you more of both and less of everything else.
8. Hands-on lab (alongside roadmap months 5–6)
- Take the debt self-check with your team for one system, and discuss the lowest-scoring area.
- Add the PR template and the commit trailer. After a month, what share of changes involved an agent?
- Baseline the metrics: DORA's five plus first-pass acceptance, for the quarter before and after agents.
- Audit identities: list every automated agent, its token, its scope and its owner. Fix any that use a person's token.
- Find the shadow tools: ask the team what AI workflows they've built. Catalogue them; pick one to make robust.
- Check your obligations: with your legal or compliance team, confirm AI literacy measures and whether any product feature needs Article 50 disclosure.
9. Self-check quiz
What is cognitive debt?
Technical debt lives in the code; cognitive debt lives in people's heads, as missing understanding.
Which metric is the newer fifth DORA metric, and an early warning for unchecked AI-assisted work?
Unplanned fixes to work already considered done. If it climbs after adopting agents, quality is slipping.
Where does the Radar put "coding throughput as a measure of productivity"?
Volume metrics encourage poorly aligned code that slows reviews; measure first-pass acceptance and DORA instead.
Your CI review agent needs repository access. How should it get it?
Then the audit trail names the agent, and a leak exposes one job's access, not a person's.
From when do the EU AI Act's Article 50 transparency rules apply?
AI literacy (Article 4) came first, in February 2025; Annex III high-risk rules follow in December 2027.
Non-coders are building AI workflows outside IT. The Radar's advice?
Govern it as part of the adoption strategy; rebuild the workflows that become critical.
10. Go deeper
| Resource | Time | Why |
|---|---|---|
| Cognitive debt (Margaret-Anne Storey, February 2026) | 10 min | Where the term comes from, its symptoms, and practices to reduce it. |
| Thoughtworks Radar, April 2026: Codebase cognitive debt, Coding throughput as a measure of productivity, DORA metrics, AI-accelerated shadow IT | 10 min | The four rings this module is built on. |
| 2025 DORA report and the DORA AI Capabilities Model | 60 min | AI as an amplifier, and the capabilities that make it pay off. |
| AI Act implementation timeline (European Commission), Article 4 and Article 50 | 20 min | The dates and the exact obligations. |
| Modules 12a, 13a, 18 and 21 | – | Sensors, review, security and rollout: the practices this module governs. |