When AI Becomes a Mirror: The Silent Revolution of Writing Specs

Core Insight

We often think we are tightening a leash on AI by writing project.md, rules, and prompts, but the AI actually holds up a mirror that forces us to articulate the parts of our own expertise we have never written down.

"We think AI is a tool we use, but it is a mirror that compels us to see ourselves. Once this happens, there is no going back."

Three Layers of Visibility (显形)

The author describes a three‑layer process that AI makes visible:

Intent Layer : "What we want" must be expressed as executable text.

Execution Layer : "How to do it" is encoded into CI, specs, and code.

Judgment Layer : "Whether it was done well" must be defined and evaluated.

Each layer forces previously tacit knowledge into a form that machines can read.

Historical Analogy

James C. Scott’s concept of legibility shows that when societies make complex systems visible (e.g., scientific forestry in 19th‑century Germany), they gain control but also lose the richness of the original ecosystem. The first century of “scientific forestry” boosted timber yields, but the second century saw soil degradation and ecosystem collapse.

The same pattern repeats in software: making code, specs, and metrics visible brings short‑term ROI, but risks erasing the tacit expertise that kept systems resilient.

Goodhart’s Law and the Impossible Triangle

Goodhart’s law ("When a measure becomes a target, it ceases to be a good measure") applies to AI‑driven development. The article identifies three desirable properties for judgment engineering:

Spec completeness – everything “good” is written down.

Goodhart resistance – metrics don’t get gamed.

Tacit preservation – unspoken intuition isn’t lost.

Only two of these can be achieved simultaneously, forming an “impossible triangle”. Teams end up in one of three trade‑offs:

Full spec + Goodhart resistance → sacrifice tacit knowledge (rigid, soulless code).

Spec + Tacit preservation → metrics become unreliable (over‑engineered KPIs).

Goodhart resistance + Tacit preservation → specs are vague and hard to enforce.

Five‑Level Judgment Spectrum (S1‑S5)

The author proposes a spectrum of how judgment can be expressed:

S1 Hard Rules – Boolean checks such as lint or type errors (very low Goodhart risk).

S2 Quantitative Metrics – Continuous values like coverage or cyclomatic complexity (high Goodhart risk).

S3 Structured Specs – Semantic contracts, acceptance criteria (moderate risk).

S4 Preference Statements – Soft constraints like "we prefer X over Y" (low risk).

S5 Bare Intuition – Untextual gut feelings (immune to Goodhart but invisible).

Mature teams know which decisions belong to which tier.

Three New “Stone Tablets”

To manage the new reality, the article suggests building three artifacts:

Acceptance as Code – Put every acceptance criterion into version‑controlled code, reviewed alongside implementation.

Adversarial Review Network – Separate the “doer” AI from the “reviewer” AI to avoid self‑consistency bias; use model‑swap or role‑swap reviews.

Taste as Asset – Capture team preferences (e.g., "no inheritance deeper than two levels") in a semi‑structured "Project Taste" document, preserving the flavor of the team without hard‑coding it.

These tablets must not cover everything; strategic direction, core values, and cultural quirks should remain unwritten to retain flexibility.

Practical Takeaways

Write specs in business language and review them as first‑class artifacts.

Never let the same AI both generate and evaluate its own output – introduce diversity of models or roles.

Document preferences as biased but explicit statements; they become the team’s fingerprint.

Accept that some judgment will always remain tacit and un‑formalizable.

"The danger of the visibility movement is not that it tries to see everything; it is that it only sees a part, and we mistakenly think that part is the whole."

Ultimately, the article urges engineers to recognize that the AI era forces a profound self‑examination: by making our hidden assumptions visible, we gain insight but also risk losing the very qualities that made our systems resilient.