One Spec to Rule Them All: Curing AI's Selective Deafness with SSOT

Core premise: SSOT (Single Source of Truth) = a single authoritative specification file for AI assistants. AI "selective deafness" — ignoring rules, switching conventions, hallucinating — is usually caused by multiple conflicting spec files scattered across the repository, not by model rebellion.

Problem: Scattered Specs Cause AI "Hallucination"

In daily development using Cursor, Claude, and Qoder, the author observed that despite writing detailed rules (e.g., "don't change X", "follow color scheme Y"), AI tools still violated them. Switching tools made it worse: one tool followed file A, another followed file B, both present in the repo. The root cause: multiple spec files coexist, some contradicting each other . AI reads whichever file it encounters first — effectively a lottery ("AI drawing lots").

Writing longer, stricter rules doesn't help. Long files bury critical prohibitions deep beyond the first screen AI reads. The author concludes: specs scattered like confetti equal no specs at all . The issue is not quantity but too many entry points .

Four Core Principles (SSOT for AI)

One canonical spec file per repo. Place AGENTS.md at the repository root. All tools (Cursor, Claude Code, etc.) read this single file. No per-tool spec files.

Other files only point, never duplicate. Tool-specific files (e.g., CLAUDE.md) must contain only a single line: "See AGENTS.md at root." No duplicate commands, prohibitions, or test instructions.

Keep the entry file lean. AGENTS.md holds only summaries and prohibitions. Detailed design ( DESIGN.md), architecture ( PRODUCT.md), etc., are referenced via pointers — loaded on demand. Avoid a monolithic "project encyclopedia" that dilutes focus.

Humans resolve conflicts before AI writes. If the repo contains two startup commands or two test setups, the human must choose one. Do not document both "for compatibility"; AI will pick arbitrarily and you'll think it obeyed.

Why Clear Rules Still Get Skipped

The author identifies five common patterns that cause AI to miss rules:

Per-tool spec files with differing content → AI reads only the one it knows.

Two files each contain a full command set → AI uses whichever it reads first.

Design, architecture, prohibitions all in one huge file → AI sees front matter, misses prohibitions buried at the end (e.g., "严禁", "跳过" on later screens).

Rewrite entire file for aesthetics, overwriting auto-updated sections → New spec looks clean but breaks other automated processes (e.g., spec-change tool blocks that auto-refresh).

Document two startup methods "for compatibility" → AI picks one, you assume unification.

The fix is not stricter wording but a single stable entry point, short enough to fit in AI's default read window, with prohibitions upfront .

The ssot-agents-md Tool

To automate the consolidation, the author built a skill named ssot-agents-md. It scans the repo, merges scattered specs into the root AGENTS.md, and leaves tool-specific files (e.g., CLAUDE.md) as thin pointers. The tool does not make the model smarter; it only cleans the doorway.

Typical result after running the tool: AGENTS.md — Single source of truth for all AI. Contains startup, test, prohibitions, architecture summary. CLAUDE.md — Claude's sticky note. No longer a full spec; only says: "Read AGENTS.md."

Old files are backed up, not deleted. Human-readable README.md, design docs, etc., remain untouched and are referenced from AGENTS.md.

Handling New vs. Existing Projects

New projects

Create AGENTS.md and a minimal CLAUDE.md pointer. Avoid inventing commands that don't exist in the repo.

Existing projects (the common case)

Scan AGENTS.md, CLAUDE.md, Cursor rule files, design docs, architecture docs.

Merge compatible content into AGENTS.md.

If AGENTS.md already exists: back it up, merge scattered content in. Preserve any auto-maintained sections (e.g., spec-change tool blocks) intact — human must approve changes.

If CLAUDE.md holds a full spec: back it up, replace with pointer. Its rules should already be merged into AGENTS.md.

If AGENTS.md was previously consolidated: only check for drift or rebuild the pointer. Show diff first, no immediate rewrite.

Design docs, architecture docs, README stay as independent sources; AGENTS.md only links to them.

Critical: When two startup commands or test setups exist, the tool stops and asks the human to decide — never writes "both are fine".

Recommended workflow: run in dry-run mode first, review the merged draft and conflict list, approve, then apply.

Summary Checklist

How many AI spec files sit at your repo root? One? Three? Four?

Do Cursor and Claude read the same rules?

Are there two startup commands or two test suites you haven't chosen between?

AI skipping rules is rarely rebellion — it's a symptom of scattered, conflicting specs.

Humans hold meetings to align; AI only follows the first file it reads.

Principle: Give AI one door. Other files only give directions.

Keep the spec lean, prohibitions first. Human resolves conflicts upfront.

Concretely: root AGENTS.md is the source; CLAUDE.md becomes a pointer.

New projects: create both. Old projects: backup, merge, human-approve conflicts, dry-run before write.

The tool is just a shovel. Once the doorway is clean, then we can talk about whether AI listens. As tools multiply, specs will try to sprout again — keep this discipline tight.

AI programming is a systematic engineering discipline. If you're fighting "AI disobedience", don't rush to swap models or add more prohibitions — go count how many spec files your repo actually has. If it's more than one, share this with the colleague who keeps saying "AI doesn't listen" and let them count too.