Semantic Claims: Conveying Intent and Verifiable Context to Humans and Agents

Description and use

Semantic claims enable developers and AI agents to capture intent, verify behavior with tests, and keep context close to code, reducing misalignment and token waste.

Problem

Agents and humans often lose context and intent when working on complex codebases, leading to misaligned implementations and wasted tokens.

Outcome

The claim‑prove‑implement workflow reduced context loss, improved test clarity, and enabled agents to focus on localized semantics, leading to more accurate implementations and lower token costs.

Workflow

• 1. Write a Markdown claim describing observable behavior (invariant or scenario).
• 2. Create a test file that proves the claim.
• 3. Implement the code that satisfies the test.
• 4. Run the checker to ensure claim, test, and implementation remain linked.
• 5. Iterate with AI assistance to refine claims and proofs.

Evidence

I started to do this—writing small, structured Markdown files with claims of the observable behavior that gives a subject its meaning.

Source

claim -> prove -> implement

Source