Dark Code: Knowledge as Infrastructure

This is part 3 of a three-part series on the dark code problem.

1. The Problem
2. The Response
3. Knowledge as Infrastructure — you are here

Dark code is a problem: AI-generated code shipping to production faster than anyone can understand it. The responses delve into various takes (cognitive debt) and approaches (spec-driven development, governance). Some of these treat understanding as individual steps in a process — write the spec, do the review, check the box, etc. But understanding isn’t a step; it’s a state of mind. And maintaining that state at AI velocity requires infrastructure, not just process.

Here’s what I believe some of that infrastructure looks like. And as is often the case in software development, these aren’t new.

The problems aren’t new. The speed is.

Google disclosed at Cloud Next last week that 75% of all new code committed internally is now AI-generated. Meta is targeting the same number by mid-year. A Pragmatic Engineer survey of 900+ developers found they now spend 11.4 hours per week reviewing AI-generated code versus 9.8 hours writing new code — a reversal that would have been unthinkable two years ago. GitHub paused new Copilot sign-ups last week because agentic sessions cost more than plans charge. The velocity problem is getting worse, not stabilizing.

But the dark code conversation keeps framing this as a fundamentally new crisis requiring fundamentally new solutions. It isn’t.

Managing hybrid work — humans alongside automation — has been a thing since we started using computers. Workflow management has been a thing. Knowledge management has been a thing. Organizations have always struggled with making the right information available to the right people at the right time, and with preserving institutional knowledge as teams change.

AI didn’t create the comprehension problem. It removed the speed limit that kept it manageable. When code moved at human speed, existing practices — documentation, code review, onboarding, tribal knowledge — could mostly keep pace. At AI speed, they can’t. The practices break, but the underlying problems haven’t changed. Which means the infrastructure patterns we need aren’t speculative. They’re proven. They just need to be applied at the scale AI demands.

The spec format problem is solved

I believe spec-driven development can be a useful and productive methodology. Write the spec; build the code; verify the code with the spec. After the December 2025 outage, Amazon rebuilt Kiro around exactly this approach. Andrew Ng and JetBrains launched a course on it. Thoughtworks endorsed it in their April macro trends report. The methodology has arrived.

But SDD as a methodology isn’t tied to a specific format — and that’s where some teams get stuck. How do you actually write an effective spec that’s testable? The good news is Behavior-Driven Development (BDD) largely solved this twenty years ago.

Gherkin — the Given/When/Then syntax at the heart of BDD — has two properties that make it uniquely suited to the dark code problem. First, it’s simply constrained English. It’s easily read and understood by non-technical stakeholders, authored by domain experts, and now parsed by AI agents — all on equal footing. When your spec format is readable by every participant in the process, you’ve eliminated an entire class of comprehension failure.

Second, Given/When/Then maps directly to Arrange/Act/Assert — the three A’s of unit testing. A Gherkin scenario isn’t just a description of what the software should do. They are functional requirements that are inherently testable, not just readable. And it’s been an industry best practice for almost a generation now.

The Agile Testing Quadrant clarifies why this matters specifically for dark code. Traditional unit testing answers the question “does the code work technically?” Scenario tests, like Gherkin-based tests, answer the question “does the code do what the business needs?” These are fundamentally different questions. AI-generated code is getting decent at passing the first — Veracode reports syntax pass rates at 95%. It’s terrible at the second, because business intent is precisely the comprehension layer that dark code skips. Gherkin captures exactly the thing being lost.

Spec-driven development done well should build on this foundation. Some already do — OpenSpec, the spec format we use for much of our own development, leverages Gherkin for acceptance criteria. Amazon’s Kiro uses EARS-style acceptance criteria. The spec format problem is a solved problem; we just need to adopt the solution, not YOLO our code.

All workers need context. All work needs structure.

AI didn’t invent hybrid work. Humans have been working with automated systems for decades — batch jobs, cron schedules, CI pipelines, deployment scripts, etc. What AI adds is a third type of worker alongside humans and deterministic automation: one that’s somewhere in between. An AI agent needs runtime context like code — project conventions, file structure, API contracts, dependency graphs. And it needs direction like a human — rationale, priorities, what approaches were tried and abandoned. It draws from both piles.

But when you boil it down, all three worker types need some form of context, structure, and guidance to do good work:

• A human reviewer needs the spec, the rationale behind the approach, and enough context to evaluate whether the output actually solves the problem — not just whether it compiles.
• An AI agent needs project history, domain conventions, and prior decisions. Without this, every task starts from zero. With it, the agent produces output that’s consistent with the project’s direction and aware of what’s been tried before.
• An automated function needs structured inputs, clear contracts, and well-defined error handling. It doesn’t “understand” anything, but it needs the right data at the right time to do its job reliably.

