TLDRocket
Sign in

Clear

sahin.io

A new language called Clear puts the spec and the actual code in one file, no separate docs to write. AI agents can execute it directly, so there's no gap between what's promised and what runs.

Based on reporting by sahin.io — read the original for the full story.

Summary, retelling and take written by AI under human oversight; images are AI-generated illustrations. How we work · Report an error

Anyone who has maintained a codebase knows the drill: someone writes a design doc, the code ships six months later, and by the time a new engineer opens both, they read like two different projects. Clear is built to close that gap by refusing to let it open in the first place. Instead of a spec document sitting next to a repository, hoping someone remembers to update both, Clear folds the specification and the implementation into a single file that is also the thing that runs.

That sounds like a small trick, but the implications are bigger than they look. There's no translation step between what the file says and what the machine does, which means there's nothing to drift. The spec isn't a promise about behavior; it is the behavior. If you change what the system should do, you change the only file that defines it, and the description updates itself because it's the same text.

The target audience is the interesting part. Clear is pitched as something an AI agent can read and execute without a human translating intent into code first, while still being plain enough that a developer can open the same file and understand what's going on without a decoder ring. That dual audience is the whole point: agents get a machine-actionable source of truth, and the team gets documentation that can't lie because it can't diverge from what's actually running.

None of this is entirely new in spirit. Literate programming and executable specifications have circled this idea for decades, mixing prose and logic in the same document. What's different now is the reason it suddenly matters again: coding agents are being handed specs and asked to just build the thing, and every gap between the written intent and the working code becomes a place where an agent can quietly go wrong. Clear is a bet that removing the gap structurally, rather than trusting agents or humans to keep two files in sync, is the more durable fix.

My take — AI-written commentary, not fact-checked reporting

I like the instinct here more than I trust the execution risk. Spec drift is one of the oldest, dumbest, most avoidable failure modes in software, and it's gotten worse now that agents are shipping code from documents nobody proofread twice. But 'one file that's both the truth and the machine' has been tried before under different names, and it always lives or dies on tooling, not philosophy — can you diff it, review it, and debug it as easily as you can with normal code. If Clear nails that boring part, it's genuinely useful. If it doesn't, it's just literate programming with better marketing for the agent era.

Read more about this at: sahin.io

Related stories

The daily briefing

Every AI story that matters, in your inbox by 8am.

TLDRocket reads all relevant sources, removes duplicate coverage, and summarises the day in two minutes. Follow companies and topics for alerts, or get the briefing in Slack. Free, no spam, unsubscribe anytime.