The knowledge problem is the same across all of them: make the right information flow to the right worker at the right time. The comprehension crisis from part 2 — Storey’s cognitive debt, Osmani’s comprehension debt, Kahana’s shared blind spots — is really a knowledge-flow problem. Understanding erodes when workers lack the context they need and when none of them contribute context back for the others.

Make work flow across all three types, and you crank the work out. Fail to, and the dark code piles up — regardless of how many specs you write or reviews you mandate.

Knowledge compounds. Reviews don’t.

This is the core distinction between treating understanding as a step versus treating it as infrastructure.

A spec is written once. A review happens once. A governance checkpoint fires once. These are point-in-time events. They catch problems at the moment they occur, and that’s valuable. But they don’t build on each other. The 100th review doesn’t benefit from the first 99.

Knowledge infrastructure is different. It persists, flows, and compounds. The 100th task on a project should be observably better than the 1st — not because the workers got smarter, but because the system accumulated understanding: what was decided and why, what patterns work in this codebase, what was tried and failed, what the domain requires. This is about wisdom, not intelligence.

Martin Fowler’s site recently published a harness engineering guide that offers a useful taxonomy here: guides and sensors. Guides — specs, context injection, constraints, conventions — shape what workers do going in. Sensors — reviews, verification, audit trails — validate what came out. Both are necessary. Neither alone is sufficient. And both need to work for every worker type, not just human developers.

What knowledge infrastructure actually requires:

Persistent memory. Not conversation history — curated, validated knowledge. Architecture decisions, domain constraints, patterns that work, approaches that failed. Available to every worker on every task. This is what turns isolated task execution into organizational learning.

Context shaped to the worker and the stage. A reviewer verifying output needs different context than the worker who produced it. Specifically, an independent reviewer should see the spec and the result — but not the implementation reasoning. This is the information barrier that prevents the shared blind spots Kahana identified: when the reviewer inherits the implementer’s assumptions, both miss the same things.

Universal contribution. Any worker type should be able to flag concerns, record observations, and capture decisions that benefit future work. Knowledge needs to flow both ways for it to compound.

An auditable record. Not just “it passed review” but the full chain: who did what, when, with what context, what was decided, and why. When something goes wrong six months from now, this is what lets someone reconstruct the reasoning — or lets the system itself identify patterns in what went wrong.

Beyond code

Dark code is the most visible symptom because software development is where AI hit first. Developers have IDEs, git, CI/CD, and code review — infrastructure that AI plugged into naturally. The comprehension crisis surfaced there because that’s where the velocity spiked.

But the knowledge infrastructure problem is domain-agnostic.

A compliance report generated by an AI agent needs the same structural guarantees as code: was the intent specified clearly, was the output verified independently, does someone understand the result well enough to defend it? A patient intake workflow, a vendor onboarding process, a monthly financial close — any work where mixed worker types participate benefits from the same patterns: persistent knowledge, stage-appropriate context, independent verification, auditable records.

The accountability infrastructure Part 2 described — the governance, the structural enforcement, the “humans answer for the result” principle — only works if the humans (and agents) actually have the understanding to answer. That’s what makes knowledge infrastructure the missing layer: it’s what makes accountability possible at scale, not just mandated by law.

What we’re building

Accountability at AI velocity requires infrastructure that produces the record automatically — not as a discipline, but as a property of how the work runs. This is one of the problems we’re working on at Mighty Code.

We’re building a work framework where humans, AI agents, and code workers collaborate through governed workflows. Three worker types participating as peers — not AI bolted onto a human process, but a unified system where the engine doesn’t care which type of worker does a given step. It cares that the work meets the criteria for moving forward.

The architecture maps directly to the knowledge infrastructure this series has been building toward:

• Governed workflows move work through defined stages with comprehension built in — shaping requires specification before work begins, review enforces independent verification.
• Persistent project memory means accumulated knowledge — decisions, conventions, domain context, what worked and what didn’t — is available to every worker on every task. The system learns.
• Step-specific context ensures each worker gets what it needs for its role. The reviewer sees the spec and the output, not the implementer’s reasoning. The information barrier is structural, not aspirational.
• An append-only ledger records every action, decision, and outcome. The auditable record is a property of the system, not a discipline of the team.
• Any domain — not just code. The engine, the worker types, the quality gates, and the knowledge system are domain-agnostic. We’ve been dogfooding it for software development, but it’s designed to support virtually any work process and domain.

It’s open source, and it doesn’t require AI to be useful. You can adjust how much or how little AI participates — this is a work platform, not an AI-hype product.

The dark code problem isn’t going to be solved by slowing down. It’s going to be solved by building the knowledge infrastructure that makes understanding scale with velocity — across every worker type, in every domain, for every organization that uses AI to get work done.

More to come at mightycode.com